Files
Oshima-Game/docs/02汐月心音模板角色交付说明.md
T
2026-09-19 17:24:02 +08:00

97 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 02 汐月心音模板角色交付说明
> 交付状态:`art-template-ready`
> 引擎状态:`not-started-no-godot-project`
> 推荐首轮接入方式:完整 PNG 关键帧动画;分解件与枢轴清单保留给后续 Skeleton2D
## 1. 唯一入口
未来建立 Godot 项目时,应优先读取:
- `assets/images/2d-game-characters/02-xinyin/template-package-v1.json`
该清单已经汇总四方向别名、装配图、动作清单、固定裁切框、脚底原点、关键帧时长、循环预览和当前限制。不要通过文件夹名称猜测运行时方向。
四方向选择规则仍以以下文件为准:
- `assets/images/2d-game-characters/02-xinyin/direction-map-v1.json`
## 2. 四方向映射
| 运行时方向 | 素材方向 ID | 构图 | 状态 |
|---|---|---|---|
| `up` | `up` | 严格背面 | 中性装配、动作、三档循环已验证 |
| `down` | `down` | 严格正面 | 中性装配、动作、三档循环已验证 |
| `left` | `front-right` | 三分之四侧身,朝画面左 | 中性装配、动作、三档循环已验证 |
| `right` | `front-left` | 三分之四侧身,朝画面右 | 中性装配、动作、三档循环已验证 |
LEFT 与 RIGHT 保留历史目录,只为兼容现有清单和重建工具。运行时必须使用 `template-package-v1.json` 的 `runtimeDirection` 与 `assetDirectionId` 映射。
## 3. 动画契约
四个方向都使用 600 × 760 px 透明动作画布和相同的七个关键帧:
| 关键帧 | 时长 |
|---|---:|
| `idle-inhale` | 420 ms |
| `idle-neutral` | 260 ms |
| `idle-exhale` | 420 ms |
| `throw-ready` | 150 ms |
| `throw-windup` | 110 ms |
| `throw-release` | 90 ms |
| `throw-recover` | 180 ms |
待机循环为 `inhale → neutral → exhale → neutral`,周期 1360 ms。投掷播放为 `ready → windup → release → recover → neutral`,周期 790 ms;投掷本身不循环。
所有方向都已经用联合固定裁切框进行播放验证,不允许逐帧重新居中。Sprite 原点使用固定裁切框的底部中心。
## 4. 显示规格
| 档位 | 角色显示高度 | 参考菱形格 |
|---|---:|---:|
| 100% | 176 px | 128 × 64 px |
| 75% | 132 px | 96 × 48 px |
| 50% | 88 px | 64 × 32 px |
176 px 为当前默认战场显示基准。132 px 和 88 px 用于远景及可读性压力测试,不代表最终镜头缩放值已经在引擎中冻结。
## 5. 首轮 Godot 接入建议
1. 创建项目后先按完整 PNG 帧动画接入,不立即搭建 Skeleton2D。
2. 每个运行时方向建立 `idle` 与 `throw` 两组动画,帧顺序和时长直接读取模板清单。
3. 角色根节点与每组帧都使用底部中心原点;禁止按单帧 Alpha 范围重新居中。
4. 移动朝向采用主轴判定与 15% 斜向滞回区,临界区保持上一方向。
5. 身体只使用四个方向;投射物、准星和技能 VFX 保持自由角度。
6. LEFT/RIGHT 不得互相水平镜像;UP/DOWN 也具有独立的固定侧别和附件关系。
7. 176/132 px 首选线性过滤;88 px 需要在实际镜头中并列比较线性与最近邻后再冻结。
## 6. 尚未完成的引擎工作
- Godot 导入预设、纹理过滤、压缩与 mipmap 策略;
- AnimatedSprite2D/SpriteFrames 或 AnimationPlayer 资源;
- 碰撞体、选择框、导航占位、阴影、Y 排序和遮挡规则;
- 投射物出生点、手部/武器/VFX Socket;
- 实际地图上的 176/132/88 px 镜头验证与性能测试;
- Skeleton2D、分解件极限旋转、关节补缝及插值动画。
因此当前版本是“可投入引擎接入的美术模板”,不是已经完成引擎验收的游戏角色。
## 7. 重建与验证
模板总清单与交付总览可通过以下脚本重复生成:
```powershell
python tools/build_xinyin_template_package.py
```
四方向循环预览由 `tools/build_xinyin_motion_playback.py` 生成。UP 示例:
```powershell
python tools/build_xinyin_motion_playback.py --direction up --motion-version 1
```
交付总览:
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-template-role-handoff-v1.png`