KIND TrainzBaseSpec

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
m (thumbnails)
m (trainz-build)
(35 intermediate revisions by 7 users not shown)
Line 1: Line 1:
[[KIND TrainzBaseSpec]] provides the basis for all Trainz asset types. It provides for a number of "Standard Tags" which are common to all Trainz assets.
+
{{FUN-beg}}
 +
{{ORP-top}}
 +
==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.
  
=KIND Hierarchy=
+
===Parent Classes===
==Parent Classes==
+
* None. TrainzBaseSpec is a root class from which other Trainz Asset classes are derived.
* ''none.''
+
==Child Classes==
+
* [[KIND Environment]]
+
* [[KIND Scenariobehavior]]
+
* [[KIND Mesh]]
+
* [[KIND Activity]]
+
* [[KIND Consist]]
+
* [[KIND Drivercommand]]
+
* [[KIND Enginesound]]
+
* [[KIND Engine]]
+
* [[KIND Groundbrush]]
+
* [[KIND Hornsound]]
+
* [[KIND HTML-asset]]
+
* [[KIND Map]]
+
* [[KIND Module]]
+
* [[KIND Product-category]]
+
* [[KIND Profile]]
+
* [[KIND Texture]]
+
* [[KIND Texture-group]]
+
* [[KIND Tracksound]]
+
* [[KIND Splinebase]]
+
* [[KIND Library]]
+
  
 +
===Child Classes===
 +
{|
 +
|-valign="top"
 +
|
 +
*  [[KIND Achievement-category]]
 +
*  [[KIND Achievement-group]]
 +
*  [[KIND Activity]]
 +
*  [[KIND Asset-group]]
 +
*  [[KIND Behavior]]
 +
*  [[KIND Bogey]]
 +
*  [[KIND Buildable]]
 +
*  [[KIND Controlset]]
 +
*  [[KIND Consist]]
 +
*  [[KIND Drivercharacter]]
 +
*  [[KIND Drivercommand]]
 +
*  [[KIND Engine]]
 +
*  [[KIND Enginesound]]
 +
*  [[KIND Environment]]
 +
*  [[KIND Fixedtrack]]
 +
*  [[KIND Gameplaymenu]]
 +
|
 +
*  [[KIND Groundbrush]]
 +
*  [[KIND Groundtexture]]
 +
*  [[KIND Hornsound]]
 +
*  [[KIND HTML-asset]]
 +
*  [[KIND Industry]]
 +
*  [[KIND Interior]]
 +
*  [[KIND Library]]
 +
*  [[Class Library]]
 +
*  [[KIND Map]]
 +
*  [[KIND Mesh]]
 +
*  [[KIND Module]]
 +
*  [[KIND MOCrossing]]
 +
*  [[KIND MOJunction]]
 +
*  [[KIND MOSignal]]
 +
*  [[KIND MOSpeedboard]]
 +
*  [[KIND Pantograph]]
 +
|
 +
*  [[KIND Product]]
 +
*  [[KIND Product-category]]
 +
*  [[KIND Profile]]
 +
*  [[KIND Region]]
 +
*  [[KIND Scenariobehavior]]
 +
*  [[KIND Scenery]]
 +
*  [[KIND Scenery-trackside]]
 +
*  [[KIND SceneryWithTrack]]
 +
*  [[KIND Servlet]]
 +
*  [[KIND Steam-engine]]
 +
*  [[KIND Texture]]
 +
*  [[KIND Texture-group]]
 +
*  [[KIND Track]]
 +
*  [[KIND Tracksound]]
 +
*  [[KIND Traincar]]
 +
*  [[KIND Turntable]]
 +
*  [[KIND Water2]]
 +
|}<!-- Careful, wikitable ends --->
  
=Supported Tags=
+
 
The [[KIND TrainzBaseSpec]] [[config.txt file]] supports the following tags. Each tag is show here with its default value.
+
 
 +
==Supported Tags==
 +
The [[KIND TrainzBaseSpec]] [[config.txt file]] supports the following tags. Each tag is show here with its ''default value'':
  
 
  kind ""
 
  kind ""
  kuid &lt;NULL&gt;
+
  kuid <NULL>
 
  trainz-build ?
 
  trainz-build ?
 
  script ""
 
  script ""
Line 59: Line 98:
 
  category-keyword ""
 
  category-keyword ""
 
  custom-category-list ""
 
  custom-category-list ""
 +
must-have-product-rights ""
 +
