# 自定义女仆模型说明
1.1.0 版本以后添加了自定义女仆模型的功能，玩家只需要通过一定方式制作资源包，在游戏内加载资源包，即可为女仆添加更多的模型样式和材质样式。
为了方便改模和使用，采用 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_model.json （模型包描述文件，固定名称和位置）
│
├─lang （语言文件夹，固定名称和位置）
│ ├─en_us.lang
│ └─zh_cn.lang
│
├─models （模型文件夹）
│ └─entity
│ ├─cirno.json
│ └─daiyousei.json
│
└─textures （材质文件夹）
└─entity
├─cirno.png
└─daiyousei.png
# 模型包描述文件说明
游戏在加载资源包的过程中，会尝试读取所有资源域主目录下的 maid_model.json 文件，进而确定模型加载，该文件的完整结构如下，仅标有（必须）的部分才必须要书写，你并不需要全部写出来。
本模组支持带注释的 JSON 文件，请放心使用。
{
"pack_name": "东方 Project 资源包", // 模型包包名（必须）
"author": ["酒石酸", "琥珀酸"], // 作者列表
"description": ["默认材质包"], // 模型包的描述文本
"version": "1.0.0", // 模型包的版本
"date": "2019-07-14", // 模型包的制作时间
// 模型包的图标，缺失此字段，材质包将没有图标
"icon": "touhou_little_maid:textures/maid_icon.png",
"model_list": [{ // 模型列表（必须，而且不能为空）
// 模型 id，使用原版资源格式写法（必须，资源域必须为当前所处的资源域）
"model_id": "touhou_little_maid:hakurei_reimu",
// 模型所在的位置，使用完整的资源地址
"model": "touhou_little_maid:models/entity/hakurei_reimu.json",
// 模型所使用的材质位置，使用完整的资源地址
"texture": "touhou_little_maid:textures/entity/hakurei_reimu.png",
"render_item_scale": 0.9, // 渲染成物品形态时的模型大小
"render_entity_scale": 0.75, // 渲染成实体时的大小，范围为 0.7~1.3
"name": "博丽灵梦", // 模型名
"description": ["乐园的巫女"], // 该模型的描述文本
// 动画脚本，如果没有此字段，将会自动调用默认动画
"animation": ["touhou_little_maid:animation/maid.default.js"]
}]
}
上述案例给出了所有可用的字段，实际上只有标注（必须）的才是或不可缺的，其他部分可以省去。
为了图方便，你甚至可以这么写该文件：
{
"pack_name": "东方 Project 资源包", // 模型包包名（必须）
"model_list": [{ // 模型列表（必须）
// 模型 id，使用原版资源格式写法（必须）
"model_id": "touhou_little_maid:hakurei_reimu"
}]
}
如果我们没有书写 model 字段或者 texture 字段，此时会依据 model_id 的名称调用默认位置的模型和材质。
比如上述案例中 model_id 为 touhou_little_maid:hakurei_reimu，那么此时模型文件就为该资源域下的 models/entity 文件夹下名为 hakurei_reimu.json 的文件，材质就为该资源域下的 textures/entity 文件夹下名为 hakurei_reimu.png 的文件。
如果我们书写了 model 或者 texture 字段，那么其内容并无限制，你甚至可以调用其他模型包中的模型，只需要书写对资源地址即可。
# 动态图标
图标没有大小限制，支持静态图标和动态图标。
任意为 1:1 的图标均会被解析为静态图标。不为 1:1 的长图，会以 0.1 秒的间隔逐次显示，从而形成动态图效果。
提示
下图就为模组自带的图标，左侧被解析为静态图标，右侧被解析为动态图标
# 模型文件说明
本模组使用基岩版
1.10.0JSON 文件来进行模型的加载，该文件可以通过建模软件 Blockbench 直接导出，不需要对其做任何修改。Blockbench 3.x 版本默认启用
1.12.0版本基岩版模型，请在绘制前请在文件 -> 转换工程菜单中将其转换为旧版基岩版模型。模型可以进行自定义动画制作，后面的自定义动画篇章有介绍。
Blockbench 可以直接加载基岩版的 JSON 模型，对于二次改模也提供了很大的便捷性。
# 注意事项
注意
怪物几何体名字（新版本为“生物几何体名称”）必须为小写的 model，否则无法正常加载模型；
提示
未设置自定义动画的模型，只需要按照如下名称命名骨骼，即可自动获得动画效果。
注意
骨骼名称可以存在或者不存在，不会导致游戏崩溃
| 骨骼名称 | 动画效果 |
|---|---|
head | 头部旋转，祈求动作 |
armLeft armRight | 行走时手臂动画效果，手臂末端持有物品的显示，待命时手臂合拢效果 |
legLeft legRight | 行走时腿部动画效果，待命骑行时腿部坐下效果 |
wingLeft wingRight | 翅膀往复摆动画 |
ahoge | 祈求状态下的呆毛圆锥摆动画 |
blink | 日常的眨眼动画 |
tail | 尾巴圆锥摆动画 |
sinFloat cosFloat -sinFloat -cosFloat _sinFloat _cosFloat | 以旋转点为中心的上下小距离浮动（新版本 BlockBench 软件不支持减号字符，可以采用短下划线形式替代） |
helmet | 穿戴头盔后显示该模型 |
chestPlate chestPlateLeft chestPlateMiddle chestPlateRight | 穿戴胸甲后显示该模型 |
leggings leggingsLeft leggingsMiddle leggingsRight | 穿戴护腿后显示该模型 |
bootsLeft bootsRight | 穿戴靴子后显示该模型 |
hat | 默认为穿戴头盔后显示该模型，但配置文件中可以调节选项总是显示此骨骼 |
-helmet _helmet | 穿戴头盔后隐藏该模型（新版本 BlockBench 软件不支持减号字符，可以采用短下划线形式替代） |
-chestPlate -chestPlateLeft -chestPlateMiddle -chestPlateRight _chestPlate _chestPlateLeft _chestPlateMiddle _chestPlateRight | 穿戴胸甲后隐藏该模型（新版本 BlockBench 软件不支持减号字符，可以采用短下划线形式替代） |
-leggings -leggingsLeft -leggingsMiddle -leggingsRight _leggings _leggingsLeft _leggingsMiddle _leggingsRight | 穿戴护腿后隐藏该模型（新版本 BlockBench 软件不支持减号字符，可以采用短下划线形式替代） |
-bootsLeft -bootsRight _bootsLeft _bootsRight | 穿戴靴子后隐藏该模型（新版本 BlockBench 软件不支持减号字符，可以采用短下划线形式替代） |
-hat _hat | 穿戴头盔后隐藏该模型（新版本 BlockBench 软件不支持减号字符，可以采用短下划线形式替代） |
armLeftPositioningBone armRightPositioningBone | 女仆手持物品的定位骨骼。该骨骼必须位于对应的 armLeft armRight 骨骼下，且为空骨骼。空骨骼的旋转点决定了手持物品的起始位置（后面有详情图） |
backpackPositioningBone | 女仆背包的定位骨骼，该骨骼没有父骨骼，该骨骼为空骨骼。空骨骼的旋转点决定了背包肩带的中心点（后面有详情图） |
提示
如果有名为 head 的骨骼，会对其会有头部旋转和上扬动画；
提示
在 Beg 模式下会有头部斜歪的动画；
提示
如果有名为 armLeft 或 armRight 的骨骼，会对其会有行走的摆臂动画
提示
持有物品的渲染、待命时手臂合拢的动画（下图仅为右侧演示）
提示
- 如果有名为
legLeft或legRight的骨骼，会对其会有行走腿部摆动
提示
待命时腿部分开抬起的动画
提示
如果有名为 wingLeft 或 wingRight 的骨骼，会对其有前后摆动的扇翅膀效果。
注意
此动画与翅膀模型的默认偏转角度无关，默认偏转角度可以随意设计；
翅膀模型的初始位置有一定的要求，在没有赋予任何旋转角度的情况下，翅膀应该与模型背部呈 90 度角，否则赋予翅膀动画时会出现方向错误等问题。
提示
如果有名为 ahoge 的骨骼，在女仆处于 Beg 状态下会有呆毛转圈旋转的动画；
提示
如果有名为 blink 的骨骼，则每 3 秒会有 0.25 秒的时间显示此骨骼。贴近模型头部添加极为贴近正面的平面（间隔可设计为 0.001），可以用于制作眨眼等动画效果。
注意
由于眨眼大多依附与头部存在，所以此骨骼需要作为 head 骨骼的子级存在
提示
如果有名为 tail 的骨骼，则会赋予转圈的尾巴摆动效果。
提示
如果有名为 sinFloat 或者 cosFloat 的骨骼，则会以其旋转点为中心，上下漂浮移动，借此可以做出实体周围漂浮物件的动画。
除此之外还有 -sinFloat 和 -cosFloat 骨骼，它们的相位和前两者正好相差 π
sinFloat 和 cosFloat 的漂浮动画频率和幅度完全一致，两者仅相位不同，这意味着你可以做出两个不同位置的漂浮物品动画。
提示
如果有名为 helmet，chestPlate，chestPlateLeft，chestPlateMiddle，chestPlateRight，leggings，leggingsLeft，leggingsMiddle，leggingsRight，bootsLeft，bootsRight等名称的骨骼，会在对应女仆穿上护甲时才会进行显示。
提示
armLeftPositioningBone armRightPositioningBone 骨骼的参考示例
提示
backpackPositioningBone 骨骼的参考示例
提示
第二条展示了很多种基本的动画，比如漂浮，翅膀拍打等。如果把这些名称的骨骼依据子父级组合起来，就可以做出复合运动。
比如下图的书页飞舞的动画，就是把翅膀动画和漂浮动画结合做出来的。
提示
其他部分骨骼，乃至子骨骼请随意添加，具体以游戏内效果为准。
# 国际化说明
作为一个面向国际化的游戏，资源包的部分内容自然也兼容国际化。
- 模型包的
pack_name和description字段支持国际化； - 模型列表的
name和description字段支持国际化。
国际化的添加方式很简单，只需要书写以 { 开头，} 结尾的字符串即可，中间部分为语言文件的 Key，而后书写对应语言文件即可。
比如我们书写了如下的内容（只截取了一小段）
"pack_name": "{pack.vanilla_touhou_model.name}",
"description": ["{pack.vanilla_touhou_model.desc}"]
而后在资源包资源域下的 lang 文件夹下创建 en_us.lang 文件，书写如下内容即可：
pack.vanilla_touhou_model.name=Vanilla Touhou Model
pack.vanilla_touhou_model.desc=Default Model Pack
我们只添加了英文文件，如果还想再支持中文，创建 zh_cn.lang 文件书写如下内容即可：
pack.vanilla_touhou_model.name=原版东方资源包
pack.vanilla_touhou_model.desc=默认的模型包
在前面的案例中，如果我们没有书写 name 字段，那么系统会依据 model_id 自动生成本地化 key，比如 model_id 为 touhou_little_maid:hakurei_reimu ，那么生成的语言文件 key 为 model.touhou_little_maid.hakurei_reim.name。
description 字段默认不生成，需要自行主动书写。
# 兼容问题
鉴于部分作者制作的模型比较特殊，与女仆本身拥有多种附加的外形显示不兼容。此处专门对非标模型提供了适配的做法：
| 问题 | 解决办法 |
|---|---|
| 动画不协调 | 通过后面介绍的自定义动画，书写专门的动画脚本 |
| 手臂持有物品位置不对 | 采用上面介绍的定位骨骼进行手持物品的定位 |
| 禁止显示手部物品 | 只要 armLeft 或者 armRight 骨骼不存在，那么对应的手持物品就不会显示 |
| 背包位置不对 | 采用上面介绍的定位骨骼进行背包的定位 |
| 背包、拉杆箱、载具、扫帚，自定义头颅等位置兼容不对 | 采用如下书写关闭这些功能 |
{
"pack_name": "东方 Project 资源包",
"model_list": [{
"model_id": "touhou_little_maid:hakurei_reimu",
"show_hata": false, // 阻止旗指物的显示
"show_backpack": false, // 阻止背包的显示
"can_hold_trolley": false, // 阻止女仆持有拉杆箱
"can_hold_vehicle": false, // 阻止女仆持有载具
"can_riding_broom": false, // 阻止女仆骑乘扫帚
"show_custom_head": false // 阻止女仆显示自定义头颅
}]
}
# 女仆彩蛋
1.2.1 版本以后，我们添加了女仆命名彩蛋功能，特殊命名的女仆可以直接调用特定模型。
彩蛋的书写方式非常简单，模组会自动识别其为彩蛋模型，也不会出现在皮肤选择界面。
# 普通彩蛋
如下为普通命名彩蛋的书写方式，普通命名彩蛋下，女仆只需要命名为下面 tag 字段，就会调用该模型。
{
"pack_name": "东方 Project 资源包",
"model_list": [{
"model_id": "touhou_little_maid:hakurei_reimu",
"easter_egg": {
"tag": "IKUN~"
}
}]
}
# 加密彩蛋
如下为加密彩蛋的书写方式，加密彩蛋彩蛋下，女仆需要特定命名，该命名的 SHA-1 值为如下的 tag 字段，才会调用该模型。
如下书写方式，当女仆命名为 IKUN~ 时，因为这个字符的 SHA-1 值为 6dadb86d91cc4c0c2c7860e1cb16cec01e1b6511，符合 tag 字段，会调用该模型。
{
"pack_name": "东方 Project 资源包",
"model_list": [{
"model_id": "touhou_little_maid:hakurei_reimu",
"easter_egg": {
"encrypt": true,
"tag": "6dadb86d91cc4c0c2c7860e1cb16cec01e1b6511"
}
}]
}
# 其他问题
# Z-fighting 问题
这是 OpenGL 本身的一个问题，我们在制作模型过程中使用了平面、或者是两个重合的立方体，就会出现此问题。
对于平面图形导致的问题，只为其中某一面附上材质，另一面留空可以解决此问题；对于两个重合几何体，只需要微移几何体，或者对重合部分的材质进行剔除即可。
# 文件名大小写问题
Minecraft 的资源包中文件名大小写全部由资源包的 pack.mcmeta 文件的 pack_format 字段决定，如果该字段为 3，则所有内部文件名均需小写，我们也推荐使用这种方式。
# 重名问题
模型骨骼部分（也就是 Blockbench 中右侧图标为文件夹图标的东西）不可以重名，即使它们分属不同的地方，否则可能会导致模型错误。但是方块（也就是 Blockbench 中右侧图标为方块图标的东西）不受影响。
← Blockbench 自定义坐垫模型 →