Trainz/AM&C/Dealing with Asset Errors

Trainz Asset Maintenance and Creation Content Manager skills tutorials for Trainz

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

Contributing authors: Fabartus

Dealing with Asset Errors

'Errors, Faults, Faulty assets, Bad Content, Faulty content are all synonyms in Trainz-speak for the same situation: An asset was distributed with malformed components, a missing component, or has become incompatible with newer software releases despite working in an earlier Trainz version. This later kind of error or fault occurs when the asset needs an tweak to conform to a newer level of asset technology, and are the most prevalent. Assets missing a texture (component) can be 'patched' and made to work, if not with the exact same appearance as used by the content creator. Whatever the flaw, it is frequently something which can be 'fixed' by simple hand edited changes into the files, most often only inside the text ini files of the asset contained in the assets defining folder(s) which one opens using third party tools in the operating system folder.

Currently, the best Error fixing advice on these pages is found here at Trainz/AM%26C/Fixing_Assets, which covers the most frequently occurring error messages in a text searchable format, allowing entry of the key phrase in the error message to read up on how to fix it.

 

Necessary tools

Composite snips, from CM to CSL of kuids.

The necessary third party software effective in dealing with Trainz assets is virtually all obtainable as freeware.

1. A good text editor is a God send, while Windows has the venerable basic text editor Notepad available for simple edits, it lacks many useful features:
   1. Instead suggest freeware programmers' editor Notepad++ as the most useful for several reasons, not least being the ability to search and replace (SAR) across line end boundaries allowing easy conversion of CM generated asset lists to be turned into Content Manager compatible comma separated lists (CSL/CSV) of kuids.
   2. Programmer's Notepad — like Notepad++ Programmer's Notepad and (the next suggested) Crimson Editor allow multiple file editing, have useful extended search and replace abilities over Windows Notepad, and have individual strengths.
   3. Crimson Editor (New update of famous Ruby Editor)
2. Open Office Suite — unlike Microsoft Office, this freeware open source package won't break your piggy bank, is fully compatible, and suggested here for two primary uses involving use of the spread sheet module:
   1. Spreadsheet makes a useful flatfile database; different tabs allows tracking different projects assets as taking a CM main screen generated list of selectees into a CSL. A CSL of kuids has many organizational benefits, not least of which is an ability to reset a filter or three with different asset kuids for use in surveyor.
   2. Pasting a copied list of assets from the CM main screen into a spreadsheet as a CSV list is the fastest way to truncate off the asset names from the kuids. The process is A) copy an asset group from CM; B) ALT+Tab ↹ to Spreadsheet scratchpad sheet; C) Paste down the copied asset names and their kuids as a CSV import with the comma as a delimiter. D) Copy just the column of kuids; E) ALT+Tab ↹ to Notepad++ scratchpad tab; F) Paste down the list (each row of the spreadsheet becomes a line with a single kuid); G) SAR across line ends from '>\n<kuid' and replace with '>,<kuid'

Be familiar with

It is assumed the reader has read through and gained a working understanding of the materials presented on the following pages before proceeding with the below:

1. PEVtools - installing PEVtools is necessary if you are going to get anywhere but frustrated quickly trying to rework assets needing tweaking.
2. Content Manager - Operating Content Manager is center stage in asset downloading, fixing and upgrading.
3. When to fix assets or when to upgrade them - Fixing and upgrading assets are two sides of a coin, but the one takes more time and indepth knowledge. This entree explains when just fixing an asset is a winning strategy and when upgrading is a better idea.

Goals of this Module

This module will give the reader a working knowledge of the following Trainz knowledge topics:

1. We're going to introduce a basic Traincar data model, vintage Trainz 1.3 and use it to introduce where the original data model put things and where things have changed since.
2. As an initial goal, we'll show you how to fix a not very broken asset
3. After fixing the asset to Trainz needs for TB V2.3 (TRS2004–TRS2006 satisfactory) you'll have learned the most frequently needed repair steps to fix most older content available on the DLS. In an nutshell it boils down to adapting the original Trainz practices with newer data model structures (Thumbnails, Mesh-table, and bogeys containers) which satisfy (in most cases) the needs of the post-TRSs era Trainz developed under N3V Games which broke the compatibility code creator Greg Lane and his programmers had installed. (Which is why such assets worked fine in the TRS&ndashTC's versions.

