Trainz/refs/ACS 文本格式

Trainz 培训基础

TOC | 开始 | 乐趣 | AM&C | 创作 | 书中参考文献 | ORP 参考文献:  • 索引 • 容器 • 种类 • 标签 | 附录  • 版本

词汇表

HKeys-CM

HKeys-DVR

HKeys-SUR

HKeys-WIN

鼠标使用

符号

ACS 文本格式 是 Auran 定义的国际语言支持的文本格式，用于存储 config.txt 文件 和其他通用键值数据。在最简单的层面上，ACS 文本文件是使用 UTF-8 编码的标准文本文件。

历史上，ACS 文本文件必须以 Unicode BOM 序列（字节顺序标记）开头，这通常由导出器或导入器模块在创建资产的过程中初始化。然而，尽管这通常仍然建议，但从 2005 年发布的 TRS2006 以及放弃将 GMAX 与 Trainz 捆绑在一起的做法以来，这不再是严格的要求。 但是，许多 BOM 代码行会在许多下载的旧资产的 config.txt 文件中被注意到，当资产及其 config.txt 打开以进行编辑时，它们会作为占据文件第一行的不可见代码出现。

基本文件结构

用程序员的行话

1. '键'（或 '关键字'）是'特定' 的人类和机器可读 '标识符'， 特别是属于 一组 这样的独特或 枚举 的性质的唯一或 枚举 的性质的'特定' 的人类和机器可读 '标识符'， 特别是属于 一组 这样的合法可指定的 标识符。这些键是用于将含义从人类翻译到机器 CPU 的词法标识符。如果该术语不合法，机器的软件就无法解释和赋予该拼写（或拼写错误）术语任何含义。 一个简单的现实是，如果一个术语拼写错误，计算机将无法匹配该值，并且不知道如何处理该结构（行）。这是一个错误，通常会导致处理停止，或者至少会生成一个记录术语不匹配的列表。
2. '值' - 这些通常是严格定义的类型，从基本机器依赖的数据元素到这些元素的组合，形成更复杂的数据类型。例如，在某些编码方案中，字符是简单的 8 位字节值，但在 Unicode 中是两个字节序列。字符串是数组中字符的连续序列。显然，后者的长度是字符长度的两倍，因为字符的长度是单个字节。
3. '无序' 列表是数据行，可以重新排列而不会影响含义。- 您将很快在 Trainz 配置文件中看到，一个标签或容器可以出现在其适当容器内的任何位置，配置本身就是一个这样的容器，它包含其他容器。数据出现的顺序与它被列出和读取的顺序无关。
4. '处理范围' - 指在特定情况的瞬时子程序、子例程或处理程序中（即一些预测和处理的上下文'，因此是一个特定的'过程'）
5. "ACS 文本文件 包含无序的键值对列表。在任何给定的处理范围内，每个键必须是唯一的。"  

• 通过这种方式，N3V 程序员的意思是某些标签名称对特定的 种类 或 容器 不是唯一的，但在这些上下文中被重复使用，只要在上下文中合理地唯一，并且上下文处理软件 - 处理此类容器及其值的子例程，知道它在做什么，并且它不是该其他合法上下文的其他 L 值 - R 值合法对。新用户应该将书签添加到 标签和容器索引表 并经常参考该表及其中的父子关系。
• 举一个具体且常见的例子：今天，标签'region' 仅在 kind 地图 资产中是配置容器（配置文件）的合法值（自大约 V2.5 - V2.7，TR06 时代以来），因此它被分组在 KIND 地图内，与其他特定于或需要定义地图的标签一起。此外，您将遇到其他配置容器，这些容器也使用'region' 作为合法标签名称，但将具有较低的 TBV。也就是说，如果配置/资产更新到更高的 TBV，'region' 将生成一个错误而不是一个警告。
• 因此，旧内容使用现在非法的字符串值作为 R 值，如'United Kingdom'、'United States' 或'Australia'，这些值几乎出现在当时的每个种类资产中 - 但在 TR06 之后的更高 TBV 中会产生错误消息，因为该关键字现在仅在需要指向 kind 地区 的地图配置容器内合法，该地区定义了诸如基础（中心）纬度、经度、半球、水色、基础海拔、默认交叉口杠杆以及区域和时期特定的道路车辆列表之类的事物，因此（哎呀！）2021 年的意大利或俄罗斯汽车不会出现在 1925 年的北美道路上（哎呀！）或者冬季、秋季和春季都会消失，因为“密歇根的地图文件夹”被错误地放置在赤道以南的某个地方（哎呀！）日出和日落反映了该地区，而不是美国北部。哦，我的天哪，哎呀！

 

技术极客话...

这里的棘手短语是 N3V Wiki 源页面的直接引述，该页面链接到页面底部的链接；我们希望解释和定义短语能让极客话变得易懂，这样外行人就可以内化其含义，并将含义'掌握' 和'可控制'。

