KIND TrainzBaseSpec

Latest revision as of 23:43, 1 February 2024

[edit] KIND Hierarchy

KIND TrainzBaseSpec provides the basis for all Trainz asset types. It provides for a number of "Standard Tags" which are common to (or at least, can legally be defined) for any and all Trainz assets. Some of these are mandatory, most are optional and a defining line using the tag may be omitted in most sub-assets.

[edit] Parent Classes

• None. TrainzBaseSpec is a root class from which other Trainz Asset classes are derived.

[edit] Child Classes

Obsolete kinds include KIND Bridge, unusable at Trainz v?.? and above

[edit] Supported Tags

The KIND TrainzBaseSpec config.txt file supports the following tags. Each tag is show here with its default value:

kind ""
kuid <NULL>
trainz-build ?
script ""
class ""
script-include-table
{
}
username ""
username-XX ""
description ""
description-XX ""
kuid-table
{
}
obsolete-table
{
}
string-table
{
}
string-table-XX
{
}
category-region ""
category-class ""
category-era ""
category-keyword ""
custom-category-list ""
must-have-product-rights ""
must-not-have-product-rights ""
privileges
{
}
thumbnails
{
}
extensions
{
}
license ""
author ""
organisation ""
contact-email ""
contact-website ""
member-of-groups
{
}

[edit] kind

type: string.

desc: The asset type which this config.txt file represents. See the list: here (above)

[edit] kuid

type: KUID

desc: The unique asset ID referencing this asset.

[edit] trainz-build

type: floating point number (must exactly match a released Trainz version number.)

desc: The file format version to which this asset is built. This number should generally be set to the trainz version number of the Trainz installation on which the asset is being created and tested. Some asset kinds are parsed significantly differently depending on their trainz-build version tag. NOTE: The trainz-build tag is compulsory. If not specified or if left blank, Trainz will make a primitive attempt to guess at a legacy Trainz version based on the contents of the config.txt file.

[edit] script

type: string.

desc: Indicates the filepath of the primary script file for this asset, if any. This filepath should always end in a ".gs" extension - the runtime will attempt to add or substitute a ".gs" extension if the filepath has an alternative extension.

[edit] class

type: string.

desc: Indicates the script class name to load as the primary class for this asset, if any. This class is loaded from the primary script file for this asset.

[edit] script-include-table

type: The "script-include-table" container.

desc: A key-value table of scripted assets which are searched for script includes when compiling this asset's script file(s). The key is currently unused but must be unique; the value indicates the KUID of the asset to include.

[edit] username

type: UTF-8 string, "Username" tag.

desc: The English human-visible name for this asset. This field should never contain non-English text, except where the asset name is a Proper Noun (eg. a place name) with no English localized variant.

[edit] username-XX

type: UTF-8 string, "Username" tag.

desc: (Where XX is replaced with the appropriate localization code for the language being represented.) The localized human-visible name for this asset. This field is similar to the username field except representing a non-English locale. Multiple username-XX tags may be present in an asset, once for each supported locale. If the appropriate 'username-XX' tag is not present to represent this asset on a given end-user system, the English username tag is used instead.

[edit] description

type: UTF-8 multi-line string, "Description" tag.

desc: The English human-visible descriptive summary for this asset. This field should be kept to a short (1-2 paragraph) blurb describing the asset. Extended details should be provided via an info-url page. This field must be comprised of English descriptive text, although the text may reference non-English Proper Nouns as explained above.

[edit] description-XX

type: UTF-8 multi-line string, "Description" tag.

desc: (Where XX is replaced with the appropriate localization code for the language being represented.) The localized human-visible descriptive summary for this asset. This field is similar to the description field except representing a non-English locale. Multiple description-XX tags may be present in an asset, once for each supported locale. If the appropriate 'description-XX' tag is not present to represent this asset on a given end-user system, the English description tag is used instead.

[edit] string-table

type: UTF-8 string list container, the "String-table" container.

desc: A key-value list of English strings. Each key is a meaningful script identifier. Each value is an English string. As described above, an English string may comprise of or reference a non-English Proper Noun.

[edit] string-table-XX

type: UTF-8 string list container, the "String-table" container.

desc: (Where XX is replaced with the appropriate localization code for the language being represented.) This field is similar to the string-table field except representing a non-English locale. Multiple string-table-XX tags may be present in an asset, once for each supported locale. Each should contain a list of strings with the same Keys as in the string-table list, but with different Values. If the appropriate 'string-table-XX' tag is not present to represent this asset on a given end-user system, or the appropriate string is missing from the that list, the English string-table container is referenced instead.

[edit] kuid-table

type: KUID list container, the "Kuid-table" container.

desc: A key-value list of assets upon which this asset is dependent. The keys may be any unique value (typically, sequential integers if the keys are meaningless, or script identifiers if the asset is to be referenced from script.) Entries in this table serve two purposes - firstly, to ensure that the game systems are aware of the dependency such that installing and loading this asset will successfully install and load any dependencies, and secondly to allow scripts to locate relevant child assets. Only first-level dependencies are included. Circular dependencies are legal. An asset cannot be listed as a dependency if it is also marked as an obsolete version of this asset. An asset cannot be listed as its own dependency.

[edit] obsolete-table

type: KUID list container, the "Kuid-table" container.

desc: A key-value list of assets which are made obsolete by this asset. Any attempt to load an asset referenced in this list will result in this asset being loaded instead. The assets referenced in this list must have the same creator as this asset. It is illegal for two assets to both mark a third asset obsolete, unless one of the two also marks the other as obsolete. Circular obsolete references are illegal. All lower-numbered KUID2 versions of this asset are implied as obsolete and need not be included in this list. It is illegal to mark a higher-numbered KUID2 version of this asset as obsolete as that creates an implicit circular reference.

