<markdown>
# OBJ 模型相關適配

NTE 支持通過資源包添加以 OBJ 格式模型文件為模型的列車。


## 基本格式

通過 NTE 使用 OBJ 列車模型時，在 `mtr_custom_resources.json` 文件中的寫法與使用 BBMODEL 並無不同。

```json
{
  "custom_trains": {
    "lu1995": {
      "name": "LU 1995",
      /* ... 其他配置和使用 BBMODEL 時相同，省略 */
      "texture_id": "mtrsteamloco:textures/block/nte_tile_faded.png",
      "model": "mtr:lu1995/modeltrain_1995_tube_train.obj",
      "model_properties": "mtr:lu1995/properties.json"
    }
  }
}
```

- `model`: 填入 OBJ 文件的資源位置，這和使用 BBMODEL 時區別不大。
- `model_properties`: 填入模型屬性文件的資源位置。
- `texture_id`: 替換貼圖的資源位置。

您使用的 OBJ 文件應當符合：相對於列車出庫時的前進方向，X 軸正方向向右，Y 軸正方向向上，Z 軸正方向向後。每個單位長度為 1m。

注意：所有文件名都需要是全小寫，文件名只可有 a-z、0-9、`-`、`_`。

## 示例文件

一個示例資源包可在 [此處](assets/mtrnte-example.zip ':ignore') 下載。

## 部件

OBJ 中可以有 **分組 (部件)** 信息，如門和車身處於不同分組 (部件)，使得可以通過選擇部件進行移動來讓開門時門獨立於車身移動。OBJ 文件可以使用任意文本編輯軟件（如記事本、Notepad3、VSCode）等打開查看內容。其中，`mtllib` 指令設置這個 OBJ 文件所使用的 MTL 文件，`g` 指令設置分組 (部件)，`usemtl` 指令設置面和材質的對應關係。大多建模軟件導出 OBJ 時可選擇一併導出分組信息。

OBJ 內的部件會被自動解析，然後即可在模型屬性文件裡使用。這和 BBMODEL 內的部件用法相同。

注意：只支持 OBJ 的分組 (`g`) 指令，不支持對象 (`o`) 指令。如果您的建模軟件導出的模型中有 "o "(o 後面一個空格) 開頭的行的話，請您把它全部換成 "g "(g 後面一個空格)。


## 模型屬性

MTR 有一個 **模型屬性** JSON 文件，裡面可指定哪些部件在開門時要移動、還可以指定哪些部件只在第幾號車顯示、哪些部件只在門開時顯示等信息，來實現開門動畫、門燈、及頭尾車顯示車頭的部件中間車不顯示車頭的部件等功能。

可以使用 MTR 自帶的資源包創建器來編輯模型屬性文件。在資源包創建器的選項中，點擊 "Blockbench 文件" 右側的 "上傳"，然後拖入您想使用的 OBJ 文件即可。如果想進一步編輯已有的屬性文件，可選擇屬性文件，否則留空即可。

您可以看到您上傳的 OBJ 模型及其包含的部件。您可對部件進行選擇，並進行門動畫等設置。您可能發現您的 OBJ 模型是沒有貼圖的白色，這是正常現象，在資源包創建器中 NTE 不加載貼圖。

**請您預先合併部件，如將所有不動的部件合併為一個。部件越多性能越差。**

編輯完成後，請到選項中任意選擇一張圖片作為紋理文件，然後點擊 ''導出資源包"。您可在導出的壓縮包中找到模型屬性文件。它是在內部一個文件夾裡，和一個 BBMODEL 文件同一級下的一個 JSON 文件。

注意：此處導出的資源包只能用於獲得模型屬性文件。其內容不全，不可在 Minecraft 中使用。


## 貼圖

由於歷史遺留問題，OBJ 模型分為多個部分。`.obj` 文件保存著對象的幾何形態、各個 **部件**、及要顯示的面到 **材質** 的對應關係， `.mtl` 文件保存著各個 **材質** 到 **貼圖** 路徑信息的對應關係，而 `.png` 文件（下稱貼圖）是要使用的 **貼圖**。每個面有一個材質名稱，而每個材質有一個貼圖文件名和一個顏色屬性，還請對這兩者予以區分。

MTL 文件也可以使用任意文本編輯軟件打開。其中，`newmtl` 創建材質，`Kd` 設置材質顏色，`d` 設置材質透明度，`map_Kd` 設置材質對應的貼圖。大多建模軟件可選擇在導出 OBJ 的同時導出 MTL 文件。

如果 OBJ 內有 `mtllib` 指令（多數建模軟件在導出時選中導出 MTL 會自動添加）的話，會自動解析對應的 MTL 文件。會自動解析相對路徑，在 OBJ 裡的 `mtllib` 處不需要也不支持寫完整的 `mtr:……` 資源位置。

和 BBMODEL 只能使用一張貼圖不同，MTL 文件本身就有設置貼圖的功能。NTE 使用以下方法為模型設置貼圖：

