# 暖雪 · 烬夜 1.2：持剑疾行重设计

本版重新设计主角奔跑动作，人物与怪物共使用 **8 套图集、152 帧动作**。

[动作预览.html](./动作预览.html) 提供连续演示和循环动作图；[index.html](./index.html) 是实际游戏。

## 1.2 持剑疾行

- 重画前倾的奔跑上身：视线朝前、胸口压低、持剑手收在后侧，空手屈肘，肩膀随步态摆动。
- 支撑脚匀速后送，完成蹬伸；摆动脚先收回再探向前方，落地前后的运动方向连续。两腿相差半个周期，保留短暂腾空阶段。
- 整条腿采用连续网格变形，膝盖和踝部使用渐变权重，改善切片旋转时的硬折角；重心按落地压力起伏，围巾末端延迟跟随。
- 正、背各 24 帧，共 48 帧跑动。两组序列、预览间隔和步幅从资源契约读取，游戏移动速度与战斗伤害不变。
- 每格地面锚点仍为 `(155, 235)`，统一身形参考仍为 `200`；移动施法继续使用纯腿部层，避免带入跑步武器。
- 预览添加雪面位移参照和“对比旧版”。版本切换保持视角与动作相位，可用半速和拖动检查；正式游戏不加载旧版对比图。

### 当前资源与重现

新上身由提供的 `gpt-image-2` Images API 生成，提示词为 `art/stride-redesign-prompts.jsonl`。脚部材质沿用原角色的绘画部件；最终姿态由本地动作设计与蒙皮生成。原画是 `output/imagegen/animation-v2/hero-stride-upper.png`，完整动作是 `hero-stride.png`，足迹与关节记录是 `hero-stride.json`。

已有原画时，安装 Pillow 和 NumPy 后可重新生成：

```powershell
python art/design-hero-stride.py
python art/prepare-animation.py
python art/make-animation-previews.py
```

`art/generate-animation.ps1 -Only hero-run` 会复用已有原画；缺少上身或腿部原画时，才从配置的接口生成对应部件。密钥仅从当前进程的 `OPENAI_API_KEY` 读取。`art/package-offline.py` 同步资源指纹并打包。

## 1.1.1 步态修正（历史）

原跑步图集的多个姿态重复伸出同一侧腿，另一侧长期藏在衣摆里；前后视角还被接在同一个 GIF 中。1.1.1 替换正、背向各八帧，保留白发、红围巾和黑白衣装，以可独立运动的绘画部件组装步态：

- 两条腿相差半个周期，依次接触、承重、蹬地、收腿，四帧后交换支撑腿；膝盖跟随脚的轨迹弯曲。
- 衣摆位于双腿后方，两只靴子可辨；持剑手与空手小幅反向摆动，围巾末端延迟起伏。
- 十六帧共用地面锚点 `(155, 235)`，不再把当前最低靴底当作每帧的新地面；主角统一比例仍为 `nominalHeight = 200`。
- 移动施法使用独立的 `hero-run-legs.webp` 图层，共用同样的十六个姿态；不会把跑步图里的刀尖、围巾或手臂贴入施法动作。图层不额外计为十六个新姿态。
- 预览保持每个视角独立循环，支持正背切换、暂停、半速、八帧拖动和系统减少动态设置。GIF 也分别保存正面、背面版本。

游戏速度、伤害、招式时序、存档格式和其他角色图集没有修改。连续演示和离线包同步使用新步态。

### 跑步资源重现

`art/run-parts-prompts.jsonl` 是采用的部件生图提示词，模型为 `gpt-image-2`，输入外观参考为 `assets/hero.png`。图像接口生成绘画部件，最终跑步姿态由 `art/rig-hero-run.py` 装配，并非模型直接生成的完整动作帧。原始部件、切片和关节轨迹在 `output/imagegen/animation-v2/`。

已有原始部件时，无需联网即可重做图集：

```powershell
python art/rig-hero-run.py
python art/prepare-animation.py
python art/make-animation-previews.py
```

需要重新生图时，先在当前进程配置 `OPENAI_API_KEY`，运行 `art/generate-animation.ps1 -Only hero-run`；工具从指定接口生成部件后装配姿态，密钥不保存到项目。已有原始图片会复用。原 1.1 跑步资源保留在 `.history/before-gait-fix-20260909-194548/`。

## 可见变化