[edit] category-region

type: string.

desc: A list of two-character Category Region codes, separated by semi-colons (';'). No other characters (including whitespace, etc.) should be present in the string. This asset is considered relevant to each of the specified regions - this is most relevant for KIND Traincar and KIND MOSignal assets, but may be supplied for any asset.

[edit] category-class

type: string.

desc: A single 2-3 character Category Class code which describes this content item. The category-class tag is used to provide additional human sub-categorization beyond what is implicit from the Asset Kind. Note that many category-class codes are only relevant to specific Asset Kinds - category-class codes must not be applied to assets of an inappropriate Kind.

[edit] category-era

type: string.

desc: A list of five-character era codes, separated by semi-colons (';'). Each era code token must be an exact match for one of the specified legal era codes. No other characters (including whitespace, etc.) should be present in the string. This asset is considered relevant to the specified era range.

[edit] category-keyword

type: UTF-8 string.

desc: A list of natural-language keywords, separated by semi-colons (';'). No other characters (including whitespace or irrelevant punctuation) should be present in the string. These keywords form the basis for asset keyword searching. The asset's name need not be repeated in the category-keyword list. Various default search keywords are supplied automatically based on the asset type.

comments: The asset creator should consider how a Trainz user might search for an assets. For example, a user looking for a narrow gauge steam locomotive used on a South African railway. This is an example from one of EDH6's locos:

category-keywords "steam;SAS;2ft;NG24;24in;Narrow;Gauge;Beira;Railways;South;African;suid;afrikaanse;spoorwee"

Alternatively a Viennese tram:

category-keywords: "electric;tram;tramcar;trolley;trolleycar;streetcar;vienna;viennese"

Adding non-english equivalents can be useful.

[edit] custom-category-list

see also related details in: Category List, and custom category identifier

type: ascii string.

desc: A list of custom category identifiers, separated by semi-colons (';'). Each custom category identifier should be a short (eg. 3-6 character) alphanumeric token. No other characters (including whitespace) should be present in the string. These custom categories are used to enable scripts to rapidly locate certain classes of asset. It is strongly recommended that new custom category identifiers are introduced sparingly. The custom-category-list tag value may have no more than 64 characters total. This tag should be left blank unless there is an existing specific script requirement that can only be fulfilled via the custom-category-list approach.

[edit] must-have-product-rights

type: ascii string.

desc: A list of required product rights, separated by semi-colons (';'). If the local installation does not have the required product rights then the asset may not be loaded by certain game systems.

[edit] must-not-have-product-rights

type: ascii string.

desc: A list of conflicting product rights, separated by semi-colons (';'). If the local installation has one of the listed product rights then the asset may not be loaded by certain game systems.

[edit] privileges

type: The "privileges" container.

desc: A set of privileges set by the asset creator to control how this asset can be used.

[edit] thumbnails

type: The "Thumbnails" container.

desc: The thumbnail(s) which are used to represent this asset in 2D preview boxes, lists, and icon form throughout the game environment (including in-game, in Content Manager, and on the Download Station.)

[edit] extensions

type: The "Extensions" container.

desc: A set of extended attributes which provide additional information to scripts beyond the Config.txt file specifications defined for this asset type. Care should be taken to abide by the extensions naming guidelines when creating a new extension, and to abide by the extension-creator's guidelines when providing data for an existing extension. Auran reserves the right to add validation for specific entries in the "Extensions" container at a later date, based on the extension-creator's guidelines.

[edit] license

type: UTF-8 multi-line string.

desc: A license describing how the asset creator would like this asset to be used. The meaning of the license tag is ambiguous and its usage is not recommended. Content uploaded to the Download Station or provided for inclusion into the game may be under a specific redistribution contract or license agreement which supersedes any text in this field. The license field does not provide for localization support. The text of the license field is not validated or enforced by Auran and may or may not be legally binding to end users.

[edit] author

type: UTF-8 string.

desc: The author's name or mark. The use of this field is not recommended as attribution can be determined programmatically.

[edit] organisation

type: UTF-8 string.

desc: The name or mark of the organization responsible for the creation of this asset. The use of this field is not recommended as attribution can be determined programmatically.

[edit] contact-email

type: email address string.

desc: The contact email address for the creator of this asset. The use of this field is not recommended as attribution can be determined programmatically and contact details can be registered against the creator's Planet Auran account where they can be limited or updated as necessary.

[edit] contact-website

type: URL string.

desc: The contact website for the creator of this asset. The use of this field is not recommended as attribution can be determined programmatically and contact details can be registered against the creator's Planet Auran account where they can be limited or updated as necessary.

[edit] info-url

type: URL string.

desc: A link to an online description of this asset. The URL must resolve to a site within the Trainz Online Security Zone. The use of custom Trainz Short URL formats is recommended to future-proof the URL against possible future site layout changes. Where this tag is present, in-game buttons are provided to allow the user to view the asset description without leaving the game environment. It is recommended that generic group pages are used for entire classes of asset in any case where the assets provide similar functionality but minor differences in appearance. This reduces the time-expense of creating, maintaining and localizing such documentation.

[edit] member-of-groups

type: "Member-of-groups" container.

desc: A list of KIND Asset-group assets to which this asset belongs. See the KIND Asset-group documentation for details on how and when this is used.

[edit] Downloads

Attach sample files here

[edit] Categories