KUID

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(New page: ''Taken from CCGTC.'' A KUID is a unique number allocated to all content created for Trainz and can be thought of as a bar code. '''KUID2 Format''' The KUID format in TS2009 follows t...)
 
(→‎Important Notes)
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
''Taken from CCGTC.''
+
{{FUN-beg}}{{TOCright}}
 +
==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.
  
−
A KUID is a unique number allocated to all content created for Trainz and can be thought of as a bar code.
+
==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.
  
  
−
'''KUID2 Format'''
+
==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>
  
−
The KUID format in TS2009 follows the standard adopted in TRS2004, and takes the form of three Identification Numbers (ID) each separated by a colon.
+
This example KUID can be parsed as into following values:
 +
:''KUID'' - The encoding format of this KUID.
 +
:''171456'' - The [[KUID#User ID Number|User ID]] of this KUID.
 +
:''38001'' - The [[KUID#Content ID Number|Content ID]] of this KUID.
  
−
The breakdown of the KUID system is as follows: <KUID2:User_ID:Content_ID:Version_ID>
 
  
−
An example of a Kuid number with actual figures:
+
==KUID2 Encoding==
 +
The second encoding format is "KUID2". The overall format string follows this field breakdown: '''<KUID2:'''User ID''':'''Content ID''':'''Version Number'''>'''
  
−
<KUID2:171456:38001:1>
+
An example of a KUID using this encoding is as follows: <KUID2:171456:38001:1>
  
−
'''User ID Number'''
+
This example KUID can be parsed as into following values:
 +
:''KUID2'' - The encoding format of this KUID.
 +
:''171456'' - The [[KUID#User ID Number|User ID]] of this KUID.
 +
:''38001'' - The [[KUID#Content ID Number|Content ID]] of this KUID.
 +
:''1'' - The [[KUID#KUID Version Number|KUID Version Number]] of this KUID.
  
−
The number 171456 after the KUID2 is the USER_ID of the content creator.
 
  
−
When you registered Trainz with the Planet Auran website, you would have been issued with your USER_ID. This is the number you should have entered into Trainz as your USER_ID.
+
==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.
  
−
Planet Auran may be found by clicking with the left mouse button on the Profile button in the top task bar of the Forum page, or visiting the website:
+
Examples of invalid encodings are as follows:
−
https://www.auran.com/planetauran/login_f.php
+
{| border="1" cellspacing="0" cellpadding="2"
 +
|'''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>||[[KUID#Content ID Number|Content ID]] field does not support negative numbers.
 +
|-
 +
|123:456||Missing surrounding braces and encoding format field.
 +
|-
 +
|<123:456>||Missing encoding format field.
 +
|}
  
−
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.
 
  
 +
==User ID Number==
  
−
'''Content ID Number'''
+
:<KUID2:'''171456''':38001:1>
  
−
The middle number is the CONTENT_ID.
+
The first number, ''171456'' in the above example, is the ''User ID'' of the content creator.
  
−
This is a number that the content creator assigns to each creation to uniquely identify it, in previous Trainz builds. In TS2009, the Content Creator Plus module will automatically assign a CONTENT_ID when you create a new asset. It will not repeat a number, and keeps track of all content list or spreadsheet of CONTENT_ID numbers for your model assets.
+
When you register Trainz with the [https://www.auran.com/planetauran/login_f.php 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.
  
−
A CONTENT_ID number is also assigned automatically when you save a layout (map).
+
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.
  
−
The combination of a creator's USER_ID and the CONTENT_ID is unique, and will not conflict with assets created by others.
+
==Content ID Number==
  
 +
:<KUID2:171456:'''38001''':1>
  
−
''Note:''
+
The middle number, ''38001'' in the above example, is the ''Content ID''.
−
''Previous versions of Trainz used Content ID Ranges for KUID creation. The automatic assignment of CONTENT_ID numbers in TS2009 has obsoleted the need for, or the usefulness of, a specific range of numbers for different kinds of assets.''
+
  
 +
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).
  
−
'''Version ID Number'''
+
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).
  
−
The third number is the asset Version_ID number. The default for all assets is 0 e.g. <KUID2:xxx:yyyyy:0>
+
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.
  
−
Should this asset require revisions after release to the Trainz Download Station, the Version ID for each subsequent revision may be updated as follows:
+
==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>
 
  First revision          <KUID2:xxx:yyyyy:1>
Line 52: Line 85:
 
  Third revision          <KUID2:xxx:yyyyy:3> Etc.
 
  Third revision          <KUID2:xxx:yyyyy:3> Etc.
  
−
The maximum version number is 127. After the maximum version number is used (rare) a new Content ID needs to be allocated for this asset, and the previous one needs to be added to the obsolete-table.
+
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, in CMP right click on the asset and select "Create New Version". The version number will be incremented in the new model. Trainz will use the highest version number found for the asset. Obsoleting a KUID2 asset of the same content ID number does not require the use of the obsolete table.
+
−
 
+
−
Obsoleting is a process of replacing a previous item with a more recent one, for updating, improving, or replacing a faulty model.
+
−
 
+
−
 
+
−
 
+
−
Example 1:
+
−
A model <KUID2:171456:38001:3> is to be replaced by a newer version. The new number <KUID2:171456:38001:4> is used in the new config.txt file. The previous model will be replaced (obsoleted).
+
  
−
Example 2:
+
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.
−
A model <KUID:171456:27001> (UTC version) is to be replaced, using the new KUID2 format, and with a new number, <KUID2:171456:27002:1>. Note the new content ID number is different from the original asset.
+
  
−
In this case, the obsolete table container is used to show the old model KUID to be obsoleted. In this way, the new KUID is linked to that of the older asset.
 
  
  
−
'''''Important Notes:'''''
+
=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.''
+
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> .''
+
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 UTC 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.''
+
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.''
+
4. 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.
  
−
''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.
  
−
''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.''
+
{{FUN-bot}}
 +
[[Category:Trainz Wiki]]
 +
[[category:Trainz reference pages]]

Latest revision as of 16:53, 30 July 2024

Contents

[edit] 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.

[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.

[edit] 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.

[edit] 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.


[edit] 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. 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.

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