build-rigged-game-assets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build Rigged Game Assets

构建Rigged游戏资产

Build one truthful actor package from source reference through gameplay and catalog proof.

从参考资源到游戏玩法验证与目录审核，构建一套真实可信的角色资产包。

Establish the contract first

先确立约定

Inspect repository truth before generating or editing files:

Locate the source image/model, runtime loader, skeleton conventions, action API, equipment system, collision system, catalog schema, review routes, budgets, and tests.
Classify the actor as
```
character
```
or
```
monster
```
.
Classify delivery as
```
catalog-only
```
,
```
review-only
```
, or
```
runtime
```
. Do not call an asset implemented until gameplay loads it.
Preserve immutable source artifacts separately from optimized runtime files.
Decide target formats before using a credit-bearing generator.

Copy the matching template from

assets/

, fill it in, and keep it beside the implementation or in the project’s asset metadata location:

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

Run

scripts/validate_asset_manifest.py <manifest>

before building. Re-run with

--root <repo>

for shipped-file checks and

--require-verified

only after every acceptance check has actually passed.

Read references/requirements.md before creating the model, rig, actions, equipment, sockets, or collision data. Read references/catalog-and-testing.md when adding the catalog card, inspector, moveset route, telemetry, or release tests.

在生成或编辑文件前，先核查仓库基准信息：

定位源图像/模型、runtime加载器、skeleton规范、动作API、装备系统、碰撞系统、目录 schema、评审流程、资源预算及测试用例。
将角色分类为
```
character
```
或
```
monster
```
。
将交付类型分类为
```
catalog-only
```
、
```
review-only
```
或
```
runtime
```
。只有当游戏玩法成功加载资产后，才可视为资产已实现。
将不可变的源工件与优化后的runtime文件分开存储。
在使用付费生成工具前，确定目标格式。

从

assets/

目录复制匹配的模板，填写内容后，将其放在实现文件旁或项目的资产元数据位置：

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

在构建前运行

scripts/validate_asset_manifest.py <manifest>

。如需检查已发布文件，添加

--root <repo>

参数；仅在所有验收检查通过后，再添加

--require-verified

参数重新运行。

在创建模型、rig、动作、装备、sockets或碰撞数据前，请阅读references/requirements.md。在添加目录卡片、检视器、动作集路由、遥测或发布测试时，请阅读references/catalog-and-testing.md。

Build the common actor package

构建通用角色资产包

Preserve the source.
- Record reference images, source tasks, imported files, licenses, generator/model, and material provenance.
- Never overwrite the high-detail source with the runtime optimization.
Produce the main model.
- Normalize scale, Y-up, forward axis, pivot, ground contact, materials, textures, and triangle budget.
- Ground from feet or authored contact sockets, never a weapon tip, cloth tail, shadow, or VFX.
- Remove isolated triangles, non-manifold fragments, duplicate surfaces, hidden generator debris, and unused nodes.
Build one stable rig.
- Name root, hips/center mass, head, limbs, feet, and attachment sockets explicitly.
- Keep at most four normalized skin influences per vertex unless the engine contract says otherwise.
- Preserve a deterministic bind pose, finite transforms, positive usable scale, and compatible skeleton identity across every clip.
Build the action library.
- Give every clip a stable
```
id
```
  , semantic
```
role
```
  , loop policy, root-motion policy, duration, contact events, and source.
- Prefer animation-only GLBs for separate clips. They must not smuggle duplicate meshes, materials, or textures.
- Make non-looping actions restartable and return to the intended locomotion/idle state.
Build runtime integration.
- Use one asset-specific loader/factory with disposal for geometry, materials, textures, mixers, events, observers, renderers, and animation frames.
- Publish source, model, rig, socket, action, equipment, collider, triangle, material, and status metadata.
- Keep a truthful rollback path when replacing a shipped runtime asset.

