自定义坐垫模型说明

1.1.3 版本以后添加了自定义坐垫模型的功能，玩家只需要通过一定方式制作资源包，在游戏内加载资源包，即可为坐垫添加更多的模型样式和材质样式。

为了方便改模和使用，采用 Minecraft 基岩版 1.10.0 JSON 文件描述的模型格式。

模型的加载是支持热重载的，你可以直接通过原版重载资源包功能对其进行热重载。

说明

• 本说明适用于 1.2.0 版本及以上 Touhou Little Maid 模组；
• 添加自定义模型需要对原版资源包结构有一定的了解；
• 需要对 JSON 格式有基本的认识；
• 推荐使用 Blockbench 3.x 版本，这是一个适用于 Minecraft 的方块、实体建模软件；
• 目前只支持 旧版本基岩版（1.10.0） 模型。使用 Blockbench 3.x 版本的玩家请注意，其默认导出的基岩版模型为 1.12.0 版本，和旧版本基岩版模型并不兼容。
• 文本编辑软件推荐 Notepad++ 或 VSCode，相关文本文件均需要用 UTF-8 无 BOM 编码进行存储。
• 不要被“坐垫”这个名称所限制，实际上你可以用它做出各种纯观赏性质的装饰物。

资源包结构

为了方便理解如何制作资源包，这里直接列出资源包的结构图

资源包文件夹   （命名随意，最好为英文）
├─pack.mcmeta   （原版的资源包描述文件，固定名称和位置）
│
└─assets    （资源文件夹，固定名称和位置，一个资源文件夹下面可以放任意多个资源域文件夹）
    └─my_model_pack  （资源域，命名随意，只要为小写英文字符和下划线即可，切记不要和已有资源域重名）
        ├─maid_chair.json   （模型包描述文件，固定名称和位置）
        │
        ├─lang   （语言文件夹，固定名称和位置）
        │    ├─en_us.lang
        │    └─zh_cn.lang
        │
        ├─models   （模型文件夹）
        │     └─entity
        │            ├─cushion.json
        │            └─wheel_chair.json
        │
        └─textures   （材质文件夹）
                 └─entity
                        ├─cushion.png
                        └─wheel_chair.png

模型包描述文件说明

游戏在加载资源包的过程中，会尝试读取所有资源域主目录下的 maid_chair.json 文件，进而确定模型加载，该文件的完整结构如下，仅标有（必须）的部分才必须要书写，你并不需要全部写出来。

本模组支持带注释的 JSON 文件，请放心使用。

{
    "pack_name": "瞎自定义的坐垫材质包", // 模型包包名（必须）
    "author": ["酒石酸", "琥珀酸"],     // 作者列表
    "description": ["默认坐垫材质包"],      // 模型包的描述文本
    "version": "1.0.3",               // 模型包的版本
    "date": "2019-08-20",             // 模型包的制作时间
    // 模型包的图标，缺失此字段，材质包将没有图标
    "icon": "touhou_little_maid:textures/maid_icon.png",
    "model_list": [{                  // 模型列表（必须，而且不能为空）
    	// 模型 id，使用原版资源格式写法（必须，资源域必须为当前所处的资源域）
    	"model_id": "touhou_little_maid:cushion",
        // 模型所在的位置，使用完整的资源地址
        "model": "touhou_little_maid:models/entity/cushion.json",
        // 模型所使用的材质位置，使用完整的资源地址
        "texture": "touhou_little_maid:textures/entity/cushion.png",
        "render_item_scale": 0.9,     // 渲染成物品形态时的模型大小        
        "mounted_height": 3,          // 坐上去的实体距离地面的高度，单位为距离地面的像素点数
        "tameable_can_ride": false,   // 女仆等可驯服生物会主动坐上去么？主要用于一些不可坐的模型
        "name": "坐垫",               // 模型名
        "description": ["只是一个普通的坐垫"], // 该模型的描述文本
        // 动画脚本，如果没有此字段，坐垫将不会拥有任何动画
        "animation": ["touhou_little_maid:animation/maid.default.js"]
    }]
}

上述案例给出了所有可用的字段，实际上只有标注（必须）的才是或不可缺的，其他部分可以省去。

为了图方便，你甚至可以这么写该文件：

{
    "pack_name": "瞎自定义的坐垫材质包", // 模型包包名（必须）
    "model_list": [{                  // 模型列表（必须）
        // 模型 id，使用原版资源格式写法（必须）
    	"model_id": "touhou_little_maid:cushion"
    }]
}