对于'程序员' 所谓的上下文无关语法，供外行读者阅读

• EBNF 字符串 '::=' 是通用赋值运算符，用于将右侧的值（'R 值'）赋予左侧的术语（变量键或关键字）（'L 值'）。（这主要是因为赋值和相等运算符在主要语言之间存在不同的解释。）
  

在下面的抽象中， '|' (管道字符) 用于表示 布尔'或' 运算符，因此下面定义一般键定界符（分隔运算符）的第一行可以翻译为

'单空格' 定界符由 空格 或 制表符 字符在 ASCII 代码中定义。这些可以被聚合（添加到合理长度），作为 EBNF 键 '<whitespace>'。（在 Trainz 中，打开以进行编辑的资产通常显示为在 L 值和 R 值参数之间具有许多多个空格（'空白填充'），使得 R 值在解包的 config.txt 文件中与它们在第 41 列的第一个字符对齐。）

键值对可以在 扩展巴科斯范式 (EBNF)（元语法，形成上下文无关文法）中声明，如下所示

• 观察以下从上到下的链，定义了以下行中出现的术语或语法... 整个链是独立的。

<singlespace> ::= ' ' | <TAB> ;
<whitespace> ::= <singlespace> | { <singlespace> } ;
<line-start> ::= { <whitespace> | <EOL> } ;
<key-value-pair> ::= <line-start> <key> <whitespace> <value> <EOL> ;
<acs-text-file> ::= [ <unicode-bom> ] { <key-value-pair> } <line-start> ;

• （我从 1976 年就开始编程了，即使是我的眼睛也无法理解和试图理解它... 所以我们在这里在 Wikibook 中为你编写！）

1. 需要注意的是，在某些情况下，<value> 可能会跨越多行。在 Trainz 中，值始终由双引号（" 字符）或一对花括号字符：'{' 和 '}' 限定。Trainz 值也可以是未定义或 NIL。展示这些特性的资产通常是可选的，一些是较新的标签，较新的软件会为较旧的内容默认使用这些标签，而这些标签在较旧版本中不存在。
2. 将 '[' ... ']' 翻译为可选。
3. N3V 的标准陈述为 <acs-text-file> ::= [ <unicode-bom> ] { <key-value-pair> } <line-start> ;
   1. 以空白行开头，或（可选...）带有 Unicode 字节顺序标记的行

用通俗的语言来说

Auran/N3V 已经建立了一个数据结构系统，其中包含对和值，而一些值是复杂类型，可以包含其他简单和复杂类型。

这些称为 数据结构，例如 结构体、联合体 或 数组，在许多语言（尤其是 C 语言 派生的 计算机语言）中 - 通常在 Trainz 中被简单地归类为 '容器'。当看到一个容器包含另一个容器时，你正在处理一个结构，其中一部分是另一个结构类型，例如数组（例如乘客列表产品类型）或转向架（卡车，指定轮子、X、y、z 安装点系数、安装类型等，但所有与其他因素相关的数据都被 '分组在一起'，因为它一起使用，这也是我们人类思考它的最佳方式。）

允许的键名字符

本节指的是在 Trainz 中创建键名或标签。普通用户无需处理这些，但内容创作者，尤其是脚本编写者，可以、会并且很可能会处理这些。

• 尽管如此，这些禁止事项也扩展到文件名，因此创建违反此标准的 用户名 可能会导致验证失败。但是，如果你喜欢错误消息，就继续吧！

键（键名）是 unicode 字符序列，最大大小为 511 字节。控制字符（ASCII 0..31）和空格字符（ASCII 32）不允许使用。大写 ASCII 字符（ASCII 64..89）不允许使用。左花括号字符（ASCII 123）不允许作为键的第一个字符。右花括号字符（ASCII 125）不允许使用。

为了未来的兼容性，强烈建议实现者在构建符合此 'ACS 文本文件标准的 config.txt 时，将键限制在以下字符集。实现者必须在解析 ACS 文本文件时接受所有有效字符。

• 'a' .. 'z'
• '0' .. '9'
• '-'
• '/'
• '_'

