build-rigged-game-assets

构建带骨骼的游戏资产

从源参考到游戏玩法和目录验证，构建一个真实可靠的角色资产包。

先明确契约

生成或编辑文件前，先检查仓库中的实际情况：

• 找出源图像／模型、运行时加载器、骨骼约定、动作 API、装备系统、碰撞系统、目录架构、审核路由、预算和测试。
• 将角色分类为 character 或 monster。
• 将交付内容分类为 catalog-only、review-only 或 runtime。游戏玩法尚未加载资产时，不要称其为已实现。
• 将不可变的源文件与优化后的运行时文件分开保存。
• 使用需要消耗额度的生成器之前，先确定目标格式。

从 assets/ 复制匹配的模板，填写后将其放在实现旁边，或放在项目的资产元数据目录中：

• character-asset-manifest.template.json
• monster-asset-manifest.template.json

构建前，运行 scripts/validate_asset_manifest.py <manifest>。交付文件检查时，使用 --root <repo> 重新运行；只有在所有验收检查确实通过后，才使用 --require-verified。

创建模型、骨架、动作、装备、挂接点或碰撞数据前，请阅读 references/requirements.md。添加目录卡片、检查器、招式路由、遥测或发布测试时，请阅读 references/catalog-and-testing.md。

构建通用角色资产包

1. 保留源文件。
   • 记录参考图像、源任务、导入文件、许可证、生成器／模型以及材质来源。
   • 绝不要用运行时优化版本覆盖高细节源文件。
2. 制作主模型。
   • 统一缩放、Y 向上、朝前轴、枢轴、接地位置、材质、纹理和三角形预算。
   • 以脚部或创作时定义的接触挂接点为接地基准，绝不要以武器尖端、布料尾部、阴影或 VFX 为基准。
   • 移除孤立三角形、非流形碎片、重复表面、隐藏的生成器杂项和未使用的节点。
3. 构建一个稳定的骨架。
   • 明确命名根节点、髋部／质心、头部、四肢、脚部和挂接点。
   • 除非引擎契约另有规定，否则每个顶点最多保留四个归一化的蒙皮影响。
   • 确保绑定姿势确定、变换有限、缩放为正且可用，并且所有动画片段的骨架标识一致。
4. 构建动作库。
   • 为每个动画片段提供稳定的 id、语义 role、循环策略、根运动策略、时长、接触事件和来源。
   • 单独的动画片段优先使用纯动画 GLB。此类文件不得夹带重复的网格、材质或纹理。
   • 确保非循环动作可以重新启动，并返回预期的移动／待机状态。
5. 构建运行时集成。
   • 使用单个专用资产加载器／工厂，并确保能释放几何体、材质、纹理、混合器、事件、观察器、渲染器和动画帧。
   • 发布源文件、模型、骨架、挂接点、动作、装备、碰撞体、三角形、材质和状态元数据。
   • 替换已交付的运行时资产时，保留真实可靠的回滚路径。

应用角色配置

将主模型视为持久的身体／基础层。不要将可更换装备融合到其中。

• 声明所有标准槽位：头饰、服装、手套、护腿、靴子、主手、副手和背部／远程武器。
• 明确标记不支持的槽位，不要默默省略。
• 将支持的剑、盾、弓、头盔、护甲和配饰存储为独立资产或可单独寻址的根节点。
• 将装备绑定到具名插槽。物品状态改变时，声明启用和收纳插槽。
• 关闭某个槽位时，不得留下悬浮饰边、握柄、单三角碎片、重复烘焙武器或附带的游戏道具。
• 如果源素材中被遮挡的装备下方没有身体，则创建贴合身体、跟随骨骼的内层，并记录这一限制。不要编造关于不可见解剖结构的说法。
• 要求角色动作包含 idle、walk、run、primary-attack、hit、dodge 和 death。如果游戏玩法中包含格挡／护盾、蓄力攻击、施法、拉弓／射击、跳跃、互动或职业动作，也应添加。
• 除非某个动作有意改变启用／收纳状态，否则装备可见性应独立于动作选择。

应用怪物配置

将怪物视为一个创作完成的战斗角色，而非玩家的穿戴装扮。

• 不要求可穿戴槽位。仅将必须独立动画、隐藏、脱落或碰撞的武器、可破坏部件、掉落部件、投射物或道具分离出来。
• 要求怪物动作包含 idle、locomotion、primary-attack、hit 和 death。
• 仅当战斗设计使用二次攻击、远程攻击、扑击、施法、召唤、格挡、踉跄、咆哮、生成或阶段转换时，才添加相应动作角色。
• 定义导航碰撞体和受击碰撞体，以及每次攻击的预警、有效和恢复时段。
• 将攻击起点、投射物、VFX、音频、头部／躯干瞄准点和脚部绑定到具名插槽。
• 将视觉动画与权威攻击范围、伤害时机、AI 状态和导航分开。
• 在设定的攻击距离和朝向下，测试每次攻击的接触时段、中断、死亡和清理边界。

构建目录实验室

创建两个界面：

• 目录卡片：透明 PNG、准确的标签、零个 WebGL 画布。
• 已选对象检查／审阅页面：恰好一个实时模型画布，并显示来源、状态、预算、骨骼、插槽、动作和已知边界。

提供：

• 拖动旋转，同时保留页面滚动功能；
• 为所有已发布动画片段提供动作选择，包括可见的 Walk、Hit 和 Death 控件；
• 重启和暂停／播放；
• 角色装备切换控件，包括干净的全部关闭状态以及启用／收纳状态；
• 为怪物提供战斗状态或攻击控件，而非角色装备控件；
• 在真实模型加载完成前显示备用图像；
• 提供目录／测试参考中定义的确定性运行时遥测。

检查器必须加载与游戏玩法所声称相同的运行时模型、骨骼、动画片段、装备规则和动作 API。截图或单独的外观开发网格不能作为运行时证明。

验证并提交

运行项目针对性的资产测试、清单验证器、构建、lint、完整测试以及 git diff --check。

在仓库批准的浏览器中：

• 验证卡片只有一张透明图像且没有画布；
• 验证检查器只有一个模型宿主／画布；
• 点击每个动作，并确认其选中／播放状态；
• 分别切换每个角色槽位，并关闭所有装备；
• 检查正面、背面和两侧，确认没有碎片或孔洞、模型贴地正常且插槽无误；
• 拖动模型、滚动页面，并测试受支持的窄屏／移动端布局；
• 验证备用内容和模型加载失败时的行为；
• 确认没有损坏的媒体，也没有控制台警告／错误。

仅提交范围精简的资产改动。报告清单、主模型／运行时模型、装备文件、骨骼和插槽、动作、目录页面、状态、验证结果、已知边界以及准确的提交 SHA。另行报告完整测试套件的基线失败。