Trainz/refs/texture.txt file

Text files names with *.texture.txt suffix and extension are used as the preferred method of specifying graphics file options and processes in virtually every asset, including those employing newer tech containing baked-in texture mapped meshes with normal and reflectivity (UV maps)— for their purpose is to configure graphics textures behavior in Trainz. These files may also control how textures are processed by Content Manager, notably by providing pathspecs, and triggering additional validations to best generate healthy assets. Furthermore, the newer LOD mesh sets with normal or UV-mapping will have their own texture.txt file controlling their application.

Trainz Annotated Reference Pages Trainz Asset Maintenance and Creation

TOC | Beginnings | Fun | AM&C | Creation | InBook Refs | ORP Refs:  • Index • Containers • Kinds • Tags | Appendixes  • Vers

Glossary

HKeys-CM

HKeys-DVR

HKeys-SUR

HKeys-WIN

Mouse use

Notations

Introduction

These files are generally located in the same folder as the texture's source image files, typically .bmp, .tga or .jpg files, as it is the job of the texture.txt file to make reference to them and direct the mesh (.im file) to them, but the texture.txt can be elsewhere since it can utilize short form DOS/Windows file structure navigation one folder level removed, but not two.

Texture files... Three types of interrelated file types are referred to as 'texture files' in Trainz society, and even the N3V programmer's have been observed calling each of these file types "Texture files". The term applies both to those with a .texture extension and those graphics display file types paired with a controlling .texture.txt file. Note, the term in some contexts might also be used applied to the texture.txt file, which is a type of control file or INI file with instructions controlling processing of it's corresponding image file, both of which get processed and compressed into a .texture file by Content Manager when the asset has passed error testing and is being committed. The secret to not getting confused about this is to realize they are both texture files, one in raw editable form (a file pair having both a texture.txt and graphics file element) and the other, that odd filename.texture is the resultant run-time ready (already compressed, processed, and ready to load) combined form of the two source files generated by CM after fault checking and as part of the asset being committed. .texture files can be unpacked using PevSoft (Pev's) Images2TGA.exe tool utility. Some versions of CM/CMP leave them present when editing an asset, some CMs complain they are present when committing or fault checking the asset, and some CMs couldn't care less. As a general rule, if they are present after importing cdp files, unpacking a .chump file, or opening an asset for edit, it is safe to delete them.

It is actually necessary that the texture.txt file be in the same folder as the mesh looking for it!. The image file can be shared by more than one texture.txt file and mesh reference. These are control files which are generated automatically by the Trainz exporter or importer (i.e. Translator software from Gmax, Blender and AutoDesk's 3dsMax formats to Trainz data needs—Auran/N3V sources and updates these from time to time) but may be edited by hand when specialization is required.

Syntax

Each token is specified on a new line. There is no white space on either side of the '=' sign. A empty value is sometimes valid. The syntax is:

<token>=<value>

Texture.txt files may be commented using the C++ 'hack-hack' comment style:

// This file was created for TRS2006-SP1 then retrograded to trainz-build 2.0 for TRS2004

Tokens

Here is a list of supported tokens. Any other values should not be used.

• Further, It must be understood that

1. the mesh and the texture.txt file are always put in the same folder.
2. The texture (image file) itself can be in a common location, and referenced by several meshes of the asset (how many black.tga textures do the 8 or more meshes of a Steam Locomotive need?), but the referencing is via the texture.txt file whose name must match with the name the mesh is referencing. i.e. The mesh refers to the name of the texture.txt file, which need not match that of the actual image/texture listed as the Primary within.
3. Assuming a common texture file, different mesh names and/or locations, and a different 'look' from additional graphics:
   1. four of the eight in the above example each with a different name' can reference the same texture and use identical processing 'tokens', but each must exist to support it's referencing from within the mesh file.
   2. two of the remaining could be referencing an entirely different 'black2.tga'
   3. and the others the same but with a different mix of the tokens presented above in the composite example, and detailed below.
4. The points to master are the Onto relationship of a texture.txt file and mesh file, and that the texture name and location can be very different—there is no reason they need be co-located with either the mesh or the texture.txt file. The later has the job of marrying the two and defining the way THAT MESH renders the texture image.

Side by Side Examples

Most texture.txt files have only two to four lines, like the two examples at left and center below. Alpha Channel data is often conveyed by the same file as is listed as the Primary, when the image type supports such. Most often that is BMP and TGA files with 32 bit depth, though several other modern types are in the works. In the last example, the first four lines are akin to the center example. Many older assets will not have AlphaHint modifiers, nor support other extensions such as those shown below at right.
Most Commonly Seen Example: Primary=SunBurn_Red.bmp Tile=st	Next Most Common Example: Primary=SemiCoolTexture.tga Alpha=SemiCoolTexture.bmp [or Alpha=SemiCoolTexture.tga] Tile=st AlphaHint=masked [or AlphaHint=Semitransparent]	Composite Example: Primary=WayCoolTexture.tga Alpha=WayCoolTexture.tga Tile=st AlphaHint=masked Anisotropy=16 MagFilter=linear MinFilter=linear MipFilter=linear (Example only, not recommended settings)

 

• In the below, we'll present a 'example line' in the same sections. And amplifying commentary in () following.

First we provide these examples to compare to the text above and below...

Primary

Specify texture file name

• <texture name> - Primary texture. Filename including extension, three examples.

Primary=Whitehorse_pub.tga

(This example is very common in non-traincar assets, which is to say most objects, buildings, animals and trees not attached to or meant to ride rails. Simple Track Class assets—which includes road, power lines and fences all also share this simplicity of location. In the case of poles and buildings with lighting (nightmode) there will often be a night or nightmode subcontainer, a method from early data model practices.

Primary=PRR40'1910sBoxcar_body\PRR40'1910sBoxcar_body.tga

(This example is very common in traincar assets, and many content creators still follow the same practices. The early data model standard practice was to have (at least) three subfolders matching the asset-filename which had the suffixes: '_art', '_body', & '_shadow'. This was not as odd as it seems, as the asset-filename tag had to also be the username and the principal mesh name of the asset. Traincars are multimesh artifacts, so the controlling or reference mesh living in the root, and the body and shadow meshes having predicable paths from the asset root saved time from typing mistakes and kept things a bit neater. The _art folder supported various menus involving asset selection or display (See: {{TL|Railyard module]}).)

Primary=common_textures\Red-roof-tiles.tga

(This folder\filename reference implies that the MESH location is in folder containing a subfolder named 'common_textures', so it is likely the mesh resides in Asset's root folder which CM will open in the path '{{TBS|username|p=..\editing\username or ..\..\editing\username, in later practice wherein N3V tucks data into the ..\UserData folder, where \editing lives.'.)

Primary=..\green-siding.tga

• (The MESH location is in a sub-folder and 'common_textures' are in the level above, likely the asset's root folder)

Primary=..\traincar_left_door\brass-window-trim.tga

• (The MESH location is likely in a '..\traincar_right_door\' 'sister folder' from it's relative containing the 'shared_texture'. Likely, both are sub-folders of a '\traincar_asset-name_body' folder. This example from tests using a Randall Whitepass Pullman coach, and the brass.tga texture.)

 

Alpha

Specify alpha channel for texture. Note that if there is only one 32bit file with RGB and A channels, this must still be specified with the same name used in Primary

• <texture name> - Alpha texture, may be the same or different from the primary

Tile

Wrap texture addressing horizontally, vertically or both. Otherwise texture is clamped.

• <empty> - (default) No wrapping
• s - Wrap horizontally
• t - Wrap vertically
• st - Wrap both horizontally and vertically

Dimension

Number of dimensions the texture has. Not required since only 2D textures are currently supported.

• two - (default) Two dimensional
• cube - (unsupported)
• volume - (unsupported)
• one - (unsupported)

Compression

Compression format used by CMP. If this is not supplied, format is chosen automatically.

• none - Do not compress. Warning: Uncompressed textures consume large amounts of memory and slow performance.
• dxt1 - Suitable for opaque or alpha masked textures
• dxt3 - Alternately the best for alpha blended textures if the texture contains sharp contrasts. Try DXT5 first.
• dxt5 - Usually the best for alpha blended textures

Hint

Texture usage hint, for internal use only. Note this should NOT be used to try and disble mip mapping.

• static - (default) Standard texture resource
• dynamic - Texture will be modified in memory

NormalMapHint

Hint about texture being a normal map. Important to use as this will affect final texture quality. Compression, mip map generation and renormalization of XYZ (RGB) is effected.

• none - (default) This is not a normal map
• normalmap - This is a normal map

ModifyMap

Allows the texture to be modified when the texture.txt file is read. Currently this is to allow the green channel (Y axis) to be flipped for normal maps.

• none - (default) Do not modify texture
• flipgreen - flip green channel which is Y Axis of normal map

AlphaHint

Specify how the alpha channel is used. Affects final alpha quality. May also affect texture compression and mip generation.

• opaque - (default with no alpha present) No alpha channel used.
• semitransparent - (default with alpha present) Alpha blended
• masked - Alpha masked - this gives 8-bit grayscale shading from full transparency to fully blocking the object depending upont the pixel by pixel values of the Alpha channel or mask.

Warning:  Pre-TS09 Trainz versions will generate Faults from AlphaHint tokens, and likely most of the below tokens as well. The PEVtool Images2tga released in 2010 and now available for download (here) may generate them even in assets from such older Trainz assets. The fix is to comment out such lines with the '//' and the asset should work in the TRS era software.

Anisotropy

Anisotropic sampling quality. The higher the number, the better the visual quality but at significant performance cost. Where texture quality is needed specify a higher value. Trainz can now control anisotropy via a slider, so the highest setting is used by default.

• 1 - No anisotropic filtering
• 2 - Low
• 4 - Medium
• 8 - High
• 16 - (default) Very High

AutoMip

Auto mip map generation. Chris, is this deprecated? CMP now generates mip maps at highest quality instead of game load/run time.

• none - Don't generate mip maps
• default - (default) Whatever the default method is
• fastest - Attempt to improve load time at expense of quality
• nicest - Attempt to improve quality regardless of time

MagFilter

Texture sampling filter used when texture is magnified

• nearest - No blending with neighboring texels
• linear - (game default) Blends with neighboring texels for smooth zoom effect
• default - (default) Game default

MinFilter

Texture sampling filter used when texture is minified

• nearest - No blending with neighboring texels
• linear - (game default) Blends with neighboring texels for smooth shrink effect
• default - (default) Game default

MipFilter

Texture sampling filter used on mip map selection

• nearest - No blending with other mip maps
• linear - (game default) Smooth blendig between mip maps (Note, operates independently but should be used in conjunction with anisotropic sampling)
• default - (default) Game default
• none - Disable mip map generation in CMP and use in game. Specifically for user interface elements.

Comments & Suggestions

• Hint is mentioned even though it is intended for internal use only, because it has been used and abused by well meaning people since its discovery. Anisotropy should be used to improve texture quality, and MipFilter=none should be used to disable mip mapping only for interface textures.