Skip to content

Script throttle

Represents a script-accessible throttle object that can control a train when acquired. Throttle objects can be created using the class.create_throttle() function.

Properties

name

The name assigned to this throttle.

train

the train currently controlled by this throttle, if any.

Methods

acquire(train [, steal])

Attempts to acquire control of train for this throttle.

Parameters:

  • train
    The train to acquire.

  • steal
    Optional flag allowing the throttle to steal control from another throttle, default is false.

Return values
Returns true if the train was successfully acquired, false otherwise.

change_direction()

Reverses the current direction of the train controlled by this throttle. The train can only change direcition if stopped.

Return values
Returns true if the direction was changed successfully, false otherwise.

emergency_stop()

Immediately stops the train controlled by this throttle, bypassing any deceleration logic.

Return values
Returns true, only returns false if throttle is not acquired.

release([stop])

Releases control of the currently controlled train.

Parameters:

  • stop
    Optional boolean indicating whether the train should stop when released, default is true.

set_direction(direction)

Sets the direction of the train. The train can only change direcition if stopped.

Parameters:

  • direction
    The desired direction for the train (enum.direction.FORWARD or enum.direction.REVERSE).

Return values
Returns true if the direction was successfully set.

set_speed(speed, unit)

Sets the current speed of the train directly.

Parameters:

  • speed
    The train speed in unit.

  • unit
    The speed unit (e.g. enum.speed_unit.KMPH or enum.speed_unit.MPH).

Return values
Returns true if the speed was successfully set, false otherwise.

set_target_speed(target_speed, unit)

Sets the target speed for the train, allowing gradual acceleration or deceleration.

Parameters:

  • target_speed
    The desired target speed for the train in unit.

  • unit
    The speed unit (e.g. enum.speed_unit.KMPH or enum.speed_unit.MPH).

Return values
Returns true if the target speed was successfully applied, false otherwise.

Events

on_acquire

Event triggered when the throttle successfully acquires a train.

Handler signature

function (throttle, train, user_data)

Arguments

  • throttle - the throttle that is acquired control of the train.

  • train - the train that is acquired by the throttle.

  • user_data - optional user-provided value (see Events).

on_release

Event triggered when the throttle releases control of its train.

Handler signature

function (throttle, user_data)

Arguments

  • throttle - the throttle that released control.

  • user_data - optional user-provided value (see Events).