Trainz/refs/ACS Text Format

The ACS Text Format is an Auran-defined international languages supporting text format used for storing s and other generic key/value data. At the simplest level, an ACS Text file is a standard text file encoded in.

Basic File Structure

 * In programmer jargon
 * 1) A 'key' (or 'keyword') is an 'specific' human and machine readable 'identifier', specifically of an unique or  nature belonging to a  of such legally specifiable s. These keys are the lexical identifiers used in translating meanings from human to machine CPU. If the term is not legal, the machine's software has no way of interpreting and giving meaning to the spelled (or misspelled) term.  A simple reality is that if a term is misspelled, the computer cannot match the value, and doesn't know what to do with the construct (line).  This is a fault or error, normally generating a halt to processing, or at minimum, a list documenting the term mismatch.
 * 2) A 'value' &mdash; These are usually tightly defined types, from basic machine dependent data elements to combinations of those into more complex data types.  For example, a character is a simple 8-bit byte value in some coding schemes, but in Unicode a two byte sequence. A string is a succession of characters in an array. Clearly the latter size is twice that of the string with chars of single bytes.
 * 3) 'unordered' lists are lines of data which can be rearranged without adversely affecting meaning. &mdash; You'll quickly see in Trainz config files, a tag or container can appear anywhere inside its proper container, the config being one such container, containing others.  The order of data appearance is independent of when it is listed and read.
 * 4) 'processing scope'  &mdash; means within the momentary subprogram, subroutine or handler of such and such a specific case (i.e. some predicted and handled context' so a particular 'process')
 * 5) "ACS Text files contain an unordered list of key-value pairs. In any given processing scope, each key must be unique."
 * By this, the N3V programmers mean some tag names are not unique to a particular or  but are reused inside such contexts as reasonably unique by context, and that the context handler software &mdash; the subroutine processing such a container and its values, knows what it is doing and that it is not the other L-value &mdash; R-value legal pair of that other legal context.  New users should bookmark and refer frequently to a  and the parent-child relationships therein.
 * For a concrete and common example: Today the tag 'region' is a config container (config file) legal value ONLY IN a asset (since ca. V2.5 - V2.7, TR06 era), so it is group inside KIND map with other tags specific to or needed to define a map.  Further, other config containers will be experienced that also have region as a legal tag name, but will have lesser TBVs.  Which is to say, if the config/asset is updated to higher TBV, 'region' will generate a fault instead of a warning.
 * THAT, older content use a now illegal string value as the R-value like 'United Kingdom', 'United States' or 'Australia' in virtually EVERY KIND OF ASSET of the day &mdash; but which in higher TBVs post-TR06&mdash;creates an fault message, for the keyword is now only legal inside the map config container which needs a kuid to a which defines things like base (center) latitude, longitude, hemisphere, water color, base altitude, default junction levers, and regional and period specific lists of road vehicles, so (oops!) Italian or Russian cars from 2021 don't show up on an North American road of 1925 (Ooops!) or winter fall and spring are all toast because "Michigan's map folder" is mislocated somewhere South of the equator (Oooops!) and sunrise and sunset reflect that region, not the upper United States. Oh-my OOooops!


 * Technical geek-speech...:the tricksy phrases here are direct quotes of the N3V Wiki source page linked below at page bottom; the interpretation and definition phrases we hope will make the geek-speak comprehensible and understandable so the lay person can internalize the meaning and make the implications 'mastered' and .''

A key-value pair can be declared in (EBNF) ( forming a context-free grammar) as follows:
 * Observe the following chain top to bottom defines terms or syntax for those lines which follow... the whole is independent.

::= | { } ;  ::= { |  } ;  ::=       ;  ::= [  ] {  }  ;


 * (I've been programming since 1976, and even my eyes glaze over reading and trying to understand that... so we write for you here in the Wikibook!)


 * 1) It is important to note that the may span multiple lines in some cases.  In Trainz, values are set off by either double-quotes (" glyph) or paired curly-braces glyphs: '{' and '}', always.  Trainz values can also be undefined or NIL.  Assets demonstrating these are usually optional, a few are newer tags that newer software will default for older content, which has no option in its genesis versions' day.
 * 2) Translate '[' ... ']' as optional.
 * 3) N3V's standard stated as  ::= [  ] {  }  ;
 * 4) Begins with either a blank line, or (OPTIONALLY...) a line with a unicode byte order marker

Auran/N3V have set up a system of data structures where there are pairs and values, and some values are complex types which can include other simple and complex types.
 * In layperson terms

Permitted Keyname characters
A key (key name) is a sequence of unicode characters with a maximum size of 511 bytes. Control characters ( 0..31) and the space character (ASCII 32) are not permitted. Uppercase ASCII characters (ASCII 64..89) are not permitted. The open-brace character (ASCII 123) is not permitted as the first character of a key. The close-brace character (ASCII 125) is not permitted.

For future compatibility, it is strongly recommended that implementations limit keys to the following set of characters when constructing an config.txt compliant with this ACS Text file standard. Implementations 'must accept all valid characters when parsing an ACS Text file.

