Class InterlockingTowerPath

The InterlockingTowerPath class is the script representation of an individual Interlocking Tower "Path". In this context a path represents the track that a train can take through an Interlocking Tower controlled area. It is defined by a number of trackside objects (signals, junctions and crossings) and the state that those objects must be in to allow the train passage through that path. Each path has an entry and exit signal. When a train approaches an entry signal the Interlocking Tower (and related libraries) will attempt to assign it a specific path, so that it may pass the signal.

• API Hierarchy
  • GSObject *
    • GameObject
      • InterlockingTowerPath

Related Classes

• InterlockingTower
• Signal
• Junction
• Crossing
• TrackCircuitBlock
• TrackPathDisplay

Common functions

Below is a list of some of the basic common functions on the InterlockingTower script class. This list is not intended to be comprehensive, merely provide an overview.

public mandatory void Init(InterlockingTower tower, SecurityToken token)

Description

Initialises the path with the parameters defined, if possible. Will throw an exception and return false if the request is invalid.

Parameters

• tower - The calling interlocking tower.
• token - A SecurityToken from the owning InterlockingTower, with sufficient rights to activate the path.

public void SetPathName(string pathName)

Description

Sets the identifying path name. This should be unique within the owning tower.

Parameters

• pathName - The new identifying name for the tower path.

public string GetPathName()

Description

Returns the identifying path name for this tower path.

public string GetLocalisedPathName()

Description

Returns the localised path name for this tower path. Localised names are stored in the string-table for the route or session. There is no interface to set this and it must be done by the session creator.

public bool IsObjectInPathDefinition(MapObject obj, int childIndex, bool bIncludeExternalRequirements)

Description

Returns whether a given object is part of the definition of this path.

Parameters

• obj - The path object (junction, signal, etc) to search for.
• childIndex - The index of a child object, or -1 for the object itself.
• bIncludeExternalRequirements - Whether to also check the external requirement list.

Returns

• bool - true if the object was found, false otherwise

public bool IsObjectOnPath(MapObject obj)

Description

Performs a track search and returns whether the passed object is on the path somewhere. Avoid calling this often as it can be quite intensive.

Parameters

• obj - The map object to search the path for.

Returns

• bool - Whether the object was found on the path.

public bool IsObjectOnOrBeyondPath(MapObject obj)

Description

Returns whether a given object is on this path, or lies on the track beyond the exit signal. Note that searching beyond the path will follow the currently set junction directions.

Parameters

• obj - The map object to search the path for.

Returns

• bool - Whether the object was found on the path, or within the search range beyond the path.

public int GetPathClearMethod()

Description

Returns the currently set path clear method, which is one of the ITP_CLEAR_* defines.

public void SetPathClearMethod(int clearMethod)

Description

Alters the path clear method for this path.

Parameters

• clearMethod - The new clearing method to set, one of the ITP_CLEAR_* defines.

bool CanTransitionPathToState(int state)

Description

Returns whether this path is in a state where it's possible to begin to transition to the state passed. When creating a custom tower script this is an ideal place to perform extra checks for path state changes.

Parameters

• state - The state we want to transition to.

Returns

• bool - true if the path is able to transition to the requested state, false otherwise.

public void ActivatePath(SecurityToken token)

Description

Begins activating the path, if possible. Will post a message to the owning tower of type "InterlockingTowerPath","Active" when the path is set.

Parameters

• token - A SecurityToken from the owning tower with rights "path-control".

public void CancelPath(SecurityToken token)

Description

Begins cancelling the path, if possible. Will post a message to the owner of type "InterlockingTowerPath","Cancelled" when the path is cancelled. This will return all controlled objects to their original state if appropriate, based on m_clearState.

Parameters

• token - A SecurityToken from the owning tower with rights "path-control".

public void SetPanicState(SecurityToken token)

Description

Instantly drops all controlled signals along this path. Does not change junction or crossing state. Used to simulate an emergency situation of some kind. To transition out of a panic state call either ActivatePath or CancelPath.

Parameters

• token - A SecurityToken from the owning tower with rights "path-control".

public void AddTrain(SecurityToken token, Train train)

Description

Adds the train passed to this path. Does not perform any validation on this operation and will warrant all requests from a valid source.

Parameters

• token - A SecurityToken from the owning tower with rights "path-control".

public void RemoveTrain(SecurityToken token, Train train)

Description

Removed the train passed from this path. Performs no validation on the operation and will warrant all requests from a valid source.

Parameters

• token - A SecurityToken from the owning tower with rights "path-control".

public bool IsOccupiedByTrain(Train train, bool bRequireHasClearedEntrySignal)

Description

Returns whether the path is known to be occupied by a specific train. Does not perform any track searching and is reliant on the owning tower correctly calling AddTrain/RemoveTrain.

Parameters

• train - The train to check for.
• bRequireHasClearedEntrySignal - If true, return true only if the train has cleared the entry signal and is occupying the path, otherwise it's sufficient that the tower has merely 'added' the train.

Returns

• bool - Whether the train has been added to the path and, optionally, has passed the entry signal.

public void EnablePathVisualisation(bool enable, bool bShouldIncludeAllTCBs)

Description

Enables/disables visualisation of this path in the game world, using TrackPathDisplay.

Parameters

• enable - true to enable the path visualisation, false to disable it
• bShouldIncludeAllTCBs - Whether to also add path visualisations for every occupied TrackCircuitBlock.