如果我们没有书写 model 字段或者 texture 字段，此时会依据 model_id 的名称调用默认位置的模型和材质。

比如上述案例中 model_id 为 touhou_little_maid:cushion，那么此时模型文件就为该资源域下的 models/entity 文件夹下名为 cushion.json 的文件，材质就为该资源域下的 textures/entity 文件夹下名为 cushion.png 的文件。

如果我们书写了 model 或者 texture 字段，那么其内容并无限制，你甚至可以调用其他模型包中的模型，只需要书写对资源地址即可。

mounted_height 为实体坐上该模型时所处的高度，单位为距离地面的像素点，可以为小数。需要注意的是坐上的生物的 X 和 Z 位置总是会在坐垫实体所处位置的正中央，请在设计模型时就预设好坐垫模型的 X 和 Z 位置。

动态图标

图标没有大小限制，支持静态图标和动态图标。

任意为 1:1 的图标均会被解析为静态图标。不为 1:1 的长图，会以 0.1 秒的间隔逐次显示，从而形成动态图效果。

提示

下图就为模组自带的图标，左侧被解析为静态图标，右侧被解析为动态图标

模型文件说明

• 本模组使用基岩版 1.10.0 JSON 文件来进行模型的加载，该文件可以通过建模软件 Blockbench 直接导出，不需要对其做任何修改。

• Blockbench 3.x 版本默认启用 1.12.0 版本基岩版模型，请在绘制前请在 文件 -> 转换工程菜单中将其转换为旧版基岩版模型。

• 模型可以进行自定义动画制作，后面的自定义动画篇章有介绍。

• 目前还不支持基岩版动画部分，后续可能会进行兼容。

• Blockbench 可以直接加载基岩版的 JSON 模型，对于二次改模也提供了很大的便捷性。

注意事项

注意

怪物几何体名字（新版本为“生物几何体名称”）必须为小写的 model，否则无法正常加载模型；

坐垫动画

最新版坐垫默认不提供任何动画，需要模组作者通过书写 js 动画脚本来为其应用动画。

国际化说明

作为一个面向国际化的游戏，资源包的部分内容自然也兼容国际化。

• 模型包的 pack_name 和 description 字段支持国际化；
• 模型列表的 name 和 description 字段支持国际化。

国际化的添加方式很简单，只需要书写以 { 开头，} 结尾的字符串即可，中间部分为语言文件的 Key，而后书写对应语言文件即可。

比如我们书写了如下的内容（只截取了一小段）

"pack_name": "{pack.vanilla_chair_model.name}",
"description": ["{pack.vanilla_chair_model.desc}"]

而后在资源包资源域下的 lang 文件夹下创建 en_us.lang 文件，书写如下内容即可：

pack.vanilla_chair_model.name=Vanilla Chair Model
pack.vanilla_chair_model.desc=Default Chair Model Pack

我们只添加了英文文件，如果还想再支持中文，创建 zh_cn.lang 文件书写如下内容即可：

pack.vanilla_chair_model.name=原版坐垫资源包
pack.vanilla_chair_model.desc=默认的坐垫模型包

在前面的案例中，如果我们没有书写 name 字段，那么系统会依据 model_id 自动生成本地化 key，比如 model_id 为 touhou_little_maid:cushion ，那么生成的语言文件 key 为 model.touhou_little_maid.cushion.name。

description 字段默认不生成，需要自行主动书写。

其他问题

Z-fighting 问题

这是 OpenGL 本身的一个问题，我们在制作模型过程中使用了平面、或者是两个重合的立方体，就会出现此问题。

对于平面图形导致的问题，只为其中某一面附上材质，另一面留空可以解决此问题；对于两个重合几何体，只需要微移几何体，或者对重合部分的材质进行剔除即可。

文件名大小写问题

Minecraft 的资源包中文件名大小写全部由资源包的 pack.mcmeta 文件的 pack_format 字段决定，如果该字段为 3，则所有内部文件名均需小写，我们也推荐使用这种方式。

重名问题

模型骨骼部分（也就是 Blockbench 中右侧图标为文件夹图标的东西）不可以重名，即使它们分属不同的地方，否则可能会导致模型错误。但是方块（也就是 Blockbench 中右侧图标为方块图标的东西）不受影响。