保留源文件。
- 记录参考图像、源任务、导入文件、许可证、生成器/模型及材质来源。
- 绝不要用runtime优化版本覆盖高细节源文件。
制作主模型。
- 统一缩放比例、Y轴向上、前向轴、轴心点、地面接触点、材质、纹理及三角面预算。
- 以脚部或预设的接触sockets为地面基准，绝不能以武器尖端、布料尾部、阴影或VFX为基准。
- 移除孤立三角面、非流形碎片、重复表面、隐藏的生成残留及未使用节点。
构建一套稳定的rig。
- 明确命名根节点、臀部/重心、头部、四肢、脚部及挂载sockets。
- 除非引擎约定另有规定，每个顶点最多保留四个归一化蒙皮影响。
- 在所有动画片段中，保留确定的bind pose、有限变换、正可用缩放比例及兼容的skeleton标识。
构建动作库。
- 为每个动画片段分配稳定的
```
"id"
```
  、语义化的
```
"role"
```
  、循环策略、root-motion策略、时长、接触事件及来源信息。
- 优先选择仅含动画的GLB格式存储独立片段。此类文件不得包含冗余的网格、材质或纹理。
- 非循环动作需支持重启，并能返回至预设的移动/idle状态。
构建runtime集成。
- 使用针对该资产的专属加载器/工厂类，处理几何、材质、纹理、混合器、事件、观察者、渲染器及动画帧的加载与销毁。
- 发布源文件、模型、rig、sockets、动作、装备、碰撞体、三角面、材质及状态元数据。
- 替换已发布的runtime资产时，需保留可靠的回滚路径。

Apply the character profile

应用角色配置

Treat the main model as the persistent body/base layer. Do not fuse swappable equipment into it.

Declare every canonical slot: headgear, vestment, gloves, leggings, boots, main hand, offhand, and back/ranged.
Mark unsupported slots explicitly instead of silently omitting them.
Store supported swords, shields, bows, helmets, armor, and accessories as separate assets or independently addressable roots.
Bind equipment to named sockets. Declare active and stowed sockets when an item changes state.
Toggling a slot off must leave no floating trim, grip, one-triangle shards, duplicate baked weapon, or incidental gameplay prop.
When the source contains no body beneath occluded equipment, create a fitted rig-following underlayer and record that limitation. Do not invent invisible anatomy claims.
Require the character action roles
```
idle
```
,
```
walk
```
,
```
run
```
,
```
primary-attack
```
,
```
hit
```
,
```
dodge
```
, and
```
death
```
. Add block/ward, charged attack, cast, bow aim/shoot, jump, interaction, or class actions when gameplay exposes them.
Keep equipment visibility independent from action selection unless the action deliberately changes active/stowed state.

将主模型视为持久化的身体/基础层，不得将可替换装备与其融合。

声明所有标准装备槽：头饰、外衣、手套、护腿、靴子、主手、副手及背部/远程装备槽。
明确标记不支持的装备槽，而非默认隐藏。
将支持的剑、盾、弓、头盔、护甲及配饰存储为独立资产或可独立寻址的根节点。
将装备绑定到命名的sockets上。当物品状态改变时，声明激活态与收纳态的sockets。
关闭装备槽时，不得残留悬浮装饰、握柄、单三角面碎片、重复烘焙的武器或无关的游戏道具。
若源文件中被遮挡的装备下方没有身体模型，需创建贴合rig的底层模型并记录该限制。不得虚构不可见的身体结构说明。
角色必须包含
```
idle
```
、
```
walk
```
、
```
run
```
、
```
primary-attack
```
、
```
hit
```
、
```
dodge
```
及
```
death
```
这些动作role。当游戏玩法需要时，添加block/ward、蓄力攻击、cast、弓箭瞄准/射击、跳跃、交互或职业专属动作。
装备可见性需与动作选择独立，除非动作刻意改变装备的激活/收纳状态。

Apply the monster profile

应用怪物配置

Treat a monster as one authored combat actor, not a player wardrobe.

Do not require wearable slots. Separate only weapons, breakable parts, dropped parts, projectiles, or props that must animate, hide, detach, or collide independently.
Require the monster action roles
```
idle
```
,
```
locomotion
```
,
```
primary-attack
```
,
```
hit
```
, and
```
death
```
.
Add secondary attack, ranged attack, pounce, cast, summon, block, stagger, roar, spawn, or phase-transition roles only when the combat design uses them.
Define navigation and hurt colliders plus per-attack telegraph, active, and recovery windows.
Bind attack origins, projectiles, VFX, audio, head/torso targeting, and feet to named sockets.
Keep visual animation separate from authoritative attack volumes, damage timing, AI state, and navigation.
Test every attack at its authored range, facing, contact window, interruption, death, and cleanup boundary.

