Class TrainzGameObject

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
m
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
*[[TrainzScript Language Reference|API Hierarchy]]
+
*[[TrainzScript Library Reference|API Hierarchy]]
−
**[[Class GSObject|GSObject]]
+
**[[Class GSObject]]
−
***[[Class GameObject|GameObject]]
+
***[[Class GameObject]]
−
****Class TrainzGameObject
+
****[[Class TrainzGameObject]]
 
<br>
 
<br>
  
 
*Base class for a GameObject that is an instance of a Trainz asset.  
 
*Base class for a GameObject that is an instance of a Trainz asset.  
−
*This class is a parent class for game objects in the Trainz world that are instances of a Trainz asset.
 
  
  
 
==Init==
 
==Init==
−
{{MethodHeader|public void Init(void)<br>public void Init(Asset asset)}}
+
{{MethodHeader|public void Init(Asset asset)}}
 
;Parameters
 
;Parameters
−
*'''asset''' = Reference to the script's associated asset.
+
*asset - Reference to the script's associated asset.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 20: Line 19:
 
*Initialisation method which is called by Trainz when the object is first created.  
 
*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.
 
*It is up to the script programmer to do any initialization tasks required here.
−
*This may include starting a thread if the object is to exist in a persistent state.
+
*This may include starting monitor threads, adding message handlers, and so on.
−
*Some derived classes have both an Init() and Init(Asset) method. There isn't much difference between them except one gets the Asset as a parameter. It is recommended that you use the Init(Asset) version whenever you can.
+
*Some derived classes have both an Init() and Init(Asset) method. It is recommended that you use the Init(Asset) version whenever you can.
−
*When overriding this base Init() method, you must call it explicitly by using the inherited keyword in the overridden implementation.
+
*Uses the 'mandatory' keyword, meaning you '''must''' call inherited() when overriding this function.
 
*Since Init() is called from native Trainz code, you cannot use [[Class GameObject#Sleep|Sleep()]] or wait(). However, Init() can start threaded methods that are allowed to sleep and process messages.  
 
*Since Init() is called from native Trainz code, you cannot use [[Class GameObject#Sleep|Sleep()]] or wait(). However, Init() can start threaded methods that are allowed to sleep and process messages.  
 
<br>
 
<br>
Line 31: Line 30:
 
*None
 
*None
 
;Returned Value
 
;Returned Value
−
*A reference to the current asset
+
*A reference to the owning asset.
 
;Syntax
 
;Syntax
 
  Asset asset = GetAsset();
 
  Asset asset = GetAsset();
 
;Notes
 
;Notes
 
*The returned [[Class Asset|Asset]] reference can be used to retrieve the KUID, StringTable or configuration data of the Asset.
 
*The returned [[Class Asset|Asset]] reference can be used to retrieve the KUID, StringTable or configuration data of the Asset.
 +
<br>
 +
 +
==IssueSecurityToken==
 +
{{MethodHeader|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 [[Class SecurityToken|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 [[Class SecurityToken|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.
 +
<br>
 +
 +
==IssueSecurityToken==
 +
{{MethodHeader|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 [[Class SecurityToken|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.
 +
<br>
 +
 +
==MergeSecurityTokens==
 +
{{MethodHeader|native SecurityToken MergeSecurityTokens(SecurityToken[] tokens)}}
 +
;Parameters
 +
*tokens - The tokens to merge together.
 +
;Returned Value
 +
*A single [[Class SecurityToken|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.
 +
<br>
 +
 +
==Validate==
 +
{{MethodHeader|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 [[Class SecurityToken|SecurityToken]] is owned by a specific object, and that it has access to perform a specific operation.
 +
<br>
 +
 +
==Validate==
 +
{{MethodHeader|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 [[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


  • 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
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.


[edit] Categories

Retrieved from "https://online.ts2009.com/mediaWiki/index.php?title=Class_TrainzGameObject&oldid=40130"
Personal tools