Zone
A zone groups multiple blocks into a logical area, such as a station, yard, or staging area. Zones make it easier to script behaviors that depend on a train’s location within a larger area, rather than tracking individual blocks.
Properties
id
Unique object identifier. Each object in Traintastic has a globally unique id that can be used in scripts (see world.get_object).
mute
If true, all sounds of trains in the zone are muted.
name
The configured name of the zone.
no_smoke
If true, smoke generaters are disabled of all trains in the zone.
trains
List of train zone status objects of all trains that are entering, entered or leaving the zone.
Events
Zone events fall into two categories:
-
Assignment events:
on_train_assignedandon_train_removedare triggered when a train is manually linked to or unlinked from a block in the zone. These indicate identification changes made by the operator, not movement. -
Movement events:
on_train_entering,on_train_entered,on_train_leaving, andon_train_leftare triggered as a train moves through the zone. They represent the lifecycle of a train entering, being inside, leaving, and fully leaving the zone.
on_train_assigned
Fired when a train is manually assigned to the first block of the zone. This happens after a train has been placed on the track and the operator links it to the block, allowing Traintastic to recognize which train it is.
This event is about train identification, not movement.
Handler signature
function (train, zone, user_data)
Arguments
-
train- the train that is assigned to a block in the zone. -
zone- the zone firing the event. -
user_data- optional user-provided value (see Events).
on_train_entered
Fired when a train is fully inside the zone. A train is considered 'in the zone' only if it exclusively occupies blocks that belong to the zone.
Note
If a zone is too small or the train too long, it may happen that while entering, the train simultaneously starts leaving the zone. In this case, the train is never fully inside, and on_train_entered will not be fired (only on_train_entering and on_train_leaving apply).
Handler signature
function (train, zone, user_data)
Arguments
-
train- the train that is in the zone. -
zone- the zone firing the event. -
user_data- optional user-provided value (see Events).
on_train_entering
Fired when a train starts moving into the zone by reserving or occupying its first block. This marks the point where the train begins to interact with the zone but is not yet fully inside it (see on_train_entered).
Unlike on_train_assigned, which is triggered when a train is manually linked to a block (e.g., placed on the track and assigned by the operator), on_train_entering reflects actual movement or reservation during operation.
Handler signature
function (train, zone, user_data)
Arguments
-
train- the train that is entering the zone. -
zone- the zone firing the event. -
user_data- optional user-provided value (see Events).
on_train_leaving
Fired when a train starts to leave the zone by reserving or occupying a block that is not part of the zone. At this point the train still has blocks in the zone, but it is extending beyond its boundaries.
Handler signature
function (train, zone, user_data)
Arguments
-
train- the train that is leaving the zone. -
zone- the zone firing the event. -
user_data- optional user-provided value (see Events).
on_train_left
Fired when a train is no longer in the zone, a train is no longer in the zone when it doesn't occupy any block that are part of the zone.
Handler signature
function (train, zone, user_data)
Arguments
-
train- the train that has left the zone. -
zone- the zone firing the event. -
user_data- optional user-provided value (see Events).
on_train_removed
Fired when a train is manually removed from the last block of the zone. This is the opposite of on_train_assigned and indicates the train is no longer linked to the zone.
This event is about train identification, not movement.
Handler signature
function (train, zone, user_data)
Arguments