<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>