共享魔杖与法杖模型
资源配置、可选动画和安全回退。
魔杖与法杖共用一个GeckoLib渲染器。与装备ID同名的资源会自动加载;需要自定义路径或片段名时,再添加资源配置。装备目录继续管理物品身份与属性。
你要做的东西
将以下资源放在assets/isekaiexpansion/下,并用装备ID替换<catalog_id>:
| 资源 | 路径 | 必需 |
|---|---|---|
| 几何 | geo/item/weapons/<catalog_id>.geo.json | 是 |
| 纹理 | textures/item/weapons/<catalog_id>.png | 是 |
| 动画 | animations/item/weapons/<catalog_id>.animation.json | 否;存在时使用idle和cast |
加载顺序为:有效的focus_models/<catalog_id>.json配置、上述同名资源、default_wand.json或default_staff.json。魔杖默认使用calibration_standard_wand,法杖默认使用clocktower_staff。目录自动提供共享父模型的主模型和低分辨率物品模型,资源包可覆盖它们。手写的models/item/<catalog_id>.json控制显示变换;GeckoLib几何必须放在geo/下。
前置要求
模型ID引用已烘焙的GeckoLib几何,纹理ID引用存在的PNG资源。动画可选。配置无效或几何与纹理不齐全时记录警告,并尝试下一步加载来源;若仍无有效外观,所有视角使用低分辨率图标,图标模型也缺失时使用普通缺失模型占位。
缺失配置的替换在 ItemRenderer.getModel 中完成,外部预览也会取得同一可见回退模型。有效配置在此保留主模型,低分辨率图标设置随后按渲染视角应用。Iceberg 详情渲染还要求 IsekaiTweaks 注册 client.geckolib.IcebergCustomItemRendererMixin,才能将有效主模型交给 GeckoLib 渲染。
步骤
- 将几何与纹理导出到上述同名路径。
- 需要动画时,在同名路径添加动画文件,片段名使用
idle和cast。静态模型不需要动画文件。 - 需要指定其他路径、复用模型或映射不同片段名时,才添加下方可选配置。显式配置只使用其中声明的动画资源。
- 重载客户端资源,检查物品栏、手持、掉落及 NPC 手持的待机和施法显示。
声明它
可选的assets/isekaiexpansion/focus_models/<catalog_id>.json优先于自动发现:
{
"model": "isekaiexpansion:geo/item/weapons/clocktower_staff.geo.json",
"texture": "isekaiexpansion:textures/item/weapons/clocktower_staff.png",
"animation": "isekaiexpansion:animations/item/weapons/clocktower_staff.animation.json",
"idle": "idle",
"cast": "cast"
}
| 字段 | 类型 | 默认值 | 契约 |
|---|---|---|---|
model | resource identifier | 必填 | 包含 .geo.json 的已烘焙 GeckoLib 几何路径。 |
texture | resource identifier | 必填 | 包含 .png 的现有纹理路径。 |
animation | resource identifier | 无 | GeckoLib 动画资源;缺少资源或片段时禁用对应动画。 |
idle | string | idle | 可选循环待机片段名。 |
cast | string | cast | 可选施法片段名;播放一次并保持末帧,直到施法结束。 |
未知字段使配置被拒绝并触发回退。没有动画资源时,仅填写 idle/cast 名称不会加载动画。施法速度为片段时长除以当前施法时长,限制在 0.05–8;待机速度为 1。玩家及其他 Spell Engine 施法过程提供者使用过程时长,基础 NPC 使用同步的施法阶段与时长。
配置成功和失败结果都会缓存到客户端资源重载。每个物品最多保留 128 个动画管理器,以持有者和渲染视角为键,淘汰最久未使用的条目。世界变化或动画缓存替换会清空保留状态。渲染不分配持久化物品动画 ID。
Iceberg详情渲染
Iceberg/GeckoLib桥接由IsekaiTweaks负责。IcebergCustomItemRendererMixin在Gecko物品渲染期间保存调用方的顶点提供器,GeoItemRendererMixin让GUI几何、附魔闪光和自发光层继续使用该提供器。光照和缓冲提交由Iceberg控制,自动回退的法杖、魔杖也走这条路径。详情预览全黑的问题不应通过更换回退纹理处理。
桥接已对照GeckoLib4.8.3及IsekaiTweaks1.20.1-0.4.0编译。应在目标渲染组合的Iceberg详情界面中检查普通物品、回退施法物品和自发光施法物品;编译不代表视觉验收。
检查清单
检查静态魔杖、动画法杖、只有待机或只有施法片段的模型,以及缺少模型、纹理或动画资源的情况。确认没有配置时能加载同名资源、显式配置优先、配置无效时仍会尝试物品自身资源。确认回退可见、重复施法能重新开始、不同持有者不共享施法状态,且切换资源包会刷新缓存。
src/main/resources/equipment 是必需的启动目录数据。钟塔法杖现使用公共目录施法物品及可重载平衡流程,旧专用物品类和渲染器已移除。编辑数据包平衡覆盖时,不要删除目录文件夹。