Trainz/Fixing Broken Assets

Trainz Asset Maintenance and Creation
Trainz | Introductory Trainz | Trainz AM&C | Creation | Appendixes |  References • Containers • Kinds • Tags • Index
 Mouse use

If you begin exploring Trainz as a building tool, crafting or modifying a route, or venture boldly forth onto the DLS and acquire one of the 2500+ routes uploaded in the last decade— you will indubitably end up facing the learning curve of 'fixing assets'. Asset fixing is something of a misnomer except in rare cases—most widely used assets need fixing by updating to new technology levels—because they have become out of date relative to updates in the game engine's data needs. Alas, there are some actual errors in downloadable content from not only the DLS but from otherwise reputable 3rd party content creators such as Mocrossing pack (zip file) pack—the fixing of which is covered in a forthcoming tutorial. Many times these are simple typos, some are misspellings (not every contributor speaks English as a native tounge, nor as their first language) and pre-TS08 error checking was far more lenient... leading to the fatal crash of Trainz or worse, Blue Screen of Death errors.

Some small numbers of "Bad Assets" can (with decreasing frequency of occurrences thanks to the systematic efforts to 'Clean Up the DLS'), and when these are found in a route many of their ills can also be fixed. Most can be graded as misuse of key words, and misspellings, missing quotes and the like. Minor repairs anyone can fix with a text editor like Notepad or Notepad++. An occasional asset will be missing a component—either a texture or a mesh (the wire frame which gets 'decorated' by textures to make a virtual object. The one is a surface, the other the skeleton of the underlying shape.)

Various techniques have been adopted requiring different data, or a difference in the way data is organized. Most of these changes are handled automatically within the software. When they cannot be, they generate an error, a good thing. Having an error appear in an asset is far better than having a flaw in an asset create a program crash—an alltoo frequent occurrence in the early days of TRS2006 when the first basic error testing was built into the CM software with Service Pack 1.

Acquiring and Installing PEVs toolsEdit

PEVs tools in a power-users C:\Downloads folder (Yours will likely be somewhere else).

