Latest revision as of 21:32, 24 September 2023

TrainzUtil is a command line Content Management tool. Please note this page has not been updated for TRS22

[edit] Functionality

TrainzUtil is an extremely capable and versatile command console tool, able to perform all content management queries and asset manipulations.
	Indeed it forms the basis for Content Manager. Its most powerful usage is when it is called from batch files or external programs.
	Typically a Trainz user will use the Content Manager GUI to perform their content management operations and may never have direct use of TrainzUtil.
	Although primarily routed in working with the local asset database, several TrainzUtil arguments, such as "installfromdls", "downloadlistings", and "searchbycategory" also give access to Download Station queries and actions as well.
	TrainzUtil gives 3rd party developers the means to perform content management operations when their applications are running in parallel with the main Trainz executable.

Additional Capabilities over Content Manager

• Although the capabilities of TrainzUtil intersect with those of the Content Manager, there is significant additionally functionality only TrainzUtil can perform:
  • "Print config.txt" of an asset (later versions of Content Manager must open edit the asset to display this)
  • "Keyword" operations (removed in newer Content Managers)
  • "List Parsing" of specified KUIDs
  • Gives the latest Asset Version of specified KUIDs (i.e. Content Manager will only list all versions)
  • Lists all Author IDs
  • Imports Consists
  • Set User's next KUID
  • Script Compilation & Encryption
  • "Chump" files conversions
  • Package Handling
  • Asset Precaching
  • Searching Assets by Asset Category Designation
    
    

Batch Command Set

• In addition to accepting arguments, TrainzUtil also has commands specifically geared towards batch file use (See Batch File Arguments below).
  
  

Output

• Although a powerful tool, the Achilles heel of TrainzUtil has been the variation in the format of its output:
  • The same TrainzUtil command will yield a differently formatted output depending on the Trainz release. Apparently TrainzUtil is rewritten with each new Trainz release and the output formats are modified. In fact, TRS19 has had multiple versions released under the same product.
  • Although TANE and TRS19 can execute a TrainzUtil command from most of their GUI windows, the format of the output to the "Task Complete" window is a refined version of the output from the same command executed from a command prompt. This, even within the same Trainz build.
    
    

Backward Compatibility

• Newer TrainzUtil compilations tend to maintain their capabilities featured in legacy Content Managers that have since fallen out of common use. Examples of these are its archiving and keyword related commands.
  
  

[edit] Set Up

To use TrainzUtil in TANE and TRS19, the user must first select the "Enable advanced debug tools" option in the "Dev" tab of the Trainz Settings dialog box. Prior Trainz releases do not require this step as the utility is inaccessible from Trainz.