must-not-have-product-rights ""
 
  privileges
 
  privileges
 
  {
 
  {
Line 73: Line 114:
 
  contact-email ""
 
  contact-email ""
 
  contact-website ""
 
  contact-website ""
 +
member-of-groups
 +
{
 +
}
  
 
  
====kind====
+
&nbsp;
 +
===kind===
 
:''type:'' string.
 
:''type:'' string.
:''desc:'' The asset type which this [[config.txt file]] represents.
+
:''desc:'' The asset type which this [[config.txt file]] represents. See the list: [[KIND_TrainzBaseSpec#Table_of_KIND_Child_Classes|here (above)]]
  
====kuid====
+
===kuid===
 
:''type:'' [[KUID]]
 
:''type:'' [[KUID]]
 
:''desc:'' The unique asset ID referencing this asset.
 
:''desc:'' The unique asset ID referencing this asset.
  
====trainz-build====
+
===[[trainz-build]]===
 
:''type:'' floating point number (must exactly match a released Trainz version number.)
 
:''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, Trainz will make a primitive attempt to guess at a legacy Trainz version based on the contents of the [[config.txt file]].
+
:''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]].
  
====script====
+
===script===
 
:''type:'' string.
 
:''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.
 
:''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.
  
====class====
+
===class===
 
:''type:'' string.
 
:''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.
 
:''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.
  
====script-include-table====
+
===script-include-table===
:''type:'' container, TBD.
+
:''type:'' The [["script-include-table" container]].
:''desc:'' A key-value table of scripted assets which are searched for script includes when compiling the primary script file. The key is currently unused; the value indicates the KUID of the asset to include.
+
:''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.
  
====username====
+
===username===
:''type:'' UTF-8 string.
+
:''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.  
+
:''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.
  
====username-XX====
+
===username-XX===
:''type:'' UTF-8 string.
+
:''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.
 
:''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.
  
====description====
+
===description===
:''type:'' UTF-8 multi-line string.
+
:''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.
 
:''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.
  
====description-XX====
+
===description-XX===
:''type:'' UTF-8 multi-line string.
+
:''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.
 
:''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.
  
====string-table====
+
===string-table===
:''type:'' UTF-8 string list container, TBD.  
+
:''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.
 
:''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.
  
====string-table-XX====
+
===string-table-XX===
:''type:'' UTF-8 string list container, TBD.  
+
:''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.  
+
:''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.
  
====kuid-table====
+
===kuid-table===
:''type:'' KUID list container, TBD.
+
:''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 meaningless, or script identifiers if the asset reference is 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. 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.
+
:''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.
  
====obsolete-table====
+
===obsolete-table===
:''type:'' KUID list container, TBD.
+
:''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 preceding KUID2 versions of this asset are implied as obsolete and need not be included in this list. It is illegal to mark a future KUID2 version of this asset as obsolete as that creates an implicit circular reference.
+
:''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.
  
====category-region====
+
===category-region===
 
:''type:'' string.
 
:''type:'' string.
:''desc:'' A list of two-character [[country code]]s, 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.
+
:''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.
  
====category-class====
+
===category-class===
 
:''type:'' string.
 
:''type:'' string.
:''desc:'' A single 2-3 character [[category 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 codes are only relevant to specific Asset Kinds - category codes must not be applied to assets of an inappropriate Kind.
+
:''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.
  
====category-era====
+
===category-era===
 
:''type:'' string.
 
:''type:'' string.
 
:''desc:'' A list of five-character [[era code]]s, separated by semi-colons (';'). Each era code token must be an exact match for one of the specified legal [[era code]]s. No other characters (including whitespace, etc.) should be present in the string. This asset is considered relevant to the specified era range.
 
:''desc:'' A list of five-character [[era code]]s, separated by semi-colons (';'). Each era code token must be an exact match for one of the specified legal [[era code]]s. No other characters (including whitespace, etc.) should be present in the string. This asset is considered relevant to the specified era range.
  
====category-keyword====
+
===category-keyword===
 
:''type:'' UTF-8 string.
 
:''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.
 
:''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.
  
====custom-category-list====
+
:''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.
 +
 
 +
===custom-category-list===
 
:''type:'' ascii string.
 
:''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.
 
:''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.
  
====privileges====
+
===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.
 +
 
 +
===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.
 +
 
 +
===privileges===
 
:''type:'' The [["privileges" container]].
 
:''type:'' The [["privileges" container]].
 
:''desc:'' A set of privileges set by the asset creator to control how this asset can be used.
 
:''desc:'' A set of privileges set by the asset creator to control how this asset can be used.
  
====thumbnails====
+
===thumbnails===
:''type:'' The [["Thumnails" container]].
+
:''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]].)
 
:''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]].)
  
====extensions====
+
===extensions===
:''type:'' The [["extensions" container]].
+
:''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.
+
:''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.
  
====license====
+
===license===
 
:''type:'' UTF-8 multi-line string.
 
:''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.
 
:''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.
  
====author====
+
===author===
 
:''type:'' UTF-8 string.
 
:''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.  
 
:''desc:'' The author's name or mark. The use of this field is not recommended as attribution can be determined programmatically.  
  
====organisation====
+
===organisation===
 
:''type:'' UTF-8 string.
 
:''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.  
 
:''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.  
  
====contact-email====
+
===contact-email===
 
:''type:'' email address string.
 
:''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.  
 
:''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.  
  
====contact-website====
+
===contact-website===
 
:''type:'' URL string.
 
:''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.  
 
:''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.  
  
====info-url====
+
===info-url===
 
:''type:'' URL string.
 
:''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.  
+
:''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.
  
 +
===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.
  
=Downloads=
+
==Downloads==
 
''Attach sample files here''
 
''Attach sample files here''
  
  
=Categories=
+
==Categories==
[[Category:Asset KIND]]
+
[[Category:Asset KIND|$BaseSpec]]
 +
{{ORP-bot|$BaseSpec}}
 +
<div>{{FUN-bot|$BaseSpec}}

Revision as of 08:52, 9 September 2016


Contents

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.

Parent Classes

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

Child Classes


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
{
}


 

kind

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

kuid

type: KUID
desc: The unique asset ID referencing this asset.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

custom-category-list

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.

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.

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.

privileges

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

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.)

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.

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.

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.

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.

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.

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.

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.

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.

Downloads

Attach sample files here


Categories

Personal tools