{{TextBox|Note these key omissions: '\', ':', ';', '`', '~',, '@', '*', '#', '$', '%', '^', '&', '{', '[', ')', ']' }}
 *  'a' .. 'z'</tt>
 * <tt> '0' .. '9'</tt>
 * <tt> '-'</tt>
 * <tt> '/'</tt>
 * <tt> '_'</tt>

Values
Each value may include zero or more UTF-8 characters. Several types of value are available with unique encodings. Value types are automatically identified based on the and/or contents of the value, no type information is written into the file.



Null Value
A null value is literally a zero-length value.

<null-value> ::= [ ] ;

Numeric Values
A numeric value is an integer or decimal representation.



Numeric Array Values
A numeric array value is a sequence of multiple numbers, separated by commas.

<array-separator> ::= [ ] "," [ ] ; <numeric-array-value> ::= <array-separator> { <array-separator> } [ ] ;

String Values
A string value is a sequence of zero or more UTF-8 characters, surrounded by quotation marks (ASCII 34.) The allowed occurences of the double quote character (ASCII 34) ('"'), the Colon (':'), the forward slash (ASCII 47) ('/'), and the backslash character (ASCII 92) ('\') are tightly proscribed .  All are Forbidden as part of a string value except when that value is a Windows OS, and technically, such parameters are Strings not String Values, which are simple terms by comparison. {{TextBox
 * 1= Examples: Some Road intersections can auto-reskin, by selection of an enumerated  string value numeric  indexing the appropriate texture library asset. The term {{{'}}string value numeric{{'}} simply means it is a number field passed into software as a string, because the software for determining a type and size of a data element is more complicated than saying enter numeric data in between quotes.

In short, it simplifies intake and communication of values.{{BullR}} Others, may just take a name, in signs and general buildings, and most often older Train Station models. {{BullR}} Conversely, some assets use string value passing of values to control things far more complex, such as the mix of numerics and textual values used to set up the late Andi06's invisible Train Stations where numbers define platform passenger limits, starting numbers, and station names just like every interactive station since TR2004 but also: platform height, platform curve, platform length (Being invisible, it has to be covered by a spline or blocky object that matches), Number of tracks and their designations (in some), and no one likes simulated passengers floating over the rails of a curving track, nor those standing ankle deep in paving, or hovering 6-10 inches above the platform decks.}} The below real world snippet has several good examples. Firstly, notice that the real string values are used to define VARIABLES in the TRAINZ data model&mdash;which can also be classed as values the programmers and program code are concerned with. Their role, is in fact, to pass information to that code to affect operations, either in digital models appearance, but also in digital models behavior if the asset is in some way programmable.

{{LeftBox|W=58%|clear=none|1= load4 {   size                                2 initial-count                      0 attachment-points {     0                                 "a.gen_goods2" 1                                "a.gen_goods9" }   allowed-products {     0                                 <kuid:57344:10003> }   conflicts-with-queues {     0                                 "load0" 1                                "load1" 2                                "load2 " 3                                "load3" } } } }} The Load containers and subcontainers above are ALL STRING VALUES, and NONE are supposed to follow STRING processing RULES. In fact, one above here (and a second in this asset in a related subcontainer) is FAULTY and won't load in Trainz because it breaks the string value processing routine's parsing rules... can you spot it? Answer given below in this NOTE

Strings
Strings, are distinct from String Values &mdash; both are enumerated values of a different nature, ... their context and expectable lengths &mdash; by the coding (or rules, algorithms whatever) that are applied to them which may be extended over multiple lines are Strings. ''Key being the length, allowed, and the prohibition of the String Values above to incorporate/enclose newlines and terminal whitespace characters of any kind. Strings may continue over multiple lines and may include whitespace (including the newline or CR-LF ASCII EOL sequence) and terminating whitespace characters (Spaces or Tabs) before the close-quote. The delimiting value is the enclosing quote marks.''

<string-value> ::= <double-quote> { <string-character> } <double-quote> [ ] ;

String Values refinements
Trainz does not directly prohibit the colon, the forward slash and back slash characters but Windows does, so any pathspec with any of the three has to refer to a directory hierarchy. Concurrently, Trainz won't allow certain characters in filespecs, which Windows would be perfectly happy to utilize in folder or file names. (.e.g. '/', '\', '(' and ')' (parenthesis) can be part of s and when that is true, their folders will never have them in the OS foldernames when opened for edit, but substitute an underscore '_'.  In reading files, Trainz's CM's also have fits if a filename includes the semi-colon: ';', but will tolerate it as part of a intake (originating) folder name) like: <tt>"File kuid2 56063 101000 1;v2-1;Boxcar traincar;40ftBoxcar_LehighValley1000_LARS-aRus"</tt> (Just now plucked from archive folder's name on this system.)

KUID Values
A KUID value is a single KUID in a kuid valid format.

<kuid-value> ::= <KUID> [ ] ;

Container Values
A container value nests additional key-value pairs over multiple lines.

<container-value> ::= [ <EOL> ] "{" <EOL> { <key-value-pair> } <line-start> "}" ;

Key Ordering
The 'ACS Text Format' is technically an unordered key-value soup, however all existing implementations are order-preserving for trivial (read, write) operations. It is recommended that future implementations maintain this convention.

Format Violations
The effect of a format violation detected during parsing is undefined. An implementation which follows this specification must not generate a file which violates any aspect of this specification.