Class TrainzGameObject
From TrainzOnline
(Difference between revisions)
| (3 intermediate revisions by one user not shown) | |||
| Line 1: | Line 1: | ||
*[[TrainzScript Library Reference|API Hierarchy]] | *[[TrainzScript Library Reference|API Hierarchy]] | ||
| − | **[[Class | + | **[[Class GSObject]] |
| − | ***[[Class | + | ***[[Class GameObject]] |
| − | ****Class TrainzGameObject | + | ****[[Class TrainzGameObject]] |
<br> | <br> | ||
| Line 11: | Line 11: | ||
{{MethodHeader|public void Init(Asset asset)}} | {{MethodHeader|public void Init(Asset asset)}} | ||
;Parameters | ;Parameters | ||
| − | * | + | *asset - Reference to the script's associated asset. |
;Returned Value | ;Returned Value | ||
*None | *None | ||
| Line 43: | Line 43: | ||
*rights - Array of string identifiers specifying the operations permitted by this token. | *rights - Array of string identifiers specifying the operations permitted by this token. | ||
;Returned Value | ;Returned Value | ||
| − | *The issued SecurityToken. | + | *The issued [[Class SecurityToken|SecurityToken]]. |
;Syntax | ;Syntax | ||
KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset"); | KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset"); | ||
| Line 76: | Line 76: | ||
;Notes | ;Notes | ||
| − | *Re-issues a SecurityToken to another asset. | + | *Re-issues a [[Class SecurityToken|SecurityToken]] to another asset. |
*The source token must permit duplication by including "duplicate-token" in the rights array. | *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. | *It is not be possible to add rights that the calling asset does not already have, only remove existing ones. | ||
| Line 86: | Line 86: | ||
*tokens - The tokens to merge together. | *tokens - The tokens to merge together. | ||
;Returned Value | ;Returned Value | ||
| − | *A single SecurityToken with all of the rights of the passed in tokens. | + | *A single [[Class SecurityToken|SecurityToken]] with all of the rights of the passed in tokens. |
;Syntax; | ;Syntax; | ||
SecurityToken[] tokens = new SecurityToken[]; | SecurityToken[] tokens = new SecurityToken[]; | ||
| Line 111: | Line 111: | ||
return; // Reject the token | return; // Reject the token | ||
;Notes | ;Notes | ||
| − | *Checks if a | + | *Checks if a [[Class SecurityToken|SecurityToken]] is owned by a specific object, and that it has access to perform a specific operation. |
<br> | <br> | ||
| Line 127: | Line 127: | ||
return; // Reject the token | return; // Reject the token | ||
;Notes | ;Notes | ||
| − | *Checks if a | + | *Checks if a [[Class SecurityToken|SecurityToken]] is owned by a specific object, and that it has access to perform a specific operation. |
<br> | <br> | ||
==Categories== | ==Categories== | ||
[[Category:Script Class]] | [[Category:Script Class]] | ||
Latest revision as of 12:48, 26 February 2024
- API Hierarchy
- Class GSObject
- Class GameObject
- Class TrainzGameObject
- Class GameObject
- Class GSObject
- Base class for a GameObject that is an instance of a Trainz asset.
Contents |
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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.
