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-value - R-value 法律对。新用户应该将书签并经常参考 标签和容器索引表 以及其中的父子关系。
• 举一个具体且常见的例子：今天，标签 'region' 是一个配置容器（配置文件）合法值，仅在 种类地图 资源（自 ca. V2.5 - V2.7，TR06 时代以来）中，因此它被分组在 KIND 地图中，与其他特定于或需要定义地图的标签一起。此外，您将遇到其他配置容器，它们也有 'region' 作为合法标签名称，但其 TBV 较少。也就是说，如果配置/资源更新到更高的 TBV，'region' 将生成一个故障而不是一个警告。
• THAT，旧内容使用现在非法的字符串值作为 R-value，如 'United Kingdom'、'United States' 或 'Australia'，几乎在当时的每一种资源类型中 - 但在 TR06 之后的更高 TBV 中 - 会产生故障消息，因为关键字现在仅在需要 kuid 到 种类区域 的地图配置容器内合法，该容器定义了诸如基准（中心）纬度、经度、半球、水色、基准高度、默认连接杆、以及特定于区域和时期的道路车辆列表，因此（哎呀！）2021 年的意大利或俄罗斯汽车不会出现在 1925 年的北美道路上（哎呀！）或冬季、秋季和春季都会被烤焦，因为 "密歇根州的地图文件夹" 被错误地放置在赤道以南的某个地方（哎呀！）并且日出和日落反映了该区域，而不是美国北部。哦 - 我的 OOooops!

 

技术极客语言...

这里的狡猾短语是 N3V Wiki 源页面的直接引述，该页面链接到页面底部的页面；我们希望解释和定义短语能让极客语言变得易于理解和理解，以便外行人能够内化其含义并将含义 '掌握' 和 '可控制'.

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

• EBNF 字符串 '::=' 是一个通用赋值运算符，用于将右侧的值（'R-value'）分配给左侧的术语（变量键或关键字）（'L-value'）。（这主要是因为主要语言之间对赋值运算符和等号运算符的不同解释。）
  

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

名为 'singlespace' 的分隔符由 空格 或 制表符 组成，它们在 ASCII 代码中都有定义。这些分隔符可以被聚合（添加到一个合理的长度）并用 EBNF 关键字 '<whitespace>' 表示。（在 Trainz 中，打开编辑的资源一般会在 L-value 和 R-value 参数之间显示许多空格（'空白填充'），这样 R-value 的第一个字符就会与解压缩的 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 年就开始编程了，即使是我的眼睛也因为阅读和试图理解它而变得模糊不清......所以我们在这里在维基教科书中为你写作！）

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 中创建键名或标签。普通用户不需要处理这些，但内容创作者，特别是脚本编写者可以、确实需要，并且可能会这样做。

• 尽管如此，这些禁止事项也扩展到文件名，因此，如果你创建的 用户名 违反了此标准，则很可能在验证时失败。但如果你喜欢错误消息，那就尽管去尝试吧！

一个键（键名）是由一个最多 511 字节的 Unicode 字符序列组成。控制字符（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> ] ;

字符串值

字符串值是由零个或多个 UTF-8 字符组成的一个序列，这些字符被引号（ASCII 34）包围。双引号字符（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 会禁止，因此任何包含这三个字符中的任何一个的路径规范都必须引用目录层次结构。 同时，Trainz 不会在文件规范中允许某些字符，而这些字符在 Windows 中可以完美地用作文件夹或文件名。（例如， '/', '\', '(' 和 ')'（括号） 可以是 用户名 的一部分，当为真时，它们的文件夹在打开编辑时永远不会在操作系统文件夹名中包含它们，而是用下划线 '_' 替换。在读取文件时，Trainz 的 CM 如果文件名包含分号：';' 也会出现问题，但会容忍它作为输入（源）文件夹名的一部分），例如"File kuid2 56063 101000 1;v2-1;Boxcar traincar;40ftBoxcar_LehighValley1000_LARS-aRus"（刚刚从此系统上存档文件夹的名称中提取。）

KUID 值

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

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

容器值

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

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

键排序

'ACS 文本格式' 技术上是一个无序的键值组合，但是所有现有的实现都保留了用于简单（读、写）操作的顺序。建议未来的实现保持此惯例。

格式违规

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