KUID

KUID identifiers

A 'KUID is an identifier uniquely allocated to each item of content created for Trainz, similar to a bar code. Typically, these identifiers are created and used internally by Trainz, so understanding the exact format is not necessary for most users - copy and paste is about all that is required. Full details are provided here for interested parties.

KUID Format

KUIDs are strings comprised of several value fields, separated by colons (':') and surrounded by angle braces. The first field denotes the encoding format used. There are two encoding formats in common use at the current time, however this may be extended in the future. In a given encoding, each value field has a specific meaning and cannot accept arbitrary text. Fields cannot be arbitrarily added or removed.

KUID Encoding

The first encoding format is simply "KUID". The overall format string follows this field breakdown: <KUID:User ID:Content ID>

An example of a KUID using this encoding is as follows: <KUID:171456:38001>

This example KUID can be parsed as into following values:

KUID - The encoding format of this KUID.

171456 - The User ID of this KUID.

38001 - The Content ID of this KUID.

KUID2 Encoding

The second encoding format is "KUID2". The overall format string follows this field breakdown: <KUID2:User ID:Content ID:Version Number>

An example of a KUID using this encoding is as follows: <KUID2:171456:38001:1>

This example KUID can be parsed as into following values:

KUID2 - The encoding format of this KUID.

171456 - The User ID of this KUID.

38001 - The Content ID of this KUID.

1 - The KUID Version Number of this KUID.

Invalid Encodings

Any KUID encoding which does not match this specification is considered invalid. In the strictest sense, any invalid encoding is not a KUID. For legacy compatibility reasons, some components of the Trainz environment will attempt to parse a incorrectly encoded KUID however this is considered unreliable any may be removed in the future.

Examples of invalid encodings are as follows:

Example Invalid Encoding	Explanation
KUID:123:456	Missing surrounding braces.
<KUID2:123:456>	KUID2 encoding requires a version field.
<KUID:123:456:1>	KUID encoding does not support a version field.
<KUID:123:-4>	Content ID field does not support negative numbers.
123:456	Missing surrounding braces and encoding format field.
<123:456>	Missing encoding format field.

User ID Number

<KUID2:171456:38001:1>

The first number, 171456 in the above example, is the User ID of the content creator.

When you register Trainz with the Planet Auran website, you are issued with your own User ID. After you enter your Planet Auran account details in the Content Manager settings, you will see this same User ID displayed. At no time should a content creator use a User ID other than the appropriate number assigned to them by Planet Auran.

Every member of the Trainz community who is a member of Planet Auran has a User ID. Now, you may be wondering why you need a User ID if you don't intend to make any content for Trainz. If you intend to make a layout (route or map) at some point in time and you'd like to share that layout with your friends or other community members, then you are in fact a content creator. Even Auran/N3V Games has a user ID, though the exact content creator may be an internal secret. These in many versions, especially in older content will show up with a negative User ID in the Kuid.

Content ID Number

<KUID2:171456:38001:1>

The middle number, 38001 in the above example, is the Content ID.

This is a number that the content creator assigns to each creation to uniquely identify it. The combination of a creator's User ID and the Content ID form a unique asset identifier, to prevent conflict with assets created by others. The number must be a positive integer in the range (1 <= id <= 2147483648).

When creating a new asset using Content Manager, an appropriate Content ID is generated automatically. Content Manager keeps track of all locally installed content and all content on the Download Station to ensure that no duplicate numbers are generated. A Content ID is also assigned automatically when you save a layout (map).

This number has no special meaning beyond helping to form a unique identifier for the asset. Historically, some users have attempted to organize content into different types by sorting on the Content ID. This is not recommended and Auran does not provide support for this workflow.

KUID Version Number

<KUID2:171456:38001:1>

The third number, 1 in the example above, is the KUID Version Number.

Should this asset require revisions after release to the Download Station, the KUID Version Number for each subsequent revision may be updated as follows:

First revision           <KUID2:xxx:yyyyy:1>
Second revision          <KUID2:xxx:yyyyy:2>
Third revision           <KUID2:xxx:yyyyy:3> Etc.

The maximum version number is 127. If the maximum version number should be reached, a new Content ID must be allocated for the asset, and the previous one needs to be added to the obsolete-table.

To make a new version asset, right click on the asset in Content Manager and select "Create New Version". The asset will be duplicated and the KUID Version Number will be updated in the new copy.

Important Notes

1. <KUID2:xxx:yyyyy:0> is exactly equal to <KUID:xxx:yyyyy> in the old KUID format. These will be read as duplicates should they be used simultaneously.

2. Similarly, <KUID2:xxx:yyyyy:1> acts as a KUID2 format obsoletion of <KUID:xxx:yyyyy>.

3. Using the zero, "0" as the first version is acceptable, however the display on the Download Station, and the installed file will be in the KUID format, without the KUID2 format display. It is recommended that you start the numbering at one, "1" if this is a problem to you.

4. The Download Station displays a History of obsoleted models. If an obsoleted model has never been placed on the Download Station, do not include it in your obsolete table, it will result in a History error notification when you try to upload the asset.

5. While you may use leading zeros in the KUID system, a version "02" will be the same as "002" or "2", and the zeros will be truncated. It is recommended not to use any leading zeros.

An asset placed in your map will display (show as) the latest installed version. When retrieving an asset from the Download Station, the newest version will be automatically provided, and the Download Station will display a History tag for the model versions.