NumberIt
by ElDavo

Script support for random vehicle running numbers

Revised 8th October 2005 for TRS2006 compatibility


What is NumberIt?

NumberIt is a Trainz GameScript library that provides a simple and convenient way for Trainz model makers to randomly set the running number of a vehicle from a range of available numbers without having to become scripting experts. The scripting system for TRS2004 is a powerful environment but to those not familiar with programming can seem somewhat daunting. NumberIt makes it easy, in fact all the scripting you require can be done by copying and pasting from the example below!

NumberIt encapsulates the selection of a vehicle running number in a script library that is shared by all the models that use it. As it is shared there is only one copy so your vehicle's script can be smaller and overall less computer memory will be consumed by copies of scripts which essentially do the same thing. The original code within NumberIt is derived from a script originally posted on the Auran Trainz forums by davidt (David Taylor). All credit goes to him for the original idea and script leg work.

Using NumberIt with your model

The config.txt file

To define the range of numbers your vehicle can take you need entries in the model's config.txt file. First up you will need to declare that the model requires TRS2004 service pack 4 at least. This is accomplished by having a trainz-build tag entry specifying 2.4 which equates to a build version of 2365 (2370 UK). NumberIt may work with earlier versions but I give no guarantees!

trainz-build					2.4

Your model config.txt will need to declare the NumberIt library as an asset that it uses. If you don't your vehicles script will not be able to find it and furthermore the download helper won't ensure that the users of your vehicle download it! This is achieved with the NumberIt_library entry.

kuid-table {
	.
	.
	NumberIt_library			<kuid2:75134:99003:4>
	.
	.
}

Your model config.txt needs to define the range of numbers to be used and this is done with three entries as below:

extensions {
	numberit-75134 {
		NumberIt_prefix					500
		NumberIt_min					001
		NumberIt_max					200
	}
}

The example above defines a group of vehicles with 6 digit running numbers ranging from 500001 to 500200. From this you can see that NumberIt_prefix defines the fixed leading part (or prefix) of the number while NumberIt_min and NumberIt_max define the lower and upper limits of the variable part.

Now define the script class for your model. The name of the class is entirely of your choosing but must match up with the filename of the file in which the source code is saved. If you already have scripting on your vehicle these entries will exist in which case omit this step.

class						"NIExample"
script						"NIExample"

The script file

The following is an example minimum script file for a model using NumberIt. To use this with your model all you need to do is copy this example (also provided in the package) to the directory containing the config.txt of your model. Rename the file and change the name entry in the class declaration to your chosen class name. Change every reference to "NIExample" to your chosen name.

In the example below we make one call to the NumberIt library function SetRunningNumber from the Init method of the script class. This call will ensure a number is selected from the range described in config.txt and set if you have not already specified what the number should be through the surveyor property dialogue.

include "vehicle.gs"
include "library.gs"

/*
   NumberIt example script
  
   Author: Dave Renshaw (eldavo)

   Copyright Dave Renshaw 2005. All rights reserved.

 */

class NIExample isclass Vehicle
{
    Library numberit;

    void Init(void) {
        inherited();

        // Pick a running number if one hasn't already been set
        numberit = World.GetLibrary(GetAsset().LookupKUIDTable("NumberIt_library"));
        if (numberit) {
            GSObject[] objectParam = new GSObject[1];
            objectParam[0] = me;
            numberit.LibraryCall("SetRunningNumber", null, objectParam);
        }
    }
};

Further info

The functions available in the library

The NumberIt library contains 2 functions that can be called with the standard "LibraryCall" method, 1 for normal use and 1 that can be used for debugging.

SetRunningNumber

The SetRunningNumber function is called from the Init method of the vehicle script to set up an initial vehicle running number. The function takes one parameter, a reference to the vehicle itself.

Example:


void Init(void) {
    inherited();

    // Pick a running number if one hasn't already been set
    numberit = World.GetLibrary(GetAsset().LookupKUIDTable("NumberIt_library"));
    if (numberit) {
        GSObject[] objectParam = new GSObject[1];
        objectParam[0] = me;
        numberit.LibraryCall("SetRunningNumber", null, objectParam);
    }
}

CheckConfig

The CheckConfig function can be used when testing your model to have the NumberIt library analyse the config.txt file of your model and to check whether it can successfully allocate a number. You should not leave calls to this function in your script once you are happy with the model as it is a fairly expensive function to call in terms of CPU.

Example:


	GSObject[] objectParam = new GSObject[1];
	objectParam[0] = me;
	numberit.LibraryCall("CheckConfig", null, objectParam);

This function is automatically called as part of the SetRunningNumber function when you examine the model in Railyard so in most cases you don't need to use this function. If somebody has problems with your model simply ask them to look at it in Railyard and then have them send you the JetLog.txt file. The following is an example of the output you might expect to see in the log file:


   : -----------------------------------------------------------------------------------------------
   : | NumberIt running number support v1.0. Copyright Dave Renshaw (Eldavo's Railway Emporium) 2005
   : |
   : | Checking config.txt for MOA bogie open box wagon 1 kuid '
   : |  instance id is '3'
   : |
   : | Checking NumberIt entries in config.txt...
   : | NumberIt_prefix     500  ()   OK.
   : | NumberIt_min        301  ()   OK.
   : | NumberIt_max        350  ()   OK.
   : |
   : | No errors found.  Config is OK.  :-)
   : -----------------------------------------------------------------------------------------------

Code examples

The source code for the NIExample script (NIExample.gs) may be downloaded here
An example config.txt file may be downloaded here

Feedback

If you have comments, suggestions, or questions regarding NumberIt please feel free to contact ElDavo via e-mail at sales@eldavos.co.uk
Copyright Dave Renshaw (Eldavo's Railway Emporium) 2005

www.000webhost.com