注意这些关键的遗漏'\', ':', ';', '`', '~',, '@', '*', '#', '$', '%', '^', '&', '{', '[', ')', ']'

值

每个值可以包含零个或多个 UTF-8 字符。有几种类型的值可用，它们具有独特的编码。值类型会根据 标签 和/或值的内容自动识别，文件中不会写入任何类型信息。

<value> ::= <null-value> | <numeric-value> | <numeric-array-value> | <string-value> | <kuid-value> | <container-value> ;

警告：  除了多行未处理的文本块标签，例如 description 和 license，任何包含字符串值的标签都不允许包含尾随 空格 字符。 这会导致警告和错误消息，例如 错误：在 'mocrossing' 中没有为标签 'category-region' 选择任何内容。 警告：'US ' 不是标签 'category-region' 的有效值（这是写入的： "US "，错误消息中添加了单引号）。此标签现在为空，必须选择新的值。

空值

空值实际上是一个零长度的值。

<null-value> ::= [ <whitespace> ] ;

数值

数值是整数或十进制表示。

<number> ::= [ "-" ] <digit> { <digit> } [ "." <digit> { <digit> } ] ;
<numeric-value> ::= <number> [ <whitespace> ] ;

数值数组值

数值数组值是由逗号分隔的多个数字的序列。

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

字符串值

字符串值是由双引号（ASCII 34）包围的零个或多个 UTF-8 字符的序列。双引号（ASCII 34）('"')、冒号（':'）、正斜杠（ASCII 47）('/') 和反斜杠字符（ASCII 92）('\') 的允许出现受到严格限制。所有字符都被禁止作为字符串值的一部分使用，除非该值是 Windows 操作系统的 路径规范，从技术上讲，此类参数是字符串而不是字符串值，与之相比，字符串值只是简单术语。

示例： 一些道路交叉口可以通过选择枚举的字符串值数字来自动重构皮肤，该数字索引了相应的纹理库资产。{'字符串值数字' 只是意味着它是一个作为字符串传递给软件的数字字段，因为用于确定数据元素类型和大小的软件比在引号之间输入数字数据要复杂得多。

简而言之，它简化了值的输入和通信。
 • 其他值可能只接受一个名称，例如在标志和普通建筑物中，以及大多数情况下，较旧的火车站模型。
 • 相反，一些资产使用字符串值传递来控制更复杂的事物，例如用来设置已故 Andi06 的不可见火车站的数字和文本值的混合，其中数字定义了站台乘客限制、起始号码和车站名称，就像自 TR2004 以来每个互动车站一样，但也包括：站台高度、站台曲线、站台长度（由于它是不可见的，因此必须用与之匹配的样条线或块状物体覆盖）、轨道数量及其指定（在某些情况下），没有人喜欢模拟乘客漂浮在弯曲轨道的铁轨上，也不喜欢那些站在铺路中的脚踝深度，或悬浮在站台甲板上方 6-10 英寸。

以下真实世界的片段包含几个很好的例子。首先，请注意，真正的字符串值用于在 TRAINZ 数据模型 中定义变量 - 这些变量也可以归类为程序员和程序代码关心的值。它们的作用实际上是将信息传递给该代码以影响操作，无论是数字模型的外观，还是数字模型的行为，如果该资产以某种方式是可编程的。

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"
   }
 }

}

上面的加载容器和子容器都是字符串值，并且都不应该遵循字符串处理规则。事实上，上面的一个（以及此资产中相关子容器中的另一个）是有缺陷的并且无法在 Trainz 中加载，因为它违反了字符串值处理例程的解析规则... 你能找到它吗？答案在下面此注释 中给出。

字符串

字符串与字符串值是截然不同的——它们都是枚举值，但本质不同，... 它们的上下文和预期长度——由应用于它们的编码（或规则、算法，无论什么）来决定，这些编码可能跨越多行，这些都是字符串。关键在于长度、允许的字符，以及上面提到的字符串值中禁止包含/封闭任何形式的新行符和终端空格字符。字符串可以跨越多行，并且可以包含空格（包括换行符或 CR-LF ASCII EOL 序列）和闭合引号前的终端空格字符（空格或制表符）。分隔值是封闭的引号。

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

字符串值细化

Trainz 不直接禁止冒号、斜杠和反斜杠字符，但 Windows 会禁止，因此任何包含这三个字符的路径规范都必须引用目录层次结构。^{[注 5]} 同时，Trainz 不允许在文件规范中使用某些字符，而这些字符在 Windows 中可以完美地用于文件夹或文件名。(例如， '/', '\', '(' and ')' (括号) 可以是 用户名 的一部分，如果真是这样，它们的文件夹在打开编辑时永远不会在操作系统文件夹名中包含它们，而是用下划线 '_' 代替。在读取文件时，Trainz 的 CM 也会在文件名包含分号时出现问题：';'，但会容忍它作为接收（源）文件夹名的一部分，例如"File kuid2 56063 101000 1;v2-1;Boxcar traincar;40ftBoxcar_LehighValley1000_LARS-aRus"(刚刚从该系统上的存档文件夹名称中提取。^{[注 6]})

KUID 值

KUID 值是 kuid 有效格式 中的单个 KUID。

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

容器值

容器值在多行上嵌套额外的键值对。

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

键排序

“ACS 文本格式”在技术上是无序的键值对集合，但是所有现有实现对于简单（读取、写入）操作都是保持顺序的。建议未来实现保持这种约定。

格式违规

在解析期间检测到的格式违规的影响是未定义的。遵循此规范的实现不得生成违反此规范任何方面的文件。