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 檔案進行編輯時，它們佔據了檔案的首行。

基本檔案結構

在程式設計師術語中

'鍵'（或 '關鍵字'）是一個“特定”的人類和機器可讀的 '識別符號'， 特別是屬於一組此類法律上可指定的識別符號的獨特或列舉的性質。這些鍵是用於將含義從人類翻譯成機器 CPU 的詞法識別符號。如果該術語不合法，機器的軟體就無法解釋和賦予拼寫（或拼錯）術語的意義。^{[note 1]} 一個簡單的現實是，如果一個術語拼錯了，計算機就無法匹配值，並且不知道如何處理該結構（行）。這是一個故障或錯誤，通常會導致處理停止，或者至少會生成一個記錄術語不匹配的列表。
一個 '值'——這些通常是嚴格定義的型別，從基本的機器相關資料元素到這些元素的組合形成更復雜的資料型別。例如，在某些編碼方案中，字元是一個簡單的 8 位位元組值，但在 Unicode 中是兩個位元組序列。字串是陣列中的一系列字元。顯然，後者的尺寸是字元位元組數為單位元組的字串的兩倍。
'無序'列表是可以重新排列而不會對含義造成不利影響的資料行。——您將很快在 Trainz 配置檔案中看到，一個標籤或容器可以出現在其適當容器內的任何位置，配置就是一個這樣的容器，它包含其他容器。資料出現順序與它被列出和讀取的時間無關。
'處理範圍'——意味著在特定情況的瞬時子程式、子例程或處理程式中（即某些預測和處理的上下文'，因此特定'過程'）
"ACS 文字檔案包含一個無序的鍵值對列表。在任何給定的處理範圍中，每個鍵必須是唯一的。"

透過這種方式，N3V 程式設計師的意思是某些標籤名稱對於特定的種類或容器並不唯一，但它們在這些上下文中被重複使用，並被上下文合理地視為唯一，並且上下文處理軟體（處理這種容器及其值的子例程）知道它正在做什麼，並且它不是那個其他合法上下文的另一個 L-value - R-value 合法對。新使用者應該收藏並經常參考標籤和容器索引表以及其中的父子關係。
為了舉一個具體的和常見的例子：今天，標籤 'region' 是一個配置容器（配置檔案）合法值，但僅在地圖種類資產中（大約從 V2.5 - V2.7，TR06 時代開始），因此它被分組在 KIND 地圖內，以及其他特定於或需要定義地圖的標籤。此外，還將體驗到其他配置容器，它們也具有 region 作為合法標籤名稱，但將具有較少的 TBV。也就是說，如果配置/資產更新為更高的 TBV，'region' 將生成一個錯誤，而不是一個警告。
也就是說，較舊的內容使用現在是非法字串值作為 R-value，例如 'United Kingdom'、'United States' 或 'Australia'，幾乎出現在當時的所有種類的資產中——但在更高的 TBV 中，在 TR06 之後——會產生錯誤訊息，因為關鍵字現在僅在地圖配置容器內合法，該容器需要一個指向區域種類的 KUID，該種類定義諸如基準（中心）緯度、經度、半球、水色、基準海拔、預設道岔槓桿以及特定於區域和時期的道路車輛列表，因此（哎呀！）來自 2021 年的義大利或俄羅斯汽車不會出現在 1925 年的北美道路上（哎呀！）或冬季、秋季和春季都將無法使用，因為“密歇根州的地圖資料夾”被錯誤地放置在赤道以南的某個地方（哎呀！）而日出和日落反映了該區域，而不是美國北部。哦，我的天哪，哎呀！

技術極客語言...: 這裡的棘手短語是 N3V 維基源頁面（連結在頁面底部的下方）的直接引述；我們希望解釋和定義短語能使極客語言變得易於理解和理解，以便外行人能夠內化含義並使含義變得“熟練”和“可控”。

關於所謂的上下文無關語法，針對外行讀者

EBNF 字串 '::=' 是通用賦值運算子，將右側的值（'R-value'）分配給左側的術語（變數鍵或關鍵字）（'L-value'）。（這主要是因為主要語言之間對賦值和等號運算子的解釋存在差異。^{[note 2]})