TrainzUtil presumes it has access to dynamic link libraries (.dll's) that accompany it. Therefore, it is not only important to maintain TrainzUtil with the main exexcutable it came with, it also has to be kept in the identical location it was provided relative to other Trainz program files. Failure to comply with this will result in error messages.

Finally, many TrainzUtil commands require the main Trainz executable program to be running in parallel. Otherwise, TrainzUtil will return a response stating the Trainz ".exe" is not running.

[edit] Known Issues

1. Some TRS19 compilations of TrainzUtil (SP2 and earlier) will erroneously report "TANE.exe is not running" when TRS19 is not running. This was corrected in April 2021 with the release of TRS19SP3 to report "Trainz" is not running.

2. TrainzUtil, when invoked from a console or third-party software, erroneously reports "- Trainz is not running. Please start Trainz and try again." when in fact Trainz is running. Rather, the issue is that "Advanced Debug Tools" is not enabled in the "devs" tab of the "Trainz Settings" window.

3. The "help" argument incorrectly states that the "version" argument yields the "TrainzUtil build version." In fact, there is no such thing, and in actuality this argument reports the Trainz executable build number.

[edit] Accessibility

    TS12 and Earlier Trainz Releases

TrainzUtil is only accessible via a Windows console and cannot be started from any Trainz window.

• To use TrainzUtil, open a command prompt with administrator privileges and navigate to the "bin" directory in the Trainz program folder (e.g. "c:\Program Files\Auran\TS2010\Bin or D:N3V Games\Trainz A New Era\bin\") using the "cd" command.
• You can then execute a TrainzUtil command with the arguments below.
  

    TANE and TRS19

TrainzUtil commands can be executed in two different ways:

• from any Trainz window, except the simulator window, using the "Developer" menu > "Run Trainzutil Command...".
• from a command prompt window with administrative privileges which is focused on the Trainz program folder.

Note that format of the output between these two sources differs significantly.

[edit] Versioning

Apparently TrainzUtil has no outwardly visible version numbers. To distinguish and sort versions chronologically, users can look and compare the application signing dates.

According to N3V Development, TrainzUtil is always recompiled as a pair with the main executable program, therefore there is no need for a separate versioning system. The "version" argument therefore outputs the Trainz build number.

[edit] Command Line Arguments

Please see the Notes section below for proper syntax of the "<KUID>" parameter

• TrainzUtil help

Display TrainzUtil help text. (...start here to see all current command line entries available)

• TrainzUtil version

Display the TrainzUtil build version. (the "help" argument is incorrect when it claims to outputs the TrainzUtil version number. TrainzUtil has no visible version numbers. See Versioning above.)

• TrainzUtil echo <TEXT>

Echo the supplied text.

• TrainzUtil time

Echoes the current time in RFC 822 format.

• TrainzUtil setlanguage <langCode>

Set the Trainz language to the language code supplied (eg. US, FR, RU, etc).

• TrainzUtil installCDP <PATH>

Install an asset from a CDP file.

• TrainzUtil installfrompath <PATH>

Install an asset from a directory.

• TrainzUtil installfromdls <KUID>

Install an asset from the Auran Download Station.

• TrainzUtil edit <KUID>

Open an asset for editing.

• TrainzUtil generateKUID

Generate a new KUID number in the local user's KUID range.

• TrainzUtil createCDP <OUTPUT PATH> <KUID1> <KUID2> ... <KUIDX>

Export assets to a CDP file.

• TrainzUtil repairdatabase

Repairs the Trainz Asset Database.

• TrainzUtil repairdatabase extended

Forces DLC packages to be reinstalled and fully repairs database corruption. Details here

• TrainzUtil printconfig <KUID>

Print the contents of an assets config file to the console.

• TrainzUtil backupkeywords

Backup all the keywords of your assets.

• TrainzUtil importkeywords

Import keywords into the Trainz Asset Database.

• TrainzUtil add-keyword <keyword> <KUID> [..]

Add a keyword to the specified assets.

• TrainzUtil remove-keyword <keyword> <KUID> [..]

Remove a keyword from the specified assets.

• TrainzUtil search-by-keyword <keyword>

Returns a list of all assets with the specified keyword.

• TrainzUtil commit <KUID>

Commit any edits that have been made to the specified asset.

Caution - Commits cannot be readily undone, like in Content Manager, unless you retrieve the unmodified asset from Download Station, or rummage through your "backups" folder. See the warning under the "revert" argument (as well as an exception to this for "builtin" assets).

• TrainzUtil revert <KUID>

Discard any edits that have been made to the specified asset.

Take care in understanding this argument properly: it is not the same as the frequently used Content Manager reversion command(s). As the definition says, it only "discards edits", it does not revert an asset that has been committed. If you need the ability to recover from an asset that commits faulty, an asset for which you have made modifications locally (beyond what is on the Download Station), you have to make separate provisions for recording the asset prior to committing a new modification to it. The exception to this is for "builtin" assets, which can be reverted to their original condition using the "delete" argument.

• TrainzUtil delete <KUID>

Delete the specified asset from disk.

Despite this description, coming from the TrainzUtil's "help" argument output, the "delete" argument in fact does not delete the foundation files for "builtin" or "base" assets from the user's disk. It will delete from disk, however, any variants made to these assets. When a "delete" argument is invoked on a "builtin" asset, if will reset that asset back to its "builtin" condition. This is particularly useful for legacy "builtin" assets for which once they are opened for edit, cannot be reverted back to their original state without become faulty, nor available on the Download Station (i.e. legacy "builtin" assets which are specially predispositioned to appear as non-faulty when they in fact could never pass modern validation). The TrainzUtil "delete" argument acts like the Content Manager's "revert to original" function, restoring a "builtin" asset back to its "out-of-the-box", faultless condition.

• TrainzUtil list <KUID> [..]

Parses the specified kuid list into the results.

• TrainzUtil list-latest-versions <KUID>

Get the latest known version of an asset. Multiple KUIDs may be specified as multiple arguments.

• TrainzUtil list-dependencies <KUID>

Get an assets direct dependencies.

• TrainzUtil list-dependants <KUID>

Get an assets direct dependants.

• TrainzUtil authors

List of all the authorIDs that have content in the game.

• TrainzUtil searchbycategory [-a] <CategoryList>
  

List all the local assets with a category set in this format, "CMP;MESH|BD;-ACTV|VE|SCEN". See Category List, Syntax for syntax instructions.

Asset Categories are not an asset classification system per se, but are determined by the main executable for purposes of setting its behavior in the simulation. Asset Categories are also output per asset using the TrainzUtil "status" command argument (see below).

Due to the nature of Asset Categories being based on simulation behavior rather than by noun identity, using this TrainzUtil argument as a means to classify assets is limited.

Unlike "Asset Status Flags" (seen under the "status" argument below), this TrainzUtil argument is not coupled with any preconceived understanding of all employed Asset Categories in Trainz; it always and only consults the accompanying main executable program as to how it categorizes an asset. To complicate matters further, Trainz has the flexibility of custom asset categories as well. Therefore, any search by Asset Category can only serve the purposes of finding assets that behave similarly in the simulation.

The listed results below using various argument <CategoryList> parameters were obtained from a specific TRS19 installation and database, to provide a general understanding of what the argument generates, your results may vary.

• Parameters: (case insensitive):
  • -a will extend the local asset search to include the Download Station as well.
• <CategoryList> is defined as follows as verified in TRS19 (case insensitive):
  • If all parameters are omitted, lists all local assets installed. Therefore the "-a" argument with no <CategoryList> lists all the assets in the Download Station. Be careful with this or else you'll get over half a million lines in return.
  • " -" (space+dash) will list all local assets except base UI-Texture assets.
  • -A without the argument "-a" has the same effect as the argument "-a" with no <CategoryList>, listing all half-million plus assets in the Download Station. In other words, don't ask for this.
  • -AC will list all local assets except Industries
  • -ACT will list all local assets except Industries
  • -ACTV will list all local assets except Industries
  • BD will list buildings and industries, regardless of their payware status.
  • CMP will list all local payware assets.
  • MESH will list all local meshes, regardless of their payware status.
  • VE appears to return a portion of installed train vehicles, but there appears to be an additional filtered applied that has not been yet identified.
  • SCEN will list local scenery (including buildings)

• TrainzUtil filterbystatus <status> <KUID>

List all assets from the specified list which match the specified status flags.

See list of <status> flag parameters in the "status" command below.

• TrainzUtil importconsists <PATH>

Import an old style Surveyor consist list, creating consist assets for any unknown entries.

• TrainzUtil setnextcontentid <int>

Provides a 'next content ID' hint for the KUID generator.

• TrainzUtil status <KUID>

Print the status of the specified asset. Note that the asset need not be locally installed, it only needs to be resident in the Download Station.

This will output + <KUID> : <Flags> : <category> : <username> where flags are a series of letters with case indicating Boolean state. (capital letters are flagged true and lowercase are flagged false.)

As Trainz evolves, the TrainzUtil command adds more status flags (all listed in caps for illustration purposes only). The order of the status flag output is shown below, and has varied at the service-pack level:

For TS12: EIADLMF

For TANE: EIABDPLMFOUXC

For TRS19 thru SP3: EIABDPLMFOUXCY

For TRS19 SP4: ABCDEFGILMOPUXY

• Aa - The asset is archived. Applies to TANE and higher
• Bb - The asset is builtin or packaged content. Applies to TANE and higher
• Cc - The asset is in the base content set. Applies to TANE and higher
• Dd - The asset is on the download station.
• Ee - The asset is open for edit.
• Ff - The asset is faulty.
• Gg - The asset is a builtin component of the game install (not just packaged). Implies flag "B". Applies to TRS19SP4 and higher only.
• Ii - The asset is installed locally.
• Ll - The asset is locally modified.
• Mm - The asset has missing dependencies.
• Oo - The asset is obsolete. Applies to TANE and higher
• Pp - The asset is listed in the DLS index as payware DLC. Applies to TANE and higher
• Uu - The asset has an update available. Applies to TANE and higher
• Xx - The asset is authorised for use in this Trainz installation. Applies to TANE and higher
• Yy - The asset is compatible with this Trainz installation. Applies to TRS19 only

• TrainzUtil validate <KUID>

Perform validation and display any errors or warnings relating to this asset.

• TrainzUtil compile <PATH>

Compile a script file.

• <-d> Display gamescript documentation.
• <-s> Silent mode.
• <-bPATH> Specify a file path for the compile log.
• <-pPATH> Specify the output directory.
• <-oPATH> Specify the output library filename.
• <PATH> Input source file.
• <-iPATH> Additional include path.

• TrainzUtil convert-config <PATH>

Converts a config.txt file to config.chump or vice versa.

• TrainzUtil open-in-driver [-wait] <KUID>

Open the specified route or session asset in Driver. Optionally wait until the module is exited.

• TrainzUtil open-in-surveyor [-wait] <KUID>

Open the specified route or session asset in Surveyor. Optionally wait until the module is exited.

• TrainzUtil open-in-preview [-wait] <KUID>

Open the specified route or session asset in the asset preview tool. Optionally wait until the module is exited.

• TrainzUtil encrypt <PATH>

Encrypt a script file (gs --> gse).

• TrainzUtil export-package <device-type> <package-name> <package-build-number> [<dependency-package-name> ...] <kuid>

Export assets to a device package. Multiple KUIDs may be specified as multiple arguments.

• TrainzUtil update-package <package-name>

Update prebuilt data within a package.

• TrainzUtil install-package <PATH>

Install a package from the specified path.

• TrainzUtil clean-package [-a] <package-name>

Remove the local build's prebuilt data from within a package. Use the -a parameter if you want to strip all prebuilt data.

• TrainzUtil uninstall-package <package-name>

Uninstall the specified package.

• TrainzUtil list-package-assets <package-name>

List the assets available in the specified package.

• TrainzUtil prebuild [--force] [--nofail] [--clear] [<KUID> ..]

Precache all installed content.

• TrainzUtil downloadcontentlistings

Fully download the latest content listings.

• TrainzUtil listbuilds <PATH>

Print the list of installed build numbers to a file.

• TrainzUtil quit

Requests the GUI to close.

• TrainzUtil async <command..>

Begins running the specified command asynchronously.

• TrainzUtil sync

Waits for all async commands to complete.

• TrainzUtil wait <seconds>

Pause for the specified number of seconds.

[edit] Batch File Arguments

• TrainzUtil @<file.txt>

Batch-execute a series of commands from the specified text file (every argument must be between double quotes). Every line of that text file will be processed like a separate call to TrainzUtil

• set <variable> <command..>

Used in a batch file, runs the specified command and overwrites the named variable with the result.

• append <variable> <command..>

Used in a batch file, runs the specified command and appends the result into the named variable.

• iferr <variable> <command..>

Used in a batch file, runs the specified command only if the named variable contains one or more errors.

• iferrflag <command..>

Used in a batch file, runs the specified command only if an error has occurred in the batch file execution up to this point.

• ifnone <variable> <command..>

Used in a batch file, runs the specified command only if the named variable contains no assets.

• ifhas <variable> <command..>

Used in a batch file, runs the specified command only if the named variable contains one or more assets.

• print <variable>

Used in a batch file, prints the content of the named variable.

• printerrors <variable>

Used in a batch file, prints any errors contained in the named variable.

• abort <TEXT>

Used in a batch files, aborts processing of the batch file immediately without raising any further errors. If arguments are present, they are logged as a single error string.

• $(<variable>)

Used as a command parameter in a batch file, replaced with the KUID(s) from the specified variable.

[edit] Notes

• Due to the Windows command prompt treating the '<' and '>' characters as pipe operators, be sure to include quotes around any KUID parameters. For example:

   trainzutil delete "<kuid:87854:982511580>"

• The console output of a TrainzUtil command is not the same as when it is executed from the Trainz program launch window

[edit] Return to Content Creation / Tools

Tools