PEV's tools will be maintained by the community on one website or another as they are invaluable. Peter V. is a real programmer situated on the opposite (or Sydney) side of Australia from N3V/Auran's small town location on the Gold Coast near Brisbane, but ceased hosting his tools on his own website in mid-2013 when the task was taken over by Trainz fan Shane Turner on his help site here.

  1. Locate PEVs tools on Shane's site and their accompanying manuals where given.
  2. Download the tools (zip files), and quit out of any Trainz you may be running.
    1. As always when quitting Trainz, Hit [CTRL][SHFT][ESC] to bring up file manager to watch until the TADdaemon module exits before doing anything else.
    2. Once the TADdaemon closes it is safe to reboot or otherwise mess with Trainz directories (backup the folder, duplicate the local folder, or other maintenance)
    3. Set a system Restore point, label it as Pre-PEVtoolz installation then reboot.
  3. Open your downloads folder, in VISTA and newer Windows versions in succession Right Click-Hold to Launch,(RUN AS ADMINISTRATOR dropdown) each of PEVs tools in succession. (Each of PEVs tools will ask if you have TS2009, TS2010 and TS12, then store the information in an .ini file in a subdirectory specific to that tool. Consequently some power users prefer to install PEVs tools in an easy to reach common directory with a brief name and include the folder in the path (Very DOS era, but PEVs tools are handy used in a batch file and the ability is in Windows still.)
  4. Once your tools are initialized in each of the TRAINZ versions you have installed, you will see under the Version-path root folder \bin subdirectory the path ...\bin\CMPData\tools\OpenWith will contain PEVtools installed in each version of Trainz.
    1. This means if you run several versions of Trainz like some of us, to install PEV tools in each, just copy the files to the off-version.
    2. The batch files can be used more usefully outside Trainz CM by copying these into the ...UserData\editing folder. In this location one can open the asset for editting, then drag and drop the folder into the PEVsoft tool.
    3. Even better the clever trainzer can edit said batch files and create an composite file that enables a single drag and drop to run all the tools. This batch file can also be placed into the ...\tools folder in the \bin directory.

Fixing AssetsEdit

Trainz user PEV has written some tools for fixing content.

Note: many texture faults can be fixed by recreating the .im file with PEV's PM2IM program, use it standalone then point it to the asset folder.

PEV has a tool for creating shadows, called QuickShadows. QuickShadows can be downloaded here: * PEV's Tools Download link

Engine spec <kuid:35837:51002> can be replaced by <kuid:44090:51016>

Content Manager Warning MessagesEdit

and what to do about them...

Content Manager validates assets when they are committed, and also includes an option to display the errors and warning for any installed asset. Below are set out some of the error messages that CM will display when it validates an asset, with a brief description. This list is based on CM v3.7.

Warning: Aliased meshes cannot currently be verified by Trainz.Edit

The asset does not contain its own mesh but refers to another asset as the source of the mesh. CM is advising that the other asset is not validated as part of the process of validating this asset, and therefore this asset cannot be confirmed as error free. This asset might not work in game even though it is listed as available.

Warning: Required tag '<tag name>' was missing and has been set to default.Edit

The tag should be added to config.txt with a suitable value.

Warning: This asset uses an obsolete trainz-build number. Trainz-build numbers below <build number> are no longer supported.Edit

The validation tests applied to an asset depend on the asset's build number. This message is indicating that the asset is considered obsolete and therefore the latest standards have not been applied. If the build number of the asset is updated, there may be more errors detected.

Warning: Tag '<tag name>' in the container '<container name>' is obsolete.Edit

That tag is no longer supported and will be ignored. It is possible that the tag function has been replaced by a container, as in the case of the tags 'category-era-n' which are replaced by the container 'category-era'.

Warning: Required container 'thumbnails' is missing.Edit

A thumbnails container should be added to config.txt

Warning: This asset requires a shadow mesh, but the mesh table does not contain one.Edit

A shadow mesh should be created for the asset and the mesh table updated.

Warning: The texture '<texture name>' is a uniform color.Edit

Uniform textures should not be used for new assets, but for older assets that would require a change to the mesh. In this case the textures should be resized to 4x4, or at least one pixel changed to a varying colour (however slight the variation). Large uniform textures are a waste of resources: do not adjust the image colour to avoid the warning without also resizing it to a suitable small size - 16x16 or smaller.

Warning: An asset must be specified for tag 'texture-kuid'.Edit

The texture-kuid tag is used by some containers (eg, a corona effect container) to reference a texture name. If it is used, the texture name should be specified.

Warning: Progressive meshes are no longer supported by TrainzEdit

Full message
Warning: Progressive meshes are no longer supported by Trainz. Though these meshes may work in Trainz, it is recommended that you switch to a LOD mesh.
Related message
Warning: Progressive meshes are no longer supported by Trainz. Though these meshes may work in Trainz, it is recommended that you switch to a IM mesh. (Until 2008's publication of TC3 introduced the LOD technology.)

Progressive meshes (.pm) can be converted to a Indexed mesh (.im) using the PEV-tools utilities. LOD meshes do not currently have a tool which can scale a mesh to the set of meshes in an LOD series (typically four meshes with less and less polygons, the farther from the camera locus the face of the object. This mimics loosely the way the eye-brain sees less details the farther an object is from the eye. In computing terms, LOD meshes reduce the processing for most objects, but preserve the ability to build fine details into an object seen up close where there can be denser polygons and mesh pairings defining surface feature details.

Content Manager Error MessagesEdit

Error: Could not commit <'asset_username'>. The asset was not open for edit. You may need to open it for edit firstEdit

A rare, oopsie message. Don't forget computers do exactly what you tell them to, even if YOU think you tole' them something else entirely.

Error: Unable to read config file for asset at <location>Edit

[[Trainz/Unable to read config file for asset at <location>|Unable to read config file for asset at <location>]]

The config.txt file could not be found or could not be read. This usually indicates that the asset is corrupted, or that it does not exist at the location where it was expected. This can happen if the asset is deleted but the cache has not been updated. The asset should be restored from a backup source, or reverted.

Error: This asset has a trainz-build number which is not recognized by this toolEdit

CM will input Versions too advanced, this content is trainz-build +0.2 versions after the Content Manager (note the version code in the title bar).

trainz-build or asset version numbers are built into every Trainz item as a mandatory entry in the a|p=Trainz-build tagsssets TrainzBaseSpec data definitions in it's config.txt file.

As a mandatory data field, it literally defines to the CMP/CM reading the file the tech level of the asset allowing the game software to appropriately translate data from older dated formats to newer more demanding technologies. It is the secret which keeps Trainz compatibility version to version and why Trainz 1.3 assets are still found in new routes and session content. If the asset is properly defined, the trainz-build code tells the software how to interpret the data, if the data structures are older.

  • This message was generated because the data item just imported had a tech level over the head of the v3.2 Content Manager.

Error: Unable to load mesh file: '<mesh filename>'Edit

The mesh file could not be loaded. Perhaps it is misspelled in config.txt, perhaps it is missing, perhaps it is the wrong format, or perhaps it is corrupted and unreadable.

Error: Attachment point '<attachment point name>' in '<effect name>' must be found in mesh '<mesh name>'.Edit

An attachment point is referred to in config.txt but it does not exist in the default mesh <mesh name>. This can often happen when a config.txt has been copied from another asset, and the attachment deleted from the mesh. For instance, a crossing gate has had a lamp attachment removed from the mesh, but the corona effect <effect name> still refers to the missing attachment point.

Error: The attachment point '<attachment point name>' must belong to the parent mesh of the effect <mesh name>.Edit

This often occurs in conjunction with the previous message. Not only was the attachment point not found in the mesh, it was not found in the parent mesh to which the effect is attached. It occurs for the same reasons as the previous message.

Error: The *.texture.txt file is missing for texture resource '<texture name>'.Edit

A texture name used in a mesh file cannot be found, or could not be loaded. A valid texture.txt file should be created with a suitable associated image file. It is possible to search the user data folder for a texture of the same name, which might or might not be suitable for the asset. It is also possible to create a new texture.txt file and an arbitrary image - this might reveal what the image needs to be, or it might reveal that the texture doesn't matter and any image will serve to get rid of the error.

If the missing file is a 'digit_xx.texture' then any image can be used to remove the error. These files are not actually used because they are substituted with the selected digit image as part of the running number creation.

Error: Unable to load primary texture '<image filename>' for texture file '<texture filename>'.Edit

The primary image referred to in the texture.txt file could not be loaded. It might be missing, the name might be misspelled in the texture.txt file, the image file might be the wrong format (for instance, compressed TGA) or the image file might be corrupted.

Error: Unable to load image file '<image filename>' for texture '<texture filename>' while validating mesh '<mesh filename>'Edit

The image referred to in the texture.txt file could not be loaded. It might be missing, the name might be misspelled in the texture.txt file, the image file might be the wrong format (for instance, compressed TGA), the image sizes might not be a power of two (where required) or the image file might be corrupted. It is possible that the image file is not really missing, but the texture file exists, and is not required. Check the required lists of textures using Assetx - if the texture name is not listed then the texture.txt file can be removed and the error will disappear.

Image file '<image filename>' is incorrectly used as both a texture.txt source file and a raw image file.Edit

The asset includes a texture.txt file that refers to an image file, but that image file is referred to directly from config.txt. This applies to image files that are used as thumbnails. Either change the thumbnail reference to the texture.txt file, or (preferably) delete the teture.txt file.

Error: Binary conversion failed for texture resource '<texture filename>'.Edit

The image referred to in the texture.txt file could not be processed for some reason. See previous.

Error: The Tag '<tag name>' is not permitted within a container of type '<kind>'.Edit

The tag is not recognized as valid for this type of asset. The tag might be a comment (earlier versions of CM ignored comments) in which case it can be deleted. It might be misspelled, in which case it can be changed to the correct spelling. It might be a valid tag that was meaningful and useful for the asset, but is no longer valid. An example is the tags used by some scripts to provide information, such as running number range. These custom tags are no longer allowed as top-level tags in config.txt - they must be moved to a container within the extensions container, and the script must be modified to find them at their new location in the file. The details depend on the script.

Error: The tag 'tag name' in '<container name>' points to a nonexistent file: '<filename>'.Edit

This error occurs when a tag references a file and the file cannot be found.

For instance, named subcontainers in the thumbnails container have an 'image' tag that can point to a texture.txt file or to an image file. If the image file is not found - perhaps the name is misspelled, or the file is missing - this message will be logged. Similarly, the 'info-page' in a 'maps' container should point to a htm file. If the file cannot be found the error will be logged.

Error: Incorrect number of values for the tag '<tag name>', expected <x> values, found <y>.Edit

Where a tag requires a list of values, there may be a required minimum or maximum number of entries in the list. If the correct number of entries is not provided, this error will be logged. Add or remove entries from the tag list as required.

Error: Unable to load animation file '<animation file name>' (no resource).Edit

The animation file was not found in the asset. It may be possible to search for the file in user data and find it - a file of the same name might or might not work with this asset. If the file has been left out of the asset because it's not actually needed, then any animation file will work.

Error: Required container '<container name>' is missing.Edit

This can also be a warning in some cases, even though it says 'required'. It indicates that the asset type requires a particular container but that container has not been included in the cofig.txt file. The fix for this depends on the container (some containers can be easily created, some can't) and the asset type.

Error: The kuid '<kuid>' specified in '<container>' is not of the correct type.Edit

When a kuid is required within a container it must be a kuid of the type that is appropriate for that container. For instance, the allowed-categories container (within a queues container) requires one or more product-category assets. A different type of asset (such as a product) will generate this error.

Error: Failed to load sound file '<sound file name>', please ensure this is a valid wav file.Edit

The sound file could not be loaded. Perhaps the file is missing - it may be possible to search for the file in user data and find it. It might be corrupted or in the wrong format. If the file has been left out of the asset because it's not actually needed, then any sound file will work, at least to get the asset installed so that the function of the sound file can be determined and a suitable replacement located. For historical reasons this error can also occur in assets that are upgraded from an earlier build number - the file exists and the config.txt file entry appears to match the filename, but the warning persists. In this case ensure that the file name in config.txt is enclosed in quote marks (") - trailing spaces or tabs can confuse CM when quotes are not used.

Error: Script class does not match asset kind (<kind>).Edit

A script is identified as a class with the isclass statement. This class must match the kind of the asset that the script is used with. It is possible that the script should not be part of the asset at all (for instance, if the asset definition has been copied from an asset of a different kind) in which case the script references from config.txt can be deleted. Or, possibly, the asset kind was changed without changing the script or selecting the correct script for the asset.

Error: Unable to commit changes to asset <kuid:xxx:yyy> as the config file contains the wrong KUIDEdit

This is a DRM policing error (and an attempt to force users to update assets via Content Creator Plus, versus manual edit) that is generated because a kuid was manually adjusted. For example, an asset is upgraded to newer standard data type forms.

  • Further, this error will ONLY happen when an attempt is made to commit the asset with a changed kuid.

The solution is straight forward:

  0. Validate the asset to check for errors and warnings. (Should have been completed, since an attempt was made to commit)
  1. Copy the entire asset folder to a nearby utility directory (e.g. from ..\UserData\editing to \UserData\temp)
  2. Select the asset in CM/CMP and type CTRL+R
  3. To be completed with photos 'sometime later today'//FrankB 13:54, 13 April 2014 (UTC)
Last modified on 15 April 2014, at 19:58