在下面的抽象中， '|' (管道字元) 用於表示布林 'OR' 運算子，因此下面定義一般鍵的定界符（分離運算子）的第一行可以翻譯為

'單個空格' 定界符由空格或製表符字元在 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 年就開始程式設計，即使我的眼睛也因閱讀和試圖理解它而變得模糊……所以我們在這裡在華夏公益教科書中為您編寫！)

需要注意的是，在某些情況下，<value> 可能跨越多行。在 Trainz 中，值總是用雙引號（" 字元）或成對的大括號字元：'{' 和 '}' 分隔。Trainz 值也可以是未定義的或 NIL。演示這些的資產通常是可選的，一些是較新的標籤，較新的軟體將為較舊的內容設定預設值，而這些內容在最初版本的那天沒有選擇。
將 '[' ... ']' 翻譯為可選。
N3V 的標準陳述為 <acs-text-file> ::= [ <unicode-bom> ] { <key-value-pair> } <line-start> ;
1. 以空白行開頭，或者（可選地……）以包含 Unicode 位元組順序標記的行開頭^{[note 3]}

以外行人的術語

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 OS 路徑規範，從技術上講，此類引數是字串，而不是字串值，與之相比，字串值只是簡單的術語。

示例： 一些道路交叉口可以透過選擇列舉的字串值數字來自動重製皮膚，該數字索引相應的紋理庫資產。術語{'字串值數字' 只是意味著它是一個傳遞給軟體的數字欄位，因為確定資料元素型別和大小的軟體比在引號之間輸入數字資料要複雜得多。

簡而言之，它簡化了值的輸入和通訊。
• 其他一些可能只是在標誌和一般建築物中使用名稱，而且通常是較舊的火車站模型。
• 相反，一些資產使用字串值傳遞值來控制更復雜的事物，例如用於設定已故 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 中載入，因為它破壞了字串值處理例程的解析規則……你能發現它嗎？答案在下面的注意中給出^{[注意 4]}

字串

字串不同於字串值——兩者都是本質不同的列舉值……它們的上下文和預期長度——透過應用於它們的編碼（或規則、演算法等等），這些編碼可以擴充套件到多行，這些都是字串。關鍵在於長度、允許和禁止上面提到的字串值包含/包含換行符和任何型別的終止空格字元。字串可以跨越多行，並且可以包含空格（包括換行符或 CR-LF ASCII EOL 序列）和終止空格字元（空格或製表符）在結束引號之前。分隔符是包含的引號。

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

字串值細化

Trainz 不會直接禁止冒號、正斜槓和反斜槓字元，但 Windows 會禁止，因此任何包含這三個字元的路徑規範都必須引用一個目錄層次結構。^{[注意 5]} 同時，Trainz 不允許在檔案規範中使用某些字元，而 Windows 則可以很樂意地在資料夾或檔名中使用這些字元。（例如， '/', '\', '(' 和 ')'（括號）可以是使用者名稱的一部分，當這種情況發生時，它們的資料夾在開啟編輯時永遠不會在 OS 資料夾名中包含它們，而是用下劃線'_' 代替。在讀取檔案時，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 文字格式”從技術上講是無序的鍵值對，但是所有現有的實現都為簡單的（讀寫）操作保留了順序。建議未來的實現保持這種約定。

格式違規

在解析期間檢測到的格式違規的效果未定義。遵循此規範的實現不得生成違反此規範任何方面的檔案。

此參考頁面改編自TrainzOnline Wiki，根據CC-BY-SA 3.0 許可證。此頁面可能比同一主題的源頁面包含更多文字解釋、說明、歷史和/或示例。

TrainzOnline Wiki 在很大程度上由程式設計師或精通內容創作者維護，並且可能包含有關當前trainz-build 程式碼標準的更新資訊，這些標準隨著軟體功能的新增而不斷變化。

[note 1]

[note 2]

[note 3]

[注意 4]

[注意 5]

[注意 6]