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 文字格式”在技術上是無序的鍵值對集合，但是所有現有實現對於簡單（讀取、寫入）操作都是保持順序的。建議未來實現保持這種約定。

格式違規

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