Script Include Directive

Revision as of 00:21, 22 August 2023

A script written in the TrainzScript language is stored in one or more ".gs" files within an asset. One of these script, referred to as the asset's "primary script", is referenced from the asset's config.txt file. Any additional ".gs" files within the asset may then be referenced from within a script file by using the "include" directive.

Example

Include "scriptname.gs"

First example is to include some more scripts into the asset script. The script .gs files to include reside in the same folder as the assets files. They will be included with the include directive include("scriptname.gs"). The included scripts work the same way as if write the code in place of the include directive.

TBD: Searchpath while including

LibraryCall

The second example uses the LibraryCall method. The config.txt connects the library assets within the kuid-table. Here we use two libraries A and B.

 kuid-table {
   methliba             <kuid2:0:21548910:1>
   methlibb             <kuid2:0:21548911:1>
 }

The two library assets define the callable methods method1, method2 and method3. The LibraryCall method organizes the calling of the callable methods. The return value will returnd into the calling script.

 /* Script Library A */
 include "Library.gs"
 class TUTLibA isclass Library {
   public void Init(void) { inherited(); }
   
   string methodinfo1 = "TUT Lib A -> method1"; 
   string methodinfo2 = "TUT Lib A -> method2";
   string methodinfo3 = "TUT Lib A -> method3"; 
   
   public string method1(string caller) { return "Called [: "+methodinfo1+" :] by [: "+caller+" :]"; }
   public string method2(string caller) { return "Called [: "+methodinfo2+" :] by [: "+caller+" :]"; }
   public string method3(string caller) { return "Called [: "+methodinfo3+" :] by [: "+caller+" :]"; }
   
   public string LibraryCall(string functionname, string[] arglist, GSObject[] gsolist) {
     string text = "";
     if (functionname == "method1") text = method1(arglist[0]);
     if (functionname == "method2") text = method2(arglist[0]);
     if (functionname == "method3") text = method3(arglist[0]);
     return text;
   }
   
 };

The callable methods may be used in an assets script. First one need a Library object that than conects the callable methods with the help of the LibraryCall method.

 /* MethodLibraryTutorial.gs V3 */
 include "MapObject.gs"
 class TUTLibTest isclass MapObject {
 
   GSObject[] gso;
   string iam = "LibTut";
 
   Library MyMethLibA;
   Library MyMethLibB;  

   public void Init(void) {
     
     inherited();
     
     MyMethLibA = World.GetLibrary(GetAsset().LookupKUIDTable("methliba"));  
     MyMethLibB = World.GetLibrary(GetAsset().LookupKUIDTable("methlibb"));
     
     string[] args = new string[1];
     args[0] = Str.CloneString(iam);
     
     Interface.Print(MyMethLibA.LibraryCall("method2", args, gso));
     Interface.Print(MyMethLibB.LibraryCall("method3", args, gso));
     Interface.Print(MyMethLibA.LibraryCall("method1", args, gso));
     Interface.Print(MyMethLibB.LibraryCall("method2", args, gso));
     Interface.Print(MyMethLibA.LibraryCall("method3", args, gso));
     Interface.Print(MyMethLibB.LibraryCall("method1", args, gso));
     
   }
   
 };  

The two variables MyMethLibA and MyMethLibB hold the two Library objects. And MyMethLibA.LibraryCall("method2", args, gso) calls the library method method2. The possible method arguments will be deliverd as strings in the string array args, possible gsobjects in the GSObject array gso. The returned string value of MyMethLibA.LibraryCall("method2", args, gso) is the result of the execution of the called method method2.

The two examples and the example libraries one will find in this ZIP archive: File:Tutorial Methods Script Library.zip

Cross-Asset Includes

Script files from other assets can be included through the use of an "script-include-table" tag in the parent asset's config.txt file. This causes the asset to become dependant on the specified child assets, and makes it possible to directly include the child assets' script file(s) from the parent asset's script file(s). If the child asset is a KIND Library, the parent asset may use World.GetLibrary() to gain a reference to the library, as demonstrated here.

This will then allow you to call public functions in the library directly without needing to use the Library.LibraryCall() syntax.

Note: When uploading a scripted asset to the Download Station, any dependency assets referenced through a script-include-table must already exist on the DLS or else must be contained in the same package (cdp) being uploaded to the DLS. The DLS will reject the upload of any asset where the necessary script dependencies are not present.

Circular Includes

Circular inclusion is not permitted. Examples of circular inclusion are "A includes B includes A" or "A includes B includes C includes A" (where A, B, C are script files.)

Scripts with Identical Names

The content creator must avoid any situation in which multiple script files (at different file paths) have the same file name. The outcome is undefined.

The content creator must avoid any situation in which multiple script files (regardless of the file name) which define same-named script classes are included at the same time. The outcome is undefined.

Categories