CCG/Config.txt Files

Latest revision as of 10:51, 3 June 2011

[edit] Config.txt File

Each model asset that is created requires a config.txt file. This file is a simple text file that is used to describe the item of content to Trainz.

In previous Trainz Builds, the config.txt file was created in a text editor. TC now uses the Content Creator Plus module to create the required file, using a series of input boxes in a graphical user interface. This simplifies the creation of the file and allows the file to be checked for errors.

Because each different 'KIND' has a different config.txt requirement, please refer to the appropriate KIND descriptions and information on the following pages.

[edit] Containers

A data container is a portion of the config.txt file that covers a particular function for the model, for example the model mesh files to be used, or the effects to be applied.

The model asset has a top level container for data that is required for, or is common to, most model assets. Nested in this container may be other subcontainers, each describing a particular function of the asset.

[edit] Tags

Within a container the commands that Trainz recognizes are called Tags. Each tag indicates data values to be used or a function to be implemented.

Dialogue boxes and drop down menus are provided for the data entry in CCP and in-built error checking will indicate faulty data or entries. An error message display will assist in creating a correctly configured model.

[edit] Directory Structure

A new asset requires that the config.txt file, mesh files, texture files and other files be placed in a directory. This directory is created whenever a new asset is commenced in CCP.

The arrangement of files within the main directory or a subdirectory is, in most cases, the choice of the creator. It may be convenient to group some files in a subdirectory, for example, the night directory mesh and texture files. This can make it easy to distinguish the files associated with a particular part or function of an asset. The mesh table layout adopted since TRS2004, makes it easy to point the config.txt file data to the required subdirectories.

For some Kinds, certain files may be required to be placed in particular directories, and the creator has no choice in the layout of the directories. The creator will make the required subdirectories, and place the files.

In these instances, requirements will be shown in the examples in the following Chapters and pages.

In other instances it may be more convenient to use only one main directory for all meshes and texture files for the asset. This can result in a smaller cdp file than if subdirectories were used. For example, sometimes a night mesh model may use the same texture files as the day mesh model. If these same textures are placed in the main directory and also in a night subdirectory, the files are actually loaded twice in the cdp package.

The same file in different locations, or a different texture file using the same file name in a separate subdirectory, are converted to binary form in the packaging process, and are given a unique binary identifier. This means that they have to be loaded individually into Trainz memory and can effect the frame rate and loading of Trainz.

[edit] Kinds and Container Relationship

Each Kind has unique attributes, but also shares some attributes with other Kinds. The tables in Chapter 11, Appendix B show the types of containers that are available in each Kind. These will indicate which asset Kind may be the most suitable for a particular model to be created, and also show the relationship of Kinds and containers.

Refer to the following chapters for a discussion and use of Kinds and Containers.

[edit] CONFIG.TXT FILES

Each item of content that you create is required to have a config.txt file. This file is a simple text file that is used to describe the item of content to Trainz. TRS assets have become far more flexible through the use of the new mesh-table fields.

Because each different 'KIND' has a different config.txt requirement, please refer to the appropriate KIND descriptions on the following pages.

[edit] Example Config.txt File, General breakdown:

[edit] General

While there is great flexibility in the order of placement of information in the config.txt file. It is important to ensure: the correct number and orientation of brackets; correct spaces within the statements are used; and the correct lower case or capitalisation is used for names. While the tabbing of information across the page is not mandatory, it assists in the readability and debugging of the file.

Note: CCP will format your config.txt file in this manner, and enter the correct brackets, quotation marks and spacings. Do not remove any apparent blank line at the top of such a file if you edit it in Explorer, as it contains hidden information used by Trainz.

[edit] kuid

Unique ID of this asset. The KUID contains basic creator information.

The New KUID2 format in TRS gives greater version control and flexibility over asset updates. It eliminates the need to give a new Content ID every time you the creator releases a new version of the same asset. Refer to the KUID2 information on Page 17.

[edit] mesh-table

This is the new and preferred method of asset mesh placement for most mesh asset types. It gives flexibility and control for mesh placement and animations. There are some asset types that cannot use a mesh-table. These include all Bridges, Tunnels, Rails, Pantographs and Other Spline Objects (eg. Fences or Catenaries).

Important Note:

Any asset that uses a mesh-table will not be compatible with pre-TRS versions of Trainz (i.e. Ultimate Trainz Collection or UTC). TRS will of course still read UTC assets.

As with most major software releases, backwards compatibility is usually achievable, while forwards compatibility is often impossible.

[edit] default

