Kzeroko KTM2

共享魔杖与法杖模型

资源配置、可选动画和安全回退。

更新于 2026/10/25 4 分钟阅读

魔杖与法杖共用一个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 渲染。

步骤

  1. 将几何与纹理导出到上述同名路径。
  2. 需要动画时,在同名路径添加动画文件,片段名使用idle和cast。静态模型不需要动画文件。
  3. 需要指定其他路径、复用模型或映射不同片段名时,才添加下方可选配置。显式配置只使用其中声明的动画资源。
  4. 重载客户端资源,检查物品栏、手持、掉落及 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"
}
字段类型默认值契约
modelresource identifier必填包含 .geo.json 的已烘焙 GeckoLib 几何路径。
textureresource identifier必填包含 .png 的现有纹理路径。
animationresource identifier无GeckoLib 动画资源;缺少资源或片段时禁用对应动画。
idlestringidle可选循环待机片段名。
caststringcast可选施法片段名;播放一次并保持末帧,直到施法结束。

未知字段使配置被拒绝并触发回退。没有动画资源时,仅填写 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 是必需的启动目录数据。钟塔法杖现使用公共目录施法物品及可重载平衡流程,旧专用物品类和渲染器已移除。编辑数据包平衡覆盖时,不要删除目录文件夹。

相关内容