- 主角前、后向跑动各二十四帧，步频跟随实际位移。
- 三连斩具有横斩、反手斩、重劈的起手、接触和收势，并提供背向攻击姿态。
- 连续飞剑有施法手诀；移动施法时，上半身动作与下半身步态分别绘制。
- 疾风步包含压身、蹬地、掠行与落地，残像保存当时的动作帧；新增受击与倒地姿态。
- 刀兵有拖刀步态、抬刀和下劈；无目僧会举杖推掌；伥犬会四足奔行、腾空扑击并缓冲落地。
- 首领有重步、抬刀、下砸、举臂放射与破相动作。
- 新增收尖刀光、剑痕、双层飞剑轨迹、召回聚气、闪避气流、脚步和落地烟尘、手部法光、治疗莲纹，以及断雪聚气和扩张剑阵。
- 增加脚步、拔剑起手、蓄力和施法音效。

## 动作与判定契约

| 动作           | 行为                                                                                 |
| -------------- | ------------------------------------------------------------------------------------ |
| 普通两段近战   | 基础命中时间为起手后 `0.075 / attackRate` 秒                                         |
| 第三段重劈     | 基础命中时间为起手后 `0.125 / attackRate` 秒                                         |
| 近战接触帧     | 同步执行身体前探、剑光、音效、伤害和击退；同段不重复命中                             |
| 闪避、受击     | 取消尚未释放的近战，不补出已经取消的伤害                                             |
| 飞剑、召回     | 保留去程和回程各自去重；轨迹与出射高度只影响绘制，平面碰撞规则不变                   |
| 断雪           | 聚气 `0.26` 秒后，以 `0.32` 秒扩张波前；伤害和清弹随可见波前推进，每目标最多命中一次 |
| 敌方攻击       | 预警时锁定方向与落点，出手后进入独立收势，再恢复移动                                 |
| 暂停与命中停顿 | 姿态、战斗特效、事件队列跟随模拟时间冻结，不用墙钟回调补发伤害                       |
| 减少动态       | 跳过停顿表现但继续消耗计时，避免重新启用时补播旧停顿                                 |
| 进入下一房间   | 清除旧动作、波面、受击速度和动作状态                                                 |

## 动作资源

| 图集               | 帧数 | 用途                 |
| ------------------ | ---: | -------------------- |
| `hero-run`         |   48 | 前、后向各二十四帧跑动 |
| `hero-combat`      |   16 | 正向三连斩与施法     |
| `hero-combat-back` |   16 | 背向三连斩与施法     |
| `hero-react`       |    8 | 闪避、受击与倒地     |
| `ghoul-motion`     |   16 | 刀兵步态、攻击与倒地 |
| `hound-motion`     |   16 | 四足步态、扑击与倒地 |
| `monk-motion`      |   16 | 漂浮移动、施法与倒地 |
| `boss-motion`      |   16 | 首领步态、重劈与施法 |

动作美术通过提供的 **`gpt-image-2` Images API** 生成，以现有角色图片作为编辑参考；1.2 的跑步经过新上身绘画、足迹设计与连续腿部蒙皮。提示词与资源目录见 `art/animation-prompts.jsonl`、`art/stride-redesign-prompts.jsonl`、`art/run-parts-prompts.jsonl`，原图在 `output/imagegen/animation-v2/`，游戏资源在 `assets/animations/`。密钥不写入工程文件。

处理流程保留原生 Alpha，同时兼容绿幕；每格等比缩放并补透明边。骨架跑步保留固定地面原点，其他图集按可见躯干和脚部注册锚点，避免把刀尖、淡透明噪声或宽站姿的衣摆误当脚点。元数据以本地脚本加载，保持双击 HTML 的离线能力。

## 代码入口

| 文件                       | 职责                                       |
| -------------------------- | ------------------------------------------ |
| `src/animation.js`         | 动作时钟、朝向、步态、动作帧和上下半身组合 |
| `src/game.js`              | 命中时点、动作取消、扩张波面与收势         |
| `src/combat-effects.js`    | 刀光、聚气、落尘、法光与剑阵               |
| `src/render.js`            | 图集绘制、姿态残像与场景合成               |
| `art/prepare-animation.py` | 透明通道、切帧、锚点和本地元数据           |

## 验证与演示边界

- 当前重设计复查：`screenshots/animation-v2/stride-review.json`；旧动作专项 `screenshots/animation-v2/verification.json` 是历史记录。
- 原有流程和输入：`screenshots/verification.json`、`screenshots/input-checks.json`。
- 图集数据：`screenshots/animation-v2/atlas-report.json`。
- 连续演示由实际游戏渲染器与键盘输入录制；位置、生命、镜头采用固定靶场状态，便于看清动作，不是一次真人通关录像。
- 循环 GIF 直接来自注册后的动作帧。实际游戏另外包含位移、镜头、预警和特效。
- 本轮保留基础伤害、宗派、圣物与九战结构。自动化验证不等同于真人完整通关、长期平衡测试或商业原作的全部动作复刻。