Default is the `main' mesh of the asset.

Bold text: Required tags Itallic text: Optional tags

kuid <KUID2:1234:5678:1>     
 mesh-table
 {
   default
   {
     mesh industry.lm
     anim anim.kin
     animation-loop-speed 1.0
     auto-create 1
     effects
    {
      0
      {                      
         kind name
         fontsize 0.15
         fontcolor 30,30,30
         att a.name0
         name name
      }
      1
      {
         kind corona
         att a.coronawhite
         frequency 1
         directional 0
         texture-kuid <KUID:-3:10111>
      }
    }
  }
  default-night
  {
     mesh nightwindows/nightwindows.im
     night-mesh-base default
  }
  attachedanimation
  {
     mesh subdirectoryname/meshname.im
     anim subdirectoryname/animname.kin
     auto-create 1
     att a.pointname
     att-parent default
     animation-loop-speed 1.0
  }
}
kuid-table
{
    0 <KUID2:1234:6000:1>
    1 <KUID2:1234:6001:3>
}
obsolete-table
{
  0 <KUID:1234:5677>
}
preview-mesh-kuid <KUID:##:####>
username My Locomotive
description "You can have multiple lines but no double quote characters in here. Trainz automatically wraps this text. This information is displayed with the model on the Download Station. Please make the description useful and informative."
region "Australia"
trainz-build 2.5
kind "traincar"
category-class "AD"
category-region “AU:US”
category-era “1960s;1970s;1980s”
author Spock2204
organisation Auran Trainz
contact-website http://www.auran.com/

[edit] mesh

The 'main' mesh name. This may include a sub-path. ie: mesh nightwindows/nightwindows.im, where the file nightwindows.im has been placed in the subdirectory nightwindows.

Use .im files exported from 3dsmax or gmax (as opposed to .pm.) or reference an .lm file if you wish your asset to have `Level of Detail' mesh reduction. A pantograph model still requires a .pm file.

Level of detail is a process of using different model meshes, depending on how far the viewer is from the model. A finer mesh is used for close up viewing in Trainz. For further information please refer to Page 373 .

[edit] anim

The animation file name (*.kin) exported from 3dsmax or gmax. This may include a sub-path.

[edit] animation-loop-speed 1.0

This tag must be here if the asset is to animate when placed. If this tag is not here when placed the animation will not play by default, but may play if controlled by script. A different value (e.g. 0.5, 2.0) may be used in the tag to play the animation at a different speed from that created in 3dsmax or gmax.

[edit] auto-create 1

The model is generated automatically when placed, or when you load a map which includes the model. In some instances you don't want the mesh visible (as this may be controlled through script). If auto-create is 0 the mesh will not be visible when placed.

[edit] default-night

'Main' night window mesh on scenery and industry and traincar assets. Modeled to the same 3d space as the default mesh and is inserted at the default mesh origin. Note that this example on the previous page has placed the mesh in a subdirectory, "nightwindows".

[edit] night-mesh-base default

This night mesh is linked to the default mesh and is visible only at night. It is invisible if the `default' mesh is invisible, (if the auto-create 0 line were used so the default mesh can be controlled by script).

[edit] att

The mesh (and animation if present) is inserted at a mesh attachment point rather than the origin (without this line the mesh is placed relative to the origin of the parent model).

[edit] att-parent name

The tag tells Trainz in which mesh the attachment point is located. The insertion attachment point is located within the mesh `name' , as listed in the config.txt.

[edit] kuid-table

A list of KUIDs required for this asset to function correctly.

A kuid-table must be included where the config.txt references additional KUIDs such as a bogey, or a pantograph, including Auran built-in KUIDs. The Download Station performs a search, and those found are added to the download pack.

[edit] obsolete-table

The obsolete-table describes the asset's revision history. This field was used extensively for pre-TRS assets, as each version required a unique Content ID. However in order to make the content creator's life a little easier, Trainz now uses the KUID2 format which adds another number as a version number. For KUID2 information see Page 17.

TRS and the Trainz Download Station automatically detects the most recent version of an asset whether it be through the KUID2 Version ID or through the obsolete-table. If there are no obsoletes, leave the obsolete tags out.

[edit] preview-mesh-kuid

Only add this to reference a different mesh for the Surveyor preview window. This is useful when an asset has a large bounding box. i.e. the Airport with it's jet animation. By using a different (smaller) mesh it will fit better in the preview window. It can also reduce the polycount on screen. It is also used for an asset that does not have a mesh (fixed track frr example).

[edit] username

The human-readable English name of this asset. Language versions are available.

[edit] description

The human-readable multi-line English description of this asset. It displays on the Download Station with your model, so please make it useful and informative so others may understand your model, for instance, entering what the model is called and under which name and category it may be found in Surveyor. It is very useful in finding an installed model. Language versions are available.

[edit] region

The country region to which this asset belongs, not used for TC - category region is used instead - see below.

[edit] trainz-build

The Trainz build is the version number for which this asset was created. Refer to Page 18 for further information.

[edit] kind

The asset kind. Must be one of the Auran-supplied asset kinds. i.e. kind industry

[edit] category-class

The class code for this asset. Refer to Category Class.

[edit] category-region

A list of REGION codes or REGION GROUP codes, formatted by CCP into one tag line in the config.txt file. Refer to Category Region.

[edit] category-era

A list of ERA codes, formatted by CCP into one tag line in the config.txt file. Refer to Category Era.

[edit] other entries

You may enter data for additional information in the config.txt file, such as:

author, contact-email and contact-website are useful information, particularly if a user has a question on your models or would like to offer help or suggestions. organisation name will show in Trainz in Railyard as the organisation for the model, for instance if you use Joe's Trainz or Cripple Creek Logging Company.

license will show information on how you wish your models to be used by others, and any limitations.

Note: In Content Creator Plus, go to the Preferences... General option and enter the details for the above tags. When one of the tags is selected, CCP will populate the tags dialogue box in your new asset with the data

[edit] Return to CCG Index

Content Creator's Guide