TrainzUtil

From TrainzOnline
Revision as of 05:33, 25 December 2020 by Deneban (Talk | contribs)

Jump to: navigation, search

TrainzUtil is a command line Content Management tool.

Contents

Functionality

TrainzUtil is an extremely capable and versatile command console tool, capable of performing all content management queries and asset manipulations. Indeed it forms the basis for Content Manager. It is at its most powerful when called from batch files or external programs. Although primarily routed in working with the local asset database, several functions, such as "installfromdls", "downloadlistings", and "searchbycategory" also give access to Download Station queries and actions as well.

Typically a Trainz user will use the Content Manager GUI to perform their content management operations and may never have direct use of TrainzUtil.

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
    • "Give latest Asset Versions" of specified KUIDs (Content Manager only lists all versions)
    • "List all Author IDs"
    • "Import Consists"
    • "Set User's next KUID"
    • "Script Compilation & Encryption"
    • "Chump" files conversions
    • "Package Handling"
    • "Asset Precaching"

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

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.

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.

Command Line Arguments

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

   trainzutil delete "<kuid:87854:982511580>"
  • TrainzUtil help
Display TrainzUtil help text. (...start here to see all current command line entries available)
  • TrainzUtil version
Display the TrainzUtil build version.
  • 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.
  • TrainzUtil revert <KUID>
Discard any edits that have been made to the specified asset.
  • TrainzUtil delete <KUID>
Delete the specified asset from disk.
  • 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".
  • Arguments: (case insensitive):
  • <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.
  • 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.
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.)
  • Aa - The asset is archived.
  • Bb - The asset is builtin or packaged content.
  • Cc - The asset is in the base content set.
  • Dd - The asset is on the download station.
  • Ee - The asset is open for edit.
  • Ff - The asset is faulty.
  • Ii - The asset is installed locally.
  • Ll - The asset is locally modified.
  • Mm - The asset has missing dependencies.
  • Oo - The asset is obsolete.
  • Pp - The asset is listed in the DLS index as payware DLC.
  • Uu - The asset has an update available.
  • Xx - The asset is authorised for use in this Trainz installation.
The actual order the categories appear in the output is: EIABDPLMFOUXC (shown in all caps for illustration purposes)
  • 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.

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.

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

Return to Content Creation

Content Creation

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