# 自定义女仆模型说明

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_idtouhou_little_maid:hakurei_reimu,那么此时模型文件就为该资源域下的 models/entity 文件夹下名为 hakurei_reimu.json 的文件,材质就为该资源域下的 textures/entity 文件夹下名为 hakurei_reimu.png 的文件。

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

# 动态图标

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

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

提示

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

020

# 模型文件说明

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

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

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

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

001

002

# 注意事项

注意

怪物几何体名字(新版本为“生物几何体名称”)必须为小写的 model,否则无法正常加载模型;

003

提示

未设置自定义动画的模型,只需要按照如下名称命名骨骼,即可自动获得动画效果。

注意

骨骼名称可以存在或者不存在,不会导致游戏崩溃

骨骼名称 动画效果
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 的骨骼,会对其会有头部旋转和上扬动画;

head

提示

在 Beg 模式下会有头部斜歪的动画;

head

提示

如果有名为 armLeftarmRight 的骨骼,会对其会有行走的摆臂动画

hand

提示

持有物品的渲染、待命时手臂合拢的动画(下图仅为右侧演示)

hand

提示

  • 如果有名为 legLeftlegRight 的骨骼,会对其会有行走腿部摆动

hand

提示

待命时腿部分开抬起的动画

leg

提示

如果有名为 wingLeftwingRight 的骨骼,会对其有前后摆动的扇翅膀效果。

wings

注意

此动画与翅膀模型的默认偏转角度无关,默认偏转角度可以随意设计;

翅膀模型的初始位置有一定的要求,在没有赋予任何旋转角度的情况下,翅膀应该与模型背部呈 90 度角,否则赋予翅膀动画时会出现方向错误等问题。

005

提示

如果有名为 ahoge 的骨骼,在女仆处于 Beg 状态下会有呆毛转圈旋转的动画;

ahoge

提示

如果有名为 blink 的骨骼,则每 3 秒会有 0.25 秒的时间显示此骨骼。贴近模型头部添加极为贴近正面的平面(间隔可设计为 0.001),可以用于制作眨眼等动画效果。

注意

由于眨眼大多依附与头部存在,所以此骨骼需要作为 head 骨骼的子级存在

blink

提示

如果有名为 tail 的骨骼,则会赋予转圈的尾巴摆动效果。

tail

提示

如果有名为 sinFloat 或者 cosFloat 的骨骼,则会以其旋转点为中心,上下漂浮移动,借此可以做出实体周围漂浮物件的动画。

除此之外还有 -sinFloat-cosFloat 骨骼,它们的相位和前两者正好相差 π

sinFloatcosFloat 的漂浮动画频率和幅度完全一致,两者仅相位不同,这意味着你可以做出两个不同位置的漂浮物品动画。

float

提示

如果有名为 helmetchestPlatechestPlateLeftchestPlateMiddlechestPlateRightleggingsleggingsLeftleggingsMiddleleggingsRightbootsLeftbootsRight等名称的骨骼,会在对应女仆穿上护甲时才会进行显示。

提示

armLeftPositioningBone armRightPositioningBone 骨骼的参考示例

20200125195245.png

提示

backpackPositioningBone 骨骼的参考示例

20200125195347.png

提示

第二条展示了很多种基本的动画,比如漂浮,翅膀拍打等。如果把这些名称的骨骼依据子父级组合起来,就可以做出复合运动。

比如下图的书页飞舞的动画,就是把翅膀动画和漂浮动画结合做出来的。

book

提示

其他部分骨骼,乃至子骨骼请随意添加,具体以游戏内效果为准。

# 国际化说明

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

  • 模型包的 pack_namedescription 字段支持国际化;
  • 模型列表的 namedescription 字段支持国际化。

国际化的添加方式很简单,只需要书写以 { 开头,} 结尾的字符串即可,中间部分为语言文件的 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_idtouhou_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 本身的一个问题,我们在制作模型过程中使用了平面、或者是两个重合的立方体,就会出现此问题。

004

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

# 文件名大小写问题

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

# 重名问题

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