Editor's note: If you're going to patch up a V1.3 to V1.5 asset so it works with both validation and commitment within TS09 and up, the changes needed are generally to add a mesh-table container, thumbnails container, and for traincars, add a bogeys container. Excepting the thumbnails, that's the cookbook for a V2.0 asset, the thumbnails added in V2.5 (TRS2006-SP0). Given that, you may as well start out by planning to upgrade the trainz-build! The asset certainly won't work in Trainz 1.3 anymore!

• Some Trainzer will say "Big Whoop! Now you have a private copy of a working boxcar with paper wheels... which I'd be ashamed to use" Consider sending this sad-sack flowers, or at least a clue stick. She clearly doesn't understand the use of the obsolete-table. Adding 100073 and 100074 (and a few others) to the obsolete-table:

obsolete-table {
  0                        <kuid:-1:100073> 
  1                        <kuid:-1:100074> 
}

The new user should take note that a bare kuid in a config.txt file (100073, a boxcar bogey or truck) is defaulted to Author #-1 ... which was the original Auran user identity. They use a number of others since, including all the negative user identity values.

• Then again, like a Model Railroader with physical model kits, all the DLS is one big source of "kit-parts" we can digitally "kit-bash" new models from with a bit of experimentation and daring.

Editor's note: Learning to fix older assets makes them useable for niche's where our imagination's engineering may need them, including satisfying the imagineering of a route builder/session writer of yesterday opening up those routes for you to exploit. Learning how to turn that wrench and tune that adjustment, the step to creating a special-purpose-built asset of your own becomes far smaller and no where near as steep.

Assessing an older model

We're use below unchanged config to give the new Trainzer a tour of asset normal features:

kuid                                    <kuid:55290:638>
origin                                  "USA"
engine                                  1
category-region-0                       "US"
category-era-0                          "1970s"
category-era-1                          "1980s"
category-era-2                          "1990s"
category-era-3                          "2000s"
category-class                          "AL"

running-numbers
{
}
name                                    "Loco CONRAIL QUALITY WEATHERED SD40-2 "
bogey                                   <kuid:-12:3535>
bogey-1                                 <kuid:-12:3535>
bogey-2                                 <kuid:58377:50012>
bogey-3                                 <kuid:58377:50013>
mass                                    135000
company                                 "CONRAIL RAILWAY"
kind                                    "traincar"
interior                                <kuid:-1:101475>
trainz-build                            1.3
fonts                                   0
smoke_shade                             1
smoke_random                            2.5
smoke_slowlife                          6
smoke_fastlife                          0.8
smoke_height                            1.7
smoke_fastspeed                         1.6
enginespec                              <kuid:58377:51022>
enginesound                             <kuid:-1:42003001>
hornsound                               <kuid:-1:42003101>

smoke0
{
  attachment                            "a.mainex0"
  mode                                  "time"
  color                                 40,40,40,120
  accel                                 0,0,0
  rate                                  20
  velocity                              3
  lifetime                              2.5
  minsize                               0.3
  maxsize                               2
}

smoke1
{
  attachment                            "a.mainex1"
  mode                                  "time"
  color                                 40,40,40,120
  accel                                 0,0,0
  rate                                  20
  velocity                              3
  lifetime                              3.5
  minsize                               0.3
  maxsize                               2
}

smoke2
{
  attachment                            "a.mainex2"
  mode                                  "time"
  color                                 40,40,40,120
  accel                                 0,0,0
  rate                                  20
  velocity                              3
  lifetime                              2.5
  minsize                               0.3
  maxsize                               2
}
description                             "CONRAIL QUALITY SD40-2. Model was created by Prjindigo, Roger Crouch and the paintwork was created by Sean Pope
"
asset-filename                          "CONRAILQwSD40-2"
username                                "CONRAIL QUALITY WEATHERED SD40-2 "
author                                  
organisation                            
contact-email                           
contact-website                         
license                                 

