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 的詞法識別符號。如果術語不合法，機器的軟體就無法解釋和賦予拼寫（或拼寫錯誤）的術語以意義。^{[腳註 1]} 一個簡單的現實是，如果一個術語拼寫錯誤，計算機就無法匹配該值，並且不知道如何處理該構造（行）。這是一個故障或錯誤，通常會導致處理停止，或者至少會生成一個記錄術語不匹配的列表。
一個 '值' - 這些通常是嚴格定義的型別，從基本的機器相關資料元素到將這些元素組合成更復雜的資料型別。例如，字元在某些編碼方案中是一個簡單的 8 位位元組值，但在 Unicode 中是一個兩位元組序列。字串是陣列中的一系列字元。顯然，後者的尺寸是單位元組字元字串的兩倍。
'無序' 列表是資料行，可以重新排列而不影響含義。- 您將在 Trainz 配置檔案中很快看到，一個標籤或容器可以在其適當的容器內出現的任何位置，配置本身就是一個這樣的容器，包含其他容器。資料出現順序與其列出和讀取時間無關。
'處理範圍' - 表示在該特定情況的暫時子程式、子例程或處理程式中（即一些預測和處理的上下文'，因此是一個特定的 '過程'）
"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'）。（這主要是因為主要語言之間對賦值運算子和等號運算子的不同解釋。^{[腳註 2]}）

在下面的抽象中， '|' （管道字元）用於表示布林 '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 年就開始程式設計了，即使是我的眼睛也因為閱讀和試圖理解它而變得模糊不清......所以我們在這裡在華夏公益教科書中為你寫作！）

需要注意的是，在某些情況下，<value> 可能跨越多行。在 Trainz 中，值用雙引號（" 字元）或成對的花括號字元：'{' 和 '}'，總是。Trainz 值也可以是未定義的或 NIL。展示這些的資源通常是可選的，有些是較新的標籤，較新的軟體會為較舊的內容預設使用，而較舊的內容在它的初始版本中沒有選項。
將 '[' ... ']' 翻譯為可選。
N3V 的標準規定為 <acs-text-file> ::= [ <unicode-bom> ] { <key-value-pair> } <line-start> ;
1. 以空行開頭，或（可選地......）以帶有 Unicode 位元組順序標記^{[註釋 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 作業系統路徑規範，從技術上講，這些引數是字串而不是字串值，它們是相對簡單的術語。

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

簡而言之，它簡化了值的輸入和通訊。
• 其他值可能只是獲取一個名稱，例如在標誌和普通建築物中，以及大多數較舊的火車站模型中。
• 相反，某些資源使用字串值傳遞來控制更復雜的事物，例如，用於設定已故 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 中可以完美地用作資料夾或檔名。（例如， '/', '\', '(' 和 ')'（括號）可以是使用者名稱的一部分，當為真時，它們的資料夾在開啟編輯時永遠不會在作業系統資料夾名中包含它們，而是用下劃線 '_' 替換。在讀取檔案時，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 程式碼標準的更新、更準確的資訊，這些標準有一些隨著軟體功能的新增而更改的趨勢。

[腳註 1]

[腳註 2]

[註釋 3]

[註釋 4]

[註釋 5]

[註釋 6]