Jump to content

Trainz/KUIDs

From Wikibooks, open books for an open world
logo
Fundamentals for Trainz Trainees

Trainz Asset Maintenance and Creation
TOC | BeginningsFun | AM&C | Creation | InBook Refs ORP Refs:  • Index • Containers • Kinds • Tags | Appendixes  • Vers
 Glossary
 HKeys-CM
 HKeys-DVR
 HKeys-SUR
 HKeys-WIN
 Mouse use
 Notations
editor screenshot
Using Programmer's Notepad's multiple-TAB panes in Windows to juggle data Managing Trainz assets.
 • Big blocks of comma-separated kuids are extremely useful in setting up SPEED for customized route building–the less assets Surveyor need consult speeds up all the Hotkeys and the building or decorating processes.
 • Such lists also have their place between versions in Content Manager as well as in this example--a list like the top part of the page (showing missing assets could be transformed into a CSL block like the page bottom list, suitable for use in a search in another install of Trainz (To see if all the dependencies or desired assets are available before entering a GUI to drive or route build, for example).
Points to ponder

An assortment of asset names and KUIDs as
Copy All might give you in Content Manager:
Highland Valley SD38 No23, <kuid:62941:123>
Sub Station, <kuid:58973:27012>
GW Malt Sec5, <kuid2:97212:5200:1>
ken, <kuid:119692:840>
mack-truck, <kuid2:50567:15770:1>
fred2, <kuid:50567:15717>
Erie covered hopper Mfx2, <kuid:58422:1067>
Tanker MBLX (FUEL), <kuid2:64038:151024:1>
Tanker UTLX 950423(LARS), <kuid2:113556:61005:1>
Tanker ExxonMobil (FUEL), <kuid2:64038:151023:1>

FYI, a Fred is the Red Light emitting instrument package now used on the end of consist where there used to be the caboose. Modern ones contain RFID circuitry and GPS and communicate data—these days, even backup camera views— to receiving instruments in the CAB to let the engineer know precisely where his tail is on the route.

A KUID is a unique identifier that is assigned to an asset when it is created. The TRS2006 manual refers to them as a mnemonic derived of Kool Things Unique Identifier Data, and Trainz relies on them to keep things straight and put together the right combinations of sub-assets to present the 3D virtual world. The central part of a KUID is an author's Trainz ID code number, which will be common to every asset he creates. This is the first part of the kuid after the first seperator—the colon ':' characters. No asset is an asset without a kuid code. Trainz will read a config with no kuid at all and immediately report one of several errors, the most common being—"Warning: Unable to read config file for asset at '<foldername>'" not "Asset does not have a valid kuid".

This KUID feature was introduced with the original Trainz 0.9 Beta prototype to organize asset component files into separate folders and in order to facilitate cataloging of assets as the earliest version of what became the Download Station (Online free library) of assets was in need of a built-in data structure to track differences between several similar assets, and also a reliable means of using the correct specified asset—for all too many names could overwrite one another if only asset-names were used as folder names in the primitive organization of Hard Disk data of that era. The solution was to not rely on names which might overlap, but organize file folders in the early Trainz (and even now) by folders coded with kuid derived names (replacing the colon (':') characters with spaces. See the folders in your ..\UserData\local\hashfolders directories.

Identification

[edit | edit source]
Kuid (base kuid) format
<kuid  : Author ID# : Base Kuid index >    
Kuid2 format
<kuid2 : Author ID# : Base Kuid index : Version Suffix>

There was also a need for some method users could use to identify between versions of assets— tell the trials that worked from the one's that didn't. There had been the obsolete-table envisioned in the early development, but in practice, these have certain shortcomings as their use 'breaks' the asset identifier code for all time thereafter. This need spawned the expanded kuid, meaning the Kuid2 format as the issue became important to trace specific asset revisions necessarily resulting during the following the flurry of service packs of Trainz 1.0. One might say, Trainz was teething and having growing pains, but growing rapidly and maturing. By UTC, which as noted elsewhere may as well be counted as a fourth service pack to Trainz 1.0, both methods were in place, the software was trained up to recognize both kuid2 and kuid formats, as well as obsolete-table legacy versions.

Further there was a desire to identify their originating author, and thus who owned their copyrights under international law, so that Auran could safeguard their ownership. There are two versions: KUID and KUID2. Pre-TRS2006 versions of Trainz require assets to be created manually and therefore KUIDs must be assigned manually. In TRS2006 and later CMP automatically assigns a KUID when you click 'new asset' or 'clone asset'.

A KUID in the original format is as follows
<KUID:123456:123456>.
  1. The first numeric element of the KUID is the User ID of the author. A user's User ID can be accessed through their Planet Auran profile. A user is assigned a User ID when he or she registers with Planet Auran, and the User IDs are assigned in RANDOM numerical order. Most of them have either 5 or 6 digits, five predominating. But some early ones can have 4 digits or less. Several exist with single digit author codes.
  2. The second numeric element of the KUID is a unique number set by the author and can be any number of digits, NORMALLY six or so, and often coded so the first couple of digits indicate a class or type of created digital asset (e.g. 10 meaning traincar [rolling stock] and so prefix of 101 as flatcar, 102 as 40' boxcar, 103 as refer, etcetera and so forth. Some CCs extend the type-branding to parts such as bogeys, or may have a group for such parts types.
  3. If creating or cloning an asset with CM/CMP, CMP assigns incremental numbers for each user install in the 1xxx range (start) by default. For example, the first piece of content you create will be likely be a change to a built-in standard route or session, so if your user identifier is '123456' the kuid would likely be created <KUID:123456:1001> and so-on.
  4. TrainzUtil can be used to alter the next generated kuid start value, and CM will then generate the next empty number above that value when making an allocation for the new asset kuid code.Tip: In the given case, since routes always have a default session, a route modification would generate two successive kuids ending 1001 and 1002.

With KUIDs, if an author had uploaded an asset to the DLS with <KUID:123456:100001> and they wished to update it, they would need to assign a new KUID to the updated asset i.e. <KUID:123456:100002>. To replace asset number 100001 on the DLS, the obsolete asset's KUID must be recorded in the obsolete-table section of the config file of the new asset. (discussed elsewhere). This can get confusing so the KUID2 was devised a solution to this problem.

KUID2

[edit | edit source]
A KUID2 has a slightly different format to the KUID
<KUID2:123456:123456:1>, where the extra field is a version indexed to a zero base.

As before, the first two numeric elements are the author's User ID and unique identifier for the asset. The third number is the asset's version number which can go as high as '127'. The Kuid2 is actually zero based, so <KUID2:123456:123456:0> is the same as <KUID:123456:123456>—though N3V'S programmers' are inconsistent as to when the equivalency is acknowledged and so effective.[note 1]

An asset can now be updated simply by incrementing the version number. The clever thing about KUID2s is that they can also apply to assets with KUIDs. For example if we take our asset <KUID:123456:100001> and want to update to a KUID2, it is simply a matter of altering the KUID tag of the updated asset to read <KUID2:123456:100001:1> and the DLS will automatically flag the original asset as out of date ('Obsolete' in the terminology of the CM search pane; CM communicates with the DLS and tracks whether an updated asset is available).[note 2] Locally, each user's CM/CMP install will detect such updates and so notifies all users who have the obsolete KUID version of the asset there is an updated version available. Since TS2009 CM displays this visually as well, using a symbol to update it to the KUID2 version.  

 

* Setting the 'freeintcam' switch parameter in trainzoptions.txt (TR04—TS12) or checking the clickbox with the same function (Freeing Internal Cameras) in TANE and after, changes the function of the keyboard arrows from rotate and tilt functions, to instead slide the camera position forward and back, or side to side. Freeintcam mode enables the user to move many cameras entirely outside the CAB or to a much better advantaged viewing (and mouse-controlling) angle.

Notes, Footnotes & References

[edit source]

Config.txt files are endemic and ever present in Trainz assets, for no asset can be defined without this type of Computer Science container. The keyword-value_of_key pairing must always be kept in mind in editing or creating Trainz content. The TrainzBaseSpec contains values and containers which are most common in asset defining config.txt files.  

Notes

  1. Some N3V Trainz releases will display <KUID2:123456:123456:0> and <KUID:123456:123456> the same, when given on a CM Kuid input window, while others treat them differently, and ignore a basic KUID form in the data base if the Kuid2 format is used in a search.
     • As has been deliberately tested, using the Kuid2 form as an identifier value in the config file, is perfectly acceptable (in new and old modified assets) and filed correctly by all versions and releases of the N3V software.
     • Hence many use only kuid2 formats when creating assets and if keeping manually maintained off-Trainz database (OS-file folders with source files) archives use the format "kuid2 xxxx yyyy n;v#-#; assetname", as it makes creating archive folders that are searchable based on kuids simpler when all are coded as kuid2 syntax. (Alpha-numeric sorting then works glitch free.)
     • Such archives also allow for searching to locate a texture when needed for a repair or new asset; and is a resource for initializing a new Trainz release or rebuilding an older install.
  2. N3V's CM versions will reject any attempt to open a file to edit, then upgrade it with a kuid change simply by recommitting it. However, two methods can be used to have the same effect.
     • 1) Change the config file's kuid, then drag and drop the folder into CM, since the older kuid is 'earmarked' as 'Opened for Edit', the software just treats the folder and data as an imported asset. The original kuid can then be re-edited back and committed independently, or assuming it was not faulty, one can just type CTRL+R and revert to the original pre-change version. If reverting one open for edit, recommitting it, before moving or deleting it's folder seems not to be necessary, but may be more safe than doing so.
     • 2) Copying the folder to another directory then changing the kuid there, whilst testing the improvement by committing the updated form under the original kuid. This has the benefit of giving the committal a full test, before adding an updated kuid version.

 

Footnotes

 

References