kuid-table
{
  0                                     <kuid:-12:3535>
  1                                     <kuid:58377:51022>
  2                                     <kuid:58377:50012>
  3                                     <kuid:58377:50013>
  4                                     <kuid:-1:101475>
  5                                     <kuid:-1:42003001>
  6                                     <kuid:-1:42003101>
}

What is/is not important

TB value key ranges	Retail or Service Pack Version equivalent	TB Value Goal
v1.3—v1.5	Trainz, Trainz 1.3, through Trainz UTC	2.3-2.6
v2.0—v2.4	TRS2004 and it's 4 SPs	2.4, 2.5-2.7
v2.5—v2.6	TRS2006 and it's 1 SP	2.6-2.9
v2.7—v2.8	TC1&2—TC3*	2.9-3.0
v2.9—v3.3	TS2009 & TS2010 each + 4 SPs	3.5-3.7

At first glance many engine traincar assets may seem to be very complicated to the new Trainzer hoping to fix a faulty asset. The significance of the trainz-build value is poorly understood, even by many content creators involved in Trainz since it's earliest. A key is to understand Greg Lane and the original programming team evolved the key more complicated data structures of an asset back in 2003–04 and they've changed little since but for extra capabilities.

1. Keeping in mind the notation 'TB' means trainz-build and v#.# is a value of that trainz-build tag, and further, that the back-asswards way N3V games chose to implement upgrading, all asset fault lists generated by your Content Manager (CM) validation procedures are dependent upon the value assigned to the trainz-build tag line in their respective config.txt file. This means making the asset fault-free at a particular minimal threshold value, should result in the asset working for all versions later on. In point of fact, that threshold is usually very low; compliance with the 'ideal' v2.0-v2.4 data model definitions will usually result in a working asset up through TS12-SP1 (TBv3.7; which assets are supposed to work with the new TANE data models). Fixing most others to v2.6 fault testing needs yield similar success for the few lonely exceptions, despite the fact N3V management has artificially pushed the minimum needed TB values upward for uploading. (The result is P.O.'d content creators who are expected by N3V to donate their free time to endlessly update hundreds of assets over and over again every few years—for no good reason or need!)
   1. The next significant change in the data model was N3V's first forays into new technical capabilities, which primarily affect only locomotives— certain config tags and previously used tags were moved into a different mix of KINDs or eliminated as being needful of definition
   2. The next major change was with TS2009-TS2010 when the programmer's formalized the older Content Creator's Guide guidelines into the TrainzOnline Wiki we are now to rely on for the technical guidance of what to fix and how. Unfortunately, it is rarely up to date, and changes are not announced in advance of need, while the DLS vetting software is updated to Windwalkr's current prejudices without any notice.
