"Extensions" container

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(import explanatory text from the TCCCG)
 
m ("Extensions" container Example)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Third parties may sometimes wish to include additional tags in an Asset’s [[config.txt file]] for the purposes of providing asset-keyed data to custom scripts.
+
The [["Extensions" container]] is a top-level [[config.txt file]] entry available to any Asset which derives from [[KIND TrainzBaseSpec]] (in short, all Assets.) This container is intended to allow third-party developers to introduce custom Asset-keyed data which may be processed by custom scripts.
It is important that the following mechanism is used to prevent potential conflict with future N3V tags or other content creators.
+
  
All third-party tags must be embedded under an extensions container which is placed at the top level in the config.txt file.
+
The extensions container is a list of custom tags or subcontainers with a specific naming convention.
Tags within the extensions container should have a meaningful name and should end with a hypen and the UserID of the content creator who is responsible for the extension. The responsible content creator should determine any rules and restrictions which apply to his or her tag and should make an effort to provide this information to other creators (outside the scope of the asset itself).
+
While creators are permitted to make use of each other’s extensions, it is not permissable to create a new extension (or change the meaning of an extension) in the namespace belonging to another creator.
+
  
Each tag in the extensions container may be either a single value, or a subcontainer. If a subcontainer is used, the contents of the subcontainer should be specified in the extension’s documentation.
+
==Supported Tags==
No restrictions are placed by Auran on the values within a specific extension, beyond the normal [[config.txt file]] format guidelines.
+
 
 +
The naming of top-level tags within the [["Extensions" container]] is important. Tag names should be meaningful and must end with a hyphen followed by the [[KUID#User_ID_Number|User ID]] of the content creator who is introducing the extension. This content creator is solely responsible for determining any rules and restrictions which apply to the tag or subcontainer, and should ideally make an effort to provide this information to other creators via this wiki. While content creators are permitted to make use of each other's extension formats, it is not permissible for a creator to introduce a new extension (or change the meaning of an extension) which exists in a namespace belonging to another content creator.
 +
 
 +
Each tag in the extensions container may be either a single value, or a subcontainer. If a subcontainer is used, the contents of the subcontainer should be specified in the extension documentation. No restrictions are placed by N3V on the values within a specific extension.
 +
 
 +
==Validation==
 +
 
 +
At the current time, the contents of the [["Extensions" container]] is not validated. It is expected that future versions of Trainz and the [[Download Station]] will perform validation of the extensions container according to the rules described on this page. Furthermore, it is feasible that N3V will formally adopt specific extensions which have entered common use. In this scenario, N3V may choose to introduce asset validation to the extension creator's formal specification or, where such specification is not available, to a formal specification written by N3V derived from the common usage.
 +
 
 +
==Extension Documentation==
 +
 
 +
If you are a third-party content creator who has created a custom extensions according to these specifications, please document your extension on this wiki and link to your extension page here:
 +
 
 +
* Add your entry here.
 +
 
 +
=="Extensions" container Example==
 +
 
 +
extensions
 +
{
 +
  delayinterval-474195      0.1
 +
  signaltype-474195        "DTV"
 +
}
 +
 
 +
[[Category:Config Container|E]]

Latest revision as of 04:09, 1 February 2016

The "Extensions" container is a top-level config.txt file entry available to any Asset which derives from KIND TrainzBaseSpec (in short, all Assets.) This container is intended to allow third-party developers to introduce custom Asset-keyed data which may be processed by custom scripts.

The extensions container is a list of custom tags or subcontainers with a specific naming convention.

Contents

[edit] Supported Tags

The naming of top-level tags within the "Extensions" container is important. Tag names should be meaningful and must end with a hyphen followed by the User ID of the content creator who is introducing the extension. This content creator is solely responsible for determining any rules and restrictions which apply to the tag or subcontainer, and should ideally make an effort to provide this information to other creators via this wiki. While content creators are permitted to make use of each other's extension formats, it is not permissible for a creator to introduce a new extension (or change the meaning of an extension) which exists in a namespace belonging to another content creator.

Each tag in the extensions container may be either a single value, or a subcontainer. If a subcontainer is used, the contents of the subcontainer should be specified in the extension documentation. No restrictions are placed by N3V on the values within a specific extension.

[edit] Validation

At the current time, the contents of the "Extensions" container is not validated. It is expected that future versions of Trainz and the Download Station will perform validation of the extensions container according to the rules described on this page. Furthermore, it is feasible that N3V will formally adopt specific extensions which have entered common use. In this scenario, N3V may choose to introduce asset validation to the extension creator's formal specification or, where such specification is not available, to a formal specification written by N3V derived from the common usage.

[edit] Extension Documentation

If you are a third-party content creator who has created a custom extensions according to these specifications, please document your extension on this wiki and link to your extension page here:

  • Add your entry here.

[edit] "Extensions" container Example

extensions
{
  delayinterval-474195      0.1
  signaltype-474195         "DTV"
}
Personal tools