Class TrainzGameObject

• API Hierarchy
  • Class GSObject
    • Class GameObject
      • Class TrainzGameObject

• Base class for a GameObject that is an instance of a Trainz asset.

Init

public void Init(Asset asset)

Parameters

• asset - Reference to the script's associated asset.

Returned Value

• None

Syntax

• None, method is automatically called by the game.

Notes

• Initialisation method which is called by Trainz when the object is first created.
• It is up to the script programmer to do any initialization tasks required here.
• This may include starting monitor threads, adding message handlers, and so on.
• Some derived classes have both an Init() and Init(Asset) method. It is recommended that you use the Init(Asset) version whenever you can.
• Uses the 'mandatory' keyword, meaning you must call inherited() when overriding this function.
• Since Init() is called from native Trainz code, you cannot use Sleep() or wait(). However, Init() can start threaded methods that are allowed to sleep and process messages.

GetAsset

public Asset GetAsset(void)

Parameters

• None

Returned Value

• A reference to the owning asset.

Syntax

Asset asset = GetAsset();

Notes

• The returned Asset reference can be used to retrieve the KUID, StringTable or configuration data of the Asset.

IssueSecurityToken

native SecurityToken IssueSecurityToken(KUID asset, string[] rights)

Parameters

• asset - The asset this token is intended to be used by.
• rights - Array of string identifiers specifying the operations permitted by this token.

Returned Value

• The issued SecurityToken.

Syntax

KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset");

string[] rights = new string[2];
rights[0] = "edit-settings";
rights[1] = "access-data";

SecurityToken token = IssueSecurityToken(friendlyAsset, rights);

Notes

• Creates a SecurityToken object which can be issued to other assets to grant access to certain features.
• The created SecurityToken can be given to trusted objects, and later passed to the Validate() function when checking permissions.
• SecurityToken.IsIsOwnerLocallyModified() can be used to check the issued asset hasn't been modified in some form.

IssueSecurityToken

native SecurityToken IssueSecurityToken(SecurityToken source, KUID asset, string[] rights))

Parameters

• source - The source security token.
• asset - The asset this token is intended to be used by.
• rights - Array of string identifiers specifying the operations permitted by this token.

Returned Value

• The issued SecurityToken.

Syntax

KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset");

string[] rights = new string[2];
rights[0] = "access-data";

SecurityToken newToken = IssueSecurityToken(m_ourToken, friendlyAsset, rights);

Notes

• Re-issues a SecurityToken to another asset.
• The source token must permit duplication by including "duplicate-token" in the rights array.
• It is not be possible to add rights that the calling asset does not already have, only remove existing ones.

MergeSecurityTokens

native SecurityToken MergeSecurityTokens(SecurityToken[] tokens)

Parameters

• tokens - The tokens to merge together.

Returned Value

• A single SecurityToken with all of the rights of the passed in tokens.

Syntax;

SecurityToken[] tokens = new SecurityToken[];
tokens[0] = m_securityToken;
tokens[1] = newRightsToken;

m_securityToken = MergeSecurityTokens(tokens);

Notes

• Can be used to merge multiple tokens together, making things easier to manage.
• Can be used to (essentially) add new rights to an existing token.
• Care should be taken when merging tokens from different owners, to avoid compromising security.

Validate

native bool Validate(SecurityToken token, TrainzGameObject owner, string operation)

Parameters

• token - The token to validate.
• owner - The owner to search for in the token.
• operation - The operation to perform (must be listed in the 'rights' of the token).

Returned Value

• Whether the token grants the required access.

Syntax;

if (!Validate(token, m_friendlyAsset, "edit-settings"))
  return; // Reject the token

Notes

• Checks if a SecurityToken is owned by a specific object, and that it has access to perform a specific operation.

Validate

native bool Validate(SecurityToken token, KUID owner, string operation)

Parameters

• token - The token to validate.
• owner - The owning asset to search for in the token.
• operation - The operation to perform (must be listed in the 'rights' of the token).

Returned Value

• Whether the token grants the required access.

Syntax;

KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset");
if (!Validate(token, friendlyAsset, "edit-settings"))
  return; // Reject the token

Notes

• Checks if a SecurityToken is owned by a specific object, and that it has access to perform a specific operation.