2. The first key to getting through the confusion is to know that CM is pretty good at delivering fault messages which indicate where a config.txt file is needing tender loving care (TLC), and that means you can mostly ignore lines where it is not complaining.
3. The second thing that eases change evolutions is to realize you can make back ups before changing a file, a practice we strongly suggest you develop into a habit.
   1. Depending upon what you use as a text editor, this might need be accomplished before opening the file, or just after.
      1. To backup before opening, LMB click the file in it's windows folder, type CTRL+C and then click in the folder off any files or folders then paste a copy using CTRL+V (Paste), and Windows will clone the original. You can then rename it as detailed in the alternative following.
      2. More economically (and assuming we are opening a old asset which defaults to TB v1.3), we prefer opening the file using Notepad++, typing ⇧ Shift+ALT+Tab ↹ (back up 1 window) to return focus to the file folder (where the file will still be selected and highlighted), followed by F2 (Windows rename) and inserting the string "v1-3.orgFlawed" or just "v1-3.org" before the terminating '.txt' extension. Naturally, if the asset began as v2.1 or v2.2, then adjust the .org. name accordingly.
         1. Finish by ALT+Tab ↹ (forward) back to Notepad++ which when it regains Windows focus will present a pop-up messagebox: "File config.txt has been moved or deleted. Keep file in editor?" to which we urge you to answer 'YES' with the apropos LH Mouse Click.
         2. This technique lets you both record the status of the file saved, and preserves it's original history (date-time stamp) which can sometimes be useful, whilst allowing you to rename the file in a way that reminds you of why it's there now. When you write a change out, it has an equally valid date-time stamp. You can immediately hit CTRL+S to save it, reconstructing the config.txt file in the folder, or wait until you've changed things (our recommendation, you're already backed up after all!)
         3. After fixing the asset using it's given trainz-build tag level plus a bump (See right hand column of table recommendations of target levels), we will suggest a follow-on procedure as we progressively evolve the fixed asset file set into a fully upgraded file set by similar notations such as 'config.v2-3a.PRLM.txt', 'config.v2-3b.OK.txt', 'config.v2-6a.OK.txt', ..., config.v2-9.near.txt, ..., config.txt. → (presumably v3.7 or higher).
4. A key point is it is usually unnecessary to fix plus evolve an older asset past v2.0 for most assets, or v2.9–3.3 in the case of certain special cases that need special TLC for TS09 and TS10.
5. A next factor aiding the neophyte is to realize the order of things (excepting inside container curly-braces, and much even there can also be reordered if desired), matters not at all. Either the asset Kinds needs have all the declarations and definitions Trainz needs, or Trainz will complain with a fault.
   1. This means if you prefer to analyze asset factors in a certain order, feel free to move lines around. Just try to never loose any, unless that's the fix!
   2. This freedom means you can group things in clumps of related data [e.g. all three tags containing 'ory-' (i.e. 'category-') or all the kuid referencing lines (parts or components such as bogeys) or all the tags containing 'name' and so forth] in ways that help you best see what is going on and makes you feel comfortable.
   3. As a general strategy, when repairing I prefer to move all the tags commonly changed or deleted as the TBv level is increased near the description block of text, where I add a change record of what I did to alter the author's asset. You may not feel the need, nor see the sense of adding a suffix as I religiously do ['-a' for altered, '-aR' for repaired, '-aRu' for repaired and upgraded, '-aRus' for that plus a screen shot added. Similarly '-aS', means I added just a screenie, and 'aCmd' means I cloned it and modified it down for an earlier Trainz release.] Annotating what you did and why is a 'good programmer' practice, and make no mistake, this is a form of software which we are maintaining
6. Feel free to be daring and experiment. That 'config.v2-3a.PRLM.txt' noted above signifies one such philosophical change in strategy, it copied fixups so-far to safety, before more daring deeds were done to jump the asset with new containers and tags to higher than originally targeted TBval. Once you get comfortable with tags common and expected by KIND type, you should do the same.
7. To be continued

Topic 5 and up

 

* Setting the 'freeintcam' switch parameter in trainzoptions.txt (TR04—TS12) or checking the clickbox with the same function (Freeing Internal Cameras) in TANE and after, changes the function of the keyboard arrows from rotate and tilt functions, to instead slide the camera position forward and back, or side to side. Freeintcam mode enables the user to move many cameras entirely outside the CAB or to a much better advantaged viewing (and mouse-controlling) angle.

Notes, Footnotes & References

Config.txt files are endemic and ever present in Trainz assets, for no asset can be defined without this type of Computer Science container. The keyword-value_of_key pairing must always be kept in mind in editing or creating Trainz content. The TrainzBaseSpec contains values and containers which are most common in asset defining config.txt files.  

 

 

References

• Trainz printed or pdf file Manuals, applicable version - usually in the ..\extras or ..\extras\manuals folder
• TrainzOnline Wiki Config.txt file page and various other pages
• TrainzOnline Wiki: Content Creator's Guide pages (various)
• Various CCG and Auran websites