Class TrainzGameObject

Revision as of 12:34, 26 February 2024

• API Hierarchy
  • GSObject
    • GameObject
      • Class TrainzGameObject

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

Init

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

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

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

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

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

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

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.

Categories