Trainz/AM&C/Dealing with Asset Errors

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
The necessary third party software effective in dealing with Trainz assets is virtually all obtainable as.
 * 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:
 * 2) Instead suggest  programmers' editor  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/) of kuids.
 * 3) Programmer's Notepad &mdash; 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.
 * 4) Crimson Editor (New update of famous Ruby Editor)
 * 5) Open Office Suite &mdash; unlike, 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:
 * 6) 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  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.
 * 7) 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)  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)  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' 

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.

obsolete-table { 0                        1                        }
 * 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 . Adding 100073 and 100074 (and a few others) to the obsolete-table:


 * 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.

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

kuid                                    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                                   bogey-1                                 bogey-2                                 bogey-3                                 mass                                   135000 company                                "CONRAIL RAILWAY" kind                                   "traincar" interior                                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                              enginesound                             hornsound                              

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                                      1                                     2                                     3                                     4                                    <kuid:-1:101475> 5                                    <kuid:-1:42003001> 6                                    <kuid:-1:42003101> }

What is/is not important
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&mdash;for no good reason or need!)
 * 2) The next significant change in the data model was N3V's first forays into new technical capabilities, which primarily affect only locomotives&mdash; certain config tags and previously used tags were moved into a different mix of KINDs or eliminated as being needful of definition
 * 3) 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.
 * 4) 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.
 * 5) 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.
 * 6) Depending upon what you use as a text editor, this might need be accomplished before opening the file, or just after.
 * 7) To backup before opening, LMB click the file in it's windows folder, type  and then click in the folder off any files or folders then paste a copy using  (Paste), and Windows will clone the original. You can then rename it as detailed in the alternative following.
 * 8) More economically (and assuming we are opening a old asset which defaults to TB v1.3), we prefer opening the file using Notepad++, typing  (back up 1 window) to return focus to the file folder (where the file will still be selected and highlighted), followed by  (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.
 * 9) Finish by  (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.
 * 10) 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  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!)
 * 11) After fixing the asset using it's given  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. &rarr; (presumably v3.7 or higher).
 * 12) 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.
 * 13) 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  needs have all the declarations and definitions Trainz needs, or Trainz will complain with a fault.
 * 14) 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!
 * 15) 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.
 * 16) 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
 * 17) 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.
 * 18) To be continued