- 如果 OBJ 模型內沒有 `mtllib` 指令，NTE 將把材質的名稱作為貼圖文件名稱。如此時一個叫作 `mat1` 的材質就會使用 OBJ 同目錄下的 `mat1.png` 作為貼圖。特別地，名為 `_` 的材質將會被設為全白。

  這個特性允許您不用 MTL 文件（如您感覺多個文件較礙事）。

- 如果 OBJ 模型內有 `mtllib` 指令，將根據 MTL 內對應材質的 `map_Kd` 設置貼圖（使用建模軟件導出 MTL 時通常就會對應地設置好它）。如此時 OBJ 內有 `mat1` 的材質，MTL 內寫著 `mat1` 有 `map_Kd 1995default.png`，那麼將會使用 `1995default.png` 給它作為貼圖。同時 MTL 內的 `Kd`、`d` 設置也會被採用。

- 您可能注意到 OBJ/MTL 裡貼圖文件都被寫死，使更換塗裝不便。為此 NTE 特別指定，如果通過上述方式使用了一個文件名為 `default.png` 的貼圖，它將被替換為 `mtr_custom_resources.json` 中 `texture_id` 的設置值，以便更換塗裝。

  如果沒有使用任何名為 `default.png` 的貼圖，那麼 `texture_id` 的設置值將被完全忽略。不過，如它不存在 MTR 會報錯，所以推薦將它設置為 `minecraft:textures/misc/white.png` 或任意的實際存在的貼圖文件。


## 渲染批量

MTR 有著 `exterior`、`interior`、`interiortranslucent`、`light` 等多個 **渲染批量**。具體來說：

- 標為 `exterior` 的面根據列車所在位置的環境亮度調整亮度，且不支持半透明（貼圖內半透明或 d 的半透明面會變全不透明）
- 標為 `interior` 的面總是全亮度（因為車內有燈麼），且不支持半透明
- 標為 `interiortranslucent` 的面總是全亮度，且支持半透明 (順帶一提，它在模型屬性文件裡叫 `INTERIOR_TRANSLUCENT`)
- 標為 `light` 的面總是全亮度，在支持的光影下有泛光效果，且不支持*任何*透明（貼圖內半透明或全透明顏色都會顯示為實心）

- NTE 額外添加了 `exteriortranslucent` ，根據列車所在位置的環境亮度調整亮度，且支持半透明
- NTE 額外添加了 `lighttranslucent` ，是 `light` 的半透明支持版。但由於原版設置此類型不寫入深度緩存（原版中用於信標光束外圍的泛光），它與稍後渲染的其他實體等之間的遮擋關係一定不正確。所以請只將其作為燈外圍的小範圍泛光效果來使用（如 NTE 自帶的 DK3/D51 的頭燈）。
- NTE 不支持 `ALWAYS_ON_LIGHT`，且不區分 `light` 和 `ALWAYS_ON_LIGHT`，即 `light` 在列車在車庫時也點亮

未設置時，缺省的渲染批量是 `exterior`。

這些渲染批量可以通過和使用 BBMODEL 時相同的方式，在模型屬性裡對部件進行設置。

特別地，為了方便建模，NTE 額外支持通過 OBJ 的材質名稱而不是 MTR 模型屬性來設置渲染批量。在材質名稱後加 `#渲染批量` 即可為使用了這一材質的面設置渲染批量。如將材質名設為 `mat1#exteriortranslucent` 將給使用 `mat1#exteriortranslucent` 這一材質的所有面添加半透明支持。這對於沒有 `mtllib` 時的情況也有效，屆時會將 `#` 之前的內容作為貼圖文件名稱。

雖然您大概不會同時使用兩種方法，在模型屬性裡對部件設置的渲染批量設置（`exterior` 之外）比通過材質名稱設置的更優先。

另外，`#` 後也可加入 `flipv=1` 來反轉材質的 V 座標。具體來說，一些建模軟件 (如 Blender) 導出時所使用的 UV 座標系可能與 Minecraft 所使用的 (原點位於左上角，V 正方向向下) 垂直方向上相反，使得貼圖倒立。您可在建模軟件導出選項中查找有無類似 “反轉 V” 的設置，如沒有也可使用這一功能來讓 NTE 替您把它扳正。這也可與渲染批量同時使用，寫法形如 `mat1#exteriortranslucent,flipv=1`。

注意：請只在確實是半透明的表面（如窗戶）上設置 `……translucent` 屬性。一方面，半透明面的渲染性能比其他的低得多；另一方面，多個半透明面之間，一個在另一個後時，它們之間的互相遮擋關係可能會不正確；而多個半透明面相交時的互相遮擋關係一定不正確。


## 不同車廂不同模型

MTR 原版中列車的所有車廂都使用同一模型，然後根據模型屬性文件的設置對於各個車顯示或隱藏車頭等特定部件，來使各車顯示外觀不同。