将怪物视为一个完整的战斗角色，而非玩家的衣柜。

无需设置可穿戴装备槽。仅分离武器、可破坏部件、掉落部件、投射物或需要独立动画、隐藏、分离或碰撞的道具。
怪物必须包含
```
idle
```
、
```
locomotion
```
、
```
primary-attack
```
、
```
hit
```
及
```
death
```
这些动作role。
仅当战斗设计需要时，添加次级攻击、远程攻击、扑击、cast、召唤、格挡、 stagger、咆哮、生成或阶段转换等动作role。
定义导航碰撞体与受击碰撞体，以及每个攻击的预警、生效与硬直窗口。
将攻击起源点、投射物、VFX、音频、头部/躯干目标点及脚部绑定到命名的sockets上。
将视觉动画与权威攻击范围、伤害判定时机、AI状态及导航逻辑分离。
在预设的攻击范围、朝向、接触窗口、打断、死亡及清理边界条件下，测试每个攻击动作。

Build the catalog lab

构建目录实验室

Create both surfaces:

Catalog card: transparent PNG, truthful label, zero WebGL canvases.
Selected inspector/review route: exactly one live model canvas with source, status, budgets, rig, sockets, actions, and known boundaries.

Provide:

drag-to-rotate while preserving page scroll;
action selection for every shipped clip, including visible Walk, Hit, and Death controls;
restart and pause/play;
equipment toggles for characters, including clean all-off and active/stowed states;
combat-state or attack controls for monsters instead of character gear controls;
a fallback image until the real model is ready;
deterministic runtime telemetry defined in the catalog/testing reference.

The inspector must load the same runtime model, rig, clips, equipment rules, and action API claimed by gameplay. A screenshot or separate look-dev mesh is not runtime proof.

创建两种界面：

目录卡片：透明PNG图片、真实标签，无WebGL画布。
选中状态检视器/评审路由：仅包含一个实时模型画布，展示源文件、状态、资源预算、rig、sockets、动作及已知限制。

需提供以下功能：

拖拽旋转模型，同时保留页面滚动功能；
支持选择所有已发布的动画片段，包括可见的Walk、Hit及Death控制；
支持重启与暂停/播放；
角色装备切换功能，包括一键清空所有装备及切换激活/收纳状态；
怪物的战斗状态或攻击控制（替代角色的装备控制）；
在真实模型加载完成前显示 fallback 图片；
目录/测试参考文档中定义的确定性runtime遥测。

检视器必须加载与游戏玩法所使用的相同runtime模型、rig、片段、装备规则及动作API。截图或单独的开发预览网格不能作为runtime验证依据。

Verify and commit

验证与提交

Run the project’s focused asset tests, manifest validator, build, lint, full tests, and

git diff --check

In the repository-approved browser:

verify the card has one transparent image and zero canvases;
verify the inspector has one model host/canvas;
click every action and confirm the selected/playing state;
toggle every character slot individually and all equipment off;
inspect front, back, and both sides for fragments, holes, grounding, and socket errors;
drag the model, scroll the page, and test the supported narrow/mobile layout;
verify fallback and model-load failure behavior;
verify no broken media or console warning/error.

Commit only the narrow asset lane. Report the manifest, main/runtime models, gear files, rig and sockets, actions, catalog route, status, verification results, known boundaries, and exact commit SHA. Report full-suite baseline failures separately.

运行项目的聚焦资产测试、清单验证器、构建、代码检查、完整测试及

git diff --check

。

在仓库认可的浏览器中：

验证目录卡片仅包含一张透明图片，无画布；
验证检视器仅包含一个模型宿主/画布；
点击每个动作，确认选中/播放状态；
单独切换每个角色装备槽，并测试所有装备关闭的状态；
从正面、背面及两侧检查模型是否存在碎片、孔洞、地面基准错误及sockets错误；
拖拽模型、滚动页面，测试支持的窄屏/移动端布局；
验证 fallback 图片及模型加载失败的处理行为；
验证无损坏媒体及控制台警告/错误。

仅提交资产相关的窄范围代码。提交清单、主/runtime模型、装备文件、rig与sockets、动作、目录路由、状态、验证结果、已知限制及精确的提交SHA。单独报告全套件基线测试失败的情况。