這不太符合 BVE/RTM 等的開發習慣，在這些平臺上各個車廂使用不同的模型。因此 NTE 對此添加了特別適配，可在 `mtr_custom_resources.json` 中的 `model` 中指定多個模型。

```json
{
  "custom_trains": {
    "lu1995": {
      "name": "LU 1995",
      /* ... 其他配置和使用 BBMODEL 時相同，省略 */
      "texture_id": "mtrsteamloco:textures/block/nte_tile_faded.png",
      "model": "mtr:lu1995/modeltrain_1995_tube_train.obj|1;%1;|mtr:lu1995/modeltrain_1995_tube_train_carriage.obj|;1,-1;|mtr:lu1995/modeltrain_1995_tube_train.obj|-1;%1,1;reversed",
      "model_properties": "mtr:lu1995/properties.json"
    }
  }
}
```

可在 `model` 處採用 "模型1|白名單1;黑名單1;額外屬性1|模型2|白名單2;黑名單2;額外屬性2" 的格式指定多個模型。其中，前一部分是模型的資源位置；後一部分是由兩個英文半角分號分隔的，對於它左側緊鄰的這一模型指定的，白名單、黑名單和額外屬性。

此寫法只能用於導入 OBJ，不能用於導入 BBMODEL 或混合使用 OBJ 和 BBMODEL。

由於 MTR 本身設計限制，各個車廂的長度不能不同。

白名單、黑名單的用法與 MTR 自身提供的模型屬性中的用法相同，對這一模型內由模型屬性文件設置了的部件生效。額外屬性設為 `reversed` 時，這一模型在加載時會被繞 Y 軸旋轉 180°，模型屬性內的車門連動亦會相應自動更新。即使某一部分為空，也需要打分號。

該特性的內部實現是通過對模型的部件改名完成的。如，通過此方法加載 `train.obj` 和 `carriage.obj` 時，設這兩個 OBJ 中均有 `body` 部件，那麼實際將把它們分別加載為 `train.obj/body` 和 `carriage.obj/body` 部件（只使用一個 OBJ 文件時就會被原樣加載為 `body` 部件）（當額外屬性設為 `reversed` 時，將加載為 `train.obj/reversed/body`）。然後，模型屬性內關於 `body` 部件的設置也會被拷貝為 `train.obj/body` 和 `carriage.obj/body`，並相應地為這兩個新的模型屬性元素設置上在 `model` 裡設置的黑白名單。

也正因如此，如果某車同時符合兩個或多個模型的黑白名單要求，那這些模型會被疊放在一起顯示。這可以用於添加轉向架模型。

由於此過程中替換了在模型屬性內設置的黑白名單，這使得模型屬性裡原先的設置不起效。如有對於某特定模型的特定部件單獨設置黑白名單的需求，這可以通過在模型屬性裡按改名後的名稱寫部件名，如添加如名為 `train.obj/body` 的元素，來解決。這樣的組名不會參與前述的改名和黑白名單覆蓋過程，它的黑白名單會被原樣保留生效。


## RTM 移植

**著作權是一項值得極大注意的問題**。大多 RTM 列車模型作者不授權其模型被用於其他用途，所以您在未獲原作者同意的前提下 **不得** 對移植後結果實施公開發布、在群組裡分享或在服務器中使用等行為。

RTM 所使用的 OBJ 或 MQO 模型與上述的相關要求有所區別，在使用前需進行編輯。MQO 模型需使用水杉建模 (Metasequoia) 編輯。

您需將過多的分組進行合併，並按照上述渲染批量相關的說明將半透明的面設置為 `……translucent` 批量。您可按需設置 `interior` 和 `light` 批量，以使得車內在夜間能亮起來。不過，RTM 的一些模型未將車內和車外的面放入不同分組，這使得設置 `interior` 批量可能有些難度。您可將車門、門燈、頭燈等放入單獨的分組以便稍後設置動畫。

導出時，需要將 MQO 轉換成 OBJ，同時將尺寸縮小到原先的一百分之一。請不要忘記勾選導出分組信息。

接下來您可創建模型屬性文件，以設置車門動畫，及按需調整門燈等元素。

RTM 中列車各車廂通常是不同的模型，因此您要對其他車廂模型也進行上述操作。由於所有模型使用同一模型屬性文件，您也要對這些模型中的相同用途部件使用相同的名稱。然後您可按照前述指引為不同車廂設置不同模型。

同時，RTM 中列車本體模型和轉向架模型是分開的。您可將轉向架模型處理後加入到多模型列表裡使其疊放，同時通過向模型屬性文件中增加相關內容來指定其放置位置。您也可在一開始處理車身模型時就把轉向架併入其中。


## 自定義顯示屏

不支持自定義顯示屏。


## BVE 移植

對於 BVE 的 CSV/ANIMATED 模型的具體支持將稍後討論添加。
</markdown>