first commit

This commit is contained in:
2026-09-19 17:24:02 +08:00
commit afb343aa49
109 changed files with 13011 additions and 0 deletions
+21
View File
@@ -0,0 +1,21 @@
# Godot generated files
.godot/
.mono/
# .NET build output
bin/
obj/
# IDE state
.vs/
.vscode/
*.user
*.suo
# Local exports and logs
build/
exports/
logs/
# Game Assets
assets/
+10
View File
@@ -0,0 +1,10 @@
本项目旨在为虚构游戏《筽祀牻》(英文:OSM)制作更多世界观设定、剧情文案以及角色人设设计,最后以制作可用的2D素材为目标。
本文档可以随时更新、补充重要信息和约束。
官方网站:https://docs.milimoe.com
世界观图书馆:https://milimoe.com/regions
Godot控制台:"C:\\milimoe\\Godot\\Godot\_v4.7-stable\_mono\_win64\_console.exe"
+11
View File
@@ -0,0 +1,11 @@
<Project Sdk="Godot.NET.Sdk/4.7.0">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<EnableDynamicLoading>true</EnableDynamicLoading>
<RootNamespace>OSM.Client</RootNamespace>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<LangVersion>latest</LangVersion>
</PropertyGroup>
</Project>
@@ -0,0 +1,96 @@
# 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`
+535
View File
@@ -0,0 +1,535 @@
# 《筽祀牻》2D 角色分解素材规范(以 02 汐月心音为例)
> 状态:4.75 头身与四方向移动方案已确认;运行时 LEFT(旧 `front-right`)、RIGHT(旧 `front-left`)、DOWN 与 UP 均已完成中性装配、待机/投掷运动及 176/132/88 px 三档循环播放验证;模板角色交付包 v1 与统一接入清单已完成;P0 v2 与 P1 v2 动作关键姿势已完成
> 适用目标:Godot 斜俯视战棋中的纯 2D 单位,固定镜头,脚底中心锚定
> 参考素材:`assets/images/characters/cards/汐月心音:银月刺客卡.png`、`assets/images/characters/overviews/铎京派系五人角色设定图.png`、02 号角色头像与技能图标
## 1. 结论
首个战场角色建议采用 **4.5~5 头身的轻 Q 版战斗比例**,而不是现有立绘约 7~7.5 头身的成体比例,也不采用 2~3 头身的大头萌系 Q 版。
2026-09-18 已通过比例对比图确认以 **4.75 头身**作为汐月心音及后续战场角色的首选测试基线。该比例仍需在实际 Godot 灰盒场景中验证,验证通过后再上升为全角色硬性规范。
若只能在“成体”和“Q 版”中二选一,应选 **Q 版**;但最终美术应明确标注为“轻 Q/战斗比例”,避免过度幼态化。
理由:
- 战场基础格为 128 × 64 px,常用镜头需同时显示约 10~14 格宽。正常人体比例缩小后,头、手、暗器与动作方向很难辨认。
- 心音的识别点是高马尾、银色羽刃、银肩甲、月白外衫和朱砂红绳。这些元素需要更大的头身占比、手部动作和轮廓面积。
- 轻 Q 比例可以保留她冷静、利落的成年刺客气质;纯萌系 Q 版会削弱离岸监狱、暗杀和铎京政治线的严肃感。
- 轻 Q 角色更容易与半隐藏网格、掩体和 HUD 共存,也便于后续 18 名角色统一剪影语言。
建议先做同一姿势的三档缩放测试:7 头身、4.75 头身、3 头身。将角色分别按战场显示高度 160、176、192 px 放入 128 × 64 菱形格和铎京灰盒地图,以 100%、75%、50% 三档镜头检查。默认候选为 **4.75 头身、显示高度约 176 px**。
## 2. 技术路线
心音适合作为 `Skeleton2D` 分解动画范例。源文件保留分层部件,Godot 中用骨骼完成呼吸、移动、瞄准、受击等连续动作;必要时把动画烘焙为 `AnimatedSprite2D` 序列帧,以兼容性能和批量生产。
不要为每一帧绘制完整人物。需要绘制的是:
1. 每个方向的中性战斗姿势分解件;
2. 关节弯曲时会露出的替换件;
3. 手型、脚型、表情和裙摆/马尾极端形变;
4. 每个动作的关键姿势参考;
5. 与角色身体分离的暗器、残影、月轮和命中特效。
正式品质改用四个画面方向:`up / down / left / right`。左右方向保留三分之四侧身表现,不要求严格正侧面;上下方向分别使用背面与正面构图。心音的发饰、腰包、持刃手和马尾存在固定不对称关系,因此 LEFT 与 RIGHT 仍需独立绘制,禁止通过水平镜像互相生成。
运行时映射暂定为:`left ← 旧 front-right`,`right ← 旧 front-left`;旧目录与清单暂不重命名,以免破坏已有提取、装配和运动路径。新制作的 UP/DOWN 及未来统一导出文件直接使用四方向名称。移动输入按主轴选择身体朝向,斜向临界区保持上一朝向以避免闪烁;身体只使用四向,但投射物、准星和技能 VFX 可以自由角度瞄准。
所有方向都以脚底中心为统一原点。人物贴图不烘焙脚底阴影、选中环、格子高亮和命中特效。
## 3. 首批动作清单
### P0:战斗竖切必需
| 动作 | 建议时长 | 关键姿势/图片 | 心音的表现重点 |
|---|---:|---:|---|
| `idle` 待机 | 1.8~2.4 s 循环 | 2 个极值姿势 | 重心微降,呼吸克制;手指靠近袖中羽刃;马尾与短披风低幅摆动 |
| `move` 移动 | 0.7~0.9 s 循环 | 4 个步态极值 | 轻跑而非普通走路;上身稳定、步幅轻快;不能像重装角色一样上下弹跳 |
| `attack_1` 普攻首击 | 0.35~0.5 s | 预备、出手、收势 3 张 | 单手甩出一枚羽刃,动作短、直、无大幅蓄力 |
| `attack_2` 被动追击 | 0.25~0.4 s | 换手、追刃、回正 3 张 | 与首击明显不同,建议反手追加两枚较小羽刃,表现“心灵之弦”的双段普攻 |
| `burst` 千羽瞬华 | 1.0~1.4 s | 起势、展开、指向、收束 4 张 | 低身洞悉弱点,旋身展开羽阵,最后并指锁定目标;月轮和羽群独立为特效层 |
| `hit` 受击 | 0.25~0.4 s | 受力极值、恢复 2 张 | 侧身卸力,幅度小但方向清晰;高马尾延迟甩动 |
| `defeat` 倒下 | 0.9~1.3 s + 静止 | 失衡、跪地、侧倒、地面 4 张 | 羽刃脱手但不飞远,最终轮廓不能超出单格太多 |
### P1:体现角色机制,建议与 P0 同批设计
| 动作 | 关键姿势/图片 | 用途 |
|---|---:|---|
| `ready` 观察/备战 | 2 张 | 轮到角色行动、选择目标时使用;视线先于身体转向 |
| `dodge` 闪避 | 压低、侧移、残影 3 张 | 对应爆发技提升闪避;身体瞬移,残影与月色轨迹独立 |
| `weakpoint_lock` 弱点锁定 | 观察、抬手标记 2 张 | 技能预览或暴露弱点时使用,强化“先观察后行动”的人设 |
| `cover_idle` 掩体待机 | 进入、贴靠、探身 3 张 | 地图已有掩体规则,避免角色站在墙后仍保持开阔地待机 |
| `cover_attack` 掩体出手 | 探身、投掷、收回 3 张 | 保持快速投掷,不让身体大面积穿过掩体 |
### P2:通用系统与展示扩展
- `item_use`:取物、使用、归位。
- `cast`:通用魔法起势与释放;法术本体独立为公共特效。
- `interact`:操作机关、拾取或开启目标。
- `victory`:确认安全后收回羽刃,不做活泼庆祝动作。
- `spawn`:从月色残影中落地,适合战斗开场。
- `revive`:跪地恢复到警戒姿势。
- `heavy_hit / knockback`:明显位移或破防时使用。
P0 共需约 20 张动作关键姿势参考;P1 再增加约 13 张。这些是动画设计稿数量,不等于最终逐帧图片数量。
## 4. 汐月心音的分解部件
### 身体基础
- 头部/颈部;
- 胸腔/腹部/骨盆;
- 左右上臂、前臂、手掌;
- 左右大腿、小腿、脚掌;
- 肩、肘、腕、髋、膝、踝部都需保留足够重叠区,旋转后不能露缝。
### 头发与面部
- 后脑基础发团、前刘海、左右鬓发;
- 高马尾根部、主马尾 2~3 段、末端散发;
- 银蓝发绳与羽形发簪独立;
- 眼白/虹膜/上眼睑、眉、嘴独立;
- 至少准备平静、专注、受击、虚弱 4 组表情,以及普通瞳和羽状发光瞳。
### 服装与硬质件
- 月白交领内衫、深靛胸腰甲、腰封;
- 左右肩部银色羽片护甲;
- 左右袖片、前裙片、后裙片、侧裙片分别拆开;
- 短披风至少拆成左、中、右三片;
- 朱砂腰绳、流苏和暗器袋独立;
- 护腕、腿甲与靴面尽量跟随对应肢体,但硬质尖角可单独切片以避免变形。
### 武器与特效挂点
- 单枚“千羽”、双枚追击羽刃、手持三枚扇形羽刃;
- 发簪形态与投掷形态分别绘制;
- 袖口、腰侧、发簪三个出刃挂点;
- 右手/左手握持点、目标锁定点、身体中心特效点、脚底特效点;
- 月轮、飞行羽群、轨迹、残影、弱点标记、命中闪光全部放入独立 VFX 图集,不与身体切片合并。
## 5. 需要制作的图稿
1. **比例测试图**:7 头身、4.75 头身、3 头身并排,附 128 × 64 格与实际战场缩放预览。
2. **四方向转面图**:UP/DOWN/LEFT/RIGHT 使用统一中性战斗姿势,先确认剪影、服装前后关系和光源。
3. **四方向分解源文件**:每个方向一组完整图层,关节重叠区与旋转轴清楚可见。
4. **P0 动作关键姿势表**:约 20 个关键姿势,先以 LEFT 与 RIGHT 验证动作语言,再扩展到 UP/DOWN。
5. **表情与替换件表**:眼、眉、嘴、手型、脚型、裙摆和马尾极端形变。
6. **千羽与 VFX 表**:暗器本体、月轮路径、残影、弱点标记和命中闪光。
7. **游戏内合成预览**:放入铎京灰盒地图,展示待机、移动、普攻、爆发、受击和倒下。
制作顺序调整为 `比例测试 → LEFT/RIGHT 三分之四侧身 → 左右完整分解与运动验证 → DOWN 正面 → UP 背面 → 游戏内四向验证`。不再生产八方向整套角色身体;斜向攻击由四向身体、手臂姿势与自由角度 VFX 共同表达。
当前已完成:
- `assets/images/2d-game-characters/02-xinyin/direction-map-v1.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-4way-direction-map-v1.png`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-proportion-comparison-v1.png`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-4dir-turnaround-v1.png`
- `assets/images/2d-game-characters/02-xinyin/source/xinyin-front-right-parts-sheet-v1.png`
- `assets/images/2d-game-characters/02-xinyin/source/action-keyposes/xinyin-p0-idle-move-attacks-v1.png`
- `assets/images/2d-game-characters/02-xinyin/source/action-keyposes/xinyin-p0-burst-hit-defeat-v1.png`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-action-readability-test-v1.png`
- `assets/images/2d-game-characters/02-xinyin/source/action-keyposes/xinyin-p0-corrections-v2.png`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-action-readability-test-v2.png`
- `assets/images/2d-game-characters/02-xinyin/source/action-keyposes/xinyin-p1-ready-dodge-weakpoint-v1.png`
- `assets/images/2d-game-characters/02-xinyin/source/action-keyposes/xinyin-p1-cover-v1.png`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-p1-readability-test-v1.png`
- `assets/images/2d-game-characters/02-xinyin/source/action-keyposes/xinyin-p1-ready-dodge-weakpoint-v2.png`
- `assets/images/2d-game-characters/02-xinyin/source/action-keyposes/xinyin-p1-cover-left-v1.png`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-p1-readability-test-v2.png`
- `assets/images/2d-game-characters/02-xinyin/parts/front-right/v1/`(40 件独立透明 PNG)
- `assets/images/2d-game-characters/02-xinyin/parts/front-right/v1/parts-manifest.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-front-right-extracted-parts-v1.png`
- `assets/images/2d-game-characters/02-xinyin/reference/xinyin-front-right-assembled-reference-v1.png`
- `assets/images/2d-game-characters/02-xinyin/assembled/front-right/xinyin-front-right-neutral-assembly-v4.png`
- `assets/images/2d-game-characters/02-xinyin/assembled/front-right/assembly-layout-v4.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-front-right-assembly-validation-v4.png`
- `assets/images/2d-game-characters/02-xinyin/motion/front-right/v3/`(7 个透明运动关键帧与清单)
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-front-right-motion-validation-v3.png`
- `assets/images/2d-game-characters/02-xinyin/previews/playback/xinyin-front-right-idle-scale-loop-v1.gif`
- `assets/images/2d-game-characters/02-xinyin/previews/playback/xinyin-front-right-throw-scale-loop-v1.gif`
- `assets/images/2d-game-characters/02-xinyin/motion/front-right/v3/playback-report.json`
- `assets/images/2d-game-characters/02-xinyin/source/rig-corrections/xinyin-front-right-rig-corrections-v1.png`(首版对照,马尾未正确分段)
- `assets/images/2d-game-characters/02-xinyin/source/rig-corrections/xinyin-front-right-rig-corrections-v2.png`(采用的补件源板)
- `assets/images/2d-game-characters/02-xinyin/parts/front-right/rig-corrections-v1/`(11 件透明补件与清单)
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-front-right-rig-corrections-v1.png`
- `assets/images/2d-game-characters/02-xinyin/source/front-left/xinyin-front-left-neutral-master-v1.png`(方向探索稿,保留作对照)
- `assets/images/2d-game-characters/02-xinyin/source/front-left/xinyin-front-left-neutral-master-v2.png`(当前前左高分辨率母版)
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-front-left-master-validation-v1.png`
- `assets/images/2d-game-characters/02-xinyin/source/front-left/xinyin-front-left-core-parts-sheet-v1.png`(17 件核心身体/四肢)
- `assets/images/2d-game-characters/02-xinyin/source/front-left/xinyin-front-left-soft-parts-sheet-v1.png`(26 件头发/衣摆/附件)
- `assets/images/2d-game-characters/02-xinyin/source/front-left/source-sheet-manifest-v1.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-front-left-parts-sheets-validation-v1.png`
- `assets/images/2d-game-characters/02-xinyin/parts/front-left/v1/`(43 件独立透明 PNG)
- `assets/images/2d-game-characters/02-xinyin/parts/front-left/v1/parts-manifest.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-front-left-extracted-parts-v1.png`
- `assets/images/2d-game-characters/02-xinyin/assembled/front-left/xinyin-front-left-neutral-assembly-v1.png`(首次装配候选,保留作对照)
- `assets/images/2d-game-characters/02-xinyin/assembled/front-left/xinyin-front-left-neutral-assembly-v2.png`(当前中性装配基线)
- `assets/images/2d-game-characters/02-xinyin/assembled/front-left/assembly-layout-v2.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-front-left-assembly-validation-v2.png`
- `assets/images/2d-game-characters/02-xinyin/source/rig-corrections/xinyin-front-left-rig-corrections-v1.png`(首版对照,马尾仍为大块候选)
- `assets/images/2d-game-characters/02-xinyin/source/rig-corrections/xinyin-front-left-rig-corrections-v2.png`(采用的前左补件源板)
- `assets/images/2d-game-characters/02-xinyin/parts/front-left/rig-corrections-v1/`(5 件透明补件与清单)
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-front-left-rig-corrections-v1.png`
- `assets/images/2d-game-characters/02-xinyin/assembled/front-left/xinyin-front-left-neutral-assembly-v4.png`(补件后的当前基线)
- `assets/images/2d-game-characters/02-xinyin/assembled/front-left/assembly-layout-v4.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-front-left-assembly-validation-v4.png`
- `assets/images/2d-game-characters/02-xinyin/motion/front-left/v1/`(运行时 RIGHT 的 7 个透明运动关键帧与清单)
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-front-left-motion-validation-v1.png`
- `assets/images/2d-game-characters/02-xinyin/previews/playback/xinyin-front-left-idle-scale-loop-v1.gif`
- `assets/images/2d-game-characters/02-xinyin/previews/playback/xinyin-front-left-throw-scale-loop-v1.gif`
- `assets/images/2d-game-characters/02-xinyin/motion/front-left/v1/playback-report.json`
- `assets/images/2d-game-characters/02-xinyin/source/down/xinyin-down-neutral-master-generation-v1.png`(内置图像生成的留档结果)
- `assets/images/2d-game-characters/02-xinyin/source/down/xinyin-down-neutral-master-v1.png`(增加透明安全边距后的当前 DOWN 母版)
- `assets/images/2d-game-characters/02-xinyin/source/down/master-manifest-v1.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-down-master-validation-v1.png`
- `assets/images/2d-game-characters/02-xinyin/source/down/xinyin-down-core-parts-sheet-v1.png`(17 件核心身体/四肢)
- `assets/images/2d-game-characters/02-xinyin/source/down/xinyin-down-soft-parts-sheet-v1.png`(拥挤排布的失败对照,保留用于追溯)
- `assets/images/2d-game-characters/02-xinyin/source/down/xinyin-down-soft-parts-sheet-v2.png`(当前 24 件头发/衣摆/附件板)
- `assets/images/2d-game-characters/02-xinyin/source/down/source-sheet-manifest-v1.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-down-parts-sheets-validation-v1.png`
- `assets/images/2d-game-characters/02-xinyin/parts/down/v1/`(41 件独立透明 PNG)
- `assets/images/2d-game-characters/02-xinyin/parts/down/v1/parts-manifest.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-down-extracted-parts-v1.png`
- `assets/images/2d-game-characters/02-xinyin/assembled/down/xinyin-down-neutral-assembly-v1.png`
- `assets/images/2d-game-characters/02-xinyin/assembled/down/assembly-layout-v1.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-down-assembly-validation-v1.png`
- `assets/images/2d-game-characters/02-xinyin/motion/down/v1/`(7 个透明运动关键帧与清单)
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-down-motion-validation-v1.png`
- `assets/images/2d-game-characters/02-xinyin/previews/playback/xinyin-down-idle-scale-loop-v1.gif`
- `assets/images/2d-game-characters/02-xinyin/previews/playback/xinyin-down-throw-scale-loop-v1.gif`
- `assets/images/2d-game-characters/02-xinyin/motion/down/v1/playback-report.json`
- `assets/images/2d-game-characters/02-xinyin/source/up/xinyin-up-neutral-master-generation-v1.png`(内置图像生成的留档结果)
- `assets/images/2d-game-characters/02-xinyin/source/up/xinyin-up-neutral-master-v1.png`(增加透明安全边距后的当前 UP 母版)
- `assets/images/2d-game-characters/02-xinyin/source/up/master-manifest-v1.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-up-master-validation-v1.png`
- `assets/images/2d-game-characters/02-xinyin/source/up/xinyin-up-core-parts-sheet-v1.png`(上臂仍带袖披的失败对照)
- `assets/images/2d-game-characters/02-xinyin/source/up/xinyin-up-core-parts-sheet-v2.png`(采用的 17 件核心板)
- `assets/images/2d-game-characters/02-xinyin/source/up/xinyin-up-soft-parts-sheet-v1.png`(肩甲/流苏层级混入的失败对照)
- `assets/images/2d-game-characters/02-xinyin/source/up/xinyin-up-soft-parts-sheet-v2.png`(采用的 24 件软性/附件板)
- `assets/images/2d-game-characters/02-xinyin/source/up/source-sheet-manifest-v1.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-up-parts-sheets-validation-v1.png`
- `assets/images/2d-game-characters/02-xinyin/parts/up/v1/`(41 件独立透明 PNG)
- `assets/images/2d-game-characters/02-xinyin/parts/up/v1/parts-manifest.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-up-extracted-parts-v1.png`
- `assets/images/2d-game-characters/02-xinyin/assembled/up/xinyin-up-neutral-assembly-v1.png`
- `assets/images/2d-game-characters/02-xinyin/assembled/up/assembly-layout-v1.json`
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-up-assembly-validation-v1.png`
- `assets/images/2d-game-characters/02-xinyin/motion/up/v1/`(7 个透明运动关键帧与清单)
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-up-motion-validation-v1.png`
- `assets/images/2d-game-characters/02-xinyin/previews/playback/xinyin-up-idle-scale-loop-v1.gif`
- `assets/images/2d-game-characters/02-xinyin/previews/playback/xinyin-up-throw-scale-loop-v1.gif`
- `assets/images/2d-game-characters/02-xinyin/motion/up/v1/playback-report.json`
- `assets/images/2d-game-characters/02-xinyin/template-package-v1.json`(四方向模板角色统一入口)
- `assets/images/2d-game-characters/02-xinyin/previews/xinyin-template-role-handoff-v1.png`
- `docs/02汐月心音模板角色交付说明.md`
- `templates/2d-character-v1/template-manifest.json`(后续角色的空白模板入口)
- `templates/2d-character-v1/production-checklist.md`
- `tools/scaffold_2d_character.py`
前右方向已按 8 邻域透明连通对象从源板中无串片拆出 40 件 PNG,每件保留 8 px 安全边距。清单记录源图裁切框、导出尺寸、建议层级和初始枢轴;左侧整身图单独保存为装配参考,不计入 40 件运行时部件。原始部件包仍标记为 `extracted-unvalidated`;11 件骨骼补件、美术侧中性站姿装配 v4 与关键帧运动验证 v3 已通过,引擎插值、关节补缝和游戏内缩放尚未验证。
当前没有 Godot 项目,故本阶段只完成可复现的美术资产拆分与元数据准备。`tools/Inspect-XinyinPartsSheet.ps1` 用于复查任意透明源板的对象编号,`tools/Extract-XinyinParts.ps1` 可从原始源板重新生成整套部件、清单、整身参考和检查总览,`tools/Extract-XinyinRigCorrections.ps1` 用于生成骨骼补件包,`tools/Build-XinyinAssemblyValidation.ps1` 与 `tools/Build-XinyinMotionValidation.ps1` 分别重建前右中性站姿和运动关键帧,`tools/build_xinyin_front_left_motion.py` 从前左装配 v4 重建运行时 RIGHT 的运动帧,`tools/build_xinyin_down_assembly.py` 与 `tools/build_xinyin_down_motion.py` 从正面部件重建 DOWN 中性站姿和运动关键帧,`tools/build_xinyin_up_master_validation.py` 与 `tools/build_xinyin_up_source_sheets_validation.py` 整理并验证 UP 母版和 17+24 件分解源板,`tools/extract_xinyin_up_parts.py` 从采用的两张 v2 源板重建 41 件 UP 独立部件、清单与检查总览,`tools/build_xinyin_up_assembly.py` 与 `tools/build_xinyin_up_motion.py` 分别重建 UP 的 32 件中性装配及 7 帧动作;通用 `tools/build_xinyin_motion_playback.py` 已支持 LEFT/RIGHT/DOWN/UP 四个运行时方向的三档循环复查,`tools/build_xinyin_template_package.py` 校验并重建统一交付清单和四向总览,`tools/scaffold_2d_character.py` 则为后续角色安全创建标准目录与初始配置。这些流程均不会覆盖原始源板或已有角色目录。
四方向运行时映射 v1:
- `left` 使用旧 `front-right` 美术包,人物鼻尖和持扇动作朝向画面左侧;该方向已经完成中性装配、待机/投掷运动与三档循环验证;
- `right` 使用旧 `front-left` 美术包,人物鼻尖和持扇动作朝向画面右侧;该方向已经完成中性装配 v4、骨骼补件及待机/投掷运动验证 v1;
- `up` 已完成严格背面高分辨率母版 v1、17+24 件分解源板、41 件独立裁切、32 件中性装配、待机/投掷运动及三档循环验证;`down` 已完成新正面高分辨率母版 v1、41 件独立裁切、32 件中性装配、待机/投掷运动与三档循环验证;旧四斜向转面图只保留为造型参考,不再作为最终方向数量;
- 旧目录保持不变,运行时或未来导出流程通过 `template-package-v1.json` 进入,再由 `direction-map-v1.json` 读取别名;新方向和最终标准化文件只使用 `up / down / left / right`;
- 方向选择使用主轴与 15% 斜向滞回区:横轴明显占优时选择 LEFT/RIGHT,纵轴明显占优时选择 UP/DOWN,临界区保持上一朝向;瞄准、投射物和 VFX 不受四向身体限制。
DOWN 正面母版 v1 结论:
- 新母版严格使用正面构图,头、胸和骨盆均朝向玩家,不沿用旧四斜向转面图中的三分之四角度,也不由 LEFT/RIGHT 镜像生成;
- 角色右手固定在画面左侧持三枚蓝银羽扇,角色左侧腰包和放松手固定在画面右侧;高马尾与外衣可以形成不对称轮廓,但双脚基线和身体主轴保持对称;
- 生成留档为 1024 × 1536 px 透明 PNG;正式母版增加 64 px 透明安全边距,画布为 1152 × 1664 px,可见 Alpha 范围为 957 × 1448 px,四边均未触碰;
- 母版采用约 4.75 头身的成年轻 Q 战斗比例;缩放到 352/176/88 px 后,高马尾、银羽肩甲、蓝银羽扇、白蓝衣摆和朱砂红绳仍可辨认;
- 母版本身状态为 `master-art-validated`;其核心/软性源板、独立裁切、中性装配与待机/投掷动作验证均已完成。
DOWN 分解源板 v1 结论:
- 核心板为 1536 × 1024 px 透明画布,检测到 17 个独立对象:头面、颈部、上身、骨盆、双肩甲、独立双上臂、双前臂、三种手型及双腿;肩甲、上臂、前臂和手没有互相粘连;
- 软性板首稿把八片衣摆的半透明边缘连成大块,保留为失败对照;v2 改用 6×4 隐形生产网格,每格只放一个对象,检测到 24 个独立对象;
- 软性板 v2 包含前发、后发帽、马尾根/中/尾、长银饰、双袖披、八片中性衣摆、一片动作替换衣摆、腰前布、腰包、双流苏及三种羽刃;
- 两张采用源板合计 41 件,在 Alpha 阈值 16、最小面积 80、8 邻域检测下均无跨件连接,画布四角透明;
- 源板状态为 `source-sheets-alpha-validated`;部件名称、父子层级、根枢轴与远端关节已经写入正式清单,并通过中性装配冻结当前取舍。
DOWN 独立部件包 v1 结论:
- 两张采用源板已按 Alpha 阈值 16 的 8 邻域连通对象裁切为 41 件独立透明 PNG,每件四周保留 10 px 安全边距;41 件均未触碰导出边缘;
- 核心件使用 `down-core-cNN-*`,软性件使用 `down-soft-cNN-*`,编号可回溯到源板诊断图;软性板 v1 不参与裁切,正式来源固定为 v2;
- A 组冻结为画面左侧/角色右侧/持扇手链,B 组冻结为画面右侧/角色左侧/放松手链;DOWN 严禁通过水平镜像交换这两组;
- `parts-manifest.json` 为每件记录源裁切框、输出尺寸、父节点、建议层级、根枢轴与下一关节点;红色十字为根枢轴,蓝色十字为下一关节;
- 原始部件包仍保留 `extracted-unvalidated` 状态,以区分“单件裁切”和“组合验证”;衣摆取舍、马尾链连接、手腕连续性和脚底基线已经由装配清单 v1 冻结。
DOWN 中性装配 v1 结论:
- 600 × 760 px 透明画布使用 32 件中性部件,另外 9 件作为投掷手、独立武器、替换衣摆/腰饰保留;41 件全部有明确去向,没有遗漏或重复使用;
- A 组保持画面左侧持扇,B 组保持画面右侧放松;肩—肘—腕通过关节内压重叠消除切口,三段马尾保持画面右后方轮廓,八片衣摆收束到骨盆挂点后再向两侧展开;
- 左右靴的 Alpha 脚底均落在 `y = 734`,基线差为 0 px;成图可见范围为 `x = 128..475`、`y = 93..734`,四边保持透明;
- `pelvis-hip-core` 已包含中性腰前布、红绳、流苏与腰包,因此对应独立件不在中性装配中重复叠画;动作时可按清单替换;
- 静态装配状态为 `static-art-validated`;其上制作的动作关键帧与三档循环也已通过,方向总状态见下节。
DOWN 动作验证 v1 结论:
- 已导出待机吸气/中性/呼气 3 帧及投掷准备/蓄势/释放/回收 4 帧,全部采用 600 × 760 px 透明画布;七帧脚底 Alpha 均落在 `y = 734`,基线差为 0 px,画布四边透明;
- 身体主轴始终保持严格正面,持扇 A 手从画面左侧蓄势并向左完全展开;释放帧切换为张手和单枚脱手羽刃,投射物与 VFX 的实际瞄准仍由运行时自由角度控制;
- 放松 B 手保持稳定,三段马尾和八片衣摆仅作滞后摆动;当前幅度内未出现明显断缝、穿脸或脚底漂移;
- 176/132/88 px 循环共用固定裁切框与脚底原点,不按帧重新居中;待机周期为 1360 ms,投掷回到中性的周期为 790 ms;
- 当前方向状态提升为 `motion-art-validated`。UP 背面母版、分解源板、独立部件包与中性装配已经完成,后续进入运动验证。
UP 背面母版 v1 结论:
- 新母版严格使用背面构图,后脑、肩背、躯干、骨盆、膝后与鞋跟均朝向玩家;没有露出脸部或侧脸,也没有沿用旧转面图的三分之四角度;
- 转身后的固定侧别为:角色右手/画面右侧持三枚蓝银羽刃,角色左手与黑色腰包位于画面左侧,长银花发饰和高马尾主体也向画面左后方展开;该关系不是对 DOWN 的简单水平镜像;
- 图像生成留档为 1044 × 1507 px 透明 PNG;正式母版置于 1152 × 1664 px 透明画布,可见 Alpha 范围为 998 × 1426 px,四边均未触碰;左右可见底部分别为 `y = 1520 / 1521`,差 1 px;
- 背部高领、肩带、银羽肩甲、红色腰绳、后腰结、腰包、八片衣摆、流苏、腿甲与鞋跟均具有可分解轮廓;352/176/88 px 下马尾、持扇手、白蓝衣摆和红绳仍可辨认;
- 母版状态为 `master-art-validated`;其核心身体/肢体板与软性部件/附件板也已完成,结论见下节。
UP 分解源板 v1 结论:
- 核心板采用 v2:1536 × 1024 px 透明画布,17 个独立对象;v1 的两件上臂错误混入完整袖披,保留为失败对照,v2 已改为紧凑的肩—肘黑色上臂段;
- 软性/附件板采用 v2:1536 × 1024 px、6×4 隐形生产网格、24 个独立对象;v1 的双袖披混入肩甲,九片衣摆中又有多片烘焙流苏/挂链,v2 已全部拆清;
- 采用板合计 41 件,在 Alpha 阈值 16、最小面积 80、8 邻域检测下恰好为 17+24 个连通对象,画布四角透明,没有跨格连接;
- UP 的 A 组冻结为画面右侧/角色右侧/持扇手链,B 组冻结为画面左侧/角色左侧/放松手及腰包侧;不得沿用 DOWN 的画面侧别;
- 源板状态为 `source-sheets-alpha-validated`;41 件对象已经完成独立裁切,进入部件包阶段。
UP 独立部件包 v1 结论:
- 两张采用的 v2 源板已按 Alpha 阈值 16 的 8 邻域连通对象裁切为 41 件独立透明 PNG;每件四周保留 10 px 安全边距,外边缘均为透明;
- 核心件使用 `up-core-cNN-*`,软性/附件件使用 `up-soft-cNN-*`,编号可以直接回溯源板诊断图;两张失败的 v1 源板不参与裁切;
- A 组冻结为画面右侧/角色右侧/持扇手链,B 组冻结为画面左侧/角色左侧/放松手及腰包侧;该约定与 DOWN 的画面侧别相反;
- `parts-manifest.json` 已为每件记录源裁切框、输出尺寸、父节点、建议层级、根枢轴与下一关节点;检查总览中的红色十字为根枢轴,蓝色十字为下一关节;
- 部件包保持 `extracted-unvalidated` 状态,用来区分原始裁切与组合验证;枢轴、层级和中性取舍已经由 UP 中性装配 v1 冻结。
UP 中性装配 v1 结论:
- 600 × 760 px 透明画布使用 32 件中性部件,另外 9 件作为投掷手、独立武器、替换衣摆/腰饰保留;41 件全部有明确去向,没有遗漏或重复使用;
- A 组保持画面右侧持扇,B 组保持画面左侧放松;肩—肘—腕通过关节内压重叠消除切口,三段马尾从头冠连续落向画面左侧腰后,八片衣摆从后腰向下展开;
- 左右靴的 Alpha 脚底均落在 `y = 735`,基线差为 0 px;成图可见范围为 `x = 130..469`、`y = 79..735`,画布四边保持透明;
- `pelvis-hip-core` 已包含中性腰后布、红绳、流苏与画面左侧腰包,因此对应独立件不在中性装配中重复叠画;动作时可按清单替换;
- 静态装配状态为 `static-art-validated`;其上的待机与投掷关键帧也已完成,结论见下节。
UP 动作验证 v1 结论:
- 已导出待机吸气/中性/呼气 3 帧及投掷准备/蓄势/释放/回收 4 帧,全部采用 600 × 760 px 透明画布;七帧脚底 Alpha 均落在 `y = 735`,基线差为 0 px,画布四边透明;
- 身体主轴始终保持严格背面,持扇 A 手从画面右侧蓄势并向右完全展开;释放帧切换为张手和单枚脱手羽刃,投射物与 VFX 的实际瞄准仍由运行时自由角度控制;
- 放松 B 手保持稳定,三段马尾和八片衣摆只作滞后摆动;当前幅度内未出现明显断缝、穿头或脚底漂移;
- 待机关键帧沿用 420/260/420 ms 节奏,投掷关键帧沿用 150/110/90/180 ms 节奏,与其余三个运行时方向保持一致;
- 动作状态为 `motion-art-validated`;其 176/132/88 px 固定裁切循环也已完成,结论见下节。
UP 三档循环验证 v1 结论:
- 待机循环使用 `inhale 420 ms → neutral 260 ms → exhale 420 ms → neutral 260 ms`,总周期 1360 ms;投掷循环使用 `ready 150 ms → windup 110 ms → release 90 ms → recover 180 ms → neutral 260 ms`,总周期 790 ms;
- 两组 GIF 均使用源画布上的同一 `484 × 677 px` 联合裁切框和同一脚底原点,没有按帧重新居中;所有源帧的可见底部均为 `y = 736`,范围差为 0;
- 176/132/88 px 三档分别对应 128×64、96×48、64×32 菱形格;缩至 88 px 后,背面朝向、画面右侧投掷、画面左侧马尾、白蓝衣摆和红色腰绳仍可辨认;
- GIF 分别包含 4 个待机播放帧和 5 个投掷播放帧,逐帧时长与 `motion-manifest.json` 一致;UP 至此达到与 LEFT/RIGHT/DOWN 相同的美术侧验证深度。
通用空白角色模板 v1 结论:
- 已从心音流程中抽离出 `templates/2d-character-v1/`,只保留四方向目录、4.75 头身基线、600×760 动作画布、底部中心原点、176/132/88 px 三档显示规格、七关键帧时序和阶段验收规则;
- 新角色默认直接使用 `up / down / left / right` 目录,不继承心音的 `front-left / front-right` 历史别名,也不继承其 A/B 侧别、武器手或附件关系;
- `production-checklist.md` 将流程拆为 G0~G7:角色基线、四向母版、分解源板、独立裁切、中性装配、动作验证、三档循环与模板交付;
- `validation-rules-v1.json` 固定透明边缘、脚底 0 px 差、联合裁切、禁止逐帧重居中、部件全量记账和镜像需显式批准等硬性门槛;
- `tools/scaffold_2d_character.py` 可按编号与名称安全生成新角色骨架,默认拒绝覆盖已有目录;模板 JSON、占位符替换和 dry-run 均已通过验证。
前左方向母版 v2 结论:
- `front-left` 是历史制作方向编号,运行时别名已经冻结为 `right`;本节继续使用旧名,只为保持已有文件路径和清单兼容;
- 旧制作方向定义以四斜向转面表第二姿为准,运行时移动方向则直接按画面 LEFT/RIGHT 判定;
- 羽扇/持械手固定在画面右侧,腰包与长银饰固定在画面左侧,高马尾主体位于左后方;后续部件板与动作不得整体水平镜像;
- `xinyin-p1-cover-left-v1.png` 表达的是左侧掩体的探身与遮挡关系,只作为动作姿势参考,不覆盖中性转面方向;
- v2 为 1017 × 1547 px 透明母版,四角透明;缩放到 352 px 工作高度、176 px 游戏基准高度和 88 px 检查高度后,高马尾、羽扇、白/靛衣摆及朱砂系带仍可辨认;
- v1 保留为方向探索对照,不进入后续拆分;下一阶段以 v2 为唯一来源绘制前左核心身体/肢体板和头发/衣摆/附件板。
前左分解源板 v1 结论:
- 核心板为 1536 × 1024 px 透明画布,恰好检测到 17 个独立对象:头面、颈部、上身、骨盆、双肩甲、双侧上臂/前臂/手型及双腿;
- 软性与附件板同为 1536 × 1024 px 透明画布,检测到 26 个独立对象:头发链、侧发、发饰、袖披、衣摆、腰布、腰包、流苏和三种羽刃;
- 两张源板合计 43 件,四角全透明,Alpha 阈值 16、最小面积 80 的 8 邻域检测下无串片;
- 软性板比原计划多出一片后裙候选,保留为动作替换件;马尾根部自带贴合头顶的花冠,独立长银饰仍作为可替换层;腰前布自带基线系绳,独立流苏作为运动替换件;
- 当前状态为 `source-sheets-alpha-validated`,尚未裁切成单件 PNG,也未完成前左中性站姿装配;下一阶段执行独立裁切、正式命名、枢轴与层级清单。
前左独立部件包 v1 结论:
- 两张源板已经按 8 邻域透明连通对象裁切为 43 件 PNG,每件四周保留 10 px 安全边距;核心板使用 `fl-core-cNN-*`,软性板使用 `fl-soft-cNN-*`,编号可以回溯到诊断图;
- `parts-manifest.json` 为每件记录源板、源裁切框、导出尺寸、父节点、建议层级、根枢轴及下一连接点;红色十字表示根枢轴,蓝色十字表示下一连接点;
- A/B 肢体按源板成组:A 为放松手链,B 为持扇/投掷手链;双腿沿用对应 A/B 组,具体画面侧在中性装配通过后冻结;
- 马尾根部与中段仍大于理想生产切片,当前只标记为可装配候选;中性装配必须检查接缝、旋转中心和对脸/躯干的穿插,未通过时再制作专用补件;
- 当前包状态为 `extracted-unvalidated`:透明裁切和元数据已完成,但层级、枢轴、九片衣摆取舍及中性轮廓仍需装配验证。
前左装配验证 v2 结论:
- 500 × 760 px 透明画布中使用 26 件部件重建中性站姿;可见 Alpha 范围为 362 × 679 px,四边保持透明,左右脚底基线差为 0 px;
- A 组冻结为画面左侧放松手链,B 组冻结为画面右侧持扇/投掷手链;羽扇在右、腰侧附件与长银饰在左的非对称关系与方向母版一致;
- 九片衣摆中采用 01~08 共八片,`coat-panel-alt-09` 保留为动作替换件;v2 加长衣摆并打开腿部站距后,轮廓不再像 v1 那样收成窄直筒;
- 袖臂源件已经包含可见肩甲与袖披,骨盆核心也已经包含中性腰前布、系绳和腰侧附件,因此独立肩甲、袖披及腰饰在当前装配中排除,避免重复叠画;
- 马尾根部单独使用可以形成稳定中性轮廓,但现有 `ponytail-middle` 与 `ponytail-tip` 仍是整块马尾候选,不是合格的连续链节;它们不进入当前基线,运动验证前需要专用三段补件;
- v2 状态为 `art-assembly-validated`,可作为前左静态美术基线;骨骼插值、待机呼吸和投掷动作尚未验证。
前左骨骼补件 v1 与装配 v4 结论:
- 首次补件源板虽然得到 5 个透明对象,但三件头发仍偏向完整马尾候选,根部还混入长银饰与头皮块,仅保留为失败对照;
- 第二版冻结为采用源板,包含去除银羽肩甲与外袖披的独立上臂 A/B,以及具有开放连接面的马尾根/中/尾,共 5 件;
- 5 件补件逐件保留 12 px 安全边距,均未触碰导出边缘;清单记录肩—肘和马尾根—中—尾连接点,状态为 `correction-parts-art-validated`;
- 装配 v4 使用 32 件部件:补件上臂替换复合上臂,独立肩甲固定回躯干,外袖披作为手臂附属层;马尾三段按根部 → 中段 → 末端连接并增加少量遮盖;
- v4 可见 Alpha 范围为 362 × 693 px,四边透明,左右脚底基线差为 0 px;肩甲权重、手腕连续性与马尾中性轮廓均通过美术检查;
- v4 取代 v2 成为当前前左静态基线;其上臂旋转、肩甲固定、袖披跟随和三段马尾滞后已在运行时 RIGHT 运动验证 v1 中通过美术侧检查。
运行时 RIGHT/旧前左运动验证 v1 结论:
- 已生成 `idle-inhale / idle-neutral / idle-exhale` 与 `throw-ready / throw-windup / throw-release / throw-recover` 共 7 个透明关键帧,动作节奏与运行时 LEFT 保持同一套 420/260/420 ms 呼吸节奏和 150/110/90/180 ms 投掷节奏;
- 所有帧统一使用 600 × 760 px 透明画布,在旧 500 px 装配画布左侧增加 50 px 安全区;7 帧四边透明,可见底边均为 y=745,基线差为 0 px;
- 持械侧使用肩—肘—腕连接点逐帧计算,蓄势时羽扇停在面部外侧而不遮挡眼睛,释放时手臂朝画面右侧展开;
- 释放帧隐藏中性持扇手,改用 `hand-throw-open-b` 与独立 `weapon-fan-open`,角色和脱手物均未触碰画布边缘;
- 马尾根/中/尾采用连续关节链,待机产生小幅呼吸滞后,蓄势、释放、回收产生方向明确的惯性摆动;当前幅度下没有明显断缝或穿过头面;
- 肩甲保持为躯干层,袖披随上臂以较小幅度转动;双腿、骨盆主根与脚底不参与动作,因此轮廓变化不会造成站立漂移;
- `motion-manifest.json` 记录 `runtimeDirection: right`、播放顺序、帧时长、完整部件变换、肩肘腕检查点和逐帧 Alpha 范围,可作为未来 Godot 动画导入或烘焙序列帧的直接输入。
运行时 RIGHT/旧前左循环播放验证 v1 结论:
- 待机循环为 `inhale 420 ms → neutral 260 ms → exhale 420 ms → neutral 260 ms`,总周期 1360 ms;投掷循环为 `ready 150 ms → windup 110 ms → release 90 ms → recover 180 ms → neutral 260 ms`,总周期 790 ms;
- 两张循环图同步展示 176/132/88 px 三档角色高度,分别搭配 128×64、96×48、64×32 菱形格;所有帧共用 x=85、y=42、479×712 px 的联合裁切框,不进行逐帧自动居中;
- 源帧可见底边的最小值和最大值均为 746,差值为 0 px;三档画面统一贴合诊断板 y=352 的脚底线,播放中没有上下跳动;
- 176 px 与 132 px 下高马尾、白色衣摆、朱砂系带、持扇手和朝右释放方向均清楚;88 px 下服装细节会合并,但马尾轮廓与投掷方向仍可读取;
- `build_xinyin_motion_playback.py` 已改为支持 `front-right` 与 `front-left` 参数,后续可用同一固定基线流程复查两个横向方向;诊断板背景只用于观看,原始运动 PNG 仍保持透明。
前右装配验证 v4 结论:
- 31 件部件参与中性站姿,其中 9 件来自骨骼补件包;其余原始切片继续作为动作替换件或未采用候选保留;
- C01 `hair-back-main` 实际包含两个被细发丝粘连的马尾方案,会在装配中形成悬空第二马尾,因此退出基线装配,改用 C03 与 C06 组合后发;
- C04 `hair-front` 已自带可见长流苏,C09 独立长发饰再次叠加会重复,因此基线装配不使用 C09;
- C15/C17 与 C18/C20 已退出基线装配,分别由独立上臂 A/B、前臂 A/B 和手型补件替换;C28/C29 重新作为躯干固定肩甲使用,不再随上臂旋转;
- 双腿、躯干、袖臂、八片衣摆、腰前垂布和腰包均可形成完整轮廓,透明件之间没有矩形裁切串片;
- A/B 肢体命名、肩—肘—腕连接和衣摆前后层级已通过待机呼吸与投掷动作验证,可作为前右方向当前基线;
- `assembly-layout-v4.json` 使用 500 × 760 px 美术画布,同时引用原始部件和骨骼补件两个清单,记录每件部件的目标枢轴、旋转、缩放与装配组;它是后续场景或动画工具的输入资料,不是 Godot 场景文件。
前右运动验证 v3 结论:
- 已生成 `idle_inhale / idle_neutral / idle_exhale` 与 `throw_ready / throw_windup / throw_release / throw_recover` 共 7 个透明关键帧;
- 呼吸只移动胸腔、头肩和软性部件 2~6 px,脚底与骨盆主根保持稳定,不会出现站立漂移;
- 蓄势帧把持械手收至面部外侧,避免武器遮挡眼睛;释放帧的独立上臂—前臂—手链条在大角度伸展下保持连续,没有透明断缝;
- 释放帧会隐藏持扇手、切换为投掷张手,并把展开羽扇作为独立脱手对象;肩甲继续固定在躯干,不再随上臂转动;
- 马尾根/中/尾分别产生滞后角度,当前幅度内接缝不明显、没有穿过头部或躯干;较大的马尾根部在实装比例下仍能接受,暂不重画;
- 所有运动帧统一使用 600 × 760 px 透明画布,并在装配原点左侧增加 50 px 安全区;7 帧均通过边缘透明检查,投掷释放帧不再被画布裁切;
- `motion-manifest.json` 保存帧时长、播放顺序、完整部件变换和肩肘手检查点,可直接作为未来动画系统的数据参考。
前右循环播放验证 v1 结论:
- 待机循环按 `inhale 420 ms → neutral 260 ms → exhale 420 ms → neutral 260 ms` 播放,总周期 1360 ms;作为战斗待机呼吸节奏合适;
- 投掷循环按 `ready 150 ms → windup 110 ms → release 90 ms → recover 180 ms → neutral 260 ms` 播放,总周期 790 ms;主要动作在 530 ms 内完成,释放点清楚;
- 两张循环图同时展示角色高度 176/132/88 px,对应 128×64、96×48、64×32 格子;三档均使用同一裁切范围和脚底基线,不做逐帧自动居中;
- 7 个源帧的可见底边完全一致,底边差值为 0 px,因此循环中的脚底没有上下跳动;
- 50% 下仍能通过左臂横向伸展识别投掷释放,但独立手型与羽刃细节不能作为唯一信息,正式效果仍应配合轨迹或闪光;
- GIF 背景、格子和红色脚底标记只用于诊断,透明运动源帧未被修改;播放报告记录固定裁切框、帧时长、循环顺序和校验结果。
前右骨骼补件 v1 结论:
- 现有运动验证确认 C15/C17 袖臂和 C18/C20 前臂属于复合切片,因此新增真正分开的上臂 A/B、前臂 A/B、放松手 A/B、持扇手、投掷张手,以及马尾根/中/尾,共 11 件;
- 首次生成的 `rig-corrections-v1` 中手臂和手型可用,但右侧仍是三个完整马尾候选,不能作为骨骼链,因此仅保留为失败对照;
- 第二版只修正右侧头发,透明检测恰好得到 11 个独立对象,所有部件之间无连接丝、无矩形串片;
- 每件补件保留 10 px 安全边距,清单记录源图裁切框、根枢轴与远端连接点:手臂为肩/肘或肘/腕,马尾为上一节/下一节;
- 马尾根部比理想生产切片大,但已经通过装配 v4 和运动 v3 的链条测试,在前右方向不再要求重画;
- 当前补件包状态为 `correction-parts-art-validated`,A/B 归属、根枢轴和远端连接点已通过美术侧验证;仍需未来引擎插值测试后才能成为最终运行时骨骼资产。
两张 P0 动作板的姿势顺序如下:
```text
板 1:idle_up, idle_down
move_contact_r, move_pass_r, move_contact_l, move_pass_l
attack_1_prepare, attack_1_release, attack_1_recover
attack_2_prepare, attack_2_release, attack_2_recover
板 2:burst_lock, burst_cross, burst_expand, burst_release
hit_recoil, hit_recover
defeat_stagger, defeat_kneel, defeat_fall, defeat_ground
```
动作可读性测试使用 128 × 64 px 基础格、176 px 基础角色高度,并同时检查 100%、75% 和 50% 三档缩放。v1 结论:
- 100% 与 75% 下,待机、移动、普攻、爆发、受击和倒下均能区分;
- 50% 下仍能判断动作大类,但 `attack_1` 与 `attack_2` 的羽刃数量和出手手型已经无法可靠辨认,正式动画需靠出手侧、轨迹颜色或音效强化差异;
- `burst` 的环形轮廓在三档缩放下都很醒目,但 VFX 不能计入角色碰撞或格子占用;
- `hit` 在 50% 下容易与攻击动作混淆,后续应加大上身后仰并收起主动投掷手;
- `defeat_ground` 的横向视觉范围超过单格,后续分解动画应把马尾和外裙进一步收拢。
v2 针对以上问题做了定向修正,并保留 v1 作为对照:
- `attack_1` 改为高位单臂直投,`attack_2` 改为低位横向双刃;50% 下已能依靠手臂高度和站姿宽度区分,羽刃数量只作为辅助信息;
- `hit` 增大后仰角度、收回双手并取消投掷表现,三档缩放下均不会再与主动攻击混淆;
- `defeat_ground` 收拢膝、裙片和马尾,视觉范围显著缩小;允许软性部件略超出格子,但逻辑占格仍固定为一格;
- v2 可作为后续分解和动画设计的当前基线,v1 不再用于新方向的动作扩展。
P1 v1 的姿势顺序与使用边界:
```text
板 1:ready_observe, ready_low
dodge_compress, dodge_dash, dodge_land
weakpoint_analyze, weakpoint_lock
板 2:cover_enter, cover_tuck, cover_peek
cover_attack_prepare, cover_attack_release, cover_attack_withdraw
```
- `dodge_dash` 的淡蓝残影属于独立 VFX,不计入身体切片;
- `weakpoint_lock` 的菱形/月牙准星属于目标提示层,不跟随角色骨骼;
- 当前掩体板只表达“威胁位于右上、角色在掩体后侧”的关系;正式制作时至少还需一套反向探身动作,不能通过简单水平镜像解决心音的发饰、腰包和投掷手方向;
- 掩体块仅为动作空间参考,不是正式地图素材,也不进入角色导出包。
P1 v1 可读性测试沿用 128 × 64 px 基础格、176 px 基础角色高度和 100%/75%/50% 三档缩放。结论:
- `ready_low` 在 50% 下仍能与待机和攻击区分,主要依靠低重心和未伸出的手臂;
- `dodge_dash` 的本体轮廓清楚,但淡蓝残影在 50% 下权重过高,正式 VFX 应降低不透明度、缩短拖尾并在动作结束前快速消失;
- `weakpoint_lock` 的手势在 50% 下只保留方向信息,准星仍可见;正式 UI 应给准星设置屏幕空间最小尺寸,不能完全随镜头等比缩小;
- `cover_idle` 与 `cover_attack` 在三档缩放下均能通过头肩暴露量和投掷手区分;
- 测试中的掩体块大于单格视觉宽度,仅用于验证遮挡关系,不作为正式掩体尺寸结论。
P1 v2 修正与补充:
- `dodge_dash` 残影缩短约 40%,降低为约 20%~25% 不透明度的单层拖尾;50% 下本体重新成为唯一主轮廓;
- 新增前左斜向的 `cover_enter_left / cover_tuck_left / cover_peek_left / cover_attack_prepare_left / cover_attack_release_left / cover_attack_withdraw_left`;
- 左右探身动作均为独立绘制,保留发饰、腰包与投掷手的非对称结构;
- P1 v2 并列测试显示两侧探身在 50% 下仍能依靠头肩暴露方向和投掷轨迹区分,可作为当前 P1 基线。
## 6. 导出与命名建议
```text
assets/images/2d-game-characters/
└─ 02-xinyin/
├─ source/ # PSD/KRA 等分层源文件
├─ parts/ # 各方向透明 PNG 分解件
│ ├─ front-right/v1/ # 历史目录;运行时映射为 LEFT
│ ├─ front-left/v1/ # 历史目录;运行时映射为 RIGHT
│ ├─ up/ # 背面方向
│ └─ down/ # 后续正面方向
├─ replacements/ # 表情、手型、裙摆、马尾替换件
├─ vfx/ # 千羽、月轮、轨迹、残影、命中特效
├─ previews/ # 比例和游戏内预览
└─ xinyin-rig.tscn # 后续 Godot Skeleton2D 场景
```
最终文件名采用 `02-xinyin_<direction>_<part>[_variant].png`,其中 `<direction>` 只允许 `up / down / left / right`。当前拆分为了保留与透明对象诊断图及脚本的映射,旧前右暂用 `fr-cNN-<part>.png`,旧前左暂用 `fl-core-cNN-<part>.png` 与 `fl-soft-cNN-<part>.png`;运行时通过方向映射清单读取,不直接批量改名。例如:
```text
02-xinyin_left_forearm-r.png
02-xinyin_right_hand-r-throw.png
02-xinyin_up_ponytail-02.png
02-xinyin_vfx_feather-single.png
```
透明 PNG 使用预乘边缘检查,分解件四周保留安全 padding。源文件以 2 倍于游戏显示尺寸制作;若默认显示高度为 176 px,工作高度建议约 352 px,并保留更高分辨率的角色设计母版。
## 7. 验收标准
- 角色缩放到约 176 px 高时,仍能一眼识别高马尾、银羽、白/靛轮廓和朱砂点色。
- 四方向的脚底原点一致,切换方向时人物不跳位。
- 待机、移动、首击、追击和爆发只看黑色剪影也能区分。
- 普攻首击与被动追击在 0.5 秒内仍有不同手型和重心变化。
- 任何关节旋转都不露透明缝,裙片、披风与马尾不穿过身体主轮廓。
- 倒地姿势不长期占用相邻格的主要视觉区域。
- 左上主光、右下投影与地图素材一致。
- 角色身体、脚底阴影、选中环、状态特效和技能 VFX 能独立开关。
+219
View File
@@ -0,0 +1,219 @@
# FunGame 代码调研
> 调研日期:2026-09-18
> 范围:`FunGame.Core`、`FunGame.Testing-v3/OshimaGameModules`、`FunGame.Testing-v3/WebAPI`,并参考 `FunGame.Server-v3`、`FunGame.Godot` 与 `webui-solo`。
> 本文记录当前代码事实与接入判断,不把尚未实现的联机能力描述为已完成。
## 1. 结论摘要
现有代码已经具备制作 Godot 竖切版本所需的三个主要部分:
1. **规则层**:`FunGame.Core` 提供完整的回合、行动队列、决策点、技能、效果、伤害、地图和回合记录能力。
2. **内容层**:`OshimaGameModules` 已把《筽祀牻》的 18 名角色、专属技能、通用技能、效果、物品和职业体系实现为可执行 C# 模块。
3. **服务器原型层**:`WebAPI` 的 `/ws/solo` 已把同步的回合制核心包装成服务器权威会话,支持状态快照、客户端决策、暂停、断线重连和 AI 接管。
因此,Godot 第一阶段不需要重写战斗规则。较稳妥的方案是:**Godot 只负责显示状态和提交玩家意图,战斗结果统一由权威主机计算**。
```text
OshimaGameModules(角色、技能、物品)
↓
FunGame.Core(回合规则与状态)
↓
WebAPI / 未来的 Server-v3(权威会话与协议)
↓
Godot C#(画面、输入、动画、声音)
```
## 2. FunGame.Core
路径:`C:\milimoe\FunGame.Core`
### 2.1 工程与职责
- 当前工程目标框架为 `net10.0`,包版本为 `3.0.0-dev`。
- 核心库本身不依赖第三方 NuGet 包。
- 许可证为 LGPL-3.0-or-later;发行游戏时需要保留许可证与署名,并单独评估修改核心库和静态/动态分发的合规方式。
- 核心入口是 `IGamingQueue` / `GamingQueue`,其职责不只是“队列”,还包括回合推进、行动解析、伤害与治疗、死亡、移动、目标选择、AI 控制和效果派发。
### 2.2 已有能力
- 行动顺序、硬直时间与时间流逝。
- 决策点(DP)、行动次数和行动类型配额。
- 普通攻击、技能、物品、移动、放弃行动与继续行动。
- 伤害、治疗、暴击、闪避、免疫、效果附加与驱散。
- 单位死亡、打断、召唤/衍生单位和淘汰队列。
- 混战队列 `MixGamingQueue` 与团队队列 `TeamGamingQueue`。
- `ActionRecord`、`RoundRecord`、统计数据和角色状态检查点。
- `IRoundRecordSink` 可将行动、回合、统计、角色、队伍和队列数据输出到外部存储或远程服务。
- `JsonService` 已包含角色、技能、效果、物品、行动记录、回合记录和快照等转换器。
### 2.3 对客户端最重要的事件
`GamingQueue` 暴露了约 29 类战斗事件,覆盖:
- 回合开始/结束、队列更新、行动完成、决策完成;
- 选择行动、技能、物品、目标、格子和询问选项;
- 攻击、施法、使用物品、移动、伤害、治疗、免疫、死亡和游戏结束。
这些事件适合由“会话适配层”转换成网络消息,不应让 Godot UI 直接订阅核心对象。
### 2.4 线程与调用约束
核心事件及其询问流程是同步的。服务器需要在游戏线程里等待玩家决策,而 Godot 的节点和界面只能在主线程安全更新。因此:
- 核心回合循环不能在 Godot 主线程运行;
- 网络消息先进入客户端状态仓库,再由 Godot 主线程更新节点;
- 即使将来提供离线内嵌模式,也要保留游戏线程与显示线程之间的消息边界。
## 3. OshimaGameModules
路径:`C:\milimoe\FunGame.Testing-v3\OshimaGameModules`
### 3.1 内容规模
- 18 名可玩角色,稳定 ID 为 1–18。
- 每名角色有 1 个专属被动和 1 个专属爆发技,共 36 个专属技能文件。
- 通用内容目前包含约 53 个魔法、59 个战技、30 个通用被动和 16 个通用爆发技。
- 效果模块包含开放效果、被动效果和技能效果;另有物品、单位与 JSON 配置。
- 世界职业体系已有 3 个基础职业、每个职业 2 个进阶分支,共 6 个成长方向。
### 3.2 角色 ID 对照
| ID | 角色类 |
|---:|---|
| 1 | OshimaShiya |
| 2 | XinYin |
| 3 | Yang |
| 4 | NanGanYu |
| 5 | NiuNan |
| 6 | DokyoMayor |
| 7 | MagicalGirl |
| 8 | QingXiang |
| 9 | QWQAQW |
| 10 | ColdBlue |
| 11 | Dddovo |
| 12 | Quduoduo |
| 13 | ShiYu |
| 14 | XReouni |
| 15 | Neptune |
| 16 | CHAOS |
| 17 | Ryuko |
| 18 | TheGodK |
角色并非只有静态数值。专属被动通过效果钩子响应回合开始、获得效果、受伤等事件,主动技能也会执行持续时间、属性变化、自伤、额外攻击等逻辑。这意味着内容层已经可以直接作为服务器规则模块使用。
### 3.3 素材映射建议
Godot 不应以中文名或类名模糊查找素材,应使用稳定数值 ID 建立清单:
- 角色头像:角色 ID `1..18` → `assets/images/2d-game-icons/characters`。
- 技能图标:技能数值 ID → 有边框版或 `skills/borderless` 无边框版。
- “不可主动使用”建议由 UI 灰度、遮罩和状态标识表达;无边框图可作为该视觉状态的底图,但不要把规则状态编码进文件名判断。
后续宜新增单一的图标清单文件,由程序和美术共同维护,避免重命名素材后代码失效。
## 4. WebAPI 单人战斗原型
路径:`C:\milimoe\FunGame.Testing-v3\WebAPI`
### 4.1 已实现接口
- WebSocket:`/ws/solo`
- REST:`/api/solo/state`、`/api/solo/stop`、`/api/solo/pause`、`/api/solo/ranking`
- 回放/归档:游戏数据、元数据、回合摘要、指定回合、统计、模拟和重载等接口。
- 职业方案:定义、选择、升级、学习、分配、应用和保存等接口。
### 4.2 消息信封
协议使用统一信封:
| 字段 | 含义 |
|---|---|
| `t` | 消息类型 |
| `i` | 请求/消息 ID |
| `ok` | 是否成功 |
| `d` | 业务数据 |
| `ts` | 时间戳 |
| `error` | 错误信息 |
主要消息包含 `gaming.start`、`gaming.action`、`gaming.state`、`gaming.request`、`gaming.resolved`、`gaming.pause`、`gaming.resume`、`gaming.round`、`gaming.queue` 和 `gaming.over`。
玩家决策类型覆盖:选择角色、行动类型、技能、物品、目标、单个格子、多个格子、询问与继续。
### 4.3 会话运行方式
`SoloGameSession` 采用服务器权威模式:
1. 服务器创建角色、队伍、地图、物品与行动队列。
2. 回合核心在后台线程运行。
3. 需要玩家输入时发送 `gaming.request`,游戏线程等待客户端的 `gaming.action`。
4. 服务器校验选择,解析行动后推送新的权威状态。
5. 客户端断线时可以重连并收到完整快照和仍待处理的决策。
6. 决策超时或异常重复时,服务器把玩家暂时交给 AI,避免整局永久阻塞。
当前快照已经包含地图、格子、全部角色、队列、玩家决策点、当前行动者、队伍、奖励、暂停和 AI 接管状态。角色 DTO 还包含 HP/MP/EP、移动力、属性、状态、格子、技能、物品、效果和装备等 UI 所需信息。
### 4.4 当前限制
- `SoloGameHost` 目前按单个单人会话设计,不是多人房间管理器。
- 服务器目前以完整快照为主,联机规模扩大后宜加入状态版本号、增量更新和带宽观测。
- WebSocket 接收处当前使用单次固定缓冲读取;正式版需要正确拼接分片消息,并为大快照设置尺寸上限、压缩或拆包策略。
- 决策请求需要进一步加入明确的截止时间、状态版本、幂等处理和拒绝原因,才能可靠应对高延迟和重复包。
- REST 快照与游戏线程并发读取已有防护思路,但正式多人版仍应统一状态复制策略。
## 5. 可参考的现有项目
### 5.1 webui-solo
路径:`C:\milimoe\FunGame.Testing-v3\webui-solo`
这是目前最接近“已验证交互原型”的客户端。它已经实现:
- 顶部回合/时间/比分与暂停区;
- 左侧行动队列和决策点;
- 中央地图、范围高亮与目标确认;
- 右侧操作、日志和队伍面板;
- 角色详情、不可用技能原因和决策确认;
- WebSocket 心跳与协议类型定义。
其 `soloClient` 已体现“传输层可替换”的思路。Godot 版可以继承其信息架构,但应重新制作适合桌面、手柄和安全区的 Godot UI。
### 5.2 FunGame.Godot
路径:`C:\milimoe\FunGame.Godot`
旧原型包含行动栏、行动面板、状态、Buff、回合队列和目标选择等场景,也有两个值得复用的思想:
- 用 `TaskCompletionSource` 把 UI 选择转换成异步请求结果;
- 用主线程调度器把后台逻辑更新安全地切回 Godot 主线程。
但该项目直接把 `Character`、`Skill`、`Item` 等核心对象绑定到 UI,引用的是 FunGame.Core 2.0.0,并大量使用固定像素位置。新的可联机客户端不应沿用这种强耦合方式。
### 5.3 FunGame.Server-v3
路径:`C:\milimoe\FunGame.Server-v3`
Server-v3 已具备 JWT、房间、匹配、WebSocket、插件、回合记录和 OSM 模块加载等专用服务器基础设施,也沿用了相同的消息信封。
不过,当前通用托管游戏仍主要让角色由 AI 执行;多名真人玩家与核心同步决策的完整桥接尚未完成。因此它适合作为专用服务器目标架构,不能直接视为“多人战斗已经完成”。下一步应把 `SoloGameSession` 已验证的决策桥接抽象成可绑定多个用户、角色和连接的通用会话组件。
## 6. 版本与工具链
- 三个主调研工程均以 `net10.0` 为当前代码基线。
- 本机已安装 .NET 7、8、10 SDK,但命令行暂未发现 Godot 可执行文件。
- 现有 `FunGame.Godot` 工程声明 `Godot.NET.Sdk/4.7.0` 与 `net10.0`,说明项目正在尝试较新的 Godot/.NET 组合。
- Godot 官方稳定文档当前仍以 .NET 8 为 C# 基线,并说明 C# 项目不能导出到 Web。正式创建工程前,应以实际安装的 Godot 编辑器、对应 .NET SDK 和目标平台导出模板做一次最小构建验证:[Godot C# 基础文档](https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/c_sharp_basics.html)。
桌面端优先可以规避 Web 导出限制;若以后要做浏览器版,应将其视为单独技术路线,而不是默认继承桌面 C# 客户端。
## 7. 推荐的近期工作边界
第一阶段只做一条端到端竖切链路:
1. Godot 连接现有 `/ws/solo`。
2. 完成角色选择并显示首个权威快照。
3. 实现行动、技能、目标/格子和询问这几类决策。
4. 显示回合队列、角色状态、决策点和结果。
5. 验证断线重连、AI 接管和恢复。
竖切通过后,再把单人会话抽象到房主模式和 Server-v3。这样可以让三种部署方式复用同一套 Godot UI、协议对象和状态更新流程。
+202
View File
@@ -0,0 +1,202 @@
# Godot 地图与素材制作建议
> 日期:2026-09-18
> 状态:首个战斗地图的制作基线
> 目标:斜俯视、半隐藏战棋格、纯 2D 人物,并让地图美术与服务器规则长期可维护。
## 1. 推荐结论
第一版采用 **全 2D 二等角地图**,继续使用熟悉的 TileMap 工作流,不引入 3D 地形。
但不要使用“一个 TileMap 包办整张地图”的结构。推荐组合是:
```text
多个 TileMapLayer 地面、道路、墙体、重复装饰
独立 Sprite2D/场景 大型物件、动画物件、可破坏物件、前景遮挡
独立规则格数据 通行、掩体、高度、出生点、任务点
运行时 GridOverlay2D 移动、攻击、技能范围和目标预览
```
Godot 4 的 `TileMap` 节点已经弃用,新工程应使用多个单层的 `TileMapLayer`。官方也建议按需要拆分多个图层,以便组织背景、前景和重叠图块:[TileMapLayer 文档](https://docs.godotengine.org/en/4.6/classes/class_tilemaplayer.html)、[使用 TileMap](https://docs.godotengine.org/en/4.4/tutorials/2d/using_tilemaps.html)。
这个方案的优点:
- 你可以继续在编辑器里“画地图”,学习成本最低。
- 逻辑格天然对应 FunGame 的格子坐标。
- 地面、掩体和装饰能大量复用,地图素材成本可控。
- 人物和高墙可以通过 Y 排序、前景淡化营造纵深。
- 将来若改用 3D 地形,服务器地图规则和 HUD 不需要重做。
主要限制:相机方向基本固定,不能像真正 3D 那样自由旋转;所有素材必须统一透视、比例和光源。对本项目而言,这是可以接受且有利于控制美术风格的约束。
## 2. 首张地图的建议规格
先制作一个小型灰盒竖切,不要一开始就做完整地区地图:
| 项目 | 建议值 |
|---|---|
| 逻辑尺寸 | 16 × 12 格起步,可扩展到约 24 × 18 格 |
| 投影 | 二等角/菱形斜投影 |
| 游戏内单格包围框 | 128 × 64 px 起步 |
| 美术源文件 | 256 × 128 px/格制作,再按测试结果导出 |
| 基准分辨率 | 1920 × 1080 |
| 相机 | 固定方向,可平移和有限缩放,不旋转 |
| 高度 | 第一版只有地面层;墙和掩体制造视觉高度 |
| 光源 | 全套素材统一为左上方主光,阴影投向右下 |
`128 × 64` 不是永久硬编码。先用色块和临时人物测试:常用缩放下,屏幕应能看见约 10–14 格宽,同时人物不能小到看不清动作。确定后再批量制作正式素材。
不建议第一版加入真正的多层高低差。高度会同时影响移动、射程、视线、遮挡和服务器规则,应该在基础战斗竖切稳定后单独设计。
## 3. TileMapLayer 分层
建议每张地图至少包含以下节点:
```text
MapRoot (Node2D)
├─ GroundBase TileMapLayer:基础地面
├─ GroundTransition TileMapLayer:道路、泥地、水迹、边缘过渡
├─ GroundDecal TileMapLayer:裂纹、污渍、标线、小碎屑
├─ LowStructure TileMapLayer:矮墙、沙袋、低掩体
├─ TallStructure TileMapLayer:墙体、门框、不可穿越结构
├─ Props Node2D:箱子、车辆、机械、可交互物
├─ Units Node2D:角色与召唤物,启用 Y 排序
├─ Foreground Node2D:会遮挡人物的屋顶、树冠、前景墙
└─ GridOverlay2D Node2D:运行时范围显示,不进入地形图集
```
图层职责必须单一。不要把地面、墙、阴影和前景全部烘焙到同一块图片,否则无法正确排序和淡化遮挡物。
### 哪些内容适合 TileMapLayer
- 大面积重复的地面、道路与边缘。
- 规则稳定的墙段、墙角、矮掩体。
- 可以用同一格尺寸切分的装饰。
- 常用的多格组合,例如路口、小型掩体阵地。
### 哪些内容适合独立场景
- 车辆、大型机器、雕像等跨多格物件。
- 有动画、粒子、音效或交互的物件。
- 可破坏物件和会改变状态的门。
- 需要单独淡化的前景或屋顶。
Godot 支持把场景作为 TileSet 的“场景图块”放置,但官方提醒它们会为每个格子实例化场景,开销高于图集。因此只对确实需要行为的少量对象使用,普通静态图块仍用 atlas:[TileSet 使用文档](https://docs.godotengine.org/en/4.6/tutorials/2d/using_tilesets.html)。
## 4. 地图规则不能只存在于图片里
联网模式下,服务器必须知道地图规则。Godot 中看起来像墙的图片,不应自动等同于服务器里的“不可通行”。
每张地图需要一份可序列化的 `MapDefinition`,至少包含:
- 地图 ID、版本和逻辑宽高;
- 每格是否存在、是否可通行、移动消耗;
- 是否阻挡视线;
- 北/东/南/西四边的掩体等级;
- 出生点、队伍区域、掉落点和任务区域;
- 预留的高度等级;
- 美术场景或地图资源的引用 ID。
编辑器里可以放一个只在制作阶段可见的 `RuleGrid`:使用不同的逻辑图块绘制不可通行、半掩体、全掩体、出生点等,再导出成服务器与 Godot 共用的数据。正式运行时隐藏该图层。
TileSet 的自定义数据适合描述“这种图块通常是什么”,例如材质、默认移动消耗或是否可破坏。官方支持为图块配置自定义数据、碰撞、导航和遮挡层:[TileSet 与自定义数据](https://docs.godotengine.org/en/4.6/tutorials/2d/using_tilesets.html#assigning-custom-metadata-to-the-tileset-s-tiles)。但是掩体方向、任务区域等“某个放置位置独有”的规则,仍应进入地图实例数据,不能只写在共享图块定义里。
战棋寻路最终应以服务器逻辑格为准。Godot 的导航多边形可服务于动画或编辑辅助,但不能替代 FunGame 的权威移动范围计算。
## 5. 地图素材拆分规范
### 5.1 地面图块
每种基础地面至少准备:
- 1 个标准中心块;
- 3–5 个轻微变化块,避免重复纹理过于明显;
- 与其他地形连接的边、内角和外角;
- 少量裂纹、污渍、车辙和标线作为独立 decal;
- 道路直线、转角、丁字口和十字口。
Godot 的 Terrain 系统可以根据相邻图块自动选择边角,是 Godot 3 自动图块的后续方案。正式制作前先用两种简单地形验证 terrain peering 配置,再决定是否为所有地形绘制完整过渡集。[官方 TileSet Terrain 说明](https://docs.godotengine.org/en/4.6/tutorials/2d/using_tilesets.html#creating-terrain-sets-autotiling)
### 5.2 掩体和墙体
每套建筑主题至少准备:
- 横向/纵向墙段及端头;
- 内角、外角、丁字与十字连接;
- 半掩体和全掩体的明显视觉差异;
- 门、破损墙和缺口;
- 独立前景切片,用于角色被遮挡时淡化;
- 脚底接触阴影或单独阴影层。
掩体美术必须对齐格子边缘,而不是随意放在格子中央。规则数据记录“哪条边提供掩体”,显示层再把盾牌提示放到对应边。
### 5.3 大型道具
大型物件需要随文件附带:
- 占用格范围;
- 脚底/排序锚点;
- 是否可穿越、是否阻挡视线;
- 需要淡化的前景轮廓;
- 若可破坏,正常与破坏后的两套状态;
- 可选的交互点和效果挂点。
大型物件不要强行切成许多互不关联的小图块。优先做成独立场景,在编辑器中吸附到逻辑格。
## 6. 图像文件规则
- 透明素材使用 PNG;大块不透明背景可在确认画质后评估无损 WebP。
- 同一个图集的格子尺寸、透视和光源必须一致。
- 地面不绘制永久战棋线;半隐藏网格由运行时统一绘制。
- 前景遮挡与地面分文件,避免淡化墙体时连地面一起消失。
- 人物、道具和墙体以脚底中心或明确的底边锚点对齐格子。
- 图集边缘保留纹理扩展/透明 padding,Godot 导入时启用 texture padding,减少缩放时的图块渗色。
- 源文件保留分层版本,导出文件不得覆盖源文件。
建议目录:
```text
assets/images/2d-game-maps/
├─ shared/
│ ├─ grid/
│ ├─ decals/
│ └─ shadows/
├─ dokyo_industrial/
│ ├─ tiles/
│ ├─ walls/
│ ├─ props/
│ ├─ foreground/
│ └─ source/
└─ prototypes/
```
当前 `assets/images/2d-game-maps` 目录为空,适合直接按这套结构建立,不需要迁移旧地图素材。
## 7. 推荐制作顺序
1. **灰盒**:用 128 × 64 的纯色菱形、简单墙块和角色剪影制作 16 × 12 测试图。
2. **规则验证**:接通格子拾取、移动范围、目标范围、掩体方向和服务器地图 DTO。
3. **遮挡验证**:加入一面高墙和一个大型前景物,验证 Y 排序与自动淡化。
4. **第一个美术包**:只制作一种地面、一条道路、一套墙、两种掩体和 5–8 个道具。
5. **地图拼装**:制作一个能完成整局战斗的竖切地图。
6. **扩充变化**:确认比例与镜头后,再制作地形过渡、破损版本和地区专属装饰。
第一批不要追求“素材很多”。能用少量模块拼出一个规则清晰、遮挡正确、角色比例舒服的战场,价值高于先画几十种没有统一规格的地砖。
## 8. 暂不建议采用的方案
- **直接上 3D 地形**:会同时增加建模、材质、灯光、Sprite3D 朝向与 2D/3D 遮挡问题,当前收益不足。
- **整张地图一幅大图**:画面容易统一,但难以复用、换地形、做遮挡和维护规则格。
- **所有物件都做场景图块**:编辑方便但实例与维护开销过高。
- **把规则写死在 TileSet 图块上**:服务器无法可靠表达位置特有的掩体、出生点和任务状态。
- **一开始支持镜头旋转**:纯 2D 素材需要为每个方向制作额外版本,成本会成倍增加。
## 9. 首个原型的验收标准
- 能在编辑器中像普通 TileMap 一样快速绘制地面和墙。
- 鼠标、触屏或手柄均能准确选中逻辑格。
- 网格在观察时隐藏,在操作时只显示相关区域。
- 人物能从墙后经过,前后关系和淡化正确。
- 规则数据与图片分离,服务器能独立判断通行、距离和掩体。
- 更换整套地面图集不会改变战斗规则。
- 同一套素材能拼出至少两张明显不同的小地图。
+305
View File
@@ -0,0 +1,305 @@
# Godot 战斗竖切实施计划
> 日期:2026-09-19
> 状态:实施中
> 前置文档:[《Godot 联机接入与 UI 草案》](./Godot联机接入与UI草案.md)、[《Godot 地图与素材制作建议》](./Godot地图与素材制作建议.md)
## 1. 目的
本阶段的目标是把已经完成的 Godot 联网脚手架推进为第一条可实际游玩的战斗竖切:玩家能够连接现有 Solo WebAPI、开始对局、选择角色、在二等角战场中看到全部单位,并通过点击单位或逻辑格完成移动与普通攻击。
本阶段不重写 FunGame.Core 规则,也不重构 Server-v3。Godot 继续只负责显示权威状态和提交玩家意图,行动是否合法及其结果均由服务器决定。
## 2. 当前基线
Godot 客户端当前已具备:
- Godot 4.7 .NET / C# 工程与 `src/` 目录结构;
- `GameSession`、`BattleStore`、`AssetCatalog`、`UiRouter` 和 `GameSettings` 五个 Autoload;
- WebSocket 与 Mock 传输层;
- 默认连接地址 `ws://localhost:11030/ws/solo`;
- `system.ping` / `system.pong` 心跳;
- `gaming.start`、`gaming.state`、`gaming.request`、`gaming.action` 等真实协议消息;
- 角色选择、基础行动、技能、物品、目标和逻辑格决策的初步控件;
- 2D 二等角投影、灰盒地图、范围网格、相机和贴边 HUD;
- 自动连接、开局、选人和接收首个权威快照的冒烟测试。
当前端到端验证结果:
```text
SOLO_SMOKE_OK game=<gameId> round=0 characters=2 units=2
SOLO_VERTICAL_OK game=<gameId> moves=1 attackTargetSubmitted=true rejectionRecovered=true units=2
```
### 执行进度
- [x] 阶段 A:`UnitView`、按 GUID 实例协调、格子定位、阵营/行动者/HP/淘汰/AI 托管显示;
- [x] 阶段 B 基础:合法格集合高亮、单位直接点击选择目标、提交前确认;
- [x] 阶段 B 完整:移动与普攻的真实端到端竖切回归、服务器拒绝后的决策恢复;
- [ ] 阶段 C:完整决策类型与行动配额;
- [ ] 阶段 D:断线恢复;
- [ ] 阶段 E:动画、日志、结算与输入完善。
阶段 A 已通过真实 Solo WebAPI 冒烟测试:权威快照含 2 名角色时,`UnitsLayer` 生成且仅生成 2 个 `UnitView`。
阶段 B 已通过真实 Solo WebAPI 竖切测试:客户端可通过合法格完成移动、通过点击单位提交普通攻击;提交期间会锁定重复输入,取消会发送协议取消意图,非法格被服务器拒绝后可以恢复并继续选择。
现有 WebAPI 的 SoloMap 为 `12 × 12`,而美术竖切建议值为 `16 × 12`。客户端不得写死地图尺寸,必须以服务器 `MapDto.length` 与 `MapDto.width` 为准动态构建显示层。
## 3. 竖切完成后的玩家流程
```text
启动 WebAPI
↓
Godot 连接 /ws/solo
↓
开始新局并选择角色
↓
收到完整权威快照
↓
生成地图与全部单位
↓
收到 ActionType 决策
├─ 移动 → 显示合法格 → 选择 → 确认
└─ 普攻 → 显示合法目标 → 选择 → 确认
↓
等待服务器计算
↓
根据新快照更新位置、HP、队列和决策点
```
客户端不得在提交后自行移动角色或预扣 HP。提交期间只显示选择结果与“等待服务器”状态;收到新快照后才更新权威画面。
## 4. 分层职责
```text
BattleScreen / UnitView / GridOverlay2D
↓ 显示 ViewModel、提交 Intent
BattleStore
↓ 解析快照、保存待处理决策
GameSession
↓ 信封、心跳、连接与重连
WebSocketTransport
↓
WebAPI /ws/solo(权威计算)
```
### GameSession
- 维护 WebSocket 生命周期和连接状态;
- 为发出消息生成递增序号;
- 定时发送心跳;
- 将后台接收的数据排队后交回 Godot 主线程;
- 后续负责重连退避和 `gaming.resume`。
### BattleStore
- 解析 Solo 协议信封;
- 保存最近一次完整权威快照;
- 保存唯一待处理的 `gaming.request`;
- 丢弃不属于当前 `gameId` 的旧局消息;
- 向场景发出快照、决策和错误信号;
- 不保存服务器规则对象,不计算伤害或合法范围。
### BattleScreen
- 将快照映射到地图、单位和 HUD;
- 根据决策种类切换输入状态;
- 把鼠标、触屏或手柄输入统一转换为决策负载;
- 提交后锁定相关输入,等待服务器返回。
## 5. 权威数据到场景的映射
| 服务器字段 | Godot 消费位置 | 用途 |
|---|---|---|
| `state.gameId` | `BattleStore` | 防止不同对局消息串线 |
| `state.map.grids` | 地图显示与 `GridOverlay2D` | 格子 ID、坐标及角色占位 |
| `state.characters[].guid` | `UnitsLayer` | `UnitView` 的稳定实例键 |
| `state.characters[].gridId` | `UnitView` | 查找逻辑坐标并计算屏幕位置 |
| `state.characters[].hp/mp/ep` | `UnitView` 与角色 HUD | 权威资源显示 |
| `state.currentActorGuid` | `UnitView`、队列 | 当前行动者高亮 |
| `state.queue` | `TopTurnQueue` | 行动顺序显示 |
| `state.playerDP` | 行动坞、角色 HUD | 决策点和行动配额 |
| `request.kind` | 输入状态机 | 决定当前允许的交互方式 |
| `request.payload.gridIds` | `GridOverlay2D` | 只显示和接受合法格子 |
| `request.payload.targets` | `UnitView` | 只允许选择合法单位 |
服务器目前没有正式的 `stateRevision` 字段。第一阶段按 WebSocket 顺序处理完整快照;正式重连和增量同步前,应在协议中补充单调递增的状态版本。
## 6. 场景新增与调整
### 6.1 UnitView
新增可复用单位场景:
```text
UnitView (Node2D)
├─ Shadow (Sprite2D / Polygon2D)
├─ SelectionRing (Node2D)
├─ Body (AnimatedSprite2D,第一版可用临时剪影)
├─ HitArea (Area2D)
│ └─ CollisionShape2D
├─ HpBar (Control)
├─ StatusIcons (HBoxContainer)
└─ NameLabel (Label)
```
职责:
- 以角色 GUID 绑定一个角色快照;
- 脚底中心与逻辑格中心对齐;
- 显示己方、敌方、当前行动者、可选目标、死亡和 AI 托管状态;
- 只发出“被点击”信号,不直接提交网络消息;
- 正式角色动画未完成前使用统一临时剪影,不以头像代替战场人物。
### 6.2 UnitsLayer
`BattleScreen` 保存 `Dictionary<string, UnitView>`:
1. 快照中出现新 GUID 时实例化;
2. 已存在 GUID 时更新位置与状态;
3. GUID 从快照消失时移除;
4. `isEliminated` 为真时播放或显示失败状态;
5. 更新完成后根据脚底 `screenY` 进行 Y 排序。
### 6.3 GridOverlay2D
从“整张地图统一着色”改为接受明确集合:
- `SetReachableCells(IEnumerable<long>)`;
- `SetAttackCells(IEnumerable<long>)`;
- `SetAffectedCells(IEnumerable<long>)`;
- `SetSelectedCell(long?)`;
- `ClearInteraction()`。
格子 ID 与坐标的转换由当前地图快照提供,不假设 ID 等于数组索引。
## 7. 实施阶段
### 阶段 A:快照生成战场单位
任务:
- 建立 `UnitView.tscn` 与 C# 控制脚本;
- 从 `map.grids[].characters` 或角色 `gridId` 建立占位关系;
- 在 `UnitsLayer` 中按 GUID 对单位实例进行增删改;
- 将当前行动者、己方和敌方用不同轮廓表示;
- HUD 和单位头顶血条同步显示服务器 HP。
验收:
- 首个快照到达后,所有角色都出现在正确格子;
- 连续接收快照不会重复创建单位;
- 角色位置、HP 或淘汰状态变化后画面正确更新;
- 地图尺寸变化时不需要修改场景代码。
### 阶段 B:地图与单位直接交互
任务:
- `TargetGrid` 仅高亮 `payload.gridIds`;
- 点击非法格不产生可提交选择;
- `Targets` 仅让 `payload.targets` 中的 `UnitView` 可选;
- 选择后显示预览,必须再次确认才发送;
- `WaitingServer` 期间锁定重复点击。
验收:
- 移动决策可以通过地图完成;
- 普通攻击可以通过点击单位完成;
- 重复点击确认不会重复执行行动;
- 服务器拒绝时能够恢复当前决策或显示错误。
### 阶段 C:补齐决策类型
任务:
- 根据 `playerDP.quotas` 控制行动按钮;
- 区分 `CastSkill`、`PreCastSkill` 和 `CastSuperSkill`;
- 实现技能与物品详情、冷却、消耗和不可用原因;
- 支持 `TargetGrids`、多目标、`selectAll`、`Inquiry` 与 `Continue`;
- 显示服务器提供的决策倒计时。
验收:
- 所有 `DecisionKind` 都有可完成或可取消的 UI;
- 不可用技能仍能查看说明,但无法提交;
- 决策超时后 UI 能反映 AI 托管状态。
### 阶段 D:断线恢复
任务:
- 对局进行中断线后按退避间隔重连;
- 重连成功后发送 `gaming.resume`;
- 清除旧的本地选择与动画队列;
- 根据补发快照重建地图、单位、队列和待处理决策;
- 显示重连与 AI 托管遮罩。
验收:
- 强制断开连接后服务器继续运行;
- 客户端恢复连接后不会收到其他旧局数据;
- 恢复后的单位位置、资源和决策与服务器一致。
### 阶段 E:表现与信息完整性
任务:
- 比较前后快照,生成移动、受击、治疗和淘汰动画任务;
- 动画积压或重连时允许跳过;
- 加入战斗日志抽屉、结果页和服务器错误提示;
- 完成键鼠与基础手柄焦点导航。
验收:
- 动画不会阻塞快照接收;
- 跳过动画后画面立即对齐最新快照;
- 16:9 窗口缩放时 HUD 不遮挡关键操作区。
## 8. 测试策略
### 自动检查
- C# 工程构建必须保持 0 错误;
- 保留 `--solo-smoke-test`,验证连接、开局、选人和首个快照;
- 为协议反序列化保存最小 JSON 样本,验证 WebAPI 字段变更不会静默破坏客户端;
- 为 `GridProjector` 增加格子到屏幕、屏幕到格子的往返测试。
### 手工竖切测试
1. 启动 WebAPI;
2. 启动 Godot 并连接默认地址;
3. 开始新局并选择角色;
4. 确认地图单位数量与快照一致;
5. 完成一次移动;
6. 完成一次普通攻击;
7. 观察 HP、队列和 DP 更新;
8. 中途断线并恢复;
9. 结束对局并查看结果。
## 9. 竖切完成定义
同时满足以下条件,才视为第一条战斗竖切完成:
- 玩家无需使用调试控制台即可完成选人、移动、普攻和结束行动;
- 所有单位来自服务器快照,并位于正确逻辑格;
- 客户端没有本地计算伤害、射程或行动合法性;
- 合法格和合法目标严格来自当前 `gaming.request`;
- 断线重连后可以从完整快照恢复;
- 鼠标可以完成全部核心流程;
- 自动冒烟测试和手工竖切测试均通过。
## 10. 暂不包含
- Server-v3 登录、房间和匹配;
- 房主模式与 NAT 穿透;
- 正式地图图集和全部角色动画;
- 战争迷雾;
- 多层高度、视线与完整掩体规则;
- 回放编辑器、观战与增量状态同步;
- 移动端发布和 Web 导出。
## 11. 下一项开发任务
立即进入阶段 A:创建 `UnitView`,并在 `BattleScreen` 中实现按 GUID 对权威快照进行实例协调。第一小步只使用临时剪影和 HP 条,确保角色数量、位置、阵营与当前行动者状态正确,再接入正式人物素材。
+330
View File
@@ -0,0 +1,330 @@
# Godot 联机接入与 UI 草案
> 状态:讨论稿
> 日期:2026-09-18
> 前提:Godot C# 客户端、FunGame.Core 规则、OSM 内容模块、服务器权威计算。
## 1. 设计目标
Godot 客户端从第一版起就按“可联机”设计,即使最初只连接本机 WebAPI,也不允许战斗 UI 直接修改规则对象。
核心原则:
1. **一个客户端,三种部署方式**:本机单人、房主权威 P2P、专用服务器共享同一套协议和界面。
2. **权威端计算**:客户端只发送意图,不能自行决定伤害、命中、效果或行动是否合法。
3. **显示与规则解耦**:Godot 只消费 DTO/视图模型,不引用服务器内部的 `Character`、`Skill` 和 `GamingQueue` 对象。
4. **状态可恢复**:任意时刻收到完整快照,客户端都能重建战场;动画不是权威状态。
5. **输入方式无关**:鼠标、触屏和手柄最终都产生相同的决策命令。
## 2. 三种部署方式
| 模式 | 权威计算位置 | 适用场景 | 主要代价 |
|---|---|---|---|
| 本机单人 | 本机 WebAPI/游戏服务 | 开发、离线、单人剧情 | 打包和进程管理 |
| 房主模式 | 房主设备的监听服务器 | 好友房、局域网、低成本联机 | 房主可作弊;房主退出会终止对局 |
| 专用服务器 | Server-v3 或其后续服务 | 排位、公开房、长期运营 | 部署、账号、监控和带宽成本 |
### 2.1 本机单人
Godot 启动或连接本机服务,仍通过与联机相同的消息协议进行游戏。这样单机版不会形成第二套战斗逻辑。
开发期可以手动启动 WebAPI;发行期再决定使用子进程、内嵌宿主或随游戏启动的本机服务。进程生命周期、端口冲突和崩溃恢复需要单独设计。
### 2.2 P2P:建议采用房主权威
这里的 P2P 建议定义为 **listen server(房主既是玩家也是服务器)**,而不是所有客户端各自运行规则后做确定性锁步。
原因:FunGame.Core 有丰富的可变效果、同步询问和随机过程,现阶段强行做确定性锁步会显著增加状态一致性和调试成本。房主权威可以直接复用 WebAPI 的会话思路。
- 局域网/直连:房主开放 WebSocket 服务,其他玩家通过地址加入。
- 互联网直连:还需要大厅/信令、端口映射、STUN/TURN 或中继服务;单有 P2P 按钮并不能解决 NAT 穿透。
- 公平性:房主能够修改进程和结果,因此该模式适合好友娱乐,不适合有强公平要求的排位。
- 第一版不建议做房主迁移;房主离开即保存记录并结束对局,复杂度更可控。
### 2.3 专用服务器
Godot 连接 Server-v3,由服务端完成登录、房间、准备、匹配、战斗、重连和记录。现有 Server-v3 已有外围框架,但仍需把 Solo 会话的真人决策桥接扩展到多连接、多玩家和多角色控制。
## 3. 统一客户端分层
```text
Godot 场景与控件
↓ 读取 ViewModel / 提交 Intent
BattleStore(当前权威快照 + 本地选中态)
↓
GameSession(请求关联、状态机、重连、心跳)
↓
IGameTransport
├─ WebSocketTransport:本机、房主、专服
└─ MockTransport:UI 演示和自动测试
```
建议的 Godot Autoload:
- `GameSession`:连接状态、消息分派、请求 ID、心跳、重连和退出。
- `BattleStore`:保存最后一个权威快照和短暂的本地 UI 状态,发出细粒度更新信号。
- `AssetCatalog`:角色/技能/状态 ID 到纹理、名称和占位图的映射。
- `UiRouter`:大厅、选人、战斗、结算和错误页之间切换。
- `GameSettings`:音量、语言、画面、输入和无障碍设置。
服务器项目和 OSM 内容模块不应成为 Godot UI 程序集的直接依赖。可以建立一个轻量的“协议契约”C# 项目,仅存放信封、DTO、枚举和序列化设置,由 WebAPI、Server-v3 和 Godot 共同引用。
## 4. 协议演进建议
现有 `t/i/ok/d/ts/error` 信封可以保留。正式联机版建议逐步增加:
- `protocolVersion`:客户端与服务器协议版本。
- `gameId` / `sessionId`:避免重连或多局消息串线。
- `stateRevision`:每次权威状态变化递增,用于丢包、乱序和去重判断。
- `requestId` 与 `deadline`:决策属于哪个请求、服务端何时超时。
- `clientActionId`:客户端重试时保持幂等。
- `actorUserId` / 控制关系:服务器明确哪个连接可控制哪些角色。
- `capabilities`:协商压缩、增量状态、观战和回放等能力。
- 结构化拒绝原因:状态过期、目标非法、资源不足、非当前玩家等。
- 重连令牌:短期恢复连接,不把登录凭据直接当对局凭据使用。
客户端只能提交类似下面的意图:
```text
选择行动类型 → 选择 skillId/itemId → 选择 targetCharacterIds/gridIds → 确认
```
客户端不能提交“造成 120 点伤害”或“给目标添加效果”之类的结果。
## 5. 战斗视觉与界面布局
视觉方向已确定为:**类似《少女前线 2:追放》的斜俯视战场、半隐藏战棋格、全屏地图与贴边悬浮 HUD,人物明确使用纯 2D 素材。**参考对象只用于镜头、信息层级和交互节奏,不复刻其美术、图标或具体版式。
结合本项目以 2D 素材为目标,本文先按“2D 场景 + 2D 人物”的斜投影方案设计;若后续确定采用“3D 场景 + 2D 人物”,网络协议、逻辑格和 HUD 均可保留,只替换战场渲染与遮挡实现。
地图分层、图块尺寸、规则数据和美术拆分详见[《Godot 地图与素材制作建议》](./Godot地图与素材制作建议.md)。
第一版以 **16:9 横屏桌面** 为基准。地图始终铺满整个视口,HUD 不再把画面硬切成左、中、右三栏:
```text
┌─菜单 / 回合 / 任务──────────────精简行动队列────────网络 / 暂停─┐
│ │
│ 全屏斜俯视 2D 战场 │
│ 平时隐藏格子;移动、攻击、目标选择时局部显现 │
│ 单位头顶只保留 HP、效果和掩体等必要信息 │
│ │
│ 当前角色头像与资源 技能 / 物品 / 等待 / 结束行动 │
└──────────────────上下文提示 / 取消 / 确认────────────────────────┘
```
- 左上:菜单、回合、胜利条件和任务进度。
- 上方中部:精简行动顺序;完整队列通过展开面板查看。
- 左下:当前角色头像、HP/MP/EP、决策点和关键状态。
- 右下:圆形或方形行动图标、技能/物品入口及结束行动。
- 底部中间:仅在目标选择期间出现“取消/确认”和选择计数。
- 角色详情、队伍、战斗日志从屏幕边缘抽屉式展开,不长期遮挡地图。
### 5.1 纯 2D 斜俯视投影
当前推荐的全 2D 战场使用 `Node2D + Camera2D`。逻辑仍是二维整数格,显示层通过独立的 `GridProjector` 将服务器格子坐标投影到斜俯视画面:
```text
screenX = (gridX - gridY) × cellWidth / 2
screenY = (gridX + gridY) × cellHeight / 2 - heightLevel × heightStep
```
推荐先使用接近 2:1 的菱形/二等角投影,再根据人物比例调整 `cellWidth : cellHeight`。服务器只关心格子 ID、坐标、高度、通行和掩体规则,不依赖实际像素位置。
纯 2D 人物建议采用:
- `AnimatedSprite2D`,脚底中心作为原点,至少准备四方向,正式品质以八方向更自然;
- 独立的脚底阴影、选中环、受击闪烁和状态特效层;
- `idle / move / attack / skill / hit / defeat` 为第一批必需动画;
- 将来如需要更细腻的待机和换装,可在不改变网络协议的情况下换成 `Skeleton2D` 切片动画。
### 5.2 Godot 场景分层
```text
BattleScreen (Node)
├─ BattleWorld (Node2D, y_sort_enabled)
│ ├─ GroundLayer (TileMapLayer / 大图切片)
│ ├─ GroundDecalLayer
│ ├─ GridOverlay2D
│ ├─ LowCoverLayer
│ ├─ UnitsLayer (Node2D, y_sort_enabled)
│ ├─ EffectsLayer
│ ├─ TallPropsLayer
│ └─ ForegroundOccluders
├─ BattleCamera (Camera2D)
├─ WorldInfoLayer (CanvasLayer)
│ ├─ UnitBars
│ ├─ CoverHints
│ └─ TargetHints
├─ HudLayer (CanvasLayer)
│ └─ SafeArea (MarginContainer, Full Rect)
│ ├─ TopLeftMissionPanel
│ ├─ TopTurnQueue
│ ├─ BottomLeftCharacterPanel
│ ├─ BottomRightActionDock
│ └─ BottomContextBar
└─ OverlayLayer (CanvasLayer)
├─ CharacterDetailDrawer
├─ TeamRosterDrawer
├─ BattleLogDrawer
├─ InquiryDialog
├─ PauseDialog
├─ ReconnectOverlay
└─ ResultScreen
```
地面可由 `TileMapLayer` 组合,也可以使用预绘的大型 2D 场景切片;两者都必须通过格子元数据与规则坐标对齐。HUD 使用 `Control`、容器和主题资源,不以固定像素定位。所有主要按钮设置鼠标、键盘和手柄焦点路径。
### 5.3 半隐藏战棋格
网格不是场景贴图的一部分,而是单独的 `GridOverlay2D`。建议用一次性绘制或复用的多边形批次显示,不为每个格子常驻一个复杂控件。
网格状态:
| 状态 | 表现 |
|---|---|
| 平时观察 | 全部隐藏;只保留必要的掩体标识和悬停轮廓 |
| 选择移动 | 淡蓝显示可达格;不可达格不显示或低亮度显示 |
| 路径预览 | 连接起点到目标格,显示消耗与终点轮廓 |
| 选择攻击 | 有效目标淡红/橙,技能范围使用第二层半透明色 |
| 范围技能 | 选中格高亮,受影响格以脉冲或描边预览 |
| 等待服务器 | 保留已提交目标的细描边,禁止继续点击 |
透明度应允许玩家看清地面与掩体。颜色不能作为唯一信息,格子还需通过图案、边线或图标区分移动、攻击和危险范围。
鼠标拾取应由 `GridProjector` 将屏幕坐标反算为候选格,再用菱形边界确认;不依赖大量 `Area2D`。触屏和手柄则通过当前格坐标移动游标。
### 5.4 遮挡、层级与掩体
纯 2D 斜俯视的关键风险是单位被墙体或前景遮住。处理规则如下:
- 单位和低矮物件按脚底 `screenY` 排序;Godot 使用 `y_sort_enabled`,必要时给跨多格物件设置人工排序锚点。
- 高墙、屋顶、树冠和前景物拆成独立遮挡层,不能与地面烘焙成一张不可分离图片。
- 遮挡当前角色、鼠标格或目标时,以 Tween/Shader 将相关前景淡化到约 25%–45%,移开后恢复。
- 掩体规则来自服务器格子边缘数据,画面中的箱子和墙只是其视觉表现;不能通过贴图颜色推断是否有掩体。
- 建议地图数据预留 `walkable`、`heightLevel`、`terrainCost`、`blocksSight` 与四边掩体信息;最终字段名以 FunGame 地图模型的扩展方式为准。
镜头支持拖拽、边缘移动、滚轮缩放、聚焦当前行动者和查看目标。自动镜头只能平滑引导,玩家手动操作后应立即让出控制。
### 5.5 决策与面板映射
| 服务器决策 | Godot 表现 |
|---|---|
| `SelectCharacter` | 选人页;卡片、详情、确认 |
| `ActionType` | 右下行动坞;移动、攻击、技能、物品、等待 |
| `Skill` | 右下技能图标展开;长按/悬停显示消耗、冷却和原因 |
| `Item` | 右侧物品抽屉,不关闭战场视野 |
| `Targets` | 单位与脚下格共同高亮;底部上下文栏确认 |
| `TargetGrid` | 可选格子高亮;单选确认 |
| `TargetGrids` | 多选计数、撤销与确认 |
| `Inquiry` | 模态选项框,保留超时提示 |
| `Continue` | 明确的继续/结束行动按钮 |
推荐交互顺序是“选中 → 预览 → 确认”,而不是点到单位立即提交。这样能兼容触屏误触和高延迟网络,也与现有 webui-solo 的验证方向一致。
### 5.6 UI 状态机
```text
Disconnected → Connecting → Lobby/CharacterSelect → LoadingBattle
↘ Reconnecting ↗ ↓
Watching → ChooseAction → ChooseSkill/Item → ChooseTarget/Grid → WaitingServer
↑ ↓
└────────────────────── Applied / Rejected ──────────────────────┘
↓
Paused / Finished
```
`WaitingServer` 期间可以显示已提交选择,但不得预演权威伤害结果。若服务器拒绝操作,恢复到服务器指定的决策状态并显示可理解的原因。
## 6. 动画与状态同步
完整快照用于恢复,事件/差异用于表现:
1. `BattleStore` 保存旧快照和新快照。
2. 比较位置、HP、效果、队列和行动者变化。
3. 生成只影响表现的动画任务,例如移动、受击、数字飘字和效果图标。
4. 动画积压过多或重连时,允许快进并直接对齐最新快照。
不要让动画完成回调决定角色是否死亡,也不要为了动画暂停服务器状态更新。表现层可以落后,但最终必须追上最新的 `stateRevision`。
## 7. 素材接入
当前项目已经有角色头像与技能图标,建议由 `AssetCatalog` 统一加载:
- `assets/images/2d-game-icons/characters`
- `assets/images/2d-game-icons/skills`
- `assets/images/2d-game-icons/skills/borderless`
建议每个图标槽包含四层:底图、品质/阵营装饰、冷却/禁用遮罩、状态角标。角色头像素材本身保持无阵营和无边框,边框由主题控件统一渲染;这样换阵营、选中、受伤和死亡状态不需要生成多套位图。
战场人物需要另行建立完整的 2D 单位素材规范。角色头像不能直接充当棋盘单位;两者使用同一个角色 ID 关联,但分别服务于 HUD 和战场。建议先用方向明确的临时剪影验证投影、格子占位和遮挡,再批量制作正式角色动画,避免美术比例在地图定型后返工。
## 8. 联机安全与公平性
- 随机种子和随机结果由权威端掌握并写入回合记录。
- 服务端校验行动者、资源、冷却、目标、距离、格子和请求时效。
- 客户端只接收自己有权看到的信息;未来若有战争迷雾,不能把隐藏单位发给客户端后仅靠 UI 隐藏。
- 所有重要选择带请求 ID,重复发送不会重复执行。
- 专用服务器保留行动记录、结果摘要和必要审计信息。
- 房主模式明确标记为非强公平模式,因为房主天然拥有服务器控制权。
## 9. 分阶段实施
### 阶段 0:契约与最小工程
- 固化消息信封、DTO、枚举和 JSON 设置。
- 建立 Godot C# 最小工程并验证目标 Godot/.NET 组合可构建、可导出。
- 建立 ID 到素材路径的清单和占位图策略。
### 阶段 1:连接现有 Solo WebAPI
- WebSocket 连接、心跳、错误和重连。
- 角色选择、全量快照、行动/技能/目标/格子/询问。
- 先用简单控件完成全流程,不追求最终美术。
### 阶段 2:完成战斗 UI 竖切
- 按 webui-solo 的信息结构重建 Godot UI。
- 加入队列、状态、DP、技能原因、日志、结果和基本动画。
- 补齐键鼠、手柄、缩放和安全区适配。
### 阶段 3:本机发行形态
- 服务启动/停止、端口选择、日志收集和异常恢复。
- 断线、暂停、存档/回放和版本不兼容提示。
### 阶段 4:房主模式
- 一名房主、多名连接、玩家到角色的控制映射。
- 房间准备、超时、掉线 AI 接管和重新加入。
- 先支持局域网/直连,再评估信令与中继。
### 阶段 5:专用服务器
- 接入 Server-v3 的 JWT、房间和匹配。
- 把已验证的真人决策桥接移入通用多人会话。
- 加入观战、运营监控、服务器回放和反作弊审计。
## 10. 验收清单
- 网络延迟或重复点击不会执行两次行动。
- 断线后能够恢复地图、队列、当前决策和倒计时。
- 玩家只能控制服务器分配给自己的角色。
- 窗口缩放后地图、队列和操作区仍可用,不重叠。
- 所有操作可用鼠标完成,核心流程也可用手柄完成。
- 不可用技能仍可查看说明,并明确显示不可用原因。
- 大量状态效果、召唤单位和长队列不会撑破布局。
- 动画被跳过后画面能立即对齐权威快照。
- 同一 Godot 构建可以切换本机、房主和专服地址。
## 11. 当前推荐决策
建议先定下以下默认值,再用竖切结果复盘:
- Windows 桌面端、16:9 横屏优先。
- 服务器权威;单人也走 WebSocket 协议。
- 全屏纯 2D 斜俯视地图;逻辑格平时隐藏,仅在移动、攻击和目标选择时局部显现。
- HUD 采用贴边悬浮布局:左上任务、上方精简队列、左下角色状态、右下行动坞、底部确认区。
- P2P 第一版为房主权威且不做房主迁移。
- 第一目标是接通 `/ws/solo`,不是立刻重构 Server-v3。
仍需产品层共同决定的内容包括:场景也采用纯 2D 斜投影还是使用 3D 地形搭配 2D 人物、每名玩家控制单角色还是小队、是否需要战争迷雾、回合决策是否有倒计时,以及首发平台是否包含移动端。
+39
View File
@@ -0,0 +1,39 @@
# 《筽祀牻》资料库
本目录用于沉淀《筽祀牻》(OSM)的公开设定、剧情与可用于后续创作的资料基线。
## 文档导航
- [世界观设定](./世界观设定.md):能量流、能量节点、主要势力、历史事件与核心矛盾。
- [主线剧情](./主线剧情.md):五章主线、两条路线与结局结构。
- [地区档案](./地区档案.md):Region-0 至 Region-12 的类别、环境、生态、资源与任务钩子。
- [角色官网资料](./角色官网资料.md):18 名角色的官网数值、专属被动和爆发技索引。
- [游戏机制摘要](./游戏机制摘要.md):回合、时间、决策点、伤害、属性、状态和技能框架。
- [角色设定](./角色设定.md):项目已有的角色视觉与人设创作文档,其中包含基于官网资料扩写的创作设定。
- [FunGame 代码调研](./FunGame代码调研.md):核心库、OSM 模块、WebAPI、Server-v3 与旧 Godot 原型的实现现状和接入边界。
- [Godot 联机接入与 UI 草案](./Godot联机接入与UI草案.md):本机、房主模式、专用服务器的统一架构,以及战斗 UI 布局与实施阶段。
- [Godot 地图与素材制作建议](./Godot地图与素材制作建议.md):二等角 TileMapLayer 分层、逻辑格数据、地图图集和首张竖切地图的制作规格。
- [Godot 战斗竖切实施计划](./Godot战斗竖切实施计划.md):从已接通的 Solo WebAPI 推进到可玩战斗原型的阶段拆分、场景职责和验收标准。
## 资料原则
1. 官网资料采集日期为 **2026-09-17**;本地代码调研日期为 **2026-09-18**。
2. “官网资料”指 [《筽祀牻》项目文档](https://docs.milimoe.com/) 中直接公开的规则、故事、角色、技能与地区信息。
3. “档案中心资料”指 [世界观图书馆地区中心页](https://milimoe.com/regions/) 及其仍可访问的地区报告。
4. 本目录中的归纳、分类和摘要不自动视为新 canon;若与源站冲突,以更新日期更晚、内容更具体的源页面为优先参考,但仍应人工确认。
5. 官网声明部分页面文字或图片可能由 AI 生成;本地文档因此保留来源、日期和不确定性说明。
6. 代码调研只描述指定日期可见的本地实现;“建议”“草案”和“后续”均不代表功能已经完成。
## 已知口径差异
- 项目介绍称游戏包含“12 个可探索地区”;地区目录实际列出 Region-0 至 Region-12 共 13 项。较合理的解释是:Region-0 铎京城为主城,“12 个可探索地区”指 Region-1 至 Region-12。
- 世界观图书馆中心页仍列出 13 个地区,但在本次采集时,Region-2、4、5、7、8、9、11 的详情页返回 404。本地档案对这些地区只记录官网目录与中心页仍可验证的内容。
- 故事页的角色表列出 17 名剧情角色,而角色目录另含 The God K,共 18 名可用角色。
- 角色技能总表与个别角色详情页存在旧名或版本差异;本地资料优先采用角色详情页名称。
## 使用建议
- 写剧情前先查阅《世界观设定》和《主线剧情》,避免把路线专属结果写成全局事实。
- 设计地区任务、敌人或掉落时,以《地区档案》的“任务钩子”和“资源”栏为起点。
- 制作角色数值时以《角色官网资料》和源页面为准;制作立绘、三视图或台词时再使用《角色设定》中的创作扩写。
- 后续同步网站时,优先更新源页面日期、失效链接和“已知口径差异”。
+151
View File
@@ -0,0 +1,151 @@
# 《筽祀牻》世界观设定基线
> 资料来源:[项目介绍](https://docs.milimoe.com/welcome/)、[故事策划书](https://docs.milimoe.com/story/)、[地区中心页](https://milimoe.com/regions/) 与 [铎京探索报告](https://milimoe.com/region-0/)。采集日期:2026-09-17。
## 一、世界概览
筽祀牻大陆是一个由**能量流**驱动、魔法与科技并存的世界。大陆上分布着多个**能量节点**;掌握节点不仅意味着掌握能源,还可能改写局部现实法则。
游戏定位为回合制角色扮演游戏。玩家围绕主角“流”的身世与选择,在铎京、META🐴、深海同盟和环大陆学者团之间行动,逐步接近能量流起源与“筽祀牻之眼”的秘密。
世界观的核心命题是:
- 力量与牺牲的悖论;
- 秩序与混沌的长期博弈;
- 技术文明对自然能量的依赖与控制;
- 个体是否能摆脱组织、实验和既定身份;
- 现实法则被改写后,记忆、时间与人格是否仍可信。
## 二、能量体系
### 能量流
能量流是大陆的基础动力与超自然现象来源。科技设备、魔法、地区生态和法则异常都可能借助能量流运行。它既能被人工转化,也会在节点之间循环、自净并对污染作出反应。
### 能量节点
能量节点像大陆的“器官”。节点能够输出能量、影响周边生态,并在受到法则级冲击后进入“创伤应激态”:
- 高浓度能量间歇外溢,制造法则乱流;
- 植物、动物和无机物出现短时异变;
- 严重时发生重力错乱、逆向瀑布或现实解离;
- 节点通常会启动约五天的自我修复;
- 离开异常节点后,污染可被其他节点的能量逐渐中和。
并非所有节点都会发生病变。现有报告推测,节点是否拥有守护者可能是影响因素之一。
### 筽祀牻之眼
筽祀牻之眼位于深海同盟传统领海,是深海能量节点,也是各方冲突的战略核心。
- 对铎京:为晶枢提供主要能量流脉冲;铎京档案称其承担晶枢基础能量流的 75%。
- 对 META🐴:是可被吞噬、用于获取根源力量的节点。
- 对深海同盟:既是领土与主权象征,也是复国和复仇的关键。
- 对时雨:是其沉睡、苏醒并执行净化使命的所在。
### 晶枢
晶枢是铎京控制的人工能源核心,位于城市中心地下约 300 米。其核心“源质立方体”是一枚边长约 2.4 米的暗紫色人工晶体。
晶枢用于:
- 把原始能量流转化为无属性基础能源;
- 供应城市温控、交通和防御;
- 实现建筑重组与气候调控等局部法则改写;
- 扫描熵化污染。
晶枢的弱点是依赖筽祀牻之眼的持续脉冲。铎京虽开发出最长可维持 12 小时的“脉冲镜像装置”,仍未真正摆脱对天然节点的依赖。
### 熵与熵核
“熵”表现为污染、法则扭曲与高代价力量。META🐴通过实验把人改造为能量载体;流是其最成功的实验体之一。大島シヤ持有双手剑“熵灭”,吖养会把熵核污染附着于武器,流则能在“熵核”与“守护”力量之间选择。
## 三、主要势力
### 铎京
大陆科技中枢和城邦国家,人口约 300 万。铎京坐落于大陆西南部平原与海岸交界,以精密机械、能量研究、现代科技和军事力量著称。
城市特征包括:
- 几何化城市规划、气候穹顶与能量网格;
- 磁轨公交、个人飞行器和地下无人货运;
- 以身份晶片记录能耗配额;
- 由中央决策矩阵、算法顾问团与七个专业局构成的政府;
- 三级治安架构:基础巡防、特勤战术队、节点防卫军;
- AI 即时裁决与九人技术陪审团并行的法院体系。
铎京追求以技术消除自然不确定性,但其“技术洁癖”带来高能量损耗,对深海节点的依赖又使其陷入地缘和伦理矛盾。
### META🐴
隐匿组织,信奉“力量即真理”,企图通过吞噬能量节点取得绝对统治。
- 头目:大島シヤ;
- 已知成员:吖养、绿拱门;
- 技术与行动:熵核污染、能量载体实验、离岸监狱人体实验、节点夺取;
- 核心据点:熵核塔;
- 与旧铎京政府曾合作,后与新政府决裂。
### 深海同盟
筽祀牻之眼海域的旧有统治势力,过去由天王星、海王星、冥王星统治。雷欧尼效忠海王星,CHAOS 曾为冥王星效力。
铎京与 META🐴在深海领海建设离岸监狱、铺设输能管道,引发海底战争。深海同盟战败,三位统治者被封印,雷欧尼与 CHAOS 率残部逃亡。此后同盟将铎京视为侵略者,把夺回海域、复活海王星与摧毁 META🐴视为主要目标。
### 环大陆学者团
研究能量流起源、古语与异常现象的学术团体。
- 牛腩:流浪法师,向流提供能量根源线索;
- 清香:与污染残留产生能量共鸣;
- 男甘雨:参与古籍和古语破译;
- QWQAQW/LUOLI66:数据分析角色。
学者团在新铎京政府与 META🐴决裂后参与调查离岸监狱,并协助揭露真相,之后获得铎京认可。
### 铎京探索者协会
协会成立于 2023-03-12,座右铭是“追随能量流的脚步”。主要职责是:
- 探索异常地区;
- 收集资源与材料;
- 研究能量流和节点;
- 编写探索报告与风险预警;
- 寻找让晶枢直接利用能量流、摆脱节点依赖的方法。
协会约有 3 万名正式成员和 1 万余名预备成员,探索者分为初、中、高、特四级。主要部门为理事会、探索指挥部、档案中心、后勤部和医疗应急部。
### 铎京时空异常研究所(D.S.A.R.I)
铎京官方支持的研究机构,专门研究时空异常、能量流、能量节点、魔法和奇异事件,并与探索者协会深度合作。
## 四、关键历史
| 时间 | 事件 |
|---|---|
| 约 2018 年 | 旧铎京市长与 META🐴签订秘密协议,在深海同盟领海建造离岸市立监狱;囚犯被用于能量载体实验,海底输能管道开始窃取筽祀牻之眼的能量。 |
| 其后 | 深海同盟反击,引发海底战争。利维坦遭大島シヤ以“熵灭”重创并封印;深海三统治者被铎京技术封印。 |
| 2019—2022 年 | 离岸监狱持续处理囚犯,引起人权与审查组织质疑。 |
| 2023 年 | 旧市长罪行曝光,铎京爆发革命;新市长推翻旧政府并与 META🐴决裂。 |
| 2023-03-12 | 铎京探索者协会成立。 |
| 2023 年 7—9 月 | 新铎京、环大陆学者团与 META🐴围绕筽祀牻之眼发生进一步冲突。 |
| 2023-09-24 | 档案记载筽祀牻之眼释放法则级冲击波,部分节点随后出现病变。 |
## 五、世界观的主要冲突轴
| 冲突 | 表层问题 | 深层问题 |
|---|---|---|
| 铎京 vs META🐴 | 城市安全、节点控制 | 制度秩序能否压制“力量即真理” |
| 铎京 vs 深海同盟 | 领海、输能管道、战争责任 | 科技文明的繁荣是否建立在他者被侵占之上 |
| META🐴 vs 深海同盟 | 熵核与时之泪、熵核塔 | 复仇是否会复制力量统治 |
| 学者团 vs 各方 | 研究、净化、真相 | 知识能否保持中立,实验对象是否拥有主体性 |
| 流 vs 自我身份 | 实验体、护卫、能量载体 | 人能否重新定义自己的力量与归属 |
| 时雨 vs 使命 | 净化节点、牺牲自身 | 被所有人视为希望的存在是否有拒绝牺牲的权利 |
## 六、创作边界
- “筽祀牻之眼归铎京完全控制”来自铎京地区档案的事件后续;主线故事则允许深海路线和大陆重置。编写剧情时应明确所处时间点与路线。
- 地区探索报告采用档案内角色的观察视角,其中可能包含推测、污染或认知不可靠,不应把所有日志内容等同于客观真相。
- 本文只整理源站可验证设定;角色外貌、年龄、服装与台词等项目扩写见《角色设定》。
+124
View File
@@ -0,0 +1,124 @@
# 《筽祀牻》主线剧情整理
> 主要来源:[《筽祀牻》故事策划书](https://docs.milimoe.com/story/)。采集日期:2026-09-17。
## 故事前提
主角“流”曾是 META🐴的实验体,实验编号 Ryuko,拥有极致回复能力,但相关记忆被封存。新任铎京市长推翻旧政府、与 META🐴决裂后,铎京、META🐴和深海同盟围绕筽祀牻之眼形成三方敌对。
故事由流的成长、记忆与阵营选择推动。第三章出现决定性分支,之后形成“光明线/铎京”和“混沌线/深海”两条路线。
## 第一章:熵噬之影
1. META🐴成员吖养突袭铎京,污染城市能源核心“晶枢”,以此向新政府示威。
2. 流作为市长贴身护卫守卫晶枢控制室,玩家在突袭中完成战斗教学。
3. 流首先发现污染痕迹,之后遇到环大陆学者团成员牛腩。
4. 牛腩说明 META🐴正在寻找能量流根源“筽祀牻之眼”,并遗落一卷刻有古语的残卷。
5. 吖养的魔法剑污染与清香的法杖发生能量共鸣。
6. 市长委托流暗中调查异常,为后续自由行动与支线探索打开空间。
## 第二章:逆命者集结
1. 铎京从旧派系成员口中得知,META🐴在离岸监狱拥有重要据点。
2. 市长委托刺客汐月心音窃取情报,流与趣多多同行。
3. 玩家可选择与趣多多正面强攻,或与心音潜行合作。
4. 一行人在监狱内遭遇绿拱门,形成“银隼”手枪与“千羽”暗器的对决。
5. 调查揭示:离岸监狱下方连接筽祀牻之眼,监狱也与流被封存的实验体记忆有关。
6. 清香、男甘雨正在破译古籍,并发现沉睡于筽祀牻之眼的“时雨”可能是唯一能够净化污染的存在。
7. 心音与趣多多返回铎京复命;流选择与学者团经监狱下方通道继续深入海底。
## 第三章:血色联盟
1. 流与学者团进入海底禁区外围,在 META🐴修建的通道中探索能量流、古语和流的记忆碎片。
2. META🐴准备已久,开始总攻筽祀牻之眼并撕裂结界。
3. 铎京依靠科技与军事投送赶到战场;流和学者团沿探索路线抵达边缘。
4. 三方混战爆发:
- META🐴;
- 铎京阵营,包括冷蓝、趣多多、魔法少女等;
- 深海同盟,包括雷欧尼、CHAOS 和雇佣兵团。
5. 雷欧尼揭示深海同盟计划夺取“时之泪”、复活海王星。
6. 雷欧尼认出流体内的熵,公开其 META🐴实验体编号 Ryuko,并以真相和力量邀请流加入深海。
7. 玩家作出路线选择:回归铎京,或加入深海同盟。
8. 多方力量令筽祀牻之眼濒临崩坏,时雨苏醒并开始以消耗自身存在为代价净化节点。
## 第四章:时雨之泪
### 共同事件
- 时雨在净化期间无法主动防御,成为各方争夺或守护的焦点。
- 大島シヤ发动“熵灭领域”,压制非熵能量并试图阻止净化。
- 无论路线如何,时雨最终完成净化、消散,并留下“时之泪”。
- 雷欧尼利用对地下区域的熟悉,在撤离阶段夺走时之泪,与 CHAOS 返回深海。
- 铎京击退 META🐴,但并不知道时之泪的真正去向。
### 光明线:铎京
- 流与铎京和学者团守护时雨;
- 时雨感知流的守护之心,选择他作为能量载体;
- 主要敌人为大島シヤ与 META🐴;
- 情感方向是流在守护行动中寻求救赎。
### 混沌线:深海
- 流协助雷欧尼干扰净化或夺取时之泪;
- 流不会成为时雨的载体,并与时雨的守护者对抗;
- 玩法偏向破坏、干扰、高风险高收益与熵力量;
- 情感方向是流在黑暗中追寻力量与身世真相。
## 第五章:筽祀牻的抉择
### 共同局势
- META🐴残党退守熵核塔;
- 深海同盟持有时之泪,准备复活海王星并消灭 META🐴;
- 铎京不知道时之泪的去向,主力追击 META🐴;
- 雷欧尼背刺濒死的大島シヤ,夺取熵核碎片;
- 铎京市长最终启动大陆重置协议。
### 光明线结局
1. 流随铎京部队攻入熵核塔。
2. 铎京意外遭遇已经复活的海王星和被召唤的利维坦。
3. 深海同盟同时攻击铎京与 META🐴。
4. 流参与利维坦和濒死大島シヤ的最终战,并保护市长或重置装置。
5. 流的回复能力影响铎京市民的存活数量,形成道德值系统。
6. 大陆重置,科技倒退:
- 高道德值:流继承时雨,成为新守护者;
- 低道德值:流未能完成全部守护,大陆未来不确定。
### 混沌线结局
1. 流与雷欧尼、CHAOS 使用时之泪复活海王星并召唤利维坦。
2. 深海大军进攻熵核塔,与大島シヤ决战。
3. 雷欧尼夺取熵核碎片,CHAOS 吞噬碎片后陷入疯狂。
4. 流协助深海力量抵抗重置影响。
5. 大島死亡,META🐴覆灭,深海同盟恢复海底统治。
6. 流携带熵核碎片,正式加入深海同盟。
7. 解锁隐藏 BOSS 战“海王星的野望”。
## 路线对照
| 项目 | 光明线/铎京 | 混沌线/深海 |
|---|---|---|
| 核心动机 | 守护、赎罪、秩序 | 真相、力量、复国 |
| 时雨关系 | 守护者与载体 | 对抗者与利用者 |
| 主要敌人 | META🐴,后遭遇深海同盟 | 铎京/学者团与 META🐴 |
| 流的力量表达 | 回复、守护、群体生存 | 熵、干扰、高风险收益 |
| 结局方向 | 大陆重置与守护者继承 | META🐴覆灭与深海复兴 |
## 配套系统
- **记忆碎片**:通过探索解锁流作为 META🐴实验体的过去。
- **阵营声望**:影响与雷欧尼、海王星的互动,并解锁隐藏任务和装备。
- **战术手册**:记录角色特性,辅助战斗策略。
- **道德值**:光明线后段以流的回复与守护结果影响市民存活和结局。
## 后续创作应确认的问题
- 大陆重置协议的发明者、权限、影响范围和不可逆代价;
- 时雨成为或不成为“载体”时,意识是否保留;
- 大島死亡是否为所有路线共同事实;
- 熵核碎片在两条路线中的最终归属;
- The God K 是否介入主线重置,以及他与因果、时雨之间的关系;
- 高/低道德值的具体判定和中间结局。
+224
View File
@@ -0,0 +1,224 @@
# 《筽祀牻》地区档案
> 资料来源:[官网地区列表](https://docs.milimoe.com/region/) 与 [世界观图书馆地区中心页](https://milimoe.com/regions/)。采集日期:2026-09-17。
## 一、地区总表
官网将大陆内容归为“此地、奇异、生态、机械、矿区、世外”六类。项目介绍中的“12 个可探索地区”应指 Region-1 至 Region-12;Region-0 铎京是主城。
| 编号 | 地区 | 类别 | 难度 | 天气 | 核心概念 |
|---:|---|---|---|---|---|
| 0 | 铎京城 | 此地/现代 | 宜居 | 酷暑至霜冻 | 科技城邦、晶枢、探索者协会、主城 |
| 1 | 银辉城 | 奇异 | ★★★★★ | 晴朗/星光 | 悬浮倒三角都市、液态月光、悖论引擎 |
| 2 | 瑟兰薇歌林海 | 生态 | ★★★ | 多云 15℃/晴朗 24℃ | 荧蓝林海、旋律古龙、脉轮圣树与可编程蜜蜡 |
| 3 | 永燃坩埚 | 矿区 | ★ | 高温 60℃/炎热 45℃ | 火山锻造城、活体金属、深渊火钻 |
| 4 | 永霜裂痕 | 奇异 | ★★★★★ | 极寒 -25℃ | 冻结的战争残影、失常时钟、时霜药剂 |
| 5 | 齿轮坟场 | 机械 | ★★ | 沙尘 30℃/阴暗 -5℃ | 机械荒漠、活体建筑、改造车间 |
| 6 | 千瞳镜湖 | 奇异 | ★★ | 阴沉 10℃/微风 8℃ | 平行时空、倒影城、瞳孔传送门 |
| 7 | 时之荒漠 | 奇异 | ★★★★ | 沙尘暴 35℃/不稳定 38℃ | 每小时重组的沙丘、昨日之城、时间碎片 |
| 8 | 谵妄海市 | 奇异 | ★★★★ | 迷幻 20℃ | 幻觉城市、思维寄生虫、可食用梦境 |
| 9 | 腐萤沼渊 | 生态 | ★★★★ | 潮湿 22℃ | 毒气沼泽、共生母体、拟声菌群 |
| 10 | 双生月崖 | 生态 | ★★★★ | 永昼 15℃/永夜 -10℃ | 悬浮山脉、昼夜切换、星空巨兽与空间湮灭 |
| 11 | 棱镜骨桥 | 生态 | ★★★★★ | 雾气 14℃/阴森 8℃ | 呼吸骨桥、亡者记忆、幽灵船与空间褶皱 |
| 12 | 泰坦遗迹 | 世外 | ★★★ | 雷暴 5℃/幽暗 10℃ | 三维岩阵、神经宝石、泰坦创世调试程序 |
## 二、地区要素索引
### Region-0:铎京城
- **设施**:锻造积分商店、赛马积分商店、共斗积分商店。
- **城市命脉**:晶枢与筽祀牻之眼构成能量双循环。
- **组织**:市政府、治安警备部队、城邦法院、铎京探索者协会、D.S.A.R.I。
- **视觉关键词**:银灰合金、深蓝夜色、荧光铭文、几何街区、气候穹顶、磁轨与悬浮交通。
- **故事用途**:主城、政治中心、任务集散地、路线中“秩序”的主要代表。
### Region-1:银辉城
- **头目**:失控的悖论引擎、星辉巨母。
- **生物**:星银守卫、星辉水母。
- **资源**:星银合金、液态月光、星辉凝露。
- **NPC**:莉娅、沉默守卫 G-7。
- **区域**:悖论深井、星屑回廊、星辉水域、上城区、旧街道。
- **任务钩子**:能量潮汐、重力观测、守卫警戒解除、月光洪流、月光萃取、湖底重力测绘。
### Region-2:瑟兰薇歌林海
- **头目**:旋律古龙、圣树守护者。
- **生物**:荧光精灵、蜜蜡蜂。
- **资源**:荧蓝汁液、可编程蜜蜡。
- **NPC**:老祭司苔藓须、封喉歌者。
- **区域**:古龙沉眠地穴、立体蜂巢市集。
- **任务钩子**:根系低频共振、蜜蜡数据安全、声波囚笼、汁液采收与蜜蜡编程。
### Region-3:永燃坩埚
- **头目**:岩浆之王、熔岩巨兽。
- **生物**:岩浆鱿鱼、火焰元素、深渊矿工、活体金属苔藓。
- **资源**:活体金属苔藓、深渊火钻。
- **NPC**:“铁颚”巴拉克、苔丝夫人。
- **区域**:鱿熔血池、活体锻炉。
- **任务钩子**:元素裂隙熵增、共生进化、火钻链式裂变、金属瘟疫、灵魂烙印认可。
### Region-4:永霜裂痕
- **头目**:时空扭曲者。
- **生物**:冰霜傀儡。
- **资源**:时霜药剂、冰封记忆。
- **NPC**:艾萨克、冻伤的信使。
- **区域**:时钟哨塔、记忆回廊。
- **任务钩子**:分析冻结战争、校准失常时钟、解救时间泡中的科研组、时霜逆向工程。
### Region-5:齿轮坟场
- **头目**:报废的构装巨龙、回廊之心。
- **生物**:齿轮傀儡、改造士兵。
- **资源**:机械核心碎片、活体魔力血。
- **NPC**:“噬罪者”、7 号改造体。
- **区域**:忏悔教堂、造物车间。
- **任务钩子**:机械与生物融合、污染隔离、活体建筑增殖、核心熔毁、上古核心解密。
### Region-6:千瞳镜湖
- **头目**:镜像之主。
- **生物**:镜像守卫。
- **资源**:量子纠缠碎片;档案另记录时渊漂流瓶和视界切片。
- **NPC**:奥尔加、溺亡观测者。
- **区域**:倒影城、千瞳之巢。
- **任务钩子**:镜像城测绘、认知污染、空间净化、传送门碎片提取。
### Region-7:时之荒漠
- **头目**:时间吞噬者、时之君王。
- **生物**:流沙蝎、时之蝎。
- **资源**:时间碎片、时凝液。
- **NPC**:卖沙人、循环勘探队。
- **区域**:昨日之城、时漏绿洲、沙丘核心。
- **任务钩子**:寻找昨日之城、预测地形重组、沙暴救援、时间污染净化、时凝液提纯。
### Region-8:谵妄海市
- **头目**:梦魇之主。
- **生物**:思维寄生虫。
- **资源**:梦境碎片。
- **NPC**:认知矫正师、洛伦佐。
- **区域**:梦境交易所、幻疡医院。
- **任务钩子**:认知过滤、寄生感染、精神隔离、梦境碎片毒性分析。
### Region-9:腐萤沼渊
- **头目**:共生母体。
- **生物**:沼泽毒虫、模拟动物叫声的诱捕菌群。
- **资源**:菌类样本。
- **NPC**:伊芙琳、溃烂猎人。
- **区域**:母体神经丛、诱捕菌林。
- **任务钩子**:共生生态调查、声波模式分析、毒气中和、麻痹菌类采样。
### Region-10:双生月崖
- **头目**:昼夜守护者、星空巨兽。
- **生物**:光鹰、浮空岛灵。
- **资源**:影玫瑰、星锚晶石。
- **NPC**:守夜人卡尔、星锚祭司。
- **区域**:永昼庭园、永夜墓园、星锚之地、中央之岛。
- **任务钩子**:加固引雷柱、观测湮灭边界、巨兽狂怒预警、边界扩张撤离、星锚晶石校准。
### Region-11:棱镜骨桥
- **头目**:远古影狼、骸骨巨龙。
- **生物**:棱镜幽灵、幽灵水手。
- **资源**:晶化记忆孢子、虚空骨髓、神经蕨类、龙骨碎片。
- **NPC**:骸骨诗人、“船长”。
- **区域**:骸鲸观星台、幽灵船坞。
- **任务钩子**:亡者记忆共鸣、幽灵舰队防线、记忆过载疏散、幽灵航线测绘。
### Region-12:泰坦遗迹
- **头目**:雷霆泰坦、矿脉之心。
- **生物**:雷霆元素、晶簇守卫。
- **资源**:泰坦符文石、神经宝石、矿脉神经纤维。
- **NPC**:泰坦刻录员、矿痛共生体。
- **区域**:神经矿脉、雷霆王座、裁决矩阵。
- **任务钩子**:符文解读、矿脉止痛、磁场稳定、共鸣阻尼、符文拓印、神经宝石采样。
## 三、详细档案中新增的关键设定
世界观图书馆在本次采集时仍可打开 Region-0、1、3、6、10、12 的完整报告。以下信息来自这些长篇档案,不是对所有地区的统一推定。
### 铎京:确定性城市
- 人口约 300 万,位于大陆西南部平原与海岸交界。
- 城市为核心高楼、工业能源带、外围绿化与水渠组成的分层结构。
- 人工生态闭环率约 87%,公共交通覆盖率约 98%。
- 市民以身份晶片管理能耗配额,住宅、出行、医疗和娱乐均嵌入能源管理系统。
- 探索者协会约有 3 万正式成员和 1 万余名预备成员。
- 旧政府曾执行“记忆清洗协议”等高压保密手段,说明新旧制度之间仍存在连续性风险。
### 银辉城:递归现实裂谷
- 倒三角都市以星银合金构成,液态月光是能源也是侵蚀性介质。
- 悖论引擎每 180 秒释放曲率震荡;午夜会出现星辉水母与强烈重力波动。
- D.S.A.R.I 报告推测城市可能是动态递归型现实裂谷,水母类似自体免疫系统,液态月光像循环介质,城市收缩则类似胎衣成型。
- 档案中的“失控”可能是误判:悖论引擎也可能在主动筛选、重置或构筑某种跨维度生命。
- 莉娅长期暴露后身体部分星银化,仍向协会提供实时数据,是该地区最适合作为叙事锚点的 NPC。
### 永燃坩埚:活体工业生态
- 城市嵌在火山腔体内,螺旋向下,环境在 45℃与 60℃状态之间变化。
- 活体金属苔藓约 72 小时繁殖一次,兼有金属延展性与自我修复能力。
- 岩浆鱿鱼、苔藓与深渊火钻形成共生链;岩浆鱿鱼死亡后可能促进火钻与苔藓异常增殖。
- 深渊火钻封存矿工意识印记,未经“灵魂烙印”认可的接触会导致危险能量爆发。
- 近期熵增和火钻裂变风险上升,适合作为资源采集逐渐演变为生态灾难的任务线。
### 千瞳镜湖:观察与身份污染
- 湖面是平行时空窗口,倒影城重力颠倒,地形会随观察者情绪和时间改变。
- 镜像之主可能通过瞳孔传送门监控、调整甚至删除不稳定时空。
- 探索者需携带反重力装置、认知稳定剂和量子锚定器,湖外同伴可作为身份锚点。
- 镜像空间内五天可能只对应现实五小时。
- 死亡者可能沉入更深的镜像层,逐步失去自我并成为镜湖系统的一部分。
- 完整报告建议:行动不超过 72 小时,不收集超过 10 枚量子纠缠碎片,不在镜像城遗留个人物品。
### 双生月崖:束缚与湮灭
- 悬浮山脉被分为永昼和永夜两侧,昼夜切换会沿边界翻转环境。
- 切换窗口结束后,未撤离的物质会发生不可逆空间湮灭。
- 中央之岛的“星锚之地”用巨型引雷柱束缚星空巨兽;光鹰、浮空岛灵与引雷柱可能组成维持束缚的生态网络。
- 守夜人卡尔是“活体枢纽”式守望者,其人格与星锚、巨兽痛苦及昼夜系统永久绑定。
- 卡尔优先维护束缚系统而非保护人类;他的警告可能救人,也可能把探索者导向系统需要保护的危险节点。
### 泰坦遗迹:创世失败现场
- 悬浮岩阵依赖神经宝石矿脉的共振维持,开采等同于刺激大型活体神经网络。
- 裁决尖碑在月圆时投射可能用于“调试世界”的泰坦符文。
- 晶簇守卫行为可被特定频率与节奏覆盖,说明其原生逻辑存在可调制接口。
- 档案推测泰坦将创世程序与地脉融合;黏液、孢子和婴儿轮廓可能是生命子程序的失败副本。
- 12.7Hz 共振、胎儿状投影、雷暴增强和婴儿轮廓都是撤离信号。
## 四、视觉与关卡语言
| 地区 | 主色与材质 | 关卡核心机制 |
|---|---|---|
| 铎京 | 银灰合金、深蓝、荧光铭文、玻璃 | 配额、权限、城市系统与政治选择 |
| 银辉城 | 星银、冷白月光、液态金属 | 重力翻转、周期重置、侵蚀 |
| 林海 | 荧蓝树液、蜜蜡、巨木 | 声波、编程材料、垂直生态城 |
| 永燃坩埚 | 暗红岩浆、铜黑、活体金属 | 高温、资源认可、共生失控 |
| 永霜裂痕 | 冰蓝晶体、战争残影 | 时间速率、记忆错乱、时钟校准 |
| 齿轮坟场 | 锈铁、微型齿轮沙、魔力血 | 改造、机械感染、核心熔毁 |
| 千瞳镜湖 | 镜银、幽蓝瞳孔、水面反射 | 认知锚点、镜像、身份污染 |
| 时之荒漠 | 金色沙海、时间晶体 | 地形重组、时间加速/减速 |
| 谵妄海市 | 迷幻霓虹、梦境食物 | 真假识别、认知过滤、寄生 |
| 腐萤沼渊 | 荧绿毒雾、肉质神经 | 声音诱捕、毒气、共生网络 |
| 双生月崖 | 白昼金/永夜紫黑 | 定时撤离、空间湮灭、浮岛移动 |
| 棱镜骨桥 | 晶红杉、骨白、幽灵蓝 | 记忆共鸣、虚空航线、精神负荷 |
| 泰坦遗迹 | 青灰岩、暗紫神经晶、雷光 | 共振、地形失稳、规则指令 |
## 五、来源状态
| 页面 | 采集时状态 |
|---|---|
| 世界观图书馆中心页 | 可访问,列出 Region-0 至 Region-12 |
| Region-0、1、3、6、10、12 | 详细报告可访问 |
| Region-2、4、5、7、8、9、11 | 中心页链接返回 404;官网简版详情可访问 |
失效详情页恢复后,应优先补充环境描述、生态系统、探索指南、日志记录者与新增 NPC/资源,并复核官网简表是否过时。
+158
View File
@@ -0,0 +1,158 @@
# 《筽祀牻》游戏机制摘要
> 来源:[游戏机制规则书](https://docs.milimoe.com/rule/) 与 [技能列表](https://docs.milimoe.com/skill/)。规则页标注更新日期为 2025-04-18;采集日期:2026-09-17。本文只作结构化摘要,具体数值以源规则书为准。
## 一、战斗时间
游戏采用完全回合制,角色依序行动。
- **Round**:游戏层面的一个行动回合;每名角色的一次行动都可计为一个 Round。
- **Turn**:某个角色自己的行动轮次。技能持续回合通常按该角色的 Turn 计算。
- **回合外**:任意角色的行动回合,对其他角色都属于回合外。
- **回合内阶段**:准备阶段 → 行动阶段 → 结束阶段。
准备阶段检查控制态与吟唱态;常态角色可在行动阶段普通攻击、释放战技、吟唱魔法、使用物品或放弃行动;结束阶段结算硬直、时间和特效。
### 硬直与行动顺序
时间在无人行动时流逝,直到顺序表队首角色的硬直时间降至 0。角色行动期间时间暂停,行动结束后按硬直重新加入顺序表。
行动系数:
```text
行动系数 = 行动速度 / 1500 × 100%
```
行动后的硬直:
```text
实际硬直时间 = 基础硬直时间 × (1 - 行动系数)
```
行动系数上限为 90%,即行动速度达到 1350 时封顶。顺序表允许低硬直角色插队;预释放爆发技可在回合外以特殊规则插入队列。
## 二、决策点
决策点决定角色在一个回合内能执行多少操作,并配有普通攻击、战技、爆发技、魔法和物品等动作配额。
- 初始决策点上限:2;
- 每次轮到角色行动,上限提高 1,最高 7;
- 回合开始补充上限的一半,向下取整且至少为 1;
- 完全行动不能或行动受限时,只补充上限的四分之一,向下取整且至少为 1;
- 普攻消耗 1 点;
- 战技或魔法消耗 2 点;
- 物品消耗 1 点;
- 回合内爆发技消耗 2 点;
- 回合外爆发技消耗 3 点。
多次行动后的硬直,取本回合最长一次行动硬直,再加已使用的决策点数量。
## 三、伤害框架
规则书将伤害分为六个连续乘区/步骤:
1. 基础伤害基底与倍率;
2. 伤害加成区间 1;
3. 减伤;
4. 暴击伤害;
5. 伤害加成区间 2;
6. 魔法效能(仅魔法伤害)。
### 物理伤害
```text
预计物理伤害 = (基础攻击力 + 附加攻击力) × 伤害系数
物理伤害减免 = 物理护甲 / (物理护甲 + 240)
```
物理穿透先削减目标护甲,再计算物理减伤。
### 魔法伤害
整体流程与物理伤害相近,但使用魔法抗性和魔法穿透。魔法伤害还具有属性,并会应用不同的属性抗性及魔法效能。
## 四、角色成长
- 最高等级:60;
- 定位:核心、先锋、近卫、支援、治疗;
- 核心属性:力量、敏捷、智力;
- 主要能力值:生命、魔法、爆发能量、行动速度、攻击、护甲、魔抗、加速、闪避、暴击、穿透、冷却缩减、回复等;
- 爆发能量最大值:200;造成和受到伤害都会获得少量爆发能量。
基础最大生命值:
```text
初始生命值 + (等级 - 1) × (17 + 0.68 × 初始生命值) + 基础力量 × 9
```
最大生命值:
```text
基础最大生命值 + 额外力量 × 9 + 额外生命值加成
```
基础最大魔法值:
```text
初始魔法值 + (等级 - 1) × (1.5 + 0.14 × 初始魔法值) + 基础智力 × 8
```
基础攻击力:
```text
初始攻击力 + (等级 - 1) × (0.95 + 0.045 × 初始攻击力) + 基础核心属性
```
## 五、角色状态
规则将角色状态分为:
- **常态**:可正常决策;
- **吟唱态**:等待魔法结算,行动受限;
- **控制态**:决策受影响或跳过回合;
- **死亡**:按死亡与复活规则处理。
技能效果还涉及增益、负面状态、控制、驱散、免疫、豁免和检定修正。免疫细分为物理免疫、魔法免疫、技能免疫和完全免疫;“完全免疫”并不自动等同于免疫所有负面效果,仍需以具体技能文本为准。
## 六、技能体系
- **普通攻击**:基础输出手段;
- **主动战技**:消耗决策点并受冷却约束;
- **被动战技**:持续或条件触发;
- **战斗天赋**:角色构筑的一部分;
- **爆发技**:消耗爆发能量,可存在回合外预释放;
- **魔法**:通常需要吟唱,受魔法瓶颈、魔法效能、消耗、冷却和施法距离影响。
每名角色拥有 1 个专属被动与 1 个专属爆发技。技能总表还包含:
- 通用爆发技;
- 通用被动;
- 伤害、治疗、增益、时间、控制/减益类魔法;
- 伤害、控制、辅助、治疗和机动型战技。
## 七、物品体系
规则书和导航中列出的物品类别包括:
- 魔法卡包;
- 武器;
- 防具;
- 鞋子;
- 饰品;
- 消耗品;
- 魔法卡;
- 收藏品;
- 特殊物品;
- 礼包。
地区资源、任务奖励和装备效果应通过这些分类进入战斗系统,避免为世界观资源另造无法落地的物品层级。
## 八、实现时需要优先验证的规则点
- Round 与 Turn 的 UI 命名,避免持续时间显示歧义;
- 多次行动、吟唱结算和回合外爆发技对硬直的叠加顺序;
- 硬直补偿功能是否保留;
- 各类驱散、强驱散、免疫与豁免的优先级;
- 魔法属性抗性和共享魔法穿透的具体数据结构;
- 角色详情页与技能总表出现名称差异时的版本来源。
+175
View File
@@ -0,0 +1,175 @@
# 《筽祀牻》角色官网资料
> 资料来源:[角色列表](https://docs.milimoe.com/character/) 与各角色详情页。采集日期:2026-09-17。本文记录官网数值和技能,不替代《角色设定》中的视觉与性格创作。
## 一、统一规则
- 官网公开 18 名角色,每名角色拥有 1 个专属被动和 1 个专属爆发技。
- 所有角色官网初始速度均为 300、生命回复均为 4、魔法回复均为 2。
- “属性”列按“初始值/每等级成长”记录力量、敏捷、智力。
- 详情页与技能总表名称不一致时,本文件采用角色详情页名称。
## 二、基础数值总表
| # | 角色 | 核心 | 攻击 | 生命 | 魔法 | 力量 | 敏捷 | 智力 |
|---:|---|---|---:|---:|---:|---|---|---|
| 1 | [大島シヤ](https://docs.milimoe.com/character/oshima/) | 力量 | 25 | 85 | 10 | 30/3.0 | 0/0 | 0/0 |
| 2 | [汐月心音](https://docs.milimoe.com/character/xinyin/) | 敏捷 | 22 | 85 | 60 | 8/0.9 | 19/1.7 | 3/0.4 |
| 3 | [吖养](https://docs.milimoe.com/character/yang/) | 力量 | 23 | 105 | 55 | 11/1.8 | 9/0.5 | 10/0.7 |
| 4 | [男甘雨](https://docs.milimoe.com/character/nanganyu/) | 智力 | 17 | 115 | 80 | 6/0.6 | 7/0.7 | 17/1.7 |
| 5 | [牛腩](https://docs.milimoe.com/character/niunan/) | 智力 | 16 | 75 | 90 | 0/0 | 0/0 | 30/3.0 |
| 6 | [铎京市长](https://docs.milimoe.com/character/mayor/) | 敏捷 | 21 | 120 | 20 | 7/1.0 | 21/1.8 | 2/0.2 |
| 7 | [魔法少女](https://docs.milimoe.com/character/magicalgirl/) | 敏捷 | 20 | 95 | 35 | 7/0.3 | 15/2.3 | 8/0.4 |
| 8 | [清香](https://docs.milimoe.com/character/qingxiang/) | 智力 | 26 | 110 | 80 | 6/0.5 | 4/0.5 | 20/2.0 |
| 9 | [LUOLI66](https://docs.milimoe.com/character/qwqaqw/) | 智力 | 18 | 100 | 45 | 0/0 | 15/1.5 | 15/1.5 |
| 10 | [冷蓝](https://docs.milimoe.com/character/coldblue/) | 力量 | 28 | 95 | 25 | 22/1.9 | 4/0.6 | 4/0.6 |
| 11 | [绿拱门](https://docs.milimoe.com/character/dddovo/) | 敏捷 | 22 | 65 | 22 | 10/1.0 | 20/2.0 | 0/0 |
| 12 | [趣多多](https://docs.milimoe.com/character/quduoduo/) | 力量 | 19 | 90 | 40 | 13/1.5 | 13/1.2 | 4/0.3 |
| 13 | [时雨](https://docs.milimoe.com/character/shiyu/) | 敏捷 | 20 | 105 | 65 | 7/0.7 | 14/1.5 | 9/0.8 |
| 14 | [雷欧尼](https://docs.milimoe.com/character/xreouniii/) | 智力 | 19 | 90 | 75 | 9/0.9 | 9/0.6 | 12/1.5 |
| 15 | [海王星](https://docs.milimoe.com/character/neptune/) | 力量 | 26 | 95 | 55 | 16/1.4 | 7/1.0 | 7/0.6 |
| 16 | [CHAOS](https://docs.milimoe.com/character/chaos/) | 力量 | 27 | 100 | 40 | 14/1.8 | 12/1.1 | 4/0.1 |
| 17 | [流](https://docs.milimoe.com/character/ryuko/) | 敏捷 | 22 | 100 | 45 | 11/0.8 | 15/1.9 | 4/0.3 |
| 18 | [The God K](https://docs.milimoe.com/character/thegodk/) | 智力 | 23 | 80 | 70 | 6/0.6 | 11/1.1 | 13/1.3 |
## 三、专属技能总览
| # | 角色 | 被动 | 爆发技 | 战斗主题 |
|---:|---|---|---|---|
| 1 | 大島シヤ | META马 | 熵灭·极诣 | 受伤加速充能,以当前生命换取固定攻击力 |
| 2 | 汐月心音 | 心灵之弦 | 千羽瞬华 | 双段普攻、低硬直、穿透与弱点爆发 |
| 3 | 吖养 | 蚀魂震击 | 咒怨洪流 | 对受控目标处决、熵核附魔、多目标普攻 |
| 4 | 男甘雨 | 灵能反射 | 三相灵枢 | 魔法连发、消除硬直、回能与减冷却 |
| 5 | 牛腩 | 双生流转 | 变幻之心 | 生命阈值触发力量/智力双模式 |
| 6 | 铎京市长 | 零式崩解 | 零式灭杀 | 高暴击伤害、暴击率与物理穿透 |
| 7 | 魔法少女 | 少女绮想 | 绝对领域 | 无上限蓄势、受击清零、短时无伤 |
| 8 | 清香 | 暗香疏影 | 残香凋零 | 削减能量、压制低能量目标、能量值伤害 |
| 9 | LUOLI66 | 破釜沉舟 | 宿命时律 | 最大生命换取伤害,濒危强化与魔法普攻 |
| 10 | 冷蓝 | 累积之压 | 极寒渴望 | 标记、战斗不能、最大生命百分比伤害 |
| 11 | 绿拱门 | 银隼之赐 | 身心一境 | 敏捷附伤、力量敏捷平衡 |
| 12 | 趣多多 | 弱者猎手 | 饕餮盛宴 | 锁定低生命目标、增伤与吸血 |
| 13 | 时雨 | 开宫 | 放监 | 复制致死技能、标记、任务型控制与真实伤害 |
| 14 | 雷欧尼 | 八卦阵 | 归元环 | 奇偶检定、概率增伤减伤、必暴与减冷却 |
| 15 | 海王星 | 深海之戟 | 海王星的野望 | 暴击分裂、全图扩散、力量强化 |
| 16 | CHAOS | 雇佣兵团 | 全军出击 | 召唤最多五名雇佣兵并获得军团反馈 |
| 17 | 流 | 不息之流 | 宿命之潮 | 持续回复;在熵核输出与团队守护间选择 |
| 18 | The God K | 概念之骰 | 神之因果 | 击杀永久叠层、记录伤害、延迟真实伤害结算 |
## 四、角色机制摘要
### 01|大島シヤ
- **META马**:额外获得初始力量与成长;受伤时获得能量提高 50%;未满 200 能量时每回合额外获得 7 点。
- **熵灭·极诣**:获得基于力量的固定攻击力加成,但普攻命中会损失 6% 当前生命值。
- **设计抓手**:攻击越强,自身裂解越明显;适合“力量有明确代价”的演出。
### 02|汐月心音
- **心灵之弦**:普攻硬直降低,并追加一次伤害折半的普攻。
- **千羽瞬华**:提升攻击、穿透、闪避、普攻速度和敏捷伤害,同时把被动冷却降至 3 秒。
- **设计抓手**:短时间内把弱点窗口转化为高频连击。
### 03|吖养
- **蚀魂震击**:对完全行动不能、行动受限、战斗不能、技能受限或攻击受限目标造成额外力量伤害;魔法伤害还能眩晕。
- **咒怨洪流**:武器熵化,普攻转魔法伤害,首攻后获得额外普攻配额,但后续目标不能重复。
- **设计抓手**:先控制、再处决;多目标时表现污染蔓延。
### 04|男甘雨
- **灵能反射**:每释放两次魔法才触发硬直,魔法命中可回能并减少技能冷却。
- **三相灵枢**:把机制扩展到普攻,提高连续消除硬直次数并回复魔法值。
- **设计抓手**:技能循环与“演算完成”节奏。
### 05|牛腩
- **双生流转**:生命低于 30% 时转为力量模式并把基础智力转为额外力量;恢复到阈值以上则回归智力模式。
- **变幻之心**:力量模式回血并获得数次吸血;智力模式强化接下来的魔法伤害。
- **设计抓手**:同一角色两套姿态、武器与特效语言。
### 06|铎京市长
- **零式崩解**:暴击伤害提高 70%。
- **零式灭杀**:短时提高暴击率、暴击伤害与物理穿透。
- **设计抓手**:没有复杂随机性,强调判断、精准和最短路径。
### 07|魔法少女
- **少女绮想**:每 7 秒提升所有伤害,受到伤害时清零,主动造成伤害也会消耗部分累积。
- **绝对领域**:提升敏捷并免受伤害,但不免疫负面效果;额外消耗能量可延长持续时间。
- **设计抓手**:蓄势期间的完美形象与受击后的碎裂反差。
### 08|清香
- **暗香疏影**:造成伤害时削减目标能量,对低能量目标额外增伤。
- **残香凋零**:以多个目标的现有能量值和自身智力计算魔法伤害。
- **设计抓手**:让力量“枯萎”,而不是直接封锁行动。
### 09|LUOLI66
- **破釜沉舟**:最大生命降低 20%,高生命阶段承受额外伤害并积累伤害加成;低生命阶段停止额外受伤并获得更高收益;致命伤害可保留 10 HP。
- **宿命时律**:提高物理减伤和魔抗,把普攻转为魔法伤害并大幅降低硬直。
- **设计抓手**:风险曲线、临界血量与“演算后押注”。
### 10|冷蓝
- **累积之压**:首次伤害标记,攻击标记目标时令其战斗不能并造成最大生命百分比伤害。
- **极寒渴望**:强化最大生命伤害并获得吸血。
- **设计抓手**:标记—追猎—回收标记的两段式节奏。
### 11|绿拱门
- **银隼之赐**:普攻命中周期性附加基于敏捷的魔法伤害。
- **身心一境**:提高敏捷;若力量低于敏捷的一定比例,则补足力量。
- **设计抓手**:枪手的稳定输出与身心数值平衡。
### 12|趣多多
- **弱者猎手**:AI 优先选择低生命目标;回合开始标记生命百分比低于自己的角色,攻击时增伤。
- **饕餮盛宴**:短时获得高额吸血。
- **设计抓手**:残血收割与越战越能维持续航。
### 13|时雨
- **开宫**:监视全局;有角色死亡时复制致死技能或获得特殊普攻,并标记击杀者。标记还能连接治疗、友方增伤与敌方混乱。
- **放监**:把已有标记强化为不可驱散,并给敌人布置必须完成的“宫监手任务”,否则结算真实伤害。
- **设计抓手**:观察、记录、复制和以规则审判。
### 14|雷欧尼
- **八卦阵**:造成或受到伤害时进行奇偶检定;偶数偏直接增伤减伤,奇数偏暴击、闪避、魔抗和延迟收益。
- **归元环**:必定暴击,八卦阵直接取得偶数效果,并以触发次数削减主动技能冷却。
- **设计抓手**:表面随机、爆发期把命运锁定为有利结果。
### 15|海王星
- **深海之戟**:普攻暴击时向附近敌人产生分裂伤害。
- **海王星的野望**:标记至多三名敌人;攻击标记目标会全图索敌分裂,并大幅提高力量。
- **设计抓手**:王权式扩张,单点命中扩散为全场压制。
### 16|CHAOS
- **雇佣兵团**:召唤最多五名雇佣兵;兵员继承部分属性,会持续损失生命,并可通过参与击杀临时增员。
- **全军出击**:补满五名雇佣兵、恢复并强化其攻击;每名存活雇佣兵反向为 CHAOS 提供攻击、速度、加速和冷却缩减。
- **设计抓手**:队伍人数既是兵力,也是首领自身的增益计量表。
### 17|流
- **不息之流**:常态和吟唱态下每秒回复最大生命并获得能量。
- **宿命之潮·熵核**:提高攻击与自身回复,承受更多伤害,并禁止敌人自然回复。
- **宿命之潮·守护**:提高自身和全队回复,并嘲讽全部敌人。
- **设计抓手**:同一套回复本质,在熵核路线用于压迫,在守护路线用于承伤与群体生存。
### 18|The God K
- **概念之骰**:参与击杀后永久取得“力、暴、噬、御”之一,每类最多八层;生命偷取超过阈值后可继续转化为攻击力。
- **神之因果**:四回合内记录对敌伤害,结束时转化为由全体敌人均摊的真实伤害;持续期间可豁免负面效果。
- **设计抓手**:战斗越长概念越多,所有伤害最终被“因果结算”。
## 五、版本差异记录
- 汐月心音:技能总表曾显示“天赐之力”,详情页为“千羽瞬华”;被动详情为“心灵之弦”。
- 吖养:技能总表旧称“魔法震荡/魔法涌流”,详情页为“蚀魂震击/咒怨洪流”。
- 男甘雨:技能总表旧称“三重叠加”,详情页为“三相灵枢”。
- 后续数值平衡应按详情页更新时间和实际代码再次核对,不能仅依赖本摘要。
+467
View File
@@ -0,0 +1,467 @@
# 《筽祀牻》角色档案 v0.6
> 本档案根据《筽祀牻》公开故事、角色与技能资料整理。
> “已确认”表示文档中已有明确依据;其余“创作设定”表示根据技能机制、剧情功能与阵营关系完成的第一版设计,后续可随美术稿继续调整。
## 一、角色档案统一字段
- 角色编号与姓名
- 外貌性别
- 年龄与体格
- 阵营/身份
- 核心属性与战斗定位
- 已确认设定
- 技能表现
- 人设设计
- 外貌与服装
- 武器与技能视觉
- 核心动机
- 内在矛盾
- 关键关系
- 视觉与语言关键词
- 可展开的剧情方向
## 二、角色总览
| 编号 | 角色 | 外貌性别 | 阵营/身份 | 核心属性 | 战斗人设关键词 |
|---:|---|---|---|---|---|
| 1 | 大島シヤ | 男性 | META🐴头目 | 力量 | 极端、牺牲、力量崇拜 |
| 2 | 汐月心音 | 女性 | 铎京委托的刺客 | 敏捷 | 冷静、精准、观察弱点 |
| 3 | 吖养 | 男性 | META🐴成员 | 力量 | 残酷、趁虚而入、污染武器 |
| 4 | 男甘雨 | 男性 | 环大陆学者团 | 智力 | 理性、计算、术式循环 |
| 5 | 牛腩 | 男性 | 环大陆学者团/流浪法师 | 智力 | 双模式、隐藏攻击性、临界反击 |
| 6 | 铎京市长 | 男性 | 铎京统治者 | 敏捷 | 战斗天才、果断、弱点击破 |
| 7 | 魔法少女 | 女性 | 铎京阵营成员 | 敏捷 | 祈祷、纯真、脆弱而无敌 |
| 8 | 清香 | 女性 | 环大陆学者团 | 智力 | 消耗、冷静、能量剥夺 |
| 9 | LUOLI66/QWQAQW | 女性 | 落璃型通用人工智能/环大陆学者团 | 智力 | 破釜沉舟、濒死爆发、赌命 |
| 10 | 冷蓝 | 男性 | 铎京阵营 | 力量 | 标记、追猎、处决 |
| 11 | 绿拱门/ddd ovo | 男性 | META🐴成员 | 敏捷 | 枪手、平衡、身心合一 |
| 12 | 趣多多 | 男性 | 铎京阵营 | 力量 | 弱者猎手、残血收割、掠食 |
| 13 | 时雨 | 女性 | 能量流相关存在 | 敏捷 | 监视、复制、审判、规则操控 |
| 14 | 雷欧尼 | 男性 | 深海同盟成员 | 智力 | 概率、八卦、命运投掷 |
| 15 | 海王星 | 男性 | 深海同盟统治者 | 力量 | 王权、扩张、全局压制 |
| 16 | CHAOS | 男性 | 深海同盟/佣兵团首领 | 力量 | 召唤、军团、混乱指挥 |
| 17 | 流 Ryuko | 男性 | 主角/META🐴实验体 | 敏捷 | 回复、选择、熵与守护 |
| 18 | K神 The God K | 男性 | 神秘存在 | 智力 | 概念、骰子、因果结算 |
## 三、外貌性别定义
本项目当前采用“外貌性别”作为角色视觉设计的基础分类。该字段用于确定立绘、三视图、角色设计稿与剧情称谓中的基本性别表现,不等同于年龄、性格、气质或性别刻板印象。
### 女性角色
- 汐月心音
- 魔法少女
- 清香
- LUOLI66/QWQAQW
- 时雨
### 男性角色
- 大島シヤ
- 吖养
- 男甘雨
- 牛腩
- 铎京市长
- 冷蓝
- 绿拱门/ddd ovo
- 趣多多
- 雷欧尼
- 海王星
- CHAOS
- 流 Ryuko
- K神 The God K
后续具体外貌设计默认遵循以上分类,除非用户另行指定。
## 四、详细角色档案
### 01|大島シヤ Oshima Shiya
- **外貌性别:** 男性。
- **年龄/身高/体重:** 29 岁/189 cm/86 kg。
- **阵营/身份:** META🐴头目,双手剑“熵灭”的持有者。
- **核心属性/定位:** 力量型近战爆发;以生命损耗换取压倒性攻击力。
- **设计概念:** “主动把自己献给力量的黑色君王”。他不是失控的莽夫,而是清醒地接受每一次自损,并将伤痕视作权力的勋章。
- **体型与面部:** 高大、肩背宽阔,肌肉线条偏实战型而非夸张健美。肤色略苍白,鼻梁挺直,眼窝较深;右眼为暗金色,左眼被熵污染侵染成黑底猩红瞳。胸口、左臂和颈侧分布熔岩般的黑红裂纹。
- **发型:** 黑色中长发,后发垂至肩胛,内层带暗红渐变;平时随意后梳,战斗过载时发梢像燃烧的灰烬般上扬。
- **服装设计:** 黑色长军装与重型剑士护甲结合。右侧保留完整肩甲,左侧为暴露污染纹路的不对称设计;长外套下摆呈撕裂状,内衬为深红。胸前佩戴抽象化“黑马”纹章,腰部使用多层束带固定熵核稳定器。
- **武器与技能视觉:** “熵灭”是一柄近乎等身的黑铁双手剑,剑身中央存在猩红裂隙,挥动时会吞没周围光线。“熵灭·极诣”发动后,裂纹从剑身蔓延至身体,攻击越强,角色立绘上的裂纹越明亮。
- **性格:** 冷静、专断、极有煽动力;很少高声愤怒,越危险时语气越平稳。他尊重真正愿意承担力量代价的人,鄙视只索取力量却逃避后果的人。
- **核心动机:** 吞噬能量节点,建立不受既有法则限制的新世界。
- **内在矛盾:** 他自称驾驭熵灭,实际上身体与思想正逐步被熵灭改写。
- **关键关系:** 把流视为最成功却最“不听话”的作品;与铎京市长构成力量统治与制度秩序的对立。
- **语言与动作习惯:** 很少使用疑问句;交谈时会把剑尖抵地,做出近似审判者的姿态。代表台词:“力量从不索取忠诚,它只索取代价。”
- **视觉关键词:** 黑红、熵裂纹、重剑、黑马纹章、不对称重甲、能量过载。
### 02|汐月心音 Xin Yin
- **外貌性别:** 女性。
- **年龄/身高/体重:** 22 岁/164 cm/46 kg。
- **阵营/身份:** 受铎京市长委托行动的知名刺客。
- **核心属性/定位:** 敏捷型单体输出/弱点刺杀。
- **已确认设定:** 使用暗器“千羽”,曾参与离岸监狱渗透行动。
- **设计概念:** “月下无声的中国风女侠”。传统侠气与现代刺客机能相结合,强调克制、轻盈和精准。
- **体型与面部:** 纤细轻盈,四肢修长,肌肉线条集中在腰腹和小腿。脸型偏柔和的鹅蛋脸,眉形利落,表情通常平静;冷灰蓝瞳在发动技能时浮现羽状光纹。
- **发型:** 乌黑长发束成高马尾,以银蓝发绳固定;额前保留两缕长碎发。发簪本身也是“千羽”暗器之一。
- **服装设计:** 月白交领内衫、深靛色轻甲与高腰分片裙裤,外搭仅及腰部的轻薄短披风。肩部与腰侧使用羽片形金属护片,袖口和裙摆不使用大面积飘带,保证潜行与快速变向。墨黑、月白、深靛为主色,朱砂红用于腰绳与暗器袋。
- **武器与技能视觉:** “千羽”是一组藏于发饰、袖口和腰带中的银色羽形细刃。普通攻击只闪过一道冷光;“千羽瞬华”会让数十枚羽刃在月轮状轨迹中连续命中目标弱点。
- **性格:** 寡言、职业化,习惯先观察再行动。她会替队友记住出口、站位和撤离路线,却不愿谈论自己的伤势与情绪。
- **核心动机:** 完成委托并保持独立,同时判断新铎京是否真正值得守护。
- **内在矛盾:** 她能够迅速看穿他人的弱点,却将自己的情感藏得过深。
- **关键关系:** 与流是行动搭档;与趣多多形成潜行与强攻的互补;与绿拱门形成暗器与枪械的镜像对决。
- **语言与动作习惯:** 说话简短,经常用“无碍”“继续”“左侧”代替完整解释。思考时会以指腹轻触暗器边缘。代表台词:“破绽只出现一瞬。足够了。”
- **视觉关键词:** 月色、银羽、云纹、高马尾、夜雨、无声移动、朱砂细节。
### 03|吖养 Ya Yang
- **外貌性别:** 男性。
- **年龄/身高/体重:** 25 岁/181 cm/73 kg。
- **阵营/身份:** META🐴核心执行成员,熵污染武器使用者。
- **核心属性/定位:** 力量型控制后处决;擅长攻击无法行动或受到限制的目标。
- **设计概念:** “被污染的年轻行刑者”。外形仍保留清俊感,但身体和武器已出现明显异变,形成危险而不稳定的反差。
- **体型与面部:** 身形修长、肌肉紧实,肤色偏冷白。嘴角习惯带着似笑非笑的弧度;右侧下颌至锁骨有紫黑色污染纹,右眼为鲜紫红色,左眼仍保持灰黑。
- **发型:** 灰白色短发,发根呈暗紫;刘海不规则地遮住右眼上缘,后颈留有一束细长发尾,以黑色金属环束起。
- **服装设计:** 破损的黑色束袖战斗长衣叠加轻型拘束装甲,轮廓带有东方驱邪师与近未来执行官的混合感。腰间悬挂数枚用于抑制污染的封锁环,胸前绑带呈交叉结构,披肩只有左侧完整保留。
- **武器与技能视觉:** 使用一柄窄刃魔法长剑“咒脊”。剑脊内嵌紫黑熵核,平时以锁环封闭;“咒怨洪流”发动时锁环依次崩断,污染像液体沿剑锋和右臂逆流。命中受控目标时会出现短暂的魂魄震离效果。
- **性格:** 嘲讽、敏锐、缺乏公平决斗观念。他认为战斗的唯一准则是“让目标失去反抗能力”,但对真正承受过实验痛苦的人偶尔流露出不自然的宽容。
- **核心动机:** 证明自己是 META🐴 最有效率、最不可替代的执行者。
- **内在矛盾:** 他越依赖熵污染,越难判断自己的欲望究竟来自本人还是组织植入的指令。
- **关键关系:** 是大島シヤ最锋利的执行端;可能与流共享早期实验记录;与清香形成污染扩张和能量衰减的克制关系。
- **语言与动作习惯:** 喜欢在敌人无法行动后俯身说话;烦躁时会转动腰间的封锁环。代表台词:“公平?那是留给还没学会活下去的人。”
- **视觉关键词:** 灰白发、紫黑污染、咒剑、封锁环、残缺披肩、危险笑意。
### 04|男甘雨 Nan Ganyu
- **外貌性别:** 男性。
- **年龄/身高/体重:** 24 岁/177 cm/65 kg。
- **阵营/身份:** 环大陆学者团术式研究员,负责能量循环与古语解析。
- **核心属性/定位:** 智力型魔法循环/资源管理。
- **设计概念:** “把魔法写成公式的年轻学者”。外观介于学院研究员和战地术士之间,所有装饰都有测量或记录功能。
- **体型与面部:** 清瘦挺拔,肩线较窄,手指修长。面容斯文,常有轻微睡眠不足形成的眼下阴影;眼睛为冷青色,施法时瞳孔浮现三层同心术式。
- **发型:** 深蓝黑色短发,梳理整齐但右侧有一缕总会翘起;佩戴无框单片术式镜,镜片可以显示魔力、硬直和能量流速。
- **服装设计:** 白灰色高领内衫、深海军蓝研究长外套和轻量护具。外套下摆分成三片,分别绣有代表物质、精神与能量的术式纹。腰间挂着笔记终端、卷轴筒和三色墨水瓶。
- **武器与技能视觉:** 武器为三枚悬浮式“灵枢演算环”,颜色分别为青、金、紫。施法时环体高速重叠,替他完成部分咏唱;“三相灵枢”发动后,三环合成一座悬浮演算仪,使技能连续衔接而几乎没有停顿。
- **性格:** 理性、克制、求知欲强;说话准确但不擅长照顾他人情绪。遇到未知现象会明显兴奋,甚至忘记危险。
- **核心动机:** 证明魔法与科技能够用统一规律解释,并找出能量流的原始方程。
- **内在矛盾:** 过度追求客观真相,容易把有意识的生命也视作可测量样本。
- **关键关系:** 与牛腩构成理论派和实践派;与清香分别研究能量的运转与衰减;会因如何对待流和时雨与同伴发生伦理冲突。
- **语言与动作习惯:** 对话中常用“假设”“误差”“重新计算”;紧张时会推不存在的眼镜镜框。代表台词:“无法解释,不代表没有规律,只代表我们的公式还不够完整。”
- **视觉关键词:** 三重术式环、蓝白光、研究长外套、单片术式镜、公式与古语。
### 05|牛腩 Niu Nan
- **外貌性别:** 男性。
- **年龄/身高/体重:** 28 岁/184 cm/79 kg。
- **阵营/身份:** 环大陆学者团成员、长期独行的流浪法师。
- **核心属性/定位:** 智力与力量双模式切换/临界反击。
- **设计概念:** “披着温和旅人外表的双生战斗者”。正常状态像可靠的旅伴,生命濒危时外貌轮廓与战斗姿态会发生明显变化。
- **体型与面部:** 高挑结实,常态姿态松弛;脸部线条温和,左眉有一道旧伤。双眼原为温暖茶色,力量模式下左眼转为炽红,犬齿与指甲略微变长。
- **发型:** 棕黑色中长发,在后脑低束;两侧各夹一束青绿色细辫。进入力量模式时发束松脱,发尾由青绿变为铜红。
- **服装设计:** 多层旅行法袍与实用皮革护具结合。外层披风正面为青绿色,内侧为暗铜红,翻转披风即可象征模式变化。胸前佩戴一枚双面护符:一面刻术式,一面刻兽纹。
- **武器与技能视觉:** 常态使用折叠长杖“流转”,杖首可展开为双环法器;力量模式下杖身分解并覆盖双臂,形成带有符文的拳甲。两种形态共享同一能量核心。
- **性格:** 平时随和、会照顾队伍生活,对陌生人也容易亲近;受到致命威胁后会变得寡言而凶狠,战斗结束后对力量模式中的记忆并不完整。
- **核心动机:** 寻找能量流真相,同时理解自己体内两种力量的来源。
- **内在矛盾:** 他一直声称自己能够控制模式转换,却逐渐发现“另一个自己”也在主动观察和保护他。
- **关键关系:** 是最早向流提供根源线索的人;与男甘雨为实践派和理论派搭档;可能把流视为与自己同样被力量分割的人。
- **语言与动作习惯:** 常态爱用玩笑缓和紧张;力量模式只说必要词句。代表台词:“别紧张,我还有另一种解法——只是那种解法不太斯文。”
- **视觉关键词:** 双面披风、旅行法袍、双面护符、青绿与铜红、法杖拳甲转换。
### 06|铎京市长 Dokyo Mayor
- **外貌性别:** 男性。
- **年龄/身高/体重:** 32 岁/186 cm/81 kg。
- **阵营/身份:** 铎京新任市长、革命后的城市最高行政与军事负责人。
- **核心属性/定位:** 敏捷型战斗领袖/弱点暴击。
- **已确认设定:** 战斗天才;旧市长罪行曝光后上台,与 META🐴 决裂。
- **设计概念:** “穿着礼服上战场的现代城邦领袖”。外形必须同时具备政治权威、军人纪律和高速剑士的锋利感。
- **体型与面部:** 身形挺拔、肩宽腰窄,动作干净克制。面部成熟端正,左眼下有一道很浅的旧伤;眼睛为金褐色,注视他人时带有强烈压迫感。
- **发型:** 黑色短发向后梳理,鬓角夹有少量银灰;即使经历战斗也很少完全散乱,表现其自律与控制欲。
- **服装设计:** 炭黑色双排扣市长礼服与白金色战术护甲融合,肩章采用铎京晶枢的几何结构。右肩披一片可拆卸的短礼披,内侧为暗红;腰部配置城市权限终端和紧急指挥投影器。
- **武器与技能视觉:** 使用高频单刃剑“零式”。剑身平时细窄如礼仪佩剑,锁定弱点后刃线展开为白金色能量锋。“零式灭杀”发动时,视野中出现多条弱点预测线,他只沿最短的一条完成斩击。
- **性格:** 果断、自律、责任感极强,习惯把个人情绪排在城市利益之后。他愿意亲临前线,却不轻易允许别人替自己承担政治后果。
- **核心动机:** 重建铎京公信力,清除旧市长与 META🐴 留下的制度性腐败。
- **内在矛盾:** 为了保护城市不断集中权力,可能逐渐成为自己曾推翻的那种统治者。
- **关键关系:** 是流的雇主和保护者;与大島シヤ代表制度秩序与力量统治;对心音既信任又保留必要的政治距离。
- **语言与动作习惯:** 讲话简洁,很少使用口号;做重大决定前会摘下右手手套。代表台词:“我可以承担失败,但铎京不能再承担一次谎言。”
- **视觉关键词:** 黑白金、战术礼服、高频剑、晶枢徽章、城市灯光、革命领袖。
### 07|魔法少女 Magical Girl
- **外貌性别:** 女性。
- **年龄/身高/体重:** 18 岁/158 cm/44 kg。
- **阵营/身份:** 铎京阵营成员、以“魔法少女”为公开代号的城市守护者。
- **核心属性/定位:** 敏捷型蓄力爆发/绝对防御。
- **设计概念:** “把理想维持成现实的祈祷者”。外观明亮梦幻,但在细节中加入轻微裂痕和疲惫感,让她并非单纯吉祥物。
- **体型与面部:** 娇小轻盈,动作带有舞台表演般的仪式感。圆润脸型和大眼使她显得亲和;虹膜为粉蓝渐变,瞳孔呈小型四芒星。笑容明亮,但独处时眼神会迅速安静下来。
- **发型:** 淡粉色及腰长发,在两侧束成较低的螺旋双马尾,发尾渐变为浅蓝;星形发扣兼具小型护盾发生器功能。
- **服装设计:** 白色短战裙、粉蓝渐变外层和金色星轨饰边;胸前不是传统蝴蝶结,而是一枚环形祈愿核心。肩部、腰侧与靴部加入透明晶体护片,兼顾魔法少女轮廓和铎京科技感。设计保持端庄,不采用暴露式装甲。
- **武器与技能视觉:** 使用“绮想棱杖”,杖首由可旋转的星环与透明晶体组成。“少女绮想”积累时,身后星环逐层增加;受击后星环像玻璃一样碎裂。“绝对领域”形成蛋壳状透明结界,表面仍会被负面状态染上裂纹与暗色。
- **性格:** 热情、认真、愿意安慰任何人;不是不知道恐惧,而是相信守护者必须先让别人看到希望。私下对“自己是否只是一个宣传符号”抱有不安。
- **核心动机:** 成为真正能够保护市民的人,而不只是铎京塑造的英雄形象。
- **内在矛盾:** 绝对领域能够挡住伤害,却挡不住恐惧、控制和失望;她越想维持完美形象,内心越容易崩裂。
- **关键关系:** 与流形成被制造的守护者和主动选择守护者的对照;尊敬铎京市长,但会质疑政治宣传对自己的利用。
- **语言与动作习惯:** 公开场合使用充满仪式感的宣言,私下说话更轻、更直接。代表台词:“害怕并不会让愿望失效。放弃才会。”
- **视觉关键词:** 粉蓝、白金、星环、玻璃裂痕、祈祷、绝对领域、城市偶像。
### 08|清香 Qing Xiang
- **外貌性别:** 女性。
- **年龄/身高/体重:** 26 岁/168 cm/52 kg。
- **阵营/身份:** 环大陆学者团能量生态与衰减研究员。
- **核心属性/定位:** 智力型能量削弱/持续压制。
- **设计概念:** “温柔地看着力量枯萎的香药学者”。外貌优雅沉静,技能却呈现令人不安的凋零感。
- **体型与面部:** 身形修长,姿态端正,动作缓慢而精确。面容柔和,肤色偏白,眼睛为灰绿色;左眼下有一颗很淡的小痣。她微笑时亲切,但观察实验对象时情绪会完全收起。
- **发型:** 墨绿色长发,盘成偏低的发髻,其余发丝垂至腰部;使用白玉枝簪固定,簪头会根据周围能量浓度开合。
- **服装设计:** 象牙白交领长衣配茶青色窄袖外袍,下摆为便于行动的分片式结构。腰间悬挂香囊、样本瓶与能量刻度管;肩背覆盖半透明暗紫薄纱,其表面像花瓣脉络一样流动。整体融合东方药师、植物学者与暗系法师。
- **武器与技能视觉:** 法杖“疏影”由深色枝木与透明能量计组成,杖首悬浮一朵不会完全开放的黑白双色花。“暗香疏影”会让敌方能量化为花粉逸散;“残香凋零”则使花瓣由边缘向中心枯萎并爆发。
- **性格:** 温和、有礼、极有耐心,擅长倾听;一旦进入研究状态,判断会变得近乎冷酷。她从不提高音量,却能用最平静的语气提出危险方案。
- **核心动机:** 理解能量的衰减规律,阻止任何势力无限抽取世界节点。
- **内在矛盾:** 她主张节制力量,却可能为了证明理论而制造一次可控的能量枯竭。
- **关键关系:** 与男甘雨分别研究运转与衰减;与吖养形成污染扩张和能量抽离的天敌关系;对时雨的牺牲机制最早产生怀疑。
- **语言与动作习惯:** 喜欢用香气和季节比喻能量状态;思考时会调整样本瓶的排列。代表台词:“盛放不是生命的全部。知道何时凋零,才是。”
- **视觉关键词:** 茶青、象牙白、暗紫、香囊、枯萎花瓣、能量刻度、玉簪。
### 09|LUOLI66/QWQAQW
- **外貌性别:** 女性。
- **外观年龄/身高/体重:** 外观约 20 岁/160 cm/47 kg;实际启用年限与完整运行记录不详。
- **出身/型号:** 出身于筽祀牻大陆东部的技术共和国“塞洛斯共和国”。由该国最高级综合科研机构“塞洛斯共和国中央高等研究院”研制,正式机体编号为“落璃型通用人工智能机器人第 66 号(LUO-LI-66)”。“LUOLI66”是其常用简称,“QWQAQW”则是她加入学者团后使用的资料库识别名之一。
- **阵营/身份:** 原属塞洛斯共和国中央高等研究院,现为环大陆学者团成员与能量流数据研究员,负责战斗模型、风险预测、能量流观测与旧实验数据复原。她脱离原机构并加入学者团的原因未知;相关时间段的公开档案、行动记录与核心记忆索引均存在缺口。
- **核心属性/定位:** 智力型受伤转化/濒死爆发。
- **设计概念:** “把自己的机体耐久也放进公式里的风险型人工智能”。她是为跨领域研究、社会协作与复杂环境决策而设计的通用人工智能,却在长期自主演算中形成了近似赌徒的风险偏好。外观看似懒散、年轻,真正战斗时会冷静地把自身完整度控制在危险边缘。
- **体型与面部:** 小巧匀称,平时姿态略显松懈;仿生面部偏圆,表情常带无所谓的淡笑。外层采用近似人类肌肤的复合材料,耳后、颈侧与关节内侧可见极细的机体接缝。双眼为异色光学阵列:左眼是青蓝数据瞳,右眼是警示红;机体完整度越低,右眼的红色占比越高。
- **发型:** 银灰色短发,长度到下颌,发尾带淡紫渐变;左侧用“66”形状的黑色发夹固定,发夹同时是型号识别与维护接口。后脑连接一枚可拆卸神经演算接口,可与浮游终端及学者团设备直接同步。
- **服装设计:** 黑白色贴身技术内装外搭宽大的灰紫短夹克,下装为不对称短裙裤和过膝机能袜。衣服边缘分布青色数据线,机体完整度过低时转为红色警戒光。颈后、腰侧与大腿护具刻有“LUO-LI/066”出厂铭文;护具保留多次自行修补的痕迹,表现她长期把机体使用到安全阈值之外。
- **机体与技能视觉:** 核心能源舱位于胸腔,由多层缓冲结构保护;战斗受损时,部分装甲缝隙会透出青红交替的能量光。她使用浮游式演算终端“时律”,由六枚小型棱片和一块主屏组成。普通攻击把演算结果转化为魔法弹道;“宿命时律”发动后,界面显示倒计时、伤害累计、机体完整度和生存概率,所有棱片围绕她组成临时护盾与炮列。
- **性格:** 嘴上懒散,喜欢用概率开玩笑,实际思维极快并具有强烈控制欲。她能够理解并模拟情绪,却拒绝回答自己的情感究竟是研究院预设、后天学习,还是自主意识的结果。她相信风险只要被量化就可以利用,因此常做出让队友无法接受的自损决策。
- **核心动机:** 以学者团成员的身份研究能量流,建立足以解释世界节点与生命能量变化的统一预测模型。同时,她持续检索自身缺失的行动记录,却从未公开自己离开塞洛斯共和国并加入学者团的真实原因。
- **内在矛盾:** 她被制造为服务人类研究的通用工具,却正在形成独立的价值判断;她最擅长计算代价,也因此总把自己的机体与意识连续性视作可以优先支付的筹码。
- **关键关系:** 与男甘雨形成理论推演和数据验证的搭档关系;与流构成“被制造的智能”与“被制造的实验体”的镜像;清香经常负责阻止她过度透支机体。学者团内部尚无人确认她的核心指令是否仍与塞洛斯共和国中央高等研究院保持联系。
- **语言与动作习惯:** 喜欢报出概率而非直接表达态度,例如“成功率 63%,够用了”;压力越大,笑容越明显。思考时,瞳孔会短暂滚动数据环,句子偶尔夹入系统式自检提示。代表台词:“别露出那种表情。只要结果还没归零,就不算绝境。”
- **视觉关键词:** 落璃型、LUO-LI-66、仿生机体、银灰短发、异色光学瞳、66 接口、浮游终端、青红警戒光、破损护具、倒计时。
### 10|冷蓝 Cold Blue
- **外貌性别:** 男性。
- **年龄/身高/体重:** 30 岁/191 cm/92 kg。
- **阵营/身份:** 铎京特别治安部队追缉官,负责高危污染目标的标记、监视与收容。
- **核心属性/定位:** 力量型标记追猎/单体处决。
- **设计概念:** “把危险锁进寒冰的城市猎犬”。他不是嗜杀者,而是将任何失控风险都视作必须迅速终止的灾害。
- **体型与面部:** 高大厚实,肩背像重型盾牌,手臂留有多处抓伤和冻伤。脸部线条硬朗,肤色偏冷;右眼为钢蓝色,左眼佩戴用于读取追踪标记的半透明战术镜。
- **发型:** 深蓝黑色短发,后颈剃短,额前有一缕冰灰色挑染。长时间使用“累积之压”后,发梢会结出细小霜晶。
- **服装设计:** 深海军蓝重型追缉外套搭配黑色防护甲,衣领高而硬,像猎犬的项圈。腰背装有两组锁链卷轴,胸前为铎京治安徽章和危险目标识别牌;左肩披有一块带编号的旧防寒布。
- **武器与技能视觉:** 使用链枪“寒铆”,由短柄重枪、伸缩锁链和腕部绞盘组成。首次命中会在目标身上留下蓝色压力印;再次命中时锁链瞬间收紧,压力印冻结并爆裂,形成“战斗不能”效果。“极寒渴望”发动后,锁链表面出现血红与冰蓝交错的脉动。
- **性格:** 沉默、纪律性强,对危险保持近乎偏执的警惕。他不轻易相信口头承诺,但一旦认定某人属于自己的保护范围,就会承担到底。
- **核心动机:** 防止铎京再次因权力者隐瞒风险而付出代价。
- **内在矛盾:** 他追求绝对安全,却可能因此把尚未犯罪的“潜在危险者”也当成敌人。
- **关键关系:** 被秘密安排监视流;与趣多多同为处决型战士,但冷蓝遵循命令与证据,趣多多更依赖本能。
- **语言与动作习惯:** 说话只陈述结论;确认安全后会逐一解除武器锁扣。代表台词:“我不判断你是什么。我只判断你失控时会伤到谁。”
- **视觉关键词:** 冰蓝、锁链、重型外套、战术镜、压力标记、城市猎犬。
### 11|绿拱门/ddd ovo
- **外貌性别:** 男性。
- **年龄/身高/体重:** 24 岁/179 cm/68 kg。
- **阵营/身份:** META🐴枪械专家与远程执行者;手枪“银隼”的持有者。
- **核心属性/定位:** 敏捷型枪手/普攻附魔与属性平衡。
- **设计概念:** “只相信完美动作的银色枪客”。他并不热衷组织信仰,而是将每场任务视作验证自身技术的实验。
- **体型与面部:** 瘦削灵活,肩臂线条精炼。五官清秀却缺少亲和力,双眼为偏灰的翡翠绿;右眼前悬浮一道拱门形瞄准界面。
- **发型:** 银灰色短发混有墨绿色内层,刘海向左侧分开;右耳佩戴羽翼形弹道校准器。
- **服装设计:** 炭黑贴身战术服外搭灰绿短风衣,衣摆裁成拱形轮廓。手套、枪套和长靴均使用银色硬质边框;内衬为低饱和象牙白,使整体不像传统黑暗刺客,而更接近冷峻决斗者。
- **武器与技能视觉:** “银隼”是单手折叠式能量手枪,枪身可展开银色翼片。普通子弹命中后会留下绿色弧形轨迹并追加魔法冲击;“身心一境”发动时,呼吸、心跳和弹道界面同步,所有动作像预先排演般流畅。
- **性格:** 克制、挑剔、个人主义,厌恶多余动作和情绪化命令。他尊重真正技术高超的对手,因此对心音有超出敌我立场的兴趣。
- **核心动机:** 证明纯粹技巧能够超越天赋、血统、科技等级乃至熵核力量。
- **内在矛盾:** 他追求绝对自洽,却依赖一个要求服从的组织提供资源和舞台。
- **关键关系:** 与心音形成枪械和暗器、远距和近距的镜像对手;与吖养代表 META🐴 内部的技术派和污染派。
- **语言与动作习惯:** 开枪前会轻敲枪柄两次;评价他人时常使用“多余”“偏差”“合格”。代表台词:“你输的不是速度,是动作里多了一次犹豫。”
- **视觉关键词:** 银色手枪、灰绿风衣、拱门瞄具、羽翼枪机、精准与克制。
### 12|趣多多 Qu Duoduo
- **外貌性别:** 男性。
- **年龄/身高/体重:** 23 岁/176 cm/75 kg。
- **阵营/身份:** 铎京突击队成员,擅长在混战中快速清除失去战斗力的目标。
- **核心属性/定位:** 力量型残血猎杀/吸血续航。
- **设计概念:** “笑着冲进最危险位置的街头猎手”。战斗方式凶狠,但核心并非虐待弱者,而是以最快速度为同伴减少敌人数量。
- **体型与面部:** 身高中等、肌肉紧凑,重心较低,像随时准备扑出的猛兽。肤色健康,鼻梁贴着常年不换的创可贴;琥珀色眼睛明亮,笑时会露出略尖的虎牙。
- **发型:** 铜红色蓬乱短发,后脑剃有两道像咬痕的纹路;发顶戴着护目镜,镜片能显示敌方生命状态。
- **服装设计:** 暗红与焦黑拼接的短战斗夹克,内部为铎京标准防护服,下装使用宽松战术裤与强化膝靴。护甲来自不同批次装备,表面布满自行修补的铆钉与涂鸦;腰间挂着能量零食和急救包。
- **武器与技能视觉:** 使用一对可拼接的钩刃“掠牙”。分离时适合追击,拼合后形成大型圆弧斩刃。“弱者猎手”触发时,护目镜会把低生命目标标记成橙红色;“饕餮盛宴”则让钩刃吸收逸散能量,沿手臂回流形成续航。
- **性格:** 直觉敏锐、外向、爱开玩笑,战斗时会显得异常兴奋。他很重视同伴,却不擅长讨论死亡和恐惧,只会用更鲁莽的保护行为回应。
- **核心动机:** 确保身边的人能够从战场活着回去。
- **内在矛盾:** 他以保护为理由不断强化收割本能,可能逐渐失去对投降者和濒危敌人的同情。
- **关键关系:** 与心音形成强攻和潜行的固定搭档;经常挑战冷蓝的过度纪律;把流的异常回复能力当成“必须阻止他乱来”的理由。
- **语言与动作习惯:** 战前吃甜食,紧张时反而笑得更大声。代表台词:“别误会,我不是喜欢打架——我只是喜欢我们这边一个都不少。”
- **视觉关键词:** 铜红乱发、虎牙、护目镜、拼接钩刃、街头涂鸦、橙红猎杀标记。
### 13|时雨 Shi Yu
- **外貌性别:** 女性。
- **年龄/身高/体重:** 外表约 19 岁/166 cm/49 kg;实际年龄与实体质量无法确定。
- **阵营/身份:** 筽祀牻之眼中沉睡的能量意识,具备净化污染和记录战斗规则的能力。
- **核心属性/定位:** 敏捷型观测控制/规则复制。
- **已确认设定:** 是唯一可能净化污染的存在,最终以消耗自身存在为代价完成净化,并留下时之泪。
- **设计概念:** “从世界记忆中诞生的水之观察者”。她看似少女,细节却不断提醒旁人这副身体只是能量流临时塑成的容器。
- **体型与面部:** 纤细、姿态轻盈,皮肤带有近似月光照在水面的半透明感。五官安静柔和,眼睛呈浅青至无色渐变,瞳孔由三层同心圆组成;情绪波动时,眼中会浮现不属于她的短暂记忆画面。
- **发型:** 银蓝色及膝长发,发梢分解成水滴与光粒;头顶两侧各悬浮一枚细小圆环,像发饰,也像监测装置。
- **服装设计:** 白色无袖内裙外覆多层冰蓝透明衣片,轮廓结合祭祀礼服、观察员制服和水母形态。衣摆边缘布满眼睛与刻度抽象化的银线纹;赤足,脚踝环绕不会落地的水环。
- **武器与技能视觉:** 不持传统武器,以六面浮游镜“监镜”记录全场。角色死亡时,其中一面镜会保存其技能残像;复制技能时,时雨以近乎完全相同的动作重演,但色彩统一转为水蓝。“放监”发动后,镜面化作巨大的环形观测宫,任务标记像判词一样悬在目标上方。
- **性格:** 平静、诚实、缺少人类社会常识,对所有生命一视同仁。她并非没有感情,而是无法判断自己的感情属于当前人格,还是来自被记录的无数记忆。
- **核心动机:** 完成净化使命,并确认自己是否有权在使命之外继续存在。
- **内在矛盾:** 她被所有人视为希望,却从未被允许选择“不牺牲”。
- **关键关系:** 与流是能量载体和净化意识的对应关系;被铎京保护、META🐴争夺、深海同盟利用;与 K 神形成规则执行者与规则观察者的对照。
- **语言与动作习惯:** 会直视说话者很久,像在确认记忆;很少使用过去时。代表台词:“我记得每一个消失的人。可我不知道,其中哪一段记忆才是我。”
- **视觉关键词:** 银蓝长发、水光、同心瞳、浮游镜、透明礼服、观测宫、时之泪。
### 14|雷欧尼 XReounIII
- **外貌性别:** 男性。
- **年龄/身高/体重:** 27 岁/182 cm/74 kg。
- **阵营/身份:** 深海同盟谋士与海王星旧部,负责预兆解读、路线规划和非常规行动。
- **核心属性/定位:** 智力型概率爆发/命运操控。
- **设计概念:** “把预言伪装成赌博的深海术士”。他表现得随性轻佻,实际上每一次玩笑都在试探他人会走向哪条未来。
- **体型与面部:** 身材修长,动作柔软而从容。肤色略带冷灰,眼尾上挑;左眼为金色,右眼为深海青,瞳孔中分别呈现奇数点与偶数环。
- **发型:** 深靛色长发束成偏侧低马尾,其中编入一束青金色细辫;额前挂有一枚可以旋转的贝壳卜片。
- **服装设计:** 墨青长袍与轻型潜海护甲叠穿,袍摆分成八片,每片对应八卦方位并绘有不同潮汐纹。腰部悬挂卜珠、骨骰和折叠式水压呼吸器;肩上披着半透明鳐鱼状短披风。
- **武器与技能视觉:** 使用浮游法器“归元盘”,由八枚可旋转卦片和中心水镜构成。“八卦阵”触发时卦片随机翻转;“归元环”发动后所有卦片转为有利面,形成深海蓝色环阵,让攻击沿预定因果必然命中。
- **性格:** 爱笑、擅长套话、看似相信运气,实际极少真正把决定交给随机。他忠于海王星,但忠诚中掺杂着对旧时代的个人执念。
- **核心动机:** 复活海王星,让深海同盟重新拥有决定自身命运的权力。
- **内在矛盾:** 他宣称尊重命运,却不断操纵投掷结果;所谓忠诚也可能只是逃避为自己做选择。
- **关键关系:** 是海王星最熟悉现代大陆的旧部;利用真相引诱流加入深海;与 CHAOS 合作频繁但互不信任。
- **语言与动作习惯:** 习惯让对方先选奇数或偶数;真正严肃时反而会收起笑容和所有卜具。代表台词:“命运当然公平——它只是从没答应让你看懂规则。”
- **视觉关键词:** 深海蓝、八卦卦片、骨骰、异色瞳、鳐鱼披风、潮汐预言。
### 15|海王星 Neptune
- **外貌性别:** 男性。
- **年龄/身高/体重:** 实际年龄超过三百年,外表约 36 岁/198 cm/108 kg。
- **阵营/身份:** 深海同盟三位统治者之一,雷欧尼的旧主。
- **核心属性/定位:** 力量型范围扩散/统治级爆发。
- **设计概念:** “从被封印的旧海中归来的帝王”。外形不只强调强壮,更要呈现古老文明对其近乎宗教性的服从。
- **体型与面部:** 极高大、体格雄健,皮肤为带冷蓝底色的深色肤质,肩颈和手臂分布微光鳞纹。面容威严成熟,双眼像深海中发光的青蓝裂隙;耳廓略呈鳍状。
- **发型:** 蓝黑色长发披至腰部,发间像浸在水中般缓慢漂动;前额佩戴由深海珊瑚、古银和能量结晶构成的半冠。
- **服装设计:** 深蓝重甲覆盖胸肩与前臂,装甲轮廓参考鲸骨和宫殿柱廊;下身叠穿墨蓝鳞甲与长袍,披风像巨大潮幕垂落。金属部分使用古旧银与青铜,而非明亮黄金,表现深海王朝的年代感。
- **武器与技能视觉:** 王戟“潮权”是一柄超过两米的三叉戟,中央戟刃包裹压缩海流。“深海之戟”暴击时,水压冲击会向周围分裂;“海王星的野望”令战场上方出现倒悬海面,所有标记者被深海光柱依次贯穿。
- **性格:** 威严、克制、具有保护臣民的责任感,也深信统治权天然属于自己。他能真诚关心深海子民,却很难把陆地文明视作平等政治主体。
- **核心动机:** 重建深海同盟,清算铎京与 META🐴 对深海领地和统治者造成的伤害。
- **内在矛盾:** 他声称恢复秩序,真正恢复的可能是一个不允许异议存在的旧帝国。
- **关键关系:** 雷欧尼是其忠诚旧部;将 CHAOS 视作必要但不可完全信任的军力;与铎京市长代表古代王权和现代城邦合法性的碰撞。
- **语言与动作习惯:** 从不直呼下属编号,记得每位旧臣的名字;发怒时周围会先安静得听不见水声。代表台词:“你们称它为废墟,因为你们从未听见废墟仍在呼吸。”
- **视觉关键词:** 王冠、鲸骨重甲、潮幕披风、三叉戟、微光鳞纹、倒悬海面。
### 16|CHAOS
- **外貌性别:** 男性。
- **年龄/身高/体重:** 34 岁/188 cm/89 kg。
- **阵营/身份:** CHAOS 雇佣兵团首领,与深海同盟保持契约合作关系。
- **核心属性/定位:** 力量型召唤军团/持续增援与战场统筹。
- **设计概念:** “把混乱训练成队形的佣兵队长”。他外表粗犷随性,真正核心能力却是迅速让不同出身的人形成可用战力。
- **体型与面部:** 强壮但不笨重,常保持向前倾的战斗姿态。肤色偏小麦,鼻梁有横向旧伤,左眼为机械义眼,可同步查看所有雇佣兵状态;笑起来带有明显挑衅感。
- **发型:** 暗红棕色短发向后抓起,两侧剪短;下颌留有修整不太整齐的短胡须。右耳挂着由旧弹壳制成的耳坠。
- **服装设计:** 砂黑色佣兵甲外搭暗红长风衣,风衣内侧缝有不同年代、不同势力的队徽布片。肩甲可展开为指挥旗标,腰带上挂满佣兵身份牌;护甲不追求统一,但每处修补都极其实用。
- **武器与技能视觉:** 使用模块化战斗步枪“乱序”和折叠指挥旗。技能召唤的雇佣兵通过身份牌投影形成短暂战斗实体;“全军出击”时所有身份牌同时亮起,五名雇佣兵从不同方向入场,并把自身增益回馈给 CHAOS。
- **性格:** 豪爽、现实、擅长谈判,习惯用玩笑掩盖对伤亡的在意。他不相信王权或理想,只相信明确的契约和愿意并肩作战的人。
- **核心动机:** 让佣兵团在任何政权更替中都能拥有生存与选择的权利。
- **内在矛盾:** 他把部下称作家人,却仍不断把他们派往高死亡率任务,并用“契约”说服自己这是平等选择。
- **关键关系:** 与海王星利益合作但拒绝臣服;与雷欧尼互相欣赏能力却提防对方算计;对流抱有把他招入佣兵团的兴趣。
- **语言与动作习惯:** 习惯用报酬金额评价任务难度,却从不收阵亡者家属的费用。代表台词:“我们不替谁的王座送死。我们只替还活着的人开路。”
- **视觉关键词:** 暗红风衣、机械义眼、身份牌、拼装护甲、指挥旗、雇佣兵投影。
### 17|流 Ryuko
- **外貌性别:** 男性。
- **年龄/身高/体重:** 21 岁/178 cm/71 kg。
- **阵营/身份:** 主角;铎京市长的贴身护卫;META🐴实验体,编号 Ryuko。
- **核心属性/定位:** 敏捷型持续回复/熵核与守护双路线核心角色。
- **已确认设定:** 拥有极致回复能力,相关记忆被封存;玩家会在铎京、深海同盟与 META🐴 的冲突中决定其路线。
- **设计概念:** “身体不断愈合,身份却始终存在伤口的人”。基础造型保持亲近和中性,使熵核与守护两种变化能够明显覆盖在同一人物之上。
- **体型与面部:** 身材匀称灵活,不像传统重甲护卫。面容年轻温和,眼下有轻微疲惫感;左眼为清澈青色,右眼平时为灰色,熵核活跃时转为暗红。锁骨下方刻有被划花的实验编号。
- **发型:** 黑色中短发,发尾带少量深青色;记忆或熵核波动时,部分发丝会短暂变为红黑。刘海略长,遮住右眼上缘。
- **服装设计:** 灰白色轻型护卫服外搭深青短风衣,肩部保留铎京护卫徽章,内层却可见 META🐴实验服残片改成的绑带。服装结构简洁,便于玩家在不同路线中替换红黑熵核组件或蓝白守护组件。
- **武器与技能视觉:** 使用折叠单刃“潮痕”。常态为轻型长刀;熵核路线下刀刃裂开黑红锯齿,攻击会阻断敌方回复;守护路线下刀背展开为弧形能量盾,水蓝回复波纹从流扩散到队友。“不息之流”使伤口先化成水纹,再恢复为完整皮肤。
- **性格:** 温和、耐受力强,习惯先照顾他人,面对自身过去则倾向逃避。他不愿杀死已经失去战斗能力的人,但熵核本能会在极端压力下追求彻底压制。
- **核心动机:** 找回记忆,并亲自决定自己是武器、容器、守护者,还是一个不属于任何标签的人。
- **内在矛盾:** 他越想保护别人,越需要动用来自 META🐴 的力量;越排斥实验体身份,越无法否认那也是自己生命的一部分。
- **关键关系:** 与大島シヤ是制造者和实验体;与时雨是载体和净化意识;受铎京市长保护并效忠于他;被雷欧尼用身世真相诱导加入深海。
- **语言与动作习惯:** 受伤后会先确认别人是否安全;谈到过去时常出现短暂断句。代表台词:“如果这份力量注定属于某个人,那个人也应该由我自己决定。”
- **视觉关键词:** 黑发青梢、实验编号、水纹愈合、折叠长刀、红黑熵核、蓝白守护。
### 18|K神 The God K
- **外貌性别:** 男性。
- **年龄/身高/体重:** 外表约 26 岁/180 cm/69 kg;真实年龄与物理质量不适用。
- **阵营/身份:** 游离于各势力之外的概念存在,可能是因果律的人格化观察者。
- **核心属性/定位:** 智力型概念叠层/延迟因果爆发。
- **设计概念:** “坐在棋盘外,却故意走进棋局的神”。他的外表优雅亲切,只有不符合物理规律的细节暴露其非人本质。
- **体型与面部:** 身材修长,比例近乎过分标准。五官俊秀,笑容自然却难以判断真假;双眼为金色,瞳孔并非圆形,而会随机显示一点至六点的骰面图案。镜中倒影偶尔会比本人慢半拍。
- **发型:** 象牙白中长发,内层为纯黑,发尾像墨水在空气中缓慢散开;左侧夹着一枚没有固定点数的金色骰子发饰。
- **服装设计:** 象牙白长礼服与黑色不对称长袍叠穿,裁剪介于魔术师、西装和祭司服之间。下摆呈棋盘格渐变,却会随观察角度改变排列;金色细线沿袖口连接成因果网络,内衬偶尔显现星空或空白页面。
- **武器与技能视觉:** 不使用常规武器,以“概念之骰”和一本无字“因果册”作战。每次参与击杀,骰子会抽取“力、暴、噬、御”等概念并写入服装金线;“神之因果”展开后,所有伤害化作金色丝线汇入因果册,结算时再同时收紧,转化为均摊真实伤害。
- **性格:** 风趣、好奇、礼貌,喜欢用游戏和故事解释严肃问题。他并非有意残忍,只是常忘记凡人无法承受“观察一个可能性”的代价。
- **核心动机:** 观察不同选择如何改变世界,并寻找一个无需被重置也值得继续存在的结果。
- **内在矛盾:** 他若能看见无数因果,就很难真正把任何一次死亡视作不可替代;进入棋局后却逐渐产生只属于这一条时间线的感情。
- **关键关系:** 与时雨是规则观察者和规则执行者;对流的路线选择抱有特别兴趣;可能知道大陆重置协议背后的真正原理。
- **语言与动作习惯:** 回答问题前会掷骰,但结果似乎从不影响他的答案。代表台词:“偶然只是因果戴上的面具。放心,我也经常被它骗到。”
- **视觉关键词:** 黑白礼服、金色骰瞳、因果丝线、无字书、棋盘下摆、延迟倒影。
## 五、角色群像的初步结构
### 铎京阵营:秩序的不同面貌
- 铎京市长:以个人力量维护政治秩序。
- 心音:以专业行动处理隐秘问题。
- 冷蓝:以标记和处决消除风险。
- 趣多多:以战场本能保护同伴。
- 魔法少女:以理想和祈祷相信守护仍有意义。
铎京并非完全统一的正义阵营,而是由政治、纪律、个人情感和理想主义共同组成。
### META🐴:力量的不同形态
- 大島シヤ:力量崇拜与自我牺牲。
- 吖养:污染与处决。
- 绿拱门:技术与个人主义。
META🐴内部可以进一步发展为“信仰派、执行派、技术派”的冲突,而不只是单一反派组织。
### 学者团:知识的代价
- 男甘雨:研究能量的运转。
- 清香:研究能量的消耗。
- 牛腩:研究能量的转化。
- LUOLI66:以人工智能演算研究能量与风险的统计关系,同时迫使学者团面对“研究工具是否也拥有研究主体资格”的问题。
学者团可以在后续剧情中面临共同问题:当研究对象拥有意识时,研究是否仍然能够保持中立?
### 深海同盟:复国、复仇与混沌
- 海王星:旧王权。
- 雷欧尼:忠诚与命运。
- CHAOS:契约与佣兵。
深海同盟内部并非完全一致:海王星追求统治,雷欧尼追求复归,CHAOS 更重视自身团体的生存。
## 六、后续创作建议
下一阶段可以按以下顺序深化:
1. 根据完整人物卡制作 18 名角色的全身立绘、三视图和表情差分。
2. 细化流、时雨、大島シヤ三人的核心关系、路线分歧与最终命题。
3. 为每名角色补写个人剧情、好感事件、角色语音和关键战斗演出。
4. 根据定稿人设统一调整技能名称、技能描述、图标和特效配色。
## 七、资料备注
- 技能列表明确说明:每名角色拥有 1 个专属被动和 1 个专属爆发技。
- 个别技能名称在总表与角色详情页存在差异,例如汐月心音的“天赐之力/千羽瞬华”、男甘雨的“三重叠加/三相灵枢”;本档案暂时优先采用角色详情页名称,并保留差异记录。
- 全部 18 名角色现已具备第一版年龄、体格、外貌、服装、武器、技能视觉、性格、动机、关系、动作习惯和代表台词,可直接作为立绘与三视图设计依据。
- 心音的 164 cm、46 kg 与中国风女侠方向来自用户明确指定;其余具体外貌数据与视觉细节属于本轮建立的创作设定,后续可按美术稿表现继续调整。
- 时雨、海王星与 K 神的年龄或质量超出普通人类定义,档案中采用“外表年龄/呈现体格”记录。
资料来源:
- [《筽祀牻》故事策划书](https://docs.milimoe.com/story/)
- [角色列表](https://docs.milimoe.com/character/)
- [技能列表](https://docs.milimoe.com/skill/)
- [地区档案中心](https://milimoe.com/regions/)
+41
View File
@@ -0,0 +1,41 @@
; Engine configuration file.
; Edit this file through the Godot editor when possible.
config_version=5
[application]
config/name="筽祀牻 / OSM"
run/main_scene="res://src/Screens/Main/Main.tscn"
config/features=PackedStringArray("4.7", "C#")
[autoload]
GameSession="*res://src/Autoload/GameSession.cs"
BattleStore="*res://src/Autoload/BattleStore.cs"
AssetCatalog="*res://src/Autoload/AssetCatalog.cs"
UiRouter="*res://src/Autoload/UiRouter.cs"
GameSettings="*res://src/Autoload/GameSettings.cs"
[display]
window/size/viewport_width=1920
window/size/viewport_height=1080
window/size/window_width_override=1280
window/size/window_height_override=720
window/stretch/mode="canvas_items"
[dotnet]
project/assembly_name="OSM.Client"
[internationalization]
locale/fallback="zh_CN"
[rendering]
renderer/rendering_method="gl_compatibility"
renderer/rendering_method.mobile="gl_compatibility"
environment/defaults/default_clear_color=Color(0.027, 0.039, 0.055, 1)
+58
View File
@@ -0,0 +1,58 @@
using System.Text.Json;
namespace OSM.Client.Autoload;
public partial class AssetCatalog : Node
{
private const string ManifestPath = "res://src/Resources/asset_catalog.json";
private readonly Dictionary<int, string> _characterPortraits = [];
private string _fallbackPortrait = string.Empty;
public override void _Ready()
{
LoadManifest();
}
public string GetCharacterPortraitPath(int characterId)
{
return _characterPortraits.GetValueOrDefault(characterId, _fallbackPortrait);
}
public Texture2D? LoadCharacterPortrait(int characterId)
{
var path = GetCharacterPortraitPath(characterId);
return string.IsNullOrWhiteSpace(path) ? null : GD.Load<Texture2D>(path);
}
private void LoadManifest()
{
if (!Godot.FileAccess.FileExists(ManifestPath))
{
GD.PushWarning($"Asset manifest not found: {ManifestPath}");
return;
}
var json = Godot.FileAccess.GetFileAsString(ManifestPath);
var manifest = JsonSerializer.Deserialize<AssetManifest>(json, new JsonSerializerOptions(JsonSerializerDefaults.Web));
if (manifest is null)
{
GD.PushWarning("Asset manifest could not be parsed.");
return;
}
_fallbackPortrait = manifest.FallbackPortrait ?? string.Empty;
foreach (var pair in manifest.CharacterPortraits)
{
if (int.TryParse(pair.Key, out var id))
{
_characterPortraits[id] = pair.Value;
}
}
}
private sealed record AssetManifest
{
public Dictionary<string, string> CharacterPortraits { get; init; } = [];
public string? FallbackPortrait { get; init; }
}
}
+1
View File
@@ -0,0 +1 @@
uid://dp1mvpr6iy7yy
+304
View File
@@ -0,0 +1,304 @@
using System.Text.Json;
using OSM.Client.Contracts;
namespace OSM.Client.Autoload;
public enum BattleSelectionMode
{
Watching,
Move,
Attack,
Skill,
WaitingServer
}
public partial class BattleStore : Node
{
private const int MaxLogLines = 4_000;
[Signal]
public delegate void SnapshotChangedEventHandler(int envelopeSequence);
[Signal]
public delegate void DecisionChangedEventHandler();
[Signal]
public delegate void SelectionModeChangedEventHandler(int mode);
[Signal]
public delegate void ProtocolErrorEventHandler(string message);
[Signal]
public delegate void GameFinishedEventHandler(string winnerName);
private GameSession _session = null!;
private bool _submissionInFlight;
public SoloGameState? Snapshot { get; private set; }
public SoloDecisionRequest? PendingDecision { get; private set; }
public IReadOnlyList<string> LogLines => _logLines;
public BattleSelectionMode SelectionMode { get; private set; } = BattleSelectionMode.Watching;
public string? GameId { get; private set; }
public bool IsStarted { get; private set; }
public bool IsWaitingForStart { get; private set; }
public long LastPongTimestamp { get; private set; }
public bool IsSubmittingDecision => _submissionInFlight;
private readonly List<string> _logLines = [];
public override void _Ready()
{
_session = GetNode<GameSession>("/root/GameSession");
_session.MessageReceived += OnMessageReceived;
_session.SessionError += OnSessionError;
}
public async Task StartGameAsync(SoloStartOptions? options = null)
{
ResetGameState();
IsWaitingForStart = true;
await _session.StartSoloGameAsync(options);
}
public Task ResumeGameAsync() => _session.ResumeSoloGameAsync();
public async Task SubmitDecisionAsync(object payload)
{
if (_submissionInFlight)
{
return;
}
var decision = PendingDecision;
if (decision is null)
{
throw new InvalidOperationException("There is no pending server decision.");
}
_submissionInFlight = true;
PendingDecision = null;
SetSelectionMode(BattleSelectionMode.WaitingServer);
EmitSignal(SignalName.DecisionChanged);
try
{
await _session.SendDecisionAsync(decision.RequestId, payload);
}
catch
{
PendingDecision = decision;
ApplyDecisionMode(decision.Kind);
EmitSignal(SignalName.DecisionChanged);
throw;
}
finally
{
_submissionInFlight = false;
}
PendingDecision = null;
}
public void SetSelectionMode(BattleSelectionMode mode)
{
if (SelectionMode == mode)
{
return;
}
SelectionMode = mode;
EmitSignal(SignalName.SelectionModeChanged, (int)mode);
}
public void Clear()
{
ResetGameState();
EmitSignal(SignalName.SnapshotChanged, 0);
EmitSignal(SignalName.DecisionChanged);
}
public override void _ExitTree()
{
if (_session is not null)
{
_session.MessageReceived -= OnMessageReceived;
_session.SessionError -= OnSessionError;
}
}
private void OnMessageReceived(string rawMessage)
{
SoloEnvelope? envelope;
try
{
envelope = JsonSerializer.Deserialize<SoloEnvelope>(rawMessage, ProtocolJson.Options);
}
catch (JsonException exception)
{
EmitSignal(SignalName.ProtocolError, $"无法解析服务器消息:{exception.Message}");
return;
}
if (envelope is null || string.IsNullOrWhiteSpace(envelope.Type))
{
return;
}
if (!envelope.Ok)
{
var error = envelope.Error is null
? "服务器拒绝了请求。"
: $"{envelope.Error.Code}: {envelope.Error.Message}";
EmitSignal(SignalName.ProtocolError, error);
return;
}
try
{
ApplyEnvelope(envelope);
}
catch (Exception exception) when (exception is JsonException or InvalidOperationException)
{
EmitSignal(SignalName.ProtocolError, $"消息 {envelope.Type} 数据无效:{exception.Message}");
}
}
private void ApplyEnvelope(SoloEnvelope envelope)
{
switch (envelope.Type)
{
case SoloMessageTypes.GamingStart:
{
var started = envelope.Data.Deserialize<SoloStartEvent>(ProtocolJson.Options);
if (started is null)
{
return;
}
GameId = started.GameId;
IsStarted = true;
IsWaitingForStart = false;
if (started.State is not null)
{
ApplySnapshot(started.State, envelope.Sequence);
}
break;
}
case SoloMessageTypes.GamingState:
{
var stateEvent = envelope.Data.Deserialize<SoloStateEvent>(ProtocolJson.Options);
if (stateEvent is null)
{
return;
}
if (!string.IsNullOrEmpty(GameId)
&& !string.Equals(GameId, stateEvent.State.GameId, StringComparison.Ordinal))
{
return;
}
GameId = stateEvent.State.GameId;
IsStarted = stateEvent.State.Running && !stateEvent.State.GameOver;
IsWaitingForStart = false;
AppendLog(stateEvent.Log);
ApplySnapshot(stateEvent.State, envelope.Sequence);
break;
}
case SoloMessageTypes.GamingRequest:
PendingDecision = envelope.Data.Deserialize<SoloDecisionRequest>(ProtocolJson.Options);
ApplyDecisionMode(PendingDecision?.Kind);
EmitSignal(SignalName.DecisionChanged);
break;
case SoloMessageTypes.GamingResolved:
{
var resolved = envelope.Data.Deserialize<SoloResolvedEvent>(ProtocolJson.Options);
if (PendingDecision?.RequestId == resolved?.RequestId)
{
PendingDecision = null;
SetSelectionMode(BattleSelectionMode.Watching);
EmitSignal(SignalName.DecisionChanged);
}
break;
}
case SoloMessageTypes.GamingOver:
{
var over = envelope.Data.Deserialize<SoloOverEvent>(ProtocolJson.Options);
if (over is null || (!string.IsNullOrEmpty(GameId) && over.GameId != GameId))
{
return;
}
IsStarted = false;
PendingDecision = null;
SetSelectionMode(BattleSelectionMode.Watching);
EmitSignal(SignalName.DecisionChanged);
EmitSignal(SignalName.GameFinished, over.WinnerName ?? string.Empty);
break;
}
case SoloMessageTypes.Pong:
if (envelope.Data.TryGetProperty("ts", out var timestamp)
&& timestamp.TryGetInt64(out var milliseconds))
{
LastPongTimestamp = milliseconds;
}
break;
case SoloMessageTypes.Notice:
if (envelope.Data.TryGetProperty("message", out var notice))
{
EmitSignal(SignalName.ProtocolError, notice.GetString() ?? string.Empty);
}
break;
}
}
private void ApplySnapshot(SoloGameState snapshot, int envelopeSequence)
{
Snapshot = snapshot;
EmitSignal(SignalName.SnapshotChanged, envelopeSequence);
}
private void ApplyDecisionMode(string? kind)
{
SetSelectionMode(kind switch
{
SoloDecisionKinds.TargetGrid => BattleSelectionMode.Move,
SoloDecisionKinds.TargetGrids => BattleSelectionMode.Skill,
SoloDecisionKinds.Targets => BattleSelectionMode.Attack,
null => BattleSelectionMode.Watching,
_ => BattleSelectionMode.Watching
});
}
private void AppendLog(IReadOnlyList<string> lines)
{
_logLines.AddRange(lines);
if (_logLines.Count > MaxLogLines)
{
_logLines.RemoveRange(0, _logLines.Count - MaxLogLines);
}
}
private void OnSessionError(string message)
{
EmitSignal(SignalName.ProtocolError, message);
}
private void ResetGameState()
{
Snapshot = null;
PendingDecision = null;
GameId = null;
IsStarted = false;
IsWaitingForStart = false;
_logLines.Clear();
_submissionInFlight = false;
SetSelectionMode(BattleSelectionMode.Watching);
}
}
+1
View File
@@ -0,0 +1 @@
uid://b5v7lpk42va6f
+205
View File
@@ -0,0 +1,205 @@
using System.Collections.Concurrent;
using System.Text.Json;
using OSM.Client.Contracts;
using OSM.Client.Networking;
namespace OSM.Client.Autoload;
public enum SessionState
{
Disconnected,
Connecting,
Connected,
Reconnecting,
Faulted
}
public partial class GameSession : Node
{
private const ulong HeartbeatIntervalMs = 15_000;
[Signal]
public delegate void StateChangedEventHandler(int state);
[Signal]
public delegate void MessageReceivedEventHandler(string message);
[Signal]
public delegate void SessionErrorEventHandler(string message);
private readonly ConcurrentQueue<string> _incomingMessages = new();
private readonly ConcurrentQueue<Exception> _incomingErrors = new();
private readonly ConcurrentQueue<SessionState> _pendingStates = new();
private IGameTransport? _transport;
private int _sequence;
private ulong _nextHeartbeatAt;
private bool _intentionalDisconnect;
public SessionState State { get; private set; } = SessionState.Disconnected;
public Uri? Endpoint { get; private set; }
public override void _Process(double delta)
{
while (_pendingStates.TryDequeue(out var state))
{
SetState(state);
}
while (_incomingMessages.TryDequeue(out var message))
{
EmitSignal(SignalName.MessageReceived, message);
}
while (_incomingErrors.TryDequeue(out var exception))
{
SetState(SessionState.Faulted);
EmitSignal(SignalName.SessionError, exception.Message);
}
if (State == SessionState.Connected && Time.GetTicksMsec() >= _nextHeartbeatAt)
{
_nextHeartbeatAt = Time.GetTicksMsec() + HeartbeatIntervalMs;
_ = SendEnvelopeSafeAsync(SoloMessageTypes.Ping, new
{
ts = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
});
}
}
public async Task<bool> ConnectAsync(
Uri endpoint,
bool useMock = false,
CancellationToken cancellationToken = default)
{
await DisconnectAsync();
Endpoint = endpoint;
_intentionalDisconnect = false;
_sequence = 0;
SetState(SessionState.Connecting);
_transport = useMock ? new MockTransport() : new WebSocketTransport();
_transport.MessageReceived += OnMessageReceived;
_transport.Faulted += OnTransportFaulted;
_transport.Closed += OnTransportClosed;
try
{
await _transport.ConnectAsync(endpoint, cancellationToken);
_nextHeartbeatAt = Time.GetTicksMsec() + HeartbeatIntervalMs;
_pendingStates.Enqueue(SessionState.Connected);
return true;
}
catch (Exception exception)
{
_incomingErrors.Enqueue(exception);
return false;
}
}
public Task StartSoloGameAsync(SoloStartOptions? options = null)
{
return SendEnvelopeAsync(SoloMessageTypes.GamingStart, options ?? new SoloStartOptions());
}
public Task SendDecisionAsync(string requestId, object payload)
{
return SendEnvelopeAsync(SoloMessageTypes.GamingAction, new { requestId, payload });
}
public Task ResumeSoloGameAsync()
{
return SendEnvelopeAsync(SoloMessageTypes.GamingResume, new
{
ts = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
});
}
public Task SetPausedAsync(bool paused)
{
return SendEnvelopeAsync(SoloMessageTypes.GamingPause, new { paused });
}
public Task EndSoloGameAsync()
{
return SendEnvelopeAsync(SoloMessageTypes.GamingEnd, new
{
ts = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
});
}
public async Task DisconnectAsync()
{
_intentionalDisconnect = true;
if (_transport is not null)
{
DetachTransport(_transport);
await _transport.DisposeAsync();
_transport = null;
}
SetState(SessionState.Disconnected);
}
public override void _ExitTree()
{
if (_transport is not null)
{
DetachTransport(_transport);
}
}
private async Task SendEnvelopeAsync<T>(string type, T data, CancellationToken cancellationToken = default)
{
if (_transport is null || !_transport.IsConnected)
{
throw new InvalidOperationException("Game session is not connected.");
}
var envelope = new SoloOutgoingEnvelope<T>(type, Interlocked.Increment(ref _sequence), data);
var message = JsonSerializer.Serialize(envelope, ProtocolJson.Options);
await _transport.SendAsync(message, cancellationToken);
}
private async Task SendEnvelopeSafeAsync<T>(string type, T data)
{
try
{
await SendEnvelopeAsync(type, data);
}
catch (Exception exception)
{
_incomingErrors.Enqueue(exception);
}
}
private void OnMessageReceived(string message) => _incomingMessages.Enqueue(message);
private void OnTransportFaulted(Exception exception) => _incomingErrors.Enqueue(exception);
private void OnTransportClosed()
{
if (!_intentionalDisconnect)
{
_pendingStates.Enqueue(SessionState.Disconnected);
}
}
private void DetachTransport(IGameTransport transport)
{
transport.MessageReceived -= OnMessageReceived;
transport.Faulted -= OnTransportFaulted;
transport.Closed -= OnTransportClosed;
}
private void SetState(SessionState state)
{
if (State == state)
{
return;
}
State = state;
EmitSignal(SignalName.StateChanged, (int)state);
}
}
+1
View File
@@ -0,0 +1 @@
uid://d2pckk0q4mpfa
+50
View File
@@ -0,0 +1,50 @@
namespace OSM.Client.Autoload;
public partial class GameSettings : Node
{
private const string SettingsPath = "user://settings.cfg";
private const string AudioSection = "audio";
private const string MasterVolumeKey = "master_volume";
private const string NetworkSection = "network";
private const string SoloServerUrlKey = "solo_server_url";
public float MasterVolume { get; private set; } = 1.0f;
public string SoloServerUrl { get; private set; } = "ws://localhost:11030/ws/solo";
public override void _Ready()
{
var config = new ConfigFile();
if (config.Load(SettingsPath) == Error.Ok)
{
MasterVolume = (float)config.GetValue(AudioSection, MasterVolumeKey, 1.0f);
SoloServerUrl = (string)config.GetValue(NetworkSection, SoloServerUrlKey, SoloServerUrl);
}
ApplyAudioSettings();
}
public void SetMasterVolume(float linearVolume)
{
MasterVolume = Mathf.Clamp(linearVolume, 0.0f, 1.0f);
ApplyAudioSettings();
var config = new ConfigFile();
config.SetValue(AudioSection, MasterVolumeKey, MasterVolume);
config.Save(SettingsPath);
}
public void SetSoloServerUrl(string url)
{
SoloServerUrl = url.Trim();
var config = new ConfigFile();
config.Load(SettingsPath);
config.SetValue(NetworkSection, SoloServerUrlKey, SoloServerUrl);
config.Save(SettingsPath);
}
private void ApplyAudioSettings()
{
var decibels = MasterVolume <= 0.0001f ? -80.0f : Mathf.LinearToDb(MasterVolume);
AudioServer.SetBusVolumeDb(0, decibels);
}
}
+1
View File
@@ -0,0 +1 @@
uid://bru2kkyc11oth
+12
View File
@@ -0,0 +1,12 @@
namespace OSM.Client.Autoload;
public partial class UiRouter : Node
{
public const string MainScene = "res://src/Screens/Main/Main.tscn";
public const string BattleScene = "res://src/Screens/Battle/BattleScreen.tscn";
public Error GoToMain() => GetTree().ChangeSceneToFile(MainScene);
public Error GoToBattle() => GetTree().ChangeSceneToFile(BattleScene);
}
+1
View File
@@ -0,0 +1 @@
uid://xogkyh8i82h1
+181
View File
@@ -0,0 +1,181 @@
using System.Text.Json.Serialization;
namespace OSM.Client.Contracts;
public sealed record SoloGridDto
{
public long Id { get; init; }
public int X { get; init; }
public int Y { get; init; }
public int Z { get; init; }
public string Color { get; init; } = string.Empty;
public IReadOnlyList<string> Characters { get; init; } = [];
}
public sealed record SoloMapDto
{
public string Name { get; init; } = string.Empty;
public int Length { get; init; }
public int Width { get; init; }
public int Height { get; init; }
public float Size { get; init; }
public IReadOnlyList<SoloGridDto> Grids { get; init; } = [];
}
public sealed record SoloSkillDto
{
public string Guid { get; init; } = string.Empty;
public long Id { get; init; }
public string Name { get; init; } = string.Empty;
public string Description { get; init; } = string.Empty;
public string SkillType { get; init; } = string.Empty;
public bool IsSuperSkill { get; init; }
public bool IsMagic { get; init; }
public bool IsActive { get; init; }
public bool Enable { get; init; }
public bool IsInEffect { get; init; }
public double CurrentCd { get; init; }
public double RealCd { get; init; }
public double RealMpCost { get; init; }
public double RealEpCost { get; init; }
public bool CanSelectEnemy { get; init; }
public bool CanSelectTeammate { get; init; }
public bool CanSelectSelf { get; init; }
public bool Usable { get; init; }
public string UnusableReason { get; init; } = string.Empty;
public int CastRange { get; init; }
public bool CastAnywhere { get; init; }
}
public sealed record SoloItemDto
{
public string Guid { get; init; } = string.Empty;
public long Id { get; init; }
public string Name { get; init; } = string.Empty;
public string Description { get; init; } = string.Empty;
public string ItemType { get; init; } = string.Empty;
public bool IsActive { get; init; }
public bool Enable { get; init; }
public bool IsInGameItem { get; init; }
public int RemainUseTimes { get; init; }
public int CastRange { get; init; }
public bool CastAnywhere { get; init; }
public bool Usable { get; init; }
public string UnusableReason { get; init; } = string.Empty;
}
public sealed record SoloCharacterDto
{
public string Guid { get; init; } = string.Empty;
public long Id { get; init; }
public string Name { get; init; } = string.Empty;
public string DisplayName { get; init; } = string.Empty;
public int Level { get; init; }
[JsonPropertyName("hp")] public double Hp { get; init; }
[JsonPropertyName("maxHP")] public double MaxHp { get; init; }
[JsonPropertyName("mp")] public double Mp { get; init; }
[JsonPropertyName("maxMP")] public double MaxMp { get; init; }
[JsonPropertyName("ep")] public double Ep { get; init; }
[JsonPropertyName("maxEP")] public double MaxEp { get; init; }
public int Mov { get; init; }
public int Atr { get; init; }
public string State { get; init; } = string.Empty;
public bool IsPlayer { get; init; }
[JsonPropertyName("isAI")] public bool IsAi { get; init; }
public bool IsEliminated { get; init; }
public long GridId { get; init; }
public string? TeamName { get; init; }
public IReadOnlyList<SoloSkillDto> Skills { get; init; } = [];
public IReadOnlyList<SoloItemDto> Items { get; init; } = [];
}
public sealed record SoloQueueEntryDto
{
public string Guid { get; init; } = string.Empty;
public string DisplayName { get; init; } = string.Empty;
public double HardnessTime { get; init; }
public int Order { get; init; }
public bool IsPlayer { get; init; }
public string? TeamName { get; init; }
}
public sealed record SoloActionQuotaDto
{
public string ActionType { get; init; } = string.Empty;
public string Label { get; init; } = string.Empty;
public int Quota { get; init; }
public int Used { get; init; }
public int Remaining { get; init; }
public int DecisionPointCost { get; init; }
public bool Available { get; init; }
}
public sealed record SoloDecisionPointsDto
{
public int Current { get; init; }
public int Max { get; init; }
public int Cost { get; init; }
public int ActionsTaken { get; init; }
public int Recovery { get; init; }
public IReadOnlyDictionary<string, int> ActionUsed { get; init; }
= new Dictionary<string, int>();
public IReadOnlyList<SoloActionQuotaDto> Quotas { get; init; } = [];
}
public sealed record SoloTeamDto
{
public string Name { get; init; } = string.Empty;
public int Score { get; init; }
public int Alive { get; init; }
public int Size { get; init; }
public bool IsPlayerTeam { get; init; }
}
public sealed record SoloGameState
{
public string GameId { get; init; } = string.Empty;
public string Mode { get; init; } = string.Empty;
public int Round { get; init; }
public double TotalTime { get; init; }
public bool Running { get; init; }
public bool GameOver { get; init; }
public SoloMapDto? Map { get; init; }
public IReadOnlyList<SoloCharacterDto> Characters { get; init; } = [];
public IReadOnlyList<SoloQueueEntryDto> Queue { get; init; } = [];
[JsonPropertyName("playerDP")] public SoloDecisionPointsDto? PlayerDp { get; init; }
public string? PlayerGuid { get; init; }
public string? CurrentActorGuid { get; init; }
[JsonPropertyName("aiEscalated")] public bool AiEscalated { get; init; }
public IReadOnlyList<SoloTeamDto> Teams { get; init; } = [];
public bool TeamMode { get; init; }
public int MaxScoreToWin { get; init; }
public bool Paused { get; init; }
}
public sealed record SoloStateEvent
{
public required SoloGameState State { get; init; }
public IReadOnlyList<string> Log { get; init; } = [];
}
public sealed record SoloStartEvent
{
public string GameId { get; init; } = string.Empty;
public string Mode { get; init; } = string.Empty;
public string? PlayerGuid { get; init; }
public SoloGameState? State { get; init; }
}
public sealed record SoloResolvedEvent
{
public string RequestId { get; init; } = string.Empty;
public string Kind { get; init; } = string.Empty;
}
public sealed record SoloOverEvent
{
public string GameId { get; init; } = string.Empty;
public int TotalRound { get; init; }
public double TotalTime { get; init; }
public string? WinnerName { get; init; }
}
+1
View File
@@ -0,0 +1 @@
uid://ctibvt7ts82nc
+165
View File
@@ -0,0 +1,165 @@
using System.Text.Json;
namespace OSM.Client.Contracts;
public static class SoloDecisionKinds
{
public const string SelectCharacter = "SelectCharacter";
public const string ActionType = "ActionType";
public const string Skill = "Skill";
public const string Item = "Item";
public const string Targets = "Targets";
public const string TargetGrid = "TargetGrid";
public const string TargetGrids = "TargetGrids";
public const string Inquiry = "Inquiry";
public const string Continue = "Continue";
}
public sealed record SoloDecisionRequest
{
public string RequestId { get; init; } = string.Empty;
public string Kind { get; init; } = string.Empty;
public JsonElement Payload { get; init; }
public int? TimeoutMs { get; init; }
public T? ReadPayload<T>()
{
return Payload.ValueKind == JsonValueKind.Object
? Payload.Deserialize<T>(ProtocolJson.Options)
: default;
}
}
public sealed record SoloCharacterOption
{
public string Guid { get; init; } = string.Empty;
public long Id { get; init; }
public string DisplayName { get; init; } = string.Empty;
public string Info { get; init; } = string.Empty;
}
public sealed record SelectCharacterPayload
{
public IReadOnlyList<SoloCharacterOption> Characters { get; init; } = [];
}
public sealed record TargetOption
{
public string Guid { get; init; } = string.Empty;
public string DisplayName { get; init; } = string.Empty;
public double Hp { get; init; }
public double MaxHp { get; init; }
public long GridId { get; init; }
}
public sealed record TargetsPayload
{
public string ActorGuid { get; init; } = string.Empty;
public string SkillName { get; init; } = string.Empty;
public int MaxTargets { get; init; } = 1;
public bool SelectAll { get; init; }
public int Range { get; init; }
public int AttackRange { get; init; }
public int MoveRange { get; init; }
public long ActorGridId { get; init; }
public IReadOnlyList<TargetOption> Targets { get; init; } = [];
}
public sealed record ActionTypePayload
{
public string ActorGuid { get; init; } = string.Empty;
public string ActorName { get; init; } = string.Empty;
public long ActorGridId { get; init; }
public int Atr { get; init; }
public int Mov { get; init; }
public SoloDecisionPointsDto? Dp { get; init; }
public IReadOnlyList<SoloSkillDto> Skills { get; init; } = [];
public IReadOnlyList<SoloItemDto> Items { get; init; } = [];
public IReadOnlyList<string> Enemys { get; init; } = [];
public IReadOnlyList<string> Teammates { get; init; } = [];
public IReadOnlyList<TargetOption> EnemyOptions { get; init; } = [];
public IReadOnlyList<TargetOption> TeammateOptions { get; init; } = [];
}
public sealed record SkillSelectionPayload
{
public IReadOnlyList<SoloSkillDto> Skills { get; init; } = [];
}
public sealed record ItemSelectionPayload
{
public IReadOnlyList<SoloItemDto> Items { get; init; } = [];
}
public sealed record GridTargetsPayload
{
public IReadOnlyList<long> GridIds { get; init; } = [];
}
public sealed record TargetGridPayload
{
public string ActorGuid { get; init; } = string.Empty;
public long CurrentGridId { get; init; }
public int MoveRange { get; init; }
public int AttackRange { get; init; }
public IReadOnlyList<long> GridIds { get; init; } = [];
}
public sealed record TargetGridsPayload
{
public string ActorGuid { get; init; } = string.Empty;
public string SkillName { get; init; } = string.Empty;
public int Range { get; init; }
public long ActorGridId { get; init; }
public IReadOnlyList<long> GridIds { get; init; } = [];
public string ShapeRangeType { get; init; } = "Diamond";
public int ShapeRadius { get; init; }
public int SectorAngle { get; init; } = 90;
public bool IncludeCharacterGrid { get; init; } = true;
}
public sealed record InquiryChoice
{
public string Key { get; init; } = string.Empty;
public string Text { get; init; } = string.Empty;
}
public sealed record InquiryPayload
{
public string ActorGuid { get; init; } = string.Empty;
public string Topic { get; init; } = string.Empty;
public string Description { get; init; } = string.Empty;
public string InquiryType { get; init; } = string.Empty;
public IReadOnlyList<InquiryChoice> Choices { get; init; } = [];
public string DefaultChoice { get; init; } = string.Empty;
public bool CanCancel { get; init; }
public double MinNumber { get; init; }
public double MaxNumber { get; init; }
public double DefaultNumber { get; init; }
}
public sealed record ContinuePayload
{
public string ActorGuid { get; init; } = string.Empty;
public string Message { get; init; } = string.Empty;
}
public sealed record SoloStartOptions
{
public int CharacterCount { get; init; } = 10;
public int Level { get; init; } = 60;
public int SkillLevel { get; init; } = 6;
public int NormalAttackLevel { get; init; } = 8;
public int MaxRound { get; init; } = 999;
public int MaxRespawnTimes { get; init; } = -1;
public bool TeamMode { get; init; } = true;
public int TeamSize { get; init; } = 5;
public int MaxScoreToWin { get; init; } = 10;
public int DecisionTimeoutSeconds { get; init; } = 60;
public bool RequireContinue { get; init; }
public int RoundDelayMs { get; init; } = 250;
public int InitialItemQuality { get; init; }
public int DropItemsIntervalSeconds { get; init; } = 40;
public bool EnableTurnDiagnostics { get; init; }
public int? Seed { get; init; }
}
+1
View File
@@ -0,0 +1 @@
uid://blfxpjmcqtvrm
+61
View File
@@ -0,0 +1,61 @@
using System.Text.Json;
using System.Text.Json.Serialization;
namespace OSM.Client.Contracts;
public static class SoloMessageTypes
{
public const string Ping = "system.ping";
public const string Pong = "system.pong";
public const string Notice = "system.notice";
public const string GamingStart = "gaming.start";
public const string GamingAction = "gaming.action";
public const string GamingEnd = "gaming.end";
public const string GamingOver = "gaming.over";
public const string GamingRound = "gaming.round";
public const string GamingQueue = "gaming.queue";
public const string GamingState = "gaming.state";
public const string GamingRequest = "gaming.request";
public const string GamingResolved = "gaming.resolved";
public const string GamingResume = "gaming.resume";
public const string GamingPause = "gaming.pause";
}
public sealed record SoloEnvelopeError(
[property: JsonPropertyName("code")] string Code,
[property: JsonPropertyName("message")] string Message);
public sealed record SoloEnvelope
{
[JsonPropertyName("t")]
public string Type { get; init; } = string.Empty;
[JsonPropertyName("i")]
public int Sequence { get; init; }
[JsonPropertyName("ok")]
public bool Ok { get; init; } = true;
[JsonPropertyName("d")]
public JsonElement Data { get; init; }
[JsonPropertyName("ts")]
public long Timestamp { get; init; }
[JsonPropertyName("error")]
public SoloEnvelopeError? Error { get; init; }
}
public sealed record SoloOutgoingEnvelope<T>(
[property: JsonPropertyName("t")] string Type,
[property: JsonPropertyName("i")] int Sequence,
[property: JsonPropertyName("d")] T Data);
public static class ProtocolJson
{
public static readonly JsonSerializerOptions Options = new(JsonSerializerDefaults.Web)
{
PropertyNameCaseInsensitive = true
};
}
+1
View File
@@ -0,0 +1 @@
uid://bp01kfvmj4m3
+111
View File
@@ -0,0 +1,111 @@
using System.Text.Json;
using OSM.Client.Contracts;
using OSM.Client.Screens.Battle;
namespace OSM.Client.Diagnostics;
public partial class PhaseCDecisionSmokeTest : Node
{
public override void _Ready()
{
try
{
VerifyActionPayload();
VerifyInquiryPayload();
VerifyShapePreview();
GD.Print("PHASE_C_DECISIONS_OK quotas=true details=true inquiry=true shapePreview=true");
GetTree().Quit(0);
}
catch (Exception exception)
{
GD.PushError($"PHASE_C_DECISIONS_FAILED {exception.Message}");
GetTree().Quit(1);
}
}
private static void VerifyActionPayload()
{
const string json = """
{
"requestId":"action-1","kind":"ActionType","timeoutMs":30000,
"payload":{
"actorGuid":"actor","actorName":"Tester","actorGridId":1,"atr":2,"mov":3,
"dp":{"current":2,"max":4,"cost":1,"actionsTaken":1,"recovery":2,
"actionUsed":{"NormalAttack":1},
"quotas":[
{"actionType":"NormalAttack","label":"普通攻击","quota":1,"used":1,"remaining":0,"decisionPointCost":1,"available":false},
{"actionType":"CastSkill","label":"战技","quota":2,"used":0,"remaining":2,"decisionPointCost":1,"available":true}
]},
"skills":[{"guid":"skill","name":"Test Skill","description":"Detail","skillType":"Skill","usable":true,
"realMPCost":10,"realEPCost":20,"currentCD":1,"realCD":3,"castRange":4}],
"items":[{"guid":"item","name":"Potion","description":"Heal","itemType":"Consumable","remainUseTimes":2,
"castRange":1,"usable":false,"unusableReason":"Cooldown"}]
}
}
""";
var request = JsonSerializer.Deserialize<SoloDecisionRequest>(json, ProtocolJson.Options)
?? throw new InvalidOperationException("ActionType request could not be deserialized.");
var payload = request.ReadPayload<ActionTypePayload>()
?? throw new InvalidOperationException("ActionType payload could not be deserialized.");
if (DecisionUiRules.IsActionAvailable(payload.Dp, "NormalAttack"))
{
throw new InvalidOperationException("Exhausted NormalAttack quota remained available.");
}
if (!DecisionUiRules.IsActionAvailable(payload.Dp, "CastSkill"))
{
throw new InvalidOperationException("Available CastSkill quota was disabled.");
}
if (!DecisionUiRules.SkillDetails(payload.Skills.Single()).Contains("MP 10", StringComparison.Ordinal)
|| !DecisionUiRules.ItemDetails(payload.Items.Single()).Contains("不可用", StringComparison.Ordinal))
{
throw new InvalidOperationException("Skill or item details omitted protocol fields.");
}
}
private static void VerifyInquiryPayload()
{
const string json = """
{"requestId":"inq-1","kind":"Inquiry","timeoutMs":12000,
"payload":{"actorGuid":"actor","topic":"Choose","description":"Pick any",
"inquiryType":"MultipleChoice","choices":[{"key":"A","text":"Alpha"},{"key":"B","text":"Beta"}],
"defaultChoice":"A","canCancel":true,"minNumber":1,"maxNumber":9,"defaultNumber":3}}
""";
var request = JsonSerializer.Deserialize<SoloDecisionRequest>(json, ProtocolJson.Options)
?? throw new InvalidOperationException("Inquiry request could not be deserialized.");
var payload = request.ReadPayload<InquiryPayload>();
if (payload is null || payload.Choices.Count != 2 || !payload.CanCancel
|| payload.InquiryType != "MultipleChoice")
{
throw new InvalidOperationException("Inquiry payload fields were not preserved.");
}
}
private static void VerifyShapePreview()
{
var map = new SoloMapDto
{
Length = 3,
Width = 3,
Grids = Enumerable.Range(0, 9)
.Select(index => new SoloGridDto
{
Id = index + 1,
X = index % 3,
Y = index / 3
})
.ToArray()
};
var payload = new TargetGridsPayload
{
ShapeRangeType = "Diamond",
ShapeRadius = 1,
IncludeCharacterGrid = true
};
var affected = DecisionUiRules.GetAffectedGridIds(payload, 5, map);
if (affected.Count != 5)
{
throw new InvalidOperationException($"Diamond preview expected 5 cells, got {affected.Count}.");
}
}
}
@@ -0,0 +1,91 @@
using OSM.Client.Autoload;
using OSM.Client.Contracts;
namespace OSM.Client.Diagnostics;
public partial class SoloConnectionSmokeTest : Node
{
private GameSession _session = null!;
private BattleStore _store = null!;
public override void _Ready()
{
_session = GetNode<GameSession>("/root/GameSession");
_store = GetNode<BattleStore>("/root/BattleStore");
_ = RunAsync();
}
private async Task RunAsync()
{
try
{
var endpoint = new Uri("ws://localhost:11030/ws/solo");
if (!await _session.ConnectAsync(endpoint))
{
throw new InvalidOperationException("WebSocket connection failed.");
}
await WaitUntilAsync(() => _session.State == SessionState.Connected, 5.0);
await _store.StartGameAsync(new SoloStartOptions
{
CharacterCount = 2,
TeamMode = false,
TeamSize = 1,
MaxRound = 1,
MaxRespawnTimes = 0,
MaxScoreToWin = 0,
DecisionTimeoutSeconds = 20,
RoundDelayMs = 0,
DropItemsIntervalSeconds = 0
});
await WaitUntilAsync(
() => _store.PendingDecision?.Kind == SoloDecisionKinds.SelectCharacter,
10.0);
var character = _store.PendingDecision!
.ReadPayload<SelectCharacterPayload>()?
.Characters
.FirstOrDefault()
?? throw new InvalidOperationException("Server returned no selectable characters.");
await _store.SubmitDecisionAsync(new { characterGuid = character.Guid });
await WaitUntilAsync(
() => _store.Snapshot is { GameId.Length: > 0, Characters.Count: > 0 },
10.0);
await WaitUntilAsync(
() => GetTree().GetNodesInGroup("battle_unit").Count == _store.Snapshot!.Characters.Count,
5.0);
GD.Print(
$"SOLO_SMOKE_OK game={_store.Snapshot!.GameId} "
+ $"round={_store.Snapshot.Round} characters={_store.Snapshot.Characters.Count} "
+ $"units={GetTree().GetNodesInGroup("battle_unit").Count}");
await _session.EndSoloGameAsync();
await _session.DisconnectAsync();
GetTree().Quit(0);
}
catch (Exception exception)
{
GD.PushError($"SOLO_SMOKE_FAILED {exception.Message}");
await _session.DisconnectAsync();
GetTree().Quit(1);
}
}
private async Task WaitUntilAsync(Func<bool> predicate, double timeoutSeconds)
{
var startedAt = Time.GetTicksMsec();
var timeoutMs = timeoutSeconds * 1_000.0;
while (!predicate())
{
if (Time.GetTicksMsec() - startedAt >= timeoutMs)
{
throw new TimeoutException($"Timed out after {timeoutSeconds:0.#} seconds.");
}
await ToSignal(GetTree().CreateTimer(0.05), SceneTreeTimer.SignalName.Timeout);
}
}
}
@@ -0,0 +1,214 @@
using OSM.Client.Autoload;
using OSM.Client.Contracts;
namespace OSM.Client.Diagnostics;
public partial class SoloVerticalSliceSmokeTest : Node
{
private GameSession _session = null!;
private BattleStore _store = null!;
private int _moves;
private bool _rejectionRecovered;
private bool _continued;
public override void _Ready()
{
_session = GetNode<GameSession>("/root/GameSession");
_store = GetNode<BattleStore>("/root/BattleStore");
_ = RunAsync();
}
private async Task RunAsync()
{
try
{
if (!await _session.ConnectAsync(new Uri("ws://localhost:11030/ws/solo")))
{
throw new InvalidOperationException("WebSocket connection failed.");
}
await WaitUntilAsync(() => _session.State == SessionState.Connected, 5.0);
await _store.StartGameAsync(new SoloStartOptions
{
CharacterCount = 2,
TeamMode = false,
TeamSize = 1,
MaxRound = 30,
MaxRespawnTimes = 0,
MaxScoreToWin = 0,
DecisionTimeoutSeconds = 30,
RequireContinue = true,
RoundDelayMs = 0,
DropItemsIntervalSeconds = 0,
Seed = 20260919
});
await WaitForDecisionAsync(SoloDecisionKinds.SelectCharacter, 10.0);
var character = _store.PendingDecision!
.ReadPayload<SelectCharacterPayload>()?
.Characters
.FirstOrDefault()
?? throw new InvalidOperationException("Server returned no selectable characters.");
await _store.SubmitDecisionAsync(new { characterGuid = character.Guid });
await WaitUntilAsync(
() => _store.Snapshot is { PlayerGuid.Length: > 0, Characters.Count: > 1, Map: not null },
10.0);
await WaitUntilAsync(
() => GetTree().GetNodesInGroup("battle_unit").Count == _store.Snapshot!.Characters.Count,
5.0);
var attacked = false;
for (var step = 0; step < 24 && (!attacked || !_continued); step++)
{
await WaitUntilAsync(() => _store.PendingDecision is not null, 45.0);
var decision = _store.PendingDecision!;
switch (decision.Kind)
{
case SoloDecisionKinds.ActionType:
await _store.SubmitDecisionAsync(new
{
actionType = attacked
? "EndTurn"
: _moves == 0
? "Move"
: HasServerAttackTarget(decision) ? "NormalAttack" : "Move"
});
break;
case SoloDecisionKinds.TargetGrid:
if (!_rejectionRecovered)
{
var rejectedRequestId = decision.RequestId;
await _store.SubmitDecisionAsync(new { gridId = long.MaxValue });
await WaitUntilAsync(
() => _store.PendingDecision is not null
&& _store.PendingDecision.RequestId != rejectedRequestId,
10.0);
_rejectionRecovered = true;
}
else
{
await SubmitBestMoveAsync(decision);
}
break;
case SoloDecisionKinds.Targets:
{
var target = decision.ReadPayload<TargetsPayload>()?.Targets.FirstOrDefault()
?? throw new InvalidOperationException("Attack request contained no legal target.");
await _store.SubmitDecisionAsync(new { targetGuids = new[] { target.Guid } });
attacked = true;
break;
}
case SoloDecisionKinds.Continue:
await _store.SubmitDecisionAsync(new { cancelled = false });
_continued = true;
break;
default:
await _store.SubmitDecisionAsync(new { cancelled = true });
break;
}
}
if (_moves == 0)
{
throw new InvalidOperationException("Vertical slice did not complete a movement.");
}
if (!attacked)
{
throw new InvalidOperationException("Vertical slice did not reach an attack target request.");
}
if (!_rejectionRecovered)
{
throw new InvalidOperationException("Vertical slice did not recover from a rejected grid.");
}
if (!_continued)
{
throw new InvalidOperationException("Vertical slice did not complete a Continue decision.");
}
GD.Print(
$"SOLO_VERTICAL_OK game={_store.Snapshot!.GameId} moves={_moves} "
+ $"attackTargetSubmitted=true rejectionRecovered=true "
+ $"continueSubmitted=true "
+ $"units={GetTree().GetNodesInGroup("battle_unit").Count}");
await _session.EndSoloGameAsync();
await _session.DisconnectAsync();
GetTree().Quit(0);
}
catch (Exception exception)
{
GD.PushError($"SOLO_VERTICAL_FAILED {exception.Message}");
await _session.DisconnectAsync();
GetTree().Quit(1);
}
}
private static bool HasServerAttackTarget(SoloDecisionRequest decision)
{
var payload = decision.ReadPayload<ActionTypePayload>();
return payload is not null
&& (payload.EnemyOptions.Count > 0 || payload.Enemys.Count > 0);
}
private async Task SubmitBestMoveAsync(SoloDecisionRequest decision)
{
var state = _store.Snapshot ?? throw new InvalidOperationException("Missing state before movement.");
var map = state.Map ?? throw new InvalidOperationException("Missing map before movement.");
var player = state.Characters.First(character => character.Guid == state.PlayerGuid);
var grids = map.Grids.ToDictionary(grid => grid.Id);
var enemies = state.Characters
.Where(character => !character.IsPlayer && !character.IsEliminated)
.Where(character => grids.ContainsKey(character.GridId))
.Select(character => grids[character.GridId])
.ToArray();
var allowed = decision.ReadPayload<TargetGridPayload>()?.GridIds ?? [];
var destination = allowed
.Where(gridId => gridId != player.GridId && grids.ContainsKey(gridId))
.Select(gridId => grids[gridId])
.OrderBy(grid => enemies.Length == 0 ? 0 : enemies.Min(enemy => Manhattan(grid, enemy)))
.FirstOrDefault();
if (destination is null)
{
await _store.SubmitDecisionAsync(new { cancelled = true });
return;
}
var originGridId = player.GridId;
await _store.SubmitDecisionAsync(new { gridId = destination.Id });
await WaitUntilAsync(
() => _store.Snapshot?.Characters
.FirstOrDefault(character => character.Guid == state.PlayerGuid)?.GridId != originGridId,
10.0);
_moves++;
}
private async Task WaitForDecisionAsync(string kind, double timeoutSeconds)
{
await WaitUntilAsync(() => _store.PendingDecision?.Kind == kind, timeoutSeconds);
}
private async Task WaitUntilAsync(Func<bool> predicate, double timeoutSeconds)
{
var startedAt = Time.GetTicksMsec();
var timeoutMs = timeoutSeconds * 1_000.0;
while (!predicate())
{
if (Time.GetTicksMsec() - startedAt >= timeoutMs)
{
throw new TimeoutException($"Timed out after {timeoutSeconds:0.#} seconds.");
}
await ToSignal(GetTree().CreateTimer(0.05), SceneTreeTimer.SignalName.Timeout);
}
}
private static int Manhattan(SoloGridDto left, SoloGridDto right)
{
return Math.Abs(left.X - right.X) + Math.Abs(left.Y - right.Y);
}
}
+2
View File
@@ -0,0 +1,2 @@
global using Godot;
+14
View File
@@ -0,0 +1,14 @@
namespace OSM.Client.Networking;
public interface IGameTransport : IAsyncDisposable
{
event Action<string>? MessageReceived;
event Action<Exception>? Faulted;
event Action? Closed;
bool IsConnected { get; }
Task ConnectAsync(Uri endpoint, CancellationToken cancellationToken = default);
Task SendAsync(string message, CancellationToken cancellationToken = default);
Task DisconnectAsync(CancellationToken cancellationToken = default);
}
+1
View File
@@ -0,0 +1 @@
uid://qkams8dk6i4d
+47
View File
@@ -0,0 +1,47 @@
namespace OSM.Client.Networking;
public sealed class MockTransport : IGameTransport
{
public event Action<string>? MessageReceived;
public event Action<Exception>? Faulted;
public event Action? Closed;
public bool IsConnected { get; private set; }
public Task ConnectAsync(Uri endpoint, CancellationToken cancellationToken = default)
{
cancellationToken.ThrowIfCancellationRequested();
IsConnected = true;
return Task.CompletedTask;
}
public Task SendAsync(string message, CancellationToken cancellationToken = default)
{
cancellationToken.ThrowIfCancellationRequested();
if (!IsConnected)
{
var exception = new InvalidOperationException("Mock transport is not connected.");
Faulted?.Invoke(exception);
throw exception;
}
MessageReceived?.Invoke(message);
return Task.CompletedTask;
}
public Task DisconnectAsync(CancellationToken cancellationToken = default)
{
var wasConnected = IsConnected;
IsConnected = false;
if (wasConnected)
{
Closed?.Invoke();
}
return Task.CompletedTask;
}
public async ValueTask DisposeAsync()
{
await DisconnectAsync();
}
}
+1
View File
@@ -0,0 +1 @@
uid://crgu7y2s1yuww
+117
View File
@@ -0,0 +1,117 @@
using System.Net.WebSockets;
using System.Text;
namespace OSM.Client.Networking;
public sealed class WebSocketTransport : IGameTransport
{
private const int MaxMessageBytes = 4 * 1024 * 1024;
private readonly ClientWebSocket _socket = new();
private readonly CancellationTokenSource _lifetime = new();
private Task? _receiveTask;
public event Action<string>? MessageReceived;
public event Action<Exception>? Faulted;
public event Action? Closed;
public bool IsConnected => _socket.State == WebSocketState.Open;
public async Task ConnectAsync(Uri endpoint, CancellationToken cancellationToken = default)
{
await _socket.ConnectAsync(endpoint, cancellationToken);
_receiveTask = ReceiveLoopAsync(_lifetime.Token);
}
public async Task SendAsync(string message, CancellationToken cancellationToken = default)
{
if (!IsConnected)
{
throw new InvalidOperationException("WebSocket is not connected.");
}
var bytes = Encoding.UTF8.GetBytes(message);
await _socket.SendAsync(bytes, WebSocketMessageType.Text, true, cancellationToken);
}
public async Task DisconnectAsync(CancellationToken cancellationToken = default)
{
_lifetime.Cancel();
if (_socket.State is WebSocketState.Open or WebSocketState.CloseReceived)
{
try
{
await _socket.CloseAsync(WebSocketCloseStatus.NormalClosure, "Client exit", cancellationToken);
}
catch (WebSocketException)
{
// The Solo endpoint may close immediately after gaming.end. Teardown is
// already complete in that case, even if no WebSocket close handshake remains.
}
}
if (_receiveTask is not null)
{
try
{
await _receiveTask;
}
catch (OperationCanceledException)
{
}
}
}
public async ValueTask DisposeAsync()
{
await DisconnectAsync();
_lifetime.Dispose();
_socket.Dispose();
}
private async Task ReceiveLoopAsync(CancellationToken cancellationToken)
{
var buffer = new byte[16 * 1024];
try
{
while (!cancellationToken.IsCancellationRequested && IsConnected)
{
using var stream = new MemoryStream();
WebSocketReceiveResult result;
do
{
result = await _socket.ReceiveAsync(buffer, cancellationToken);
if (result.MessageType == WebSocketMessageType.Close)
{
return;
}
await stream.WriteAsync(buffer.AsMemory(0, result.Count), cancellationToken);
if (stream.Length > MaxMessageBytes)
{
throw new InvalidDataException($"WebSocket message exceeded {MaxMessageBytes} bytes.");
}
}
while (!result.EndOfMessage);
if (result.MessageType == WebSocketMessageType.Text)
{
MessageReceived?.Invoke(Encoding.UTF8.GetString(stream.GetBuffer(), 0, (int)stream.Length));
}
}
}
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
{
}
catch (Exception exception)
{
Faulted?.Invoke(exception);
}
finally
{
Closed?.Invoke();
}
}
}
+1
View File
@@ -0,0 +1 @@
uid://24gdtimqyft8
+45
View File
@@ -0,0 +1,45 @@
# OSM Godot 客户端
这里是《筽祀牻》的 Godot C# 客户端源码。仓库根目录是 Godot 工程根目录,因此现有素材可通过 `res://assets/...` 直接访问。
## 当前边界
- 客户端只显示权威快照并提交玩家意图,不计算伤害、命中或行动是否合法。
- 不直接依赖 `FunGame.Core`、`OshimaGameModules` 或服务器内部对象。
- 单人、房主和专用服务器都通过 `IGameTransport` 复用同一套客户端状态流。
- 战斗场景采用 2D 二等角逻辑格,默认规格为 16 × 12、单格 128 × 64。
## 目录
```text
src/
├─ Autoload/ 全局会话、状态仓库、素材、路由与设置
├─ Contracts/ 网络信封、DTO 与玩家意图
├─ Networking/ WebSocket 与 Mock 传输
├─ Resources/ 运行时资源清单
├─ Screens/ 主场景和战斗场景
└─ World/ 二等角投影、网格显示和相机
```
## 启动
使用 Godot 4.7 .NET 打开仓库根目录的 `project.godot`。当前客户端会进入灰盒战斗场景,并默认连接:
```text
ws://localhost:11030/ws/solo
```
先启动 `FunGame.Testing-v3/WebAPI`,再在右上角点击“连接”和“开始新局”。客户端目前支持:
- `system.ping` / `system.pong` 心跳;
- `gaming.start`、`gaming.state`、`gaming.request` 和 `gaming.action`;
- 角色选择、基础行动类型、技能/物品/目标选择与逻辑格选择;
- HUD 根据服务器权威快照更新回合、队列、角色资源和决策点。
可使用以下参数运行只在开发环境触发的连接冒烟测试:
```text
Godot_v4.7-stable_mono_win64_console.exe --headless --path <项目目录> -- --solo-smoke-test
```
测试会自动连接、开局、选择首个候选角色并等待首个权威快照;成功时输出 `SOLO_SMOKE_OK`。
+24
View File
@@ -0,0 +1,24 @@
{
"characterPortraits": {
"1": "res://assets/images/2d-game-icons/characters/01-大島シヤ.png",
"2": "res://assets/images/2d-game-icons/characters/02-汐月心音.png",
"3": "res://assets/images/2d-game-icons/characters/03-吖养.png",
"4": "res://assets/images/2d-game-icons/characters/04-男甘雨.png",
"5": "res://assets/images/2d-game-icons/characters/05-牛腩.png",
"6": "res://assets/images/2d-game-icons/characters/06-铎京市长.png",
"7": "res://assets/images/2d-game-icons/characters/07-魔法少女.png",
"8": "res://assets/images/2d-game-icons/characters/08-清香.png",
"9": "res://assets/images/2d-game-icons/characters/09-LUOLI66.png",
"10": "res://assets/images/2d-game-icons/characters/10-冷蓝.png",
"11": "res://assets/images/2d-game-icons/characters/11-绿拱门.png",
"12": "res://assets/images/2d-game-icons/characters/12-趣多多.png",
"13": "res://assets/images/2d-game-icons/characters/13-时雨.png",
"14": "res://assets/images/2d-game-icons/characters/14-雷欧尼.png",
"15": "res://assets/images/2d-game-icons/characters/15-海王星.png",
"16": "res://assets/images/2d-game-icons/characters/16-CHAOS.png",
"17": "res://assets/images/2d-game-icons/characters/17-流.png",
"18": "res://assets/images/2d-game-icons/characters/18-K神.png"
},
"fallbackPortrait": ""
}
+978
View File
@@ -0,0 +1,978 @@
using OSM.Client.Autoload;
using OSM.Client.Contracts;
using OSM.Client.Units;
using OSM.Client.World;
namespace OSM.Client.Screens.Battle;
public partial class BattleScreen : Node
{
private GameSession _session = null!;
private BattleStore _store = null!;
private GameSettings _settings = null!;
private GridOverlay2D _gridOverlay = null!;
private GreyboxMap2D _greyboxMap = null!;
private Node2D _unitsLayer = null!;
private PackedScene _unitViewScene = null!;
private readonly Dictionary<string, UnitView> _unitViews = [];
private LineEdit _endpointEdit = null!;
private Label _connectionLabel = null!;
private Button _connectButton = null!;
private Button _startButton = null!;
private Label _roundLabel = null!;
private Label _objectiveLabel = null!;
private Label _characterName = null!;
private Label _hpLabel = null!;
private Label _mpLabel = null!;
private Label _dpLabel = null!;
private Label _contextLabel = null!;
private Label _timeoutLabel = null!;
private Label _queueActor1 = null!;
private Label _queueActor2 = null!;
private Button _moveButton = null!;
private Button _attackButton = null!;
private Button _skillButton = null!;
private Button _superSkillButton = null!;
private Button _itemButton = null!;
private Button _endTurnButton = null!;
private Button _confirmGridButton = null!;
private Button _contextCancelButton = null!;
private Control _decisionDialog = null!;
private Label _decisionTitle = null!;
private Label _decisionInfo = null!;
private OptionButton _decisionOptions = null!;
private ItemList _decisionChoiceList = null!;
private LineEdit _decisionTextInput = null!;
private SpinBox _decisionNumberInput = null!;
private Button _decisionConfirm = null!;
private Button _decisionCancel = null!;
private readonly List<string> _dialogValues = [];
private readonly List<bool> _dialogAvailable = [];
private readonly List<string> _dialogDetails = [];
private string? _dialogDecisionKind;
private string _skillIntent = "normal";
private ulong _decisionReceivedAtMs;
private long? _selectedGridId;
private readonly HashSet<string> _selectedTargetGuids = new(StringComparer.Ordinal);
public override void _Ready()
{
_session = GetNode<GameSession>("/root/GameSession");
_store = GetNode<BattleStore>("/root/BattleStore");
_settings = GetNode<GameSettings>("/root/GameSettings");
_gridOverlay = GetNode<GridOverlay2D>("BattleWorld/GridOverlay2D");
_greyboxMap = GetNode<GreyboxMap2D>("BattleWorld/GroundLayer/GreyboxPreview");
_unitsLayer = GetNode<Node2D>("BattleWorld/UnitsLayer");
_unitViewScene = GD.Load<PackedScene>("res://src/Units/UnitView.tscn");
const string layout = "HudLayer/SafeArea/Layout/";
_endpointEdit = GetNode<LineEdit>(layout + "ConnectionPanel/ConnectionContent/EndpointEdit");
_connectionLabel = GetNode<Label>(layout + "ConnectionPanel/ConnectionContent/ConnectionStatus");
_connectButton = GetNode<Button>(layout + "ConnectionPanel/ConnectionContent/ConnectionButtons/ConnectButton");
_startButton = GetNode<Button>(layout + "ConnectionPanel/ConnectionContent/ConnectionButtons/StartButton");
_roundLabel = GetNode<Label>(layout + "TopLeftMissionPanel/MissionInfo/Round");
_objectiveLabel = GetNode<Label>(layout + "TopLeftMissionPanel/MissionInfo/Objective");
_queueActor1 = GetNode<Label>(layout + "TopTurnQueue/QueueRow/Actor1");
_queueActor2 = GetNode<Label>(layout + "TopTurnQueue/QueueRow/Actor2");
_characterName = GetNode<Label>(layout + "BottomLeftCharacterPanel/CharacterInfo/Name");
_hpLabel = GetNode<Label>(layout + "BottomLeftCharacterPanel/CharacterInfo/Hp");
_mpLabel = GetNode<Label>(layout + "BottomLeftCharacterPanel/CharacterInfo/Mp");
_dpLabel = GetNode<Label>(layout + "BottomLeftCharacterPanel/CharacterInfo/Dp");
_contextLabel = GetNode<Label>(layout + "BottomContextBar/ContextRow/ContextLabel");
_timeoutLabel = GetNode<Label>(layout + "BottomContextBar/ContextRow/TimeoutLabel");
_moveButton = GetNode<Button>(layout + "BottomRightActionDock/ActionGrid/MoveButton");
_attackButton = GetNode<Button>(layout + "BottomRightActionDock/ActionGrid/AttackButton");
_skillButton = GetNode<Button>(layout + "BottomRightActionDock/ActionGrid/SkillButton");
_superSkillButton = GetNode<Button>(layout + "BottomRightActionDock/ActionGrid/SuperSkillButton");
_itemButton = GetNode<Button>(layout + "BottomRightActionDock/ActionGrid/ItemButton");
_endTurnButton = GetNode<Button>(layout + "BottomRightActionDock/ActionGrid/EndTurnButton");
_confirmGridButton = GetNode<Button>(layout + "BottomContextBar/ContextRow/ConfirmButton");
_contextCancelButton = GetNode<Button>(layout + "BottomContextBar/ContextRow/CancelButton");
_decisionDialog = GetNode<Control>("OverlayLayer/DecisionDialog");
_decisionTitle = GetNode<Label>("OverlayLayer/DecisionDialog/DialogPanel/DialogContent/Title");
_decisionInfo = GetNode<Label>("OverlayLayer/DecisionDialog/DialogPanel/DialogContent/Info");
_decisionOptions = GetNode<OptionButton>("OverlayLayer/DecisionDialog/DialogPanel/DialogContent/Options");
_decisionChoiceList = GetNode<ItemList>("OverlayLayer/DecisionDialog/DialogPanel/DialogContent/ChoiceList");
_decisionTextInput = GetNode<LineEdit>("OverlayLayer/DecisionDialog/DialogPanel/DialogContent/TextInput");
_decisionNumberInput = GetNode<SpinBox>("OverlayLayer/DecisionDialog/DialogPanel/DialogContent/NumberInput");
_decisionConfirm = GetNode<Button>("OverlayLayer/DecisionDialog/DialogPanel/DialogContent/DialogButtons/ConfirmButton");
_decisionCancel = GetNode<Button>("OverlayLayer/DecisionDialog/DialogPanel/DialogContent/DialogButtons/CancelButton");
_endpointEdit.Text = _settings.SoloServerUrl;
_connectButton.Pressed += OnConnectPressed;
_startButton.Pressed += OnStartPressed;
_moveButton.Pressed += () => SubmitActionType("Move");
_attackButton.Pressed += () => SubmitActionType("NormalAttack");
_skillButton.Pressed += () => SubmitSkillAction("normal");
_superSkillButton.Pressed += () => SubmitSkillAction("super");
_itemButton.Pressed += () => SubmitActionType("UseItem");
GetNode<Button>(layout + "BottomRightActionDock/ActionGrid/HideGridButton").Pressed += HideGrid;
_endTurnButton.Pressed += OnEndTurnPressed;
_confirmGridButton.Pressed += OnConfirmGridPressed;
_contextCancelButton.Pressed += OnContextCancelPressed;
_decisionConfirm.Pressed += OnDialogConfirmPressed;
_decisionCancel.Pressed += OnDialogCancelPressed;
_decisionOptions.ItemSelected += OnDialogOptionSelected;
_decisionChoiceList.MultiSelected += OnInquiryChoiceToggled;
_decisionTextInput.TextChanged += _ => _decisionConfirm.Disabled = false;
_decisionNumberInput.ValueChanged += _ => _decisionConfirm.Disabled = false;
_gridOverlay.HoveredCellChanged += OnHoveredCellChanged;
_gridOverlay.CellClicked += OnGridCellClicked;
_session.StateChanged += OnSessionStateChanged;
_session.SessionError += ShowError;
_store.SnapshotChanged += OnSnapshotChanged;
_store.DecisionChanged += OnDecisionChanged;
_store.ProtocolError += ShowError;
_store.GameFinished += OnGameFinished;
UpdateConnectionUi();
UpdateActionButtons();
HideGrid();
}
public override void _Process(double delta)
{
var decision = _store?.PendingDecision;
if (decision?.TimeoutMs is not int timeoutMs || timeoutMs <= 0)
{
_timeoutLabel.Text = string.Empty;
return;
}
var elapsed = Time.GetTicksMsec() - _decisionReceivedAtMs;
var remainingSeconds = Math.Max(0, (timeoutMs - (long)elapsed + 999) / 1000);
_timeoutLabel.Text = $"{remainingSeconds}s";
}
public override void _ExitTree()
{
if (_session is not null)
{
_session.StateChanged -= OnSessionStateChanged;
_session.SessionError -= ShowError;
}
if (_store is not null)
{
_store.SnapshotChanged -= OnSnapshotChanged;
_store.DecisionChanged -= OnDecisionChanged;
_store.ProtocolError -= ShowError;
_store.GameFinished -= OnGameFinished;
}
}
private async void OnConnectPressed()
{
if (_session.State == SessionState.Connected)
{
await _session.DisconnectAsync();
UpdateConnectionUi();
return;
}
if (!Uri.TryCreate(_endpointEdit.Text.Trim(), UriKind.Absolute, out var endpoint)
|| endpoint.Scheme is not ("ws" or "wss"))
{
ShowError("请输入有效的 ws:// 或 wss:// 地址。");
return;
}
_settings.SetSoloServerUrl(endpoint.ToString());
_connectButton.Disabled = true;
_connectionLabel.Text = "● 正在连接……";
var connected = await _session.ConnectAsync(endpoint);
_connectButton.Disabled = false;
if (!connected)
{
ShowError("无法连接 Solo WebAPI,请确认服务已在 11030 端口启动。");
}
UpdateConnectionUi();
}
private async void OnStartPressed()
{
if (_session.State != SessionState.Connected)
{
ShowError("请先连接 /ws/solo。");
return;
}
try
{
_startButton.Disabled = true;
_contextLabel.Text = "已发送 gaming.start,等待角色选择请求……";
await _store.StartGameAsync(new SoloStartOptions());
}
catch (Exception exception)
{
ShowError(exception.Message);
_startButton.Disabled = false;
}
}
private async void SubmitActionType(string actionType)
{
if (_store.PendingDecision?.Kind != SoloDecisionKinds.ActionType)
{
return;
}
try
{
await _store.SubmitDecisionAsync(new { actionType });
UpdateActionButtons();
_contextLabel.Text = $"已提交 {actionType},等待服务器裁定……";
}
catch (Exception exception)
{
ShowError(exception.Message);
}
}
private void SubmitSkillAction(string intent)
{
_skillIntent = intent;
SubmitActionType("PreCastSkill");
}
private async void OnEndTurnPressed()
{
try
{
if (_store.PendingDecision?.Kind == SoloDecisionKinds.Continue)
{
await _store.SubmitDecisionAsync(new { cancelled = false });
}
else
{
await _store.SubmitDecisionAsync(new { actionType = "EndTurn" });
}
UpdateActionButtons();
}
catch (Exception exception)
{
ShowError(exception.Message);
}
}
private void OnSnapshotChanged(int envelopeSequence)
{
var state = _store.Snapshot;
if (state is null)
{
return;
}
_roundLabel.Text = $"Round {state.Round} · {state.TotalTime:0.0}s";
_objectiveLabel.Text = state.TeamMode
? $"团队比分:{string.Join(" / ", state.Teams.Select(team => $"{team.Name} {team.Score}"))}"
: $"模式:{state.Mode}";
if (state.Map is not null)
{
var mapSize = new Vector2I(state.Map.Length, state.Map.Width);
_greyboxMap.SetMapSize(mapSize);
_gridOverlay.SetMapSize(mapSize);
_gridOverlay.SetGridCoordinates(state.Map.Grids.Select(grid =>
new KeyValuePair<long, Vector2I>(grid.Id, new Vector2I(grid.X, grid.Y))));
}
ReconcileUnits(state);
var player = state.Characters.FirstOrDefault(character => character.Guid == state.PlayerGuid);
if (player is not null)
{
_characterName.Text = $"{player.DisplayName} Lv.{player.Level}"
+ (state.AiEscalated ? " · AI 托管" : string.Empty);
_hpLabel.Text = $"HP {player.Hp:0} / {player.MaxHp:0}";
_mpLabel.Text = $"MP {player.Mp:0} / {player.MaxMp:0} EP {player.Ep:0} / {player.MaxEp:0}";
}
_dpLabel.Text = state.PlayerDp is null
? "决策点 —"
: $"决策点 {state.PlayerDp.Current} / {state.PlayerDp.Max} · 已行动 {state.PlayerDp.ActionsTaken}";
_queueActor1.Text = state.Queue.ElementAtOrDefault(0)?.DisplayName ?? "—";
_queueActor2.Text = state.Queue.ElementAtOrDefault(1)?.DisplayName ?? "—";
_startButton.Disabled = state.Running;
UpdateActionButtons();
}
private void OnDecisionChanged()
{
_selectedGridId = null;
_selectedTargetGuids.Clear();
_decisionReceivedAtMs = Time.GetTicksMsec();
_confirmGridButton.Disabled = true;
_decisionDialog.Visible = false;
_gridOverlay.ClearInteraction();
UpdateActionButtons();
var decision = _store.PendingDecision;
if (decision is null)
{
ReconcileUnits(_store.Snapshot);
return;
}
_contextLabel.Text = $"服务器请求:{decision.Kind}";
switch (decision.Kind)
{
case SoloDecisionKinds.ActionType:
{
var payload = decision.ReadPayload<ActionTypePayload>();
_contextLabel.Text = payload is null
? "选择本回合行动。"
: $"{payload.ActorName} · 移动 {payload.Mov} · 攻击距离 {payload.Atr}";
break;
}
case SoloDecisionKinds.SelectCharacter:
{
var payload = decision.ReadPayload<SelectCharacterPayload>();
ShowDecisionDialog(
"选择角色",
"选择后将以该角色进入本局。",
payload?.Characters.Select(option => (
option.DisplayName,
option.Guid,
true,
string.IsNullOrWhiteSpace(option.Info) ? "选择该角色进入战斗。" : option.Info)) ?? [],
canCancel: false);
break;
}
case SoloDecisionKinds.Skill:
{
var payload = decision.ReadPayload<SkillSelectionPayload>();
var skills = payload?.Skills
.Where(skill => _skillIntent == "super" ? skill.IsSuperSkill : !skill.IsSuperSkill)
?? [];
ShowDecisionDialog(
_skillIntent == "super" ? "选择爆发技" : "选择战技 / 魔法",
"可以查看全部详情;冷却或资源不足的技能不能确认。",
skills.Select(skill => (
$"{(skill.IsMagic ? "魔法" : skill.IsSuperSkill ? "爆发" : "战技")} · {skill.Name}{(skill.Usable ? string.Empty : "(不可用)")}",
skill.Guid,
skill.Usable,
DecisionUiRules.SkillDetails(skill))),
canCancel: true);
break;
}
case SoloDecisionKinds.Item:
{
var payload = decision.ReadPayload<ItemSelectionPayload>();
ShowDecisionDialog(
"选择物品",
"可以查看全部详情;不可用物品不能确认。",
payload?.Items.Select(item => (
$"{item.Name}{(item.Usable ? string.Empty : "(不可用)")}",
item.Guid,
item.Usable,
DecisionUiRules.ItemDetails(item))) ?? [],
canCancel: true);
break;
}
case SoloDecisionKinds.Targets:
{
var payload = decision.ReadPayload<TargetsPayload>();
if (payload?.SelectAll == true)
{
_selectedTargetGuids.UnionWith(payload.Targets.Select(target => target.Guid));
_confirmGridButton.Disabled = _selectedTargetGuids.Count == 0;
}
_contextLabel.Text = string.IsNullOrEmpty(payload?.SkillName)
? TargetSelectionHint(payload)
: $"{payload.SkillName} · {TargetSelectionHint(payload)}";
break;
}
case SoloDecisionKinds.TargetGrid:
_gridOverlay.SetReachableCells(
decision.ReadPayload<TargetGridPayload>()?.GridIds ?? []);
_contextLabel.Text = "选择服务器允许的移动格,然后确认。";
break;
case SoloDecisionKinds.TargetGrids:
{
var payload = decision.ReadPayload<TargetGridsPayload>();
_gridOverlay.SetAttackCells(payload?.GridIds ?? []);
_contextLabel.Text = payload is null
? "选择技能中心格,然后确认。"
: $"{payload.SkillName} · 选择中心格({ShapeLabel(payload.ShapeRangeType)},半径 {payload.ShapeRadius})。";
break;
}
case SoloDecisionKinds.Inquiry:
ShowInquiryDialog(decision.ReadPayload<InquiryPayload>());
break;
case SoloDecisionKinds.Continue:
{
var payload = decision.ReadPayload<ContinuePayload>();
ShowDecisionDialog(
"准备继续",
string.IsNullOrWhiteSpace(payload?.Message) ? "服务器等待玩家继续。" : payload.Message,
[("继续", "continue", true, "确认后继续服务器流程。")],
canCancel: false);
break;
}
}
ReconcileUnits(_store.Snapshot);
}
private void ShowDecisionDialog(
string title,
string info,
IEnumerable<(string Label, string Value, bool Available, string Details)> options,
bool canCancel)
{
_dialogDecisionKind = _store.PendingDecision?.Kind;
_decisionTitle.Text = title;
_decisionInfo.Text = info;
_decisionOptions.Clear();
_dialogValues.Clear();
_dialogAvailable.Clear();
_dialogDetails.Clear();
ResetDecisionInputs();
foreach (var option in options)
{
_decisionOptions.AddItem(option.Label);
_dialogValues.Add(option.Value);
_dialogAvailable.Add(option.Available);
_dialogDetails.Add(option.Details);
}
if (_dialogValues.Count == 0)
{
_decisionOptions.AddItem("没有可用选项");
_decisionOptions.Disabled = true;
}
else
{
_decisionOptions.Disabled = false;
_decisionOptions.Select(0);
ApplyDialogOption(0);
}
_decisionCancel.Disabled = !canCancel;
_decisionConfirm.Text = _dialogDecisionKind == SoloDecisionKinds.Continue ? "继续" : "确认";
_decisionConfirm.Disabled = _dialogValues.Count == 0
|| (_dialogAvailable.Count > 0 && !_dialogAvailable[0]);
_decisionDialog.Visible = true;
}
private void ResetDecisionInputs()
{
_decisionOptions.Visible = true;
_decisionOptions.Disabled = false;
_decisionChoiceList.Visible = false;
_decisionChoiceList.Clear();
_decisionTextInput.Visible = false;
_decisionTextInput.Text = string.Empty;
_decisionNumberInput.Visible = false;
}
private void OnDialogOptionSelected(long index)
{
ApplyDialogOption((int)index);
}
private void ApplyDialogOption(int index)
{
if (index < 0 || index >= _dialogValues.Count)
{
_decisionConfirm.Disabled = true;
return;
}
_decisionConfirm.Disabled = !_dialogAvailable[index];
if (!string.IsNullOrWhiteSpace(_dialogDetails[index]))
{
_decisionInfo.Text = _dialogDetails[index];
}
}
private void ShowInquiryDialog(InquiryPayload? payload)
{
if (payload is null)
{
ShowError("服务器下发的 Inquiry 负载无效。");
return;
}
_dialogDecisionKind = SoloDecisionKinds.Inquiry;
_decisionTitle.Text = string.IsNullOrWhiteSpace(payload.Topic) ? "询问" : payload.Topic;
_decisionInfo.Text = payload.Description;
_dialogValues.Clear();
_dialogAvailable.Clear();
_dialogDetails.Clear();
ResetDecisionInputs();
_decisionOptions.Visible = false;
_decisionCancel.Disabled = !payload.CanCancel;
_decisionConfirm.Text = "确认";
switch (payload.InquiryType)
{
case "NumberInput":
_decisionNumberInput.MinValue = payload.MinNumber;
_decisionNumberInput.MaxValue = payload.MaxNumber;
_decisionNumberInput.Value = Math.Clamp(
payload.DefaultNumber,
payload.MinNumber,
payload.MaxNumber);
_decisionNumberInput.Visible = true;
_decisionConfirm.Disabled = false;
break;
case "TextInput":
_decisionTextInput.Visible = true;
_decisionConfirm.Disabled = false;
break;
default:
_decisionChoiceList.Visible = true;
foreach (var choice in payload.Choices)
{
_decisionChoiceList.AddItem($"{choice.Key} · {choice.Text}");
_dialogValues.Add(choice.Key);
_dialogAvailable.Add(true);
_dialogDetails.Add(choice.Text);
}
if (!string.IsNullOrWhiteSpace(payload.DefaultChoice))
{
var defaultIndex = _dialogValues.IndexOf(payload.DefaultChoice);
if (defaultIndex >= 0)
{
_decisionChoiceList.Select(defaultIndex, false);
}
}
_decisionConfirm.Disabled = _decisionChoiceList.GetSelectedItems().Length == 0;
break;
}
_decisionDialog.Visible = true;
}
private void OnInquiryChoiceToggled(long index, bool selected)
{
_decisionConfirm.Disabled = _decisionChoiceList.GetSelectedItems().Length == 0;
if (selected && index >= 0 && index < _dialogDetails.Count
&& !string.IsNullOrWhiteSpace(_dialogDetails[(int)index]))
{
_decisionInfo.Text = _dialogDetails[(int)index];
}
}
private async void OnDialogConfirmPressed()
{
if (_store.PendingDecision is null)
{
return;
}
object payload;
if (_dialogDecisionKind == SoloDecisionKinds.Inquiry)
{
var inquiry = _store.PendingDecision.ReadPayload<InquiryPayload>();
payload = inquiry?.InquiryType switch
{
"NumberInput" => new { number = _decisionNumberInput.Value },
"TextInput" => new { text = _decisionTextInput.Text },
_ => new
{
choices = _decisionChoiceList.GetSelectedItems()
.Select(index => _dialogValues[(int)index])
.ToArray()
}
};
}
else if (_dialogDecisionKind == SoloDecisionKinds.Continue)
{
payload = new { cancelled = false };
}
else
{
if (_dialogValues.Count == 0 || _decisionOptions.Selected < 0)
{
return;
}
var value = _dialogValues[_decisionOptions.Selected];
payload = _dialogDecisionKind switch
{
SoloDecisionKinds.SelectCharacter => new { characterGuid = value },
SoloDecisionKinds.Skill => new { skillGuid = value },
SoloDecisionKinds.Item => new { itemGuid = value },
_ => new { cancelled = true }
};
}
try
{
_decisionDialog.Visible = false;
await _store.SubmitDecisionAsync(payload);
}
catch (Exception exception)
{
ShowError(exception.Message);
}
}
private async void OnDialogCancelPressed()
{
if (_store.PendingDecision is null)
{
return;
}
try
{
_decisionDialog.Visible = false;
var payload = _dialogDecisionKind == SoloDecisionKinds.Inquiry
? (object)new { cancel = true }
: new { cancelled = true };
await _store.SubmitDecisionAsync(payload);
}
catch (Exception exception)
{
ShowError(exception.Message);
}
}
private void OnGridCellClicked(Vector2I cell)
{
var decision = _store.PendingDecision;
var map = _store.Snapshot?.Map;
if (decision is null || map is null
|| decision.Kind is not (SoloDecisionKinds.TargetGrid or SoloDecisionKinds.TargetGrids))
{
return;
}
var grid = map.Grids.FirstOrDefault(candidate => candidate.X == cell.X && candidate.Y == cell.Y);
var allowed = decision.Kind == SoloDecisionKinds.TargetGrid
? decision.ReadPayload<TargetGridPayload>()?.GridIds ?? []
: decision.ReadPayload<TargetGridsPayload>()?.GridIds ?? [];
if (grid is null || !allowed.Contains(grid.Id))
{
_contextLabel.Text = $"逻辑格 ({cell.X}, {cell.Y}) 不在服务器允许范围内。";
return;
}
_selectedGridId = grid.Id;
_selectedTargetGuids.Clear();
_gridOverlay.SetSelectedCell(grid.Id);
if (decision.Kind == SoloDecisionKinds.TargetGrids)
{
var payload = decision.ReadPayload<TargetGridsPayload>();
if (payload is not null)
{
_gridOverlay.SetAffectedCells(
DecisionUiRules.GetAffectedGridIds(payload, grid.Id, map));
}
}
_confirmGridButton.Disabled = false;
_contextLabel.Text = $"已选择逻辑格 ({cell.X}, {cell.Y}) / ID {grid.Id}";
}
private async void OnConfirmGridPressed()
{
if (_store.PendingDecision is null)
{
return;
}
object payload;
if (_store.PendingDecision.Kind == SoloDecisionKinds.Targets
&& _selectedTargetGuids.Count > 0)
{
payload = new { targetGuids = _selectedTargetGuids.ToArray() };
}
else if (_selectedGridId is not null)
{
payload = _store.PendingDecision.Kind == SoloDecisionKinds.TargetGrid
? new { gridId = _selectedGridId.Value }
: new { gridIds = new[] { _selectedGridId.Value } };
}
else
{
return;
}
try
{
await _store.SubmitDecisionAsync(payload);
_selectedGridId = null;
_selectedTargetGuids.Clear();
_confirmGridButton.Disabled = true;
_gridOverlay.ClearInteraction();
ReconcileUnits(_store.Snapshot);
}
catch (Exception exception)
{
ShowError(exception.Message);
}
}
private async void OnContextCancelPressed()
{
var kind = _store.PendingDecision?.Kind;
if (kind is not (SoloDecisionKinds.Targets
or SoloDecisionKinds.TargetGrid
or SoloDecisionKinds.TargetGrids))
{
return;
}
try
{
_confirmGridButton.Disabled = true;
_contextCancelButton.Disabled = true;
await _store.SubmitDecisionAsync(new { cancelled = true });
_selectedGridId = null;
_selectedTargetGuids.Clear();
_gridOverlay.ClearInteraction();
ReconcileUnits(_store.Snapshot);
}
catch (Exception exception)
{
ShowError(exception.Message);
}
finally
{
_contextCancelButton.Disabled = false;
}
}
private void UpdateActionButtons()
{
var kind = _store.PendingDecision?.Kind;
var choosingAction = kind == SoloDecisionKinds.ActionType;
var dp = _store.PendingDecision?.ReadPayload<ActionTypePayload>()?.Dp
?? _store.Snapshot?.PlayerDp;
_moveButton.Disabled = !choosingAction;
_attackButton.Disabled = !choosingAction
|| !DecisionUiRules.IsActionAvailable(dp, "NormalAttack");
_skillButton.Disabled = !choosingAction
|| !DecisionUiRules.IsActionAvailable(dp, "CastSkill", "PreCastSkill");
_superSkillButton.Disabled = !choosingAction
|| !DecisionUiRules.IsActionAvailable(dp, "CastSuperSkill");
_itemButton.Disabled = !choosingAction
|| !DecisionUiRules.IsActionAvailable(dp, "UseItem");
_attackButton.Text = DecisionUiRules.QuotaLabel("普通攻击", dp, "NormalAttack");
_skillButton.Text = DecisionUiRules.QuotaLabel("战技 / 魔法", dp, "CastSkill", "PreCastSkill");
_superSkillButton.Text = DecisionUiRules.QuotaLabel("爆发技", dp, "CastSuperSkill");
_itemButton.Text = DecisionUiRules.QuotaLabel("物品", dp, "UseItem");
_endTurnButton.Disabled = kind is not (SoloDecisionKinds.ActionType or SoloDecisionKinds.Continue);
_endTurnButton.Text = kind == SoloDecisionKinds.Continue ? "继续" : "结束行动";
_contextCancelButton.Disabled = kind is not (SoloDecisionKinds.Targets
or SoloDecisionKinds.TargetGrid
or SoloDecisionKinds.TargetGrids);
}
private void OnSessionStateChanged(int state)
{
UpdateConnectionUi();
}
private void UpdateConnectionUi()
{
_connectionLabel.Text = _session.State switch
{
SessionState.Connected => "● 已连接 /ws/solo",
SessionState.Connecting => "● 正在连接……",
SessionState.Reconnecting => "● 正在重连……",
SessionState.Faulted => "● 连接错误",
_ => "● 未连接"
};
_connectButton.Text = _session.State == SessionState.Connected ? "断开" : "连接";
_startButton.Disabled = _session.State != SessionState.Connected || _store.IsStarted;
_endpointEdit.Editable = _session.State != SessionState.Connected;
}
private void HideGrid()
{
_gridOverlay.ClearInteraction();
if (_store.PendingDecision is null)
{
_contextLabel.Text = "观察模式 · 等待服务器决策";
}
}
private void OnHoveredCellChanged(Vector2I cell)
{
if (cell.X >= 0 && _store.PendingDecision is null)
{
_contextLabel.Text = $"逻辑格 ({cell.X}, {cell.Y})";
}
}
private void ShowError(string message)
{
_contextLabel.Text = message;
GD.PushWarning(message);
UpdateConnectionUi();
}
private void OnGameFinished(string winnerName)
{
_contextLabel.Text = string.IsNullOrEmpty(winnerName)
? "对局结束。"
: $"对局结束,胜者:{winnerName}";
_startButton.Disabled = _session.State != SessionState.Connected;
}
private void ReconcileUnits(SoloGameState? state)
{
if (state?.Map is null)
{
return;
}
var activeGuids = state.Characters
.Select(character => character.Guid)
.ToHashSet(StringComparer.Ordinal);
var staleGuids = _unitViews.Keys
.Where(guid => !activeGuids.Contains(guid))
.ToArray();
foreach (var guid in staleGuids)
{
var stale = _unitViews[guid];
stale.Clicked -= OnUnitClicked;
stale.QueueFree();
_unitViews.Remove(guid);
}
var gridsById = state.Map.Grids.ToDictionary(grid => grid.Id);
var player = state.Characters.FirstOrDefault(character => character.Guid == state.PlayerGuid);
var selectableTargets = _store.PendingDecision?.Kind == SoloDecisionKinds.Targets
? (_store.PendingDecision.ReadPayload<TargetsPayload>()?.Targets
.Select(target => target.Guid)
.ToHashSet(StringComparer.Ordinal) ?? [])
: [];
foreach (var character in state.Characters)
{
if (!_unitViews.TryGetValue(character.Guid, out var unit))
{
unit = _unitViewScene.Instantiate<UnitView>();
unit.Name = $"Unit_{character.Guid.Replace("-", string.Empty)}";
_unitsLayer.AddChild(unit);
unit.Clicked += OnUnitClicked;
_unitViews[character.Guid] = unit;
}
var hasGrid = gridsById.TryGetValue(character.GridId, out var grid);
grid ??= state.Map.Grids.FirstOrDefault(candidate =>
candidate.Characters.Contains(character.Guid, StringComparer.Ordinal));
hasGrid = grid is not null;
if (!hasGrid)
{
unit.Visible = character.IsEliminated && unit.Visible;
continue;
}
unit.Visible = true;
var worldPosition = GridProjector.GridToScreen(
new Vector2I(grid!.X, grid.Y),
_gridOverlay.CellSize.X,
_gridOverlay.CellSize.Y,
grid.Z);
var isFriendly = character.IsPlayer
|| (!string.IsNullOrEmpty(player?.TeamName)
&& string.Equals(character.TeamName, player.TeamName, StringComparison.Ordinal));
unit.ApplySnapshot(
character,
isFriendly,
character.Guid == state.CurrentActorGuid,
selectableTargets.Contains(character.Guid),
worldPosition);
unit.SetSelected(_selectedTargetGuids.Contains(character.Guid));
}
}
private void OnUnitClicked(string characterGuid)
{
if (_store.PendingDecision?.Kind != SoloDecisionKinds.Targets)
{
return;
}
var payload = _store.PendingDecision.ReadPayload<TargetsPayload>();
var allowedTargets = payload?.Targets
.Select(target => target.Guid)
.ToHashSet(StringComparer.Ordinal) ?? [];
if (!allowedTargets.Contains(characterGuid))
{
return;
}
if (_selectedTargetGuids.Contains(characterGuid))
{
_selectedTargetGuids.Remove(characterGuid);
}
else
{
var maxTargets = Math.Max(1, payload?.MaxTargets ?? 1);
if (maxTargets == 1)
{
_selectedTargetGuids.Clear();
}
else if (_selectedTargetGuids.Count >= maxTargets)
{
_contextLabel.Text = $"最多选择 {maxTargets} 个目标。";
return;
}
_selectedTargetGuids.Add(characterGuid);
}
_selectedGridId = null;
_confirmGridButton.Disabled = _selectedTargetGuids.Count == 0;
foreach (var pair in _unitViews)
{
pair.Value.SetSelected(_selectedTargetGuids.Contains(pair.Key));
}
var target = _store.Snapshot?.Characters.FirstOrDefault(character => character.Guid == characterGuid);
var max = Math.Max(1, payload?.MaxTargets ?? 1);
_contextLabel.Text = target is null
? $"已选择 {_selectedTargetGuids.Count}/{max} 个目标。"
: $"{target.DisplayName} · 已选择 {_selectedTargetGuids.Count}/{max},确认后提交服务器。";
}
private static string TargetSelectionHint(TargetsPayload? payload)
{
if (payload is null)
{
return "点击合法目标。";
}
return payload.SelectAll
? $"全体目标已默认选中({payload.Targets.Count} 个),确认后提交。"
: $"点击合法单位选择目标,最多 {Math.Max(1, payload.MaxTargets)} 个。";
}
private static string ShapeLabel(string shape)
{
return shape.ToLowerInvariant() switch
{
"circle" => "圆形",
"square" => "方形",
"line" => "线段",
"linepass" => "贯穿直线",
"sector" => "扇形",
_ => "菱形"
};
}
}
+1
View File
@@ -0,0 +1 @@
uid://bga0784famvyp
+403
View File
@@ -0,0 +1,403 @@
[gd_scene load_steps=5 format=3]
[ext_resource type="Script" path="res://src/Screens/Battle/BattleScreen.cs" id="1_screen"]
[ext_resource type="Script" path="res://src/World/GreyboxMap2D.cs" id="2_map"]
[ext_resource type="Script" path="res://src/World/GridOverlay2D.cs" id="3_grid"]
[ext_resource type="Script" path="res://src/World/BattleCameraController.cs" id="4_camera"]
[node name="BattleScreen" type="Node"]
script = ExtResource("1_screen")
[node name="BattleWorld" type="Node2D" parent="."]
y_sort_enabled = true
[node name="GroundLayer" type="TileMapLayer" parent="BattleWorld"]
[node name="GreyboxPreview" type="Node2D" parent="BattleWorld/GroundLayer"]
script = ExtResource("2_map")
[node name="GroundDecalLayer" type="TileMapLayer" parent="BattleWorld"]
[node name="GridOverlay2D" type="Node2D" parent="BattleWorld"]
z_index = 10
script = ExtResource("3_grid")
[node name="LowCoverLayer" type="TileMapLayer" parent="BattleWorld"]
[node name="UnitsLayer" type="Node2D" parent="BattleWorld"]
y_sort_enabled = true
[node name="EffectsLayer" type="Node2D" parent="BattleWorld"]
[node name="TallPropsLayer" type="Node2D" parent="BattleWorld"]
[node name="ForegroundOccluders" type="Node2D" parent="BattleWorld"]
[node name="BattleCamera" type="Camera2D" parent="."]
position = Vector2(128, 360)
zoom = Vector2(0.82, 0.82)
position_smoothing_enabled = true
position_smoothing_speed = 8.0
script = ExtResource("4_camera")
[node name="WorldInfoLayer" type="CanvasLayer" parent="."]
layer = 5
[node name="UnitBars" type="Control" parent="WorldInfoLayer"]
layout_mode = 3
anchors_preset = 15
anchor_right = 1.0
anchor_bottom = 1.0
grow_horizontal = 2
grow_vertical = 2
mouse_filter = 2
[node name="CoverHints" type="Control" parent="WorldInfoLayer"]
layout_mode = 3
anchors_preset = 15
anchor_right = 1.0
anchor_bottom = 1.0
grow_horizontal = 2
grow_vertical = 2
mouse_filter = 2
[node name="TargetHints" type="Control" parent="WorldInfoLayer"]
layout_mode = 3
anchors_preset = 15
anchor_right = 1.0
anchor_bottom = 1.0
grow_horizontal = 2
grow_vertical = 2
mouse_filter = 2
[node name="HudLayer" type="CanvasLayer" parent="."]
layer = 10
[node name="SafeArea" type="MarginContainer" parent="HudLayer"]
anchors_preset = 15
anchor_right = 1.0
anchor_bottom = 1.0
grow_horizontal = 2
grow_vertical = 2
theme_override_constants/margin_left = 20
theme_override_constants/margin_top = 20
theme_override_constants/margin_right = 20
theme_override_constants/margin_bottom = 20
[node name="Layout" type="Control" parent="HudLayer/SafeArea"]
layout_mode = 2
[node name="TopLeftMissionPanel" type="PanelContainer" parent="HudLayer/SafeArea/Layout"]
layout_mode = 1
anchors_preset = 0
anchor_left = 0.01
anchor_top = 0.01
anchor_right = 0.27
anchor_bottom = 0.17
grow_horizontal = 2
grow_vertical = 2
[node name="MissionInfo" type="VBoxContainer" parent="HudLayer/SafeArea/Layout/TopLeftMissionPanel"]
layout_mode = 2
theme_override_constants/separation = 8
[node name="Title" type="Label" parent="HudLayer/SafeArea/Layout/TopLeftMissionPanel/MissionInfo"]
layout_mode = 2
text = "灰盒战斗竖切"
theme_override_font_sizes/font_size = 24
[node name="Round" type="Label" parent="HudLayer/SafeArea/Layout/TopLeftMissionPanel/MissionInfo"]
layout_mode = 2
text = "Round 1 · 等待权威快照"
[node name="Objective" type="Label" parent="HudLayer/SafeArea/Layout/TopLeftMissionPanel/MissionInfo"]
layout_mode = 2
text = "目标:验证 16 × 12 二等角逻辑格"
[node name="TopTurnQueue" type="PanelContainer" parent="HudLayer/SafeArea/Layout"]
layout_mode = 1
anchor_left = 0.32
anchor_top = 0.01
anchor_right = 0.68
anchor_bottom = 0.09
grow_horizontal = 2
grow_vertical = 2
[node name="QueueRow" type="HBoxContainer" parent="HudLayer/SafeArea/Layout/TopTurnQueue"]
layout_mode = 2
alignment = 1
theme_override_constants/separation = 24
[node name="QueueTitle" type="Label" parent="HudLayer/SafeArea/Layout/TopTurnQueue/QueueRow"]
layout_mode = 2
text = "行动顺序"
[node name="Actor1" type="Label" parent="HudLayer/SafeArea/Layout/TopTurnQueue/QueueRow"]
layout_mode = 2
text = "01 心音"
[node name="Arrow1" type="Label" parent="HudLayer/SafeArea/Layout/TopTurnQueue/QueueRow"]
layout_mode = 2
text = "→"
[node name="Actor2" type="Label" parent="HudLayer/SafeArea/Layout/TopTurnQueue/QueueRow"]
layout_mode = 2
text = "02 敌方"
[node name="ConnectionPanel" type="PanelContainer" parent="HudLayer/SafeArea/Layout"]
layout_mode = 1
anchor_left = 0.70
anchor_top = 0.01
anchor_right = 0.99
anchor_bottom = 0.18
grow_horizontal = 2
grow_vertical = 2
[node name="ConnectionContent" type="VBoxContainer" parent="HudLayer/SafeArea/Layout/ConnectionPanel"]
layout_mode = 2
theme_override_constants/separation = 6
[node name="EndpointEdit" type="LineEdit" parent="HudLayer/SafeArea/Layout/ConnectionPanel/ConnectionContent"]
layout_mode = 2
text = "ws://localhost:11030/ws/solo"
placeholder_text = "Solo WebSocket 地址"
[node name="ConnectionStatus" type="Label" parent="HudLayer/SafeArea/Layout/ConnectionPanel/ConnectionContent"]
layout_mode = 2
text = "● 未连接"
horizontal_alignment = 1
[node name="ConnectionButtons" type="HBoxContainer" parent="HudLayer/SafeArea/Layout/ConnectionPanel/ConnectionContent"]
layout_mode = 2
alignment = 1
theme_override_constants/separation = 10
[node name="ConnectButton" type="Button" parent="HudLayer/SafeArea/Layout/ConnectionPanel/ConnectionContent/ConnectionButtons"]
custom_minimum_size = Vector2(120, 42)
layout_mode = 2
text = "连接"
[node name="StartButton" type="Button" parent="HudLayer/SafeArea/Layout/ConnectionPanel/ConnectionContent/ConnectionButtons"]
custom_minimum_size = Vector2(120, 42)
layout_mode = 2
disabled = true
text = "开始新局"
[node name="BottomLeftCharacterPanel" type="PanelContainer" parent="HudLayer/SafeArea/Layout"]
layout_mode = 1
anchor_left = 0.01
anchor_top = 0.76
anchor_right = 0.30
anchor_bottom = 0.99
grow_horizontal = 2
grow_vertical = 2
[node name="CharacterInfo" type="VBoxContainer" parent="HudLayer/SafeArea/Layout/BottomLeftCharacterPanel"]
layout_mode = 2
theme_override_constants/separation = 7
[node name="Name" type="Label" parent="HudLayer/SafeArea/Layout/BottomLeftCharacterPanel/CharacterInfo"]
layout_mode = 2
text = "汐月心音 Lv. 1"
theme_override_font_sizes/font_size = 24
[node name="Hp" type="Label" parent="HudLayer/SafeArea/Layout/BottomLeftCharacterPanel/CharacterInfo"]
layout_mode = 2
text = "HP 100 / 100"
[node name="Mp" type="Label" parent="HudLayer/SafeArea/Layout/BottomLeftCharacterPanel/CharacterInfo"]
layout_mode = 2
text = "MP 80 / 80 EP 0 / 200"
[node name="Dp" type="Label" parent="HudLayer/SafeArea/Layout/BottomLeftCharacterPanel/CharacterInfo"]
layout_mode = 2
text = "决策点 ◆ ◆"
[node name="Hint" type="Label" parent="HudLayer/SafeArea/Layout/BottomLeftCharacterPanel/CharacterInfo"]
layout_mode = 2
text = "UI 数据将由 BattleStore 权威快照驱动"
autowrap_mode = 2
[node name="BottomRightActionDock" type="PanelContainer" parent="HudLayer/SafeArea/Layout"]
layout_mode = 1
anchor_left = 0.69
anchor_top = 0.76
anchor_right = 0.99
anchor_bottom = 0.99
grow_horizontal = 2
grow_vertical = 2
[node name="ActionGrid" type="GridContainer" parent="HudLayer/SafeArea/Layout/BottomRightActionDock"]
layout_mode = 2
columns = 2
theme_override_constants/h_separation = 10
theme_override_constants/v_separation = 10
[node name="MoveButton" type="Button" parent="HudLayer/SafeArea/Layout/BottomRightActionDock/ActionGrid"]
custom_minimum_size = Vector2(150, 62)
layout_mode = 2
disabled = true
text = "移动"
focus_neighbor_right = NodePath("../AttackButton")
[node name="AttackButton" type="Button" parent="HudLayer/SafeArea/Layout/BottomRightActionDock/ActionGrid"]
custom_minimum_size = Vector2(150, 62)
layout_mode = 2
disabled = true
text = "普通攻击"
focus_neighbor_left = NodePath("../MoveButton")
[node name="SkillButton" type="Button" parent="HudLayer/SafeArea/Layout/BottomRightActionDock/ActionGrid"]
custom_minimum_size = Vector2(150, 62)
layout_mode = 2
disabled = true
text = "战技 / 魔法"
[node name="SuperSkillButton" type="Button" parent="HudLayer/SafeArea/Layout/BottomRightActionDock/ActionGrid"]
custom_minimum_size = Vector2(150, 62)
layout_mode = 2
disabled = true
text = "爆发技"
[node name="ItemButton" type="Button" parent="HudLayer/SafeArea/Layout/BottomRightActionDock/ActionGrid"]
custom_minimum_size = Vector2(150, 62)
layout_mode = 2
disabled = true
text = "物品"
[node name="HideGridButton" type="Button" parent="HudLayer/SafeArea/Layout/BottomRightActionDock/ActionGrid"]
custom_minimum_size = Vector2(150, 62)
layout_mode = 2
text = "隐藏网格"
[node name="EndTurnButton" type="Button" parent="HudLayer/SafeArea/Layout/BottomRightActionDock/ActionGrid"]
custom_minimum_size = Vector2(150, 62)
layout_mode = 2
disabled = true
text = "结束行动"
tooltip_text = "接入服务器请求后启用"
[node name="BottomContextBar" type="PanelContainer" parent="HudLayer/SafeArea/Layout"]
layout_mode = 1
anchor_left = 0.32
anchor_top = 0.89
anchor_right = 0.68
anchor_bottom = 0.99
grow_horizontal = 2
grow_vertical = 2
[node name="ContextRow" type="HBoxContainer" parent="HudLayer/SafeArea/Layout/BottomContextBar"]
layout_mode = 2
alignment = 1
theme_override_constants/separation = 18
[node name="ContextLabel" type="Label" parent="HudLayer/SafeArea/Layout/BottomContextBar/ContextRow"]
layout_mode = 2
size_flags_horizontal = 3
text = "移动预览 · 选择目标格后确认"
[node name="TimeoutLabel" type="Label" parent="HudLayer/SafeArea/Layout/BottomContextBar/ContextRow"]
custom_minimum_size = Vector2(72, 0)
layout_mode = 2
text = ""
horizontal_alignment = 2
[node name="CancelButton" type="Button" parent="HudLayer/SafeArea/Layout/BottomContextBar/ContextRow"]
layout_mode = 2
text = "取消"
[node name="ConfirmButton" type="Button" parent="HudLayer/SafeArea/Layout/BottomContextBar/ContextRow"]
layout_mode = 2
disabled = true
text = "确认"
[node name="OverlayLayer" type="CanvasLayer" parent="."]
layer = 20
[node name="DecisionDialog" type="CenterContainer" parent="OverlayLayer"]
visible = false
anchors_preset = 15
anchor_right = 1.0
anchor_bottom = 1.0
grow_horizontal = 2
grow_vertical = 2
mouse_filter = 1
[node name="DialogPanel" type="PanelContainer" parent="OverlayLayer/DecisionDialog"]
custom_minimum_size = Vector2(680, 320)
layout_mode = 2
[node name="DialogContent" type="VBoxContainer" parent="OverlayLayer/DecisionDialog/DialogPanel"]
layout_mode = 2
theme_override_constants/separation = 16
[node name="Title" type="Label" parent="OverlayLayer/DecisionDialog/DialogPanel/DialogContent"]
layout_mode = 2
text = "服务器决策"
horizontal_alignment = 1
theme_override_font_sizes/font_size = 28
[node name="Info" type="Label" parent="OverlayLayer/DecisionDialog/DialogPanel/DialogContent"]
layout_mode = 2
text = "请选择一个选项。"
horizontal_alignment = 1
autowrap_mode = 2
[node name="Options" type="OptionButton" parent="OverlayLayer/DecisionDialog/DialogPanel/DialogContent"]
custom_minimum_size = Vector2(0, 56)
layout_mode = 2
[node name="ChoiceList" type="ItemList" parent="OverlayLayer/DecisionDialog/DialogPanel/DialogContent"]
visible = false
custom_minimum_size = Vector2(0, 130)
layout_mode = 2
select_mode = 1
[node name="TextInput" type="LineEdit" parent="OverlayLayer/DecisionDialog/DialogPanel/DialogContent"]
visible = false
custom_minimum_size = Vector2(0, 48)
layout_mode = 2
placeholder_text = "输入答复"
[node name="NumberInput" type="SpinBox" parent="OverlayLayer/DecisionDialog/DialogPanel/DialogContent"]
visible = false
custom_minimum_size = Vector2(0, 48)
layout_mode = 2
allow_greater = false
allow_lesser = false
[node name="DialogButtons" type="HBoxContainer" parent="OverlayLayer/DecisionDialog/DialogPanel/DialogContent"]
layout_mode = 2
alignment = 1
theme_override_constants/separation = 18
[node name="CancelButton" type="Button" parent="OverlayLayer/DecisionDialog/DialogPanel/DialogContent/DialogButtons"]
custom_minimum_size = Vector2(140, 48)
layout_mode = 2
text = "取消"
[node name="ConfirmButton" type="Button" parent="OverlayLayer/DecisionDialog/DialogPanel/DialogContent/DialogButtons"]
custom_minimum_size = Vector2(140, 48)
layout_mode = 2
text = "确认"
[node name="CharacterDetailDrawer" type="Control" parent="OverlayLayer"]
visible = false
[node name="TeamRosterDrawer" type="Control" parent="OverlayLayer"]
visible = false
[node name="BattleLogDrawer" type="Control" parent="OverlayLayer"]
visible = false
[node name="InquiryDialog" type="Control" parent="OverlayLayer"]
visible = false
[node name="PauseDialog" type="Control" parent="OverlayLayer"]
visible = false
[node name="ReconnectOverlay" type="Control" parent="OverlayLayer"]
visible = false
[node name="ResultScreen" type="Control" parent="OverlayLayer"]
visible = false
+115
View File
@@ -0,0 +1,115 @@
using OSM.Client.Contracts;
namespace OSM.Client.Screens.Battle;
public static class DecisionUiRules
{
public static SoloActionQuotaDto? FindQuota(SoloDecisionPointsDto? dp, string actionType)
{
return dp?.Quotas.FirstOrDefault(quota =>
string.Equals(quota.ActionType, actionType, StringComparison.OrdinalIgnoreCase));
}
public static bool IsActionAvailable(SoloDecisionPointsDto? dp, params string[] actionTypes)
{
if (dp is null || dp.Quotas.Count == 0)
{
return true;
}
return actionTypes.Any(actionType => FindQuota(dp, actionType)?.Available == true);
}
public static string QuotaLabel(string baseLabel, SoloDecisionPointsDto? dp, params string[] actionTypes)
{
var quotas = actionTypes
.Select(actionType => FindQuota(dp, actionType))
.Where(quota => quota is not null)
.Cast<SoloActionQuotaDto>()
.ToArray();
if (quotas.Length == 0)
{
return baseLabel;
}
var remaining = quotas.Sum(quota => quota.Remaining);
var total = quotas.Sum(quota => quota.Quota);
var minimumCost = quotas.Min(quota => quota.DecisionPointCost);
return $"{baseLabel} {remaining}/{total} · {minimumCost}DP";
}
public static string SkillDetails(SoloSkillDto skill)
{
var kind = skill.IsSuperSkill ? "爆发技" : skill.IsMagic ? "魔法" : "战技";
var range = skill.CastAnywhere ? "全图" : $"{skill.CastRange} 格";
var resources = new List<string>();
if (skill.RealMpCost > 0)
{
resources.Add($"MP {skill.RealMpCost:0.#}");
}
if (skill.RealEpCost > 0)
{
resources.Add($"EP {skill.RealEpCost:0.#}");
}
if (skill.RealCd > 0)
{
resources.Add($"冷却 {skill.RealCd:0.#}");
}
if (skill.CurrentCd > 0)
{
resources.Add($"剩余 CD {skill.CurrentCd:0.#}");
}
var cost = resources.Count == 0 ? "无额外消耗" : string.Join(" · ", resources);
var reason = skill.Usable ? string.Empty : $"\n不可用:{skill.UnusableReason}";
var description = string.IsNullOrWhiteSpace(skill.Description) ? "暂无描述" : skill.Description;
return $"{kind} · 射程 {range} · {cost}{reason}\n{description}";
}
public static string ItemDetails(SoloItemDto item)
{
var range = item.CastRange <= 0 ? "—" : item.CastAnywhere ? "全图" : $"{item.CastRange} 格";
var uses = item.RemainUseTimes > 0 ? $"剩余 {item.RemainUseTimes} 次" : "次数不限或未提供";
var reason = item.Usable ? string.Empty : $"\n不可用:{item.UnusableReason}";
var description = string.IsNullOrWhiteSpace(item.Description) ? "暂无描述" : item.Description;
return $"{item.ItemType} · 射程 {range} · {uses}{reason}\n{description}";
}
public static IReadOnlyList<long> GetAffectedGridIds(
TargetGridsPayload payload,
long centerGridId,
SoloMapDto? map)
{
if (map is null)
{
return [];
}
var center = map.Grids.FirstOrDefault(grid => grid.Id == centerGridId);
if (center is null)
{
return [];
}
var radius = Math.Max(0, payload.ShapeRadius);
return map.Grids
.Where(grid => IsInShape(payload.ShapeRangeType, radius, center, grid))
.Where(grid => payload.IncludeCharacterGrid || grid.Characters.Count == 0)
.Select(grid => grid.Id)
.ToArray();
}
private static bool IsInShape(string shape, int radius, SoloGridDto center, SoloGridDto grid)
{
var dx = Math.Abs(grid.X - center.X);
var dy = Math.Abs(grid.Y - center.Y);
return shape.ToLowerInvariant() switch
{
"square" => Math.Max(dx, dy) <= radius,
"circle" => (dx * dx) + (dy * dy) <= radius * radius,
// Line/Sector 的精确朝向由服务器权威决定;没有方向输入时只预览中心到半径。
"line" or "linepass" or "sector" => dx + dy <= radius,
_ => dx + dy <= radius
};
}
}
+25
View File
@@ -0,0 +1,25 @@
namespace OSM.Client.Screens.Main;
public partial class Main : Node
{
public override void _Ready()
{
GD.Print("OSM client scaffold ready.");
var userArguments = OS.GetCmdlineUserArgs()
.Select(argument => argument.TrimStart('-'))
.ToHashSet(StringComparer.Ordinal);
if (userArguments.Contains("phase-c-smoke-test"))
{
AddChild(new OSM.Client.Diagnostics.PhaseCDecisionSmokeTest());
}
else if (userArguments.Contains("solo-vertical-smoke-test"))
{
AddChild(new OSM.Client.Diagnostics.SoloVerticalSliceSmokeTest());
}
else if (userArguments.Contains("solo-smoke-test"))
{
AddChild(new OSM.Client.Diagnostics.SoloConnectionSmokeTest());
}
}
}
+1
View File
@@ -0,0 +1 @@
uid://dh7gyhgvf4j4s
+10
View File
@@ -0,0 +1,10 @@
[gd_scene load_steps=3 format=3]
[ext_resource type="Script" path="res://src/Screens/Main/Main.cs" id="1_main"]
[ext_resource type="PackedScene" path="res://src/Screens/Battle/BattleScreen.tscn" id="2_battle"]
[node name="Main" type="Node"]
script = ExtResource("1_main")
[node name="BattleScreen" parent="." instance=ExtResource("2_battle")]
+136
View File
@@ -0,0 +1,136 @@
using OSM.Client.Contracts;
namespace OSM.Client.Units;
public partial class UnitView : Node2D
{
[Signal]
public delegate void ClickedEventHandler(string characterGuid);
private Polygon2D _shadow = null!;
private Line2D _selectionRing = null!;
private AnimatedSprite2D _body = null!;
private Polygon2D _placeholderBody = null!;
private Area2D _hitArea = null!;
private ProgressBar _hpBar = null!;
private Label _aiLabel = null!;
private Label _nameLabel = null!;
private bool _isFriendly;
private bool _isCurrentActor;
private bool _isSelectable;
private bool _isSelected;
private bool _isEliminated;
public string CharacterGuid { get; private set; } = string.Empty;
public long CharacterId { get; private set; }
public override void _Ready()
{
_shadow = GetNode<Polygon2D>("Shadow");
_selectionRing = GetNode<Line2D>("SelectionRing");
_body = GetNode<AnimatedSprite2D>("Body");
_placeholderBody = GetNode<Polygon2D>("PlaceholderBody");
_hitArea = GetNode<Area2D>("HitArea");
_hpBar = GetNode<ProgressBar>("HpBar");
_aiLabel = GetNode<Label>("StatusIcons/AiLabel");
_nameLabel = GetNode<Label>("NameLabel");
_hitArea.InputEvent += OnInputEvent;
_hitArea.MouseEntered += OnMouseEntered;
_hitArea.MouseExited += OnMouseExited;
AddToGroup("battle_unit");
}
public void ApplySnapshot(
SoloCharacterDto character,
bool isFriendly,
bool isCurrentActor,
bool isSelectable,
Vector2 worldPosition)
{
CharacterGuid = character.Guid;
CharacterId = character.Id;
_isFriendly = isFriendly;
_isCurrentActor = isCurrentActor;
_isSelectable = isSelectable;
_isEliminated = character.IsEliminated;
Position = worldPosition;
_nameLabel.Text = character.DisplayName;
_hpBar.MaxValue = Math.Max(1.0, character.MaxHp);
_hpBar.Value = Mathf.Clamp((float)character.Hp, 0.0f, (float)_hpBar.MaxValue);
_hpBar.TooltipText = $"HP {character.Hp:0} / {character.MaxHp:0}";
_aiLabel.Visible = character.IsAi;
_body.Visible = false;
_placeholderBody.Visible = true;
_hitArea.InputPickable = isSelectable && !_isEliminated;
UpdateVisuals();
}
public void SetSelected(bool selected)
{
if (_isSelected == selected)
{
return;
}
_isSelected = selected;
UpdateVisuals();
}
private void UpdateVisuals()
{
var teamColor = _isFriendly
? new Color("55b9e8")
: new Color("e56b6f");
_placeholderBody.Color = _isEliminated
? new Color(0.30f, 0.33f, 0.36f, 0.60f)
: teamColor;
_shadow.Color = _isEliminated
? new Color(0.0f, 0.0f, 0.0f, 0.12f)
: new Color(0.0f, 0.0f, 0.0f, 0.34f);
_selectionRing.Visible = _isCurrentActor || _isSelectable || _isSelected;
_selectionRing.DefaultColor = _isSelected
? new Color("fff3a1")
: _isSelectable
? new Color("ff9a62")
: new Color("f4d35e");
_selectionRing.Width = _isSelected ? 5.0f : 3.0f;
_hpBar.Modulate = _isEliminated ? new Color(1, 1, 1, 0.45f) : Colors.White;
_nameLabel.Modulate = _isEliminated ? new Color(1, 1, 1, 0.55f) : Colors.White;
ZIndex = 0;
}
private void OnInputEvent(Node viewport, InputEvent @event, long shapeIndex)
{
if (!_isSelectable || _isEliminated
|| @event is not InputEventMouseButton
{
ButtonIndex: MouseButton.Left,
Pressed: true
})
{
return;
}
EmitSignal(SignalName.Clicked, CharacterGuid);
GetViewport().SetInputAsHandled();
}
private void OnMouseEntered()
{
if (_isSelectable && !_isEliminated)
{
_placeholderBody.Scale = Vector2.One * 1.06f;
}
}
private void OnMouseExited()
{
_placeholderBody.Scale = Vector2.One;
}
}
+76
View File
@@ -0,0 +1,76 @@
[gd_scene load_steps=4 format=3]
[ext_resource type="Script" path="res://src/Units/UnitView.cs" id="1_unit"]
[sub_resource type="SpriteFrames" id="SpriteFrames_unit"]
[sub_resource type="RectangleShape2D" id="RectangleShape2D_unit"]
size = Vector2(72, 116)
[node name="UnitView" type="Node2D"]
script = ExtResource("1_unit")
[node name="Shadow" type="Polygon2D" parent="."]
polygon = PackedVector2Array(-46, -4, -32, -12, 0, -16, 32, -12, 46, -4, 32, 4, 0, 8, -32, 4)
color = Color(0, 0, 0, 0.34)
[node name="SelectionRing" type="Line2D" parent="."]
visible = false
points = PackedVector2Array(-52, -4, -42, -15, -20, -23, 0, -26, 20, -23, 42, -15, 52, -4, 42, 7, 20, 15, 0, 18, -20, 15, -42, 7, -52, -4)
width = 3.0
default_color = Color(0.956863, 0.827451, 0.368627, 1)
antialiased = true
[node name="Body" type="AnimatedSprite2D" parent="."]
position = Vector2(0, -61)
sprite_frames = SubResource("SpriteFrames_unit")
[node name="PlaceholderBody" type="Polygon2D" parent="."]
polygon = PackedVector2Array(-18, -112, 0, -124, 18, -112, 24, -86, 35, -58, 25, -32, 20, -7, 7, -7, 5, -45, -5, -45, -7, -7, -20, -7, -25, -32, -35, -58, -24, -86)
color = Color(0.333333, 0.72549, 0.909804, 1)
[node name="HitArea" type="Area2D" parent="."]
position = Vector2(0, -62)
collision_mask = 0
input_pickable = true
[node name="CollisionShape2D" type="CollisionShape2D" parent="HitArea"]
shape = SubResource("RectangleShape2D_unit")
[node name="HpBar" type="ProgressBar" parent="."]
offset_left = -48.0
offset_top = -146.0
offset_right = 48.0
offset_bottom = -134.0
mouse_filter = 2
value = 100.0
show_percentage = false
[node name="StatusIcons" type="HBoxContainer" parent="."]
offset_left = -48.0
offset_top = -170.0
offset_right = 48.0
offset_bottom = -148.0
alignment = 1
mouse_filter = 2
[node name="AiLabel" type="Label" parent="StatusIcons"]
visible = false
layout_mode = 2
text = "AI 托管"
horizontal_alignment = 1
theme_override_colors/font_color = Color(1, 0.78, 0.34, 1)
theme_override_font_sizes/font_size = 14
[node name="NameLabel" type="Label" parent="."]
offset_left = -88.0
offset_top = 12.0
offset_right = 88.0
offset_bottom = 42.0
mouse_filter = 2
text = "单位"
horizontal_alignment = 1
theme_override_colors/font_outline_color = Color(0.02, 0.03, 0.05, 1)
theme_override_constants/outline_size = 5
theme_override_font_sizes/font_size = 18
+79
View File
@@ -0,0 +1,79 @@
namespace OSM.Client.World;
public partial class BattleCameraController : Camera2D
{
[Export]
public float PanSpeed { get; set; } = 720.0f;
[Export]
public float ZoomStep { get; set; } = 0.1f;
[Export]
public float MinimumZoom { get; set; } = 0.55f;
[Export]
public float MaximumZoom { get; set; } = 1.5f;
private bool _dragging;
public override void _Process(double delta)
{
var direction = Vector2.Zero;
if (Input.IsKeyPressed(Key.A) || Input.IsKeyPressed(Key.Left))
{
direction.X -= 1;
}
if (Input.IsKeyPressed(Key.D) || Input.IsKeyPressed(Key.Right))
{
direction.X += 1;
}
if (Input.IsKeyPressed(Key.W) || Input.IsKeyPressed(Key.Up))
{
direction.Y -= 1;
}
if (Input.IsKeyPressed(Key.S) || Input.IsKeyPressed(Key.Down))
{
direction.Y += 1;
}
if (direction != Vector2.Zero)
{
Position += direction.Normalized() * PanSpeed * (float)delta / Zoom.X;
}
}
public override void _UnhandledInput(InputEvent @event)
{
switch (@event)
{
case InputEventMouseButton mouseButton when mouseButton.ButtonIndex == MouseButton.Middle:
_dragging = mouseButton.Pressed;
GetViewport().SetInputAsHandled();
break;
case InputEventMouseMotion mouseMotion when _dragging:
Position -= mouseMotion.Relative / Zoom;
GetViewport().SetInputAsHandled();
break;
case InputEventMouseButton mouseButton when mouseButton.Pressed
&& mouseButton.ButtonIndex == MouseButton.WheelUp:
SetZoom(Zoom.X + ZoomStep);
GetViewport().SetInputAsHandled();
break;
case InputEventMouseButton mouseButton when mouseButton.Pressed
&& mouseButton.ButtonIndex == MouseButton.WheelDown:
SetZoom(Zoom.X - ZoomStep);
GetViewport().SetInputAsHandled();
break;
}
}
private void SetZoom(float value)
{
var clamped = Mathf.Clamp(value, MinimumZoom, MaximumZoom);
Zoom = Vector2.One * clamped;
}
}
+1
View File
@@ -0,0 +1 @@
uid://cct24e2kc86ud
+75
View File
@@ -0,0 +1,75 @@
namespace OSM.Client.World;
public partial class GreyboxMap2D : Node2D
{
[Export]
public Vector2I MapSize { get; set; } = new(16, 12);
[Export]
public Vector2 CellSize { get; set; } = new(128, 64);
public override void _Ready()
{
QueueRedraw();
}
public void SetMapSize(Vector2I mapSize)
{
MapSize = mapSize;
QueueRedraw();
}
public override void _Draw()
{
for (var y = 0; y < MapSize.Y; y++)
{
for (var x = 0; x < MapSize.X; x++)
{
var center = GridProjector.GridToScreen(new Vector2I(x, y), CellSize.X, CellSize.Y);
var points = Diamond(center);
var checker = (x + y) % 2 == 0;
var fill = checker
? new Color("273746")
: new Color("22313f");
DrawColoredPolygon(points, fill);
}
}
DrawCover(new Vector2I(5, 4), new Color("526777"));
DrawCover(new Vector2I(6, 4), new Color("526777"));
DrawCover(new Vector2I(10, 7), new Color("705d54"));
DrawCover(new Vector2I(11, 7), new Color("705d54"));
}
private Vector2[] Diamond(Vector2 center)
{
var halfWidth = CellSize.X * 0.5f;
var halfHeight = CellSize.Y * 0.5f;
return
[
center + new Vector2(0, -halfHeight),
center + new Vector2(halfWidth, 0),
center + new Vector2(0, halfHeight),
center + new Vector2(-halfWidth, 0)
];
}
private void DrawCover(Vector2I grid, Color color)
{
var center = GridProjector.GridToScreen(grid, CellSize.X, CellSize.Y);
var top = center + new Vector2(0, -28);
var basePoints = Diamond(center);
var topPoints = Diamond(top);
DrawColoredPolygon(
[
basePoints[1], basePoints[2], topPoints[2], topPoints[1]
], color.Darkened(0.25f));
DrawColoredPolygon(
[
basePoints[2], basePoints[3], topPoints[3], topPoints[2]
], color.Darkened(0.4f));
DrawColoredPolygon(topPoints, color);
}
}
+1
View File
@@ -0,0 +1 @@
uid://fv2diskg1tlf
+201
View File
@@ -0,0 +1,201 @@
namespace OSM.Client.World;
public enum GridVisualState
{
Hidden,
Move,
Attack,
WaitingServer
}
public partial class GridOverlay2D : Node2D
{
[Signal]
public delegate void HoveredCellChangedEventHandler(Vector2I cell);
[Signal]
public delegate void CellClickedEventHandler(Vector2I cell);
[Export]
public Vector2I MapSize { get; set; } = new(16, 12);
[Export]
public Vector2 CellSize { get; set; } = new(128, 64);
private GridVisualState _visualState = GridVisualState.Hidden;
private Vector2I _hoveredCell = new(-1, -1);
private readonly Dictionary<long, Vector2I> _cellsById = [];
private readonly HashSet<long> _reachableCells = [];
private readonly HashSet<long> _attackCells = [];
private readonly HashSet<long> _affectedCells = [];
private long? _selectedCell;
public GridVisualState VisualState
{
get => _visualState;
set
{
if (_visualState == value)
{
return;
}
_visualState = value;
QueueRedraw();
}
}
public override void _Process(double delta)
{
var localMouse = ToLocal(GetGlobalMousePosition());
var nextHovered = GridProjector.TryScreenToGrid(
localMouse,
MapSize,
out var cell,
CellSize.X,
CellSize.Y)
? cell
: new Vector2I(-1, -1);
if (nextHovered == _hoveredCell)
{
return;
}
_hoveredCell = nextHovered;
EmitSignal(SignalName.HoveredCellChanged, _hoveredCell);
QueueRedraw();
}
public override void _UnhandledInput(InputEvent @event)
{
if (@event is not InputEventMouseButton
{
ButtonIndex: MouseButton.Left,
Pressed: true
})
{
return;
}
if (_hoveredCell.X >= 0)
{
EmitSignal(SignalName.CellClicked, _hoveredCell);
GetViewport().SetInputAsHandled();
}
}
public void SetMapSize(Vector2I mapSize)
{
MapSize = mapSize;
_hoveredCell = new Vector2I(-1, -1);
QueueRedraw();
}
public void SetGridCoordinates(IEnumerable<KeyValuePair<long, Vector2I>> cells)
{
_cellsById.Clear();
foreach (var cell in cells)
{
_cellsById[cell.Key] = cell.Value;
}
QueueRedraw();
}
public void SetReachableCells(IEnumerable<long> gridIds)
{
ReplaceSet(_reachableCells, gridIds);
VisualState = GridVisualState.Move;
QueueRedraw();
}
public void SetAttackCells(IEnumerable<long> gridIds)
{
ReplaceSet(_attackCells, gridIds);
VisualState = GridVisualState.Attack;
QueueRedraw();
}
public void SetAffectedCells(IEnumerable<long> gridIds)
{
ReplaceSet(_affectedCells, gridIds);
QueueRedraw();
}
public void SetSelectedCell(long? gridId)
{
_selectedCell = gridId;
QueueRedraw();
}
public void ClearInteraction()
{
_reachableCells.Clear();
_attackCells.Clear();
_affectedCells.Clear();
_selectedCell = null;
VisualState = GridVisualState.Hidden;
QueueRedraw();
}
public override void _Draw()
{
if (VisualState == GridVisualState.Move)
{
DrawCells(_reachableCells, new Color(0.18f, 0.72f, 1.0f, 0.24f), 1.5f);
}
else if (VisualState == GridVisualState.Attack)
{
DrawCells(_attackCells, new Color(1.0f, 0.34f, 0.18f, 0.22f), 1.5f);
DrawCells(_affectedCells, new Color(1.0f, 0.68f, 0.18f, 0.27f), 2.0f);
}
if (_selectedCell is long selectedId && _cellsById.TryGetValue(selectedId, out var selected))
{
DrawCell(selected, new Color(1.0f, 0.95f, 0.55f, 0.42f), 4.0f);
}
if (_hoveredCell.X >= 0)
{
DrawCell(_hoveredCell, new Color(1.0f, 0.95f, 0.55f, 0.35f), 3.0f);
}
}
private void DrawCells(IEnumerable<long> gridIds, Color color, float lineWidth)
{
foreach (var gridId in gridIds)
{
if (_cellsById.TryGetValue(gridId, out var grid))
{
DrawCell(grid, color, lineWidth);
}
}
}
private static void ReplaceSet(HashSet<long> target, IEnumerable<long> source)
{
target.Clear();
foreach (var value in source)
{
target.Add(value);
}
}
private void DrawCell(Vector2I grid, Color fill, float lineWidth)
{
var center = GridProjector.GridToScreen(grid, CellSize.X, CellSize.Y);
var halfWidth = CellSize.X * 0.5f;
var halfHeight = CellSize.Y * 0.5f;
Vector2[] points =
[
center + new Vector2(0, -halfHeight),
center + new Vector2(halfWidth, 0),
center + new Vector2(0, halfHeight),
center + new Vector2(-halfWidth, 0)
];
DrawColoredPolygon(points, fill);
Vector2[] outline = [points[0], points[1], points[2], points[3], points[0]];
DrawPolyline(outline, fill.Lightened(0.45f) with { A = 0.78f }, lineWidth, true);
}
}
+1
View File
@@ -0,0 +1 @@
uid://rq6x5ti1wkuw
+56
View File
@@ -0,0 +1,56 @@
namespace OSM.Client.World;
public static class GridProjector
{
public static Vector2 GridToScreen(
Vector2I grid,
float cellWidth = 128.0f,
float cellHeight = 64.0f,
int heightLevel = 0,
float heightStep = 32.0f)
{
return new Vector2(
(grid.X - grid.Y) * cellWidth * 0.5f,
(grid.X + grid.Y) * cellHeight * 0.5f - heightLevel * heightStep);
}
public static Vector2 ScreenToGridFractional(
Vector2 screen,
float cellWidth = 128.0f,
float cellHeight = 64.0f,
int heightLevel = 0,
float heightStep = 32.0f)
{
var adjustedY = screen.Y + heightLevel * heightStep;
return new Vector2(
screen.X / cellWidth + adjustedY / cellHeight,
adjustedY / cellHeight - screen.X / cellWidth);
}
public static bool TryScreenToGrid(
Vector2 screen,
Vector2I mapSize,
out Vector2I grid,
float cellWidth = 128.0f,
float cellHeight = 64.0f)
{
var fractional = ScreenToGridFractional(screen, cellWidth, cellHeight);
var candidate = new Vector2I(
Mathf.RoundToInt(fractional.X),
Mathf.RoundToInt(fractional.Y));
var center = GridToScreen(candidate, cellWidth, cellHeight);
var offset = screen - center;
var insideDiamond = Mathf.Abs(offset.X) / (cellWidth * 0.5f)
+ Mathf.Abs(offset.Y) / (cellHeight * 0.5f) <= 1.0f;
var insideMap = candidate.X >= 0
&& candidate.Y >= 0
&& candidate.X < mapSize.X
&& candidate.Y < mapSize.Y;
grid = candidate;
return insideDiamond && insideMap;
}
}
+1
View File
@@ -0,0 +1 @@
uid://dt7c0vmxfpt35
+53
View File
@@ -0,0 +1,53 @@
# OSM 2D 角色空白模板 v1
本模板由 02 汐月心音的完整美术生产流程抽象而来,用于新角色的四方向 2D 战场素材。它只复用目录、命名、动画契约和验收门槛,不复制心音的造型、固定侧别或历史目录。
## 固定基线
- 角色比例:4.75 头身的成年轻 Q 战斗比例;允许在角色设定要求下调整,但必须重新做三档尺寸验证。
- 运行时身体方向:`up / down / left / right`。
- 新角色目录直接使用四方向名称,不使用 `front-left / front-right` 历史别名。
- 标准动作画布:600 × 760 px,透明背景,原点为底部中心。
- 默认显示高度:176 px;压力测试高度为 132 px 和 88 px。
- 身体使用四方向;投射物、准星和技能 VFX 可以自由角度瞄准。
- LEFT 与 RIGHT 默认独立制作。只有角色完全对称且通过专门审查后,才可以考虑镜像。
## 标准动画契约
| 关键帧 | 时长 |
|---|---:|
| `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。
## 使用方法
在项目根目录运行:
```powershell
python tools/scaffold_2d_character.py 03-example --name-zh "角色名" --name-en "English Name"
```
先使用 `--dry-run` 可只查看将创建的内容:
```powershell
python tools/scaffold_2d_character.py 03-example --name-zh "角色名" --dry-run
```
脚手架拒绝覆盖已存在的角色目录。创建后,从 `source/up`、`source/down`、`source/left`、`source/right` 开始制作,按 `production-checklist.md` 逐阶段提升状态。
## 模板文件
- `template-manifest.json`:模板自身的版本、文件入口和验证结果。
- `character-config.template.json`:角色级美术与运行时约束。
- `direction-map.template.json`:四方向状态与路径入口。
- `template-package.template.json`:未来引擎接入的统一入口占位。
- `character-readme.template.md`:新角色目录内的说明。
- `validation-rules-v1.json`:可机器读取的硬性验收规则。
- `production-checklist.md`:从母版到交付包的阶段检查表。
@@ -0,0 +1,42 @@
{
"characterId": "__CHARACTER_ID__",
"characterNameZh": "__CHARACTER_NAME_ZH__",
"characterNameEn": "__CHARACTER_NAME_EN__",
"templateVersion": 1,
"artDirection": {
"proportionHeads": 4.75,
"style": "adult-light-chibi-combat",
"workingScale": 2,
"defaultDisplayHeight": 176,
"validationDisplayHeights": [176, 132, 88],
"masterBackground": "transparent"
},
"runtime": {
"directionModel": "four-cardinal",
"directions": ["up", "down", "left", "right"],
"motionCanvas": {"width": 600, "height": 760},
"spriteOrigin": "bottom-center",
"bodyFacing": "four-cardinal",
"projectileAndVfxAim": "free-angle"
},
"sideConvention": {
"status": "unfrozen",
"instruction": "Freeze screen-side ownership independently for every direction before source-sheet production. Do not inherit another character's A/B mapping."
},
"animationContract": {
"idle": {
"frames": ["idle-inhale", "idle-neutral", "idle-exhale", "idle-neutral"],
"durationsMs": [420, 260, 420, 260],
"cycleMs": 1360,
"loop": true
},
"throw": {
"frames": ["throw-ready", "throw-windup", "throw-release", "throw-recover", "idle-neutral"],
"durationsMs": [150, 110, 90, 180, 260],
"cycleMs": 790,
"loop": false
}
},
"notes": []
}
@@ -0,0 +1,18 @@
# __CHARACTER_ID__ __CHARACTER_NAME_ZH__
本目录由 OSM 2D 角色空白模板 v1 创建。
- 当前状态:`scaffold-created`
- 运行时方向:`up / down / left / right`
- 标准动作画布:600 × 760 px
- Sprite 原点:底部中心
- 默认显示高度:176 px
- 英文名:__CHARACTER_NAME_EN__
制作前先在 `character-config-v1.json` 中补充角色专属识别点,并为四个方向分别冻结固定侧别。禁止直接复制 02 汐月心音的 A/B 侧别关系。
阶段验收规则见项目文件:
- `templates/2d-character-v1/production-checklist.md`
- `templates/2d-character-v1/validation-rules-v1.json`
@@ -0,0 +1,27 @@
{
"characterId": "__CHARACTER_ID__",
"version": 1,
"templatePackage": "assets/images/2d-game-characters/__CHARACTER_ID__/template-package-v1.json",
"runtimeDirectionModel": "four-cardinal",
"runtimeDirections": ["up", "down", "left", "right"],
"coordinateSystem": {
"space": "screen",
"xPositive": "right",
"yPositive": "down",
"footOrigin": "bottom-center"
},
"directions": {
"up": {"legacyDirectionId": null, "status": "not-started", "master": null, "sourceSheetManifest": null, "partsManifest": null, "assembly": null, "motionManifest": null, "notes": "Freeze strict-back silhouette and side ownership before decomposition."},
"down": {"legacyDirectionId": null, "status": "not-started", "master": null, "sourceSheetManifest": null, "partsManifest": null, "assembly": null, "motionManifest": null, "notes": "Freeze strict-front silhouette and side ownership before decomposition."},
"left": {"legacyDirectionId": null, "status": "not-started", "master": null, "sourceSheetManifest": null, "partsManifest": null, "assembly": null, "motionManifest": null, "notes": "Create an independent screen-left-facing three-quarter view unless symmetry is explicitly approved."},
"right": {"legacyDirectionId": null, "status": "not-started", "master": null, "sourceSheetManifest": null, "partsManifest": null, "assembly": null, "motionManifest": null, "notes": "Create an independent screen-right-facing three-quarter view unless symmetry is explicitly approved."}
},
"selectionRule": {
"minimumInputMagnitude": 0.1,
"axisPolicy": "dominant-axis",
"diagonalTiePolicy": "keep-previous-facing",
"axisHysteresisRatio": 0.15
},
"aimingRule": {"bodyFacing": "four-cardinal", "projectileAndVfxAim": "free-angle"}
}
@@ -0,0 +1,72 @@
# OSM 2D 角色生产验收清单 v1
## G0:角色基线
- [ ] 确认 4.75 头身或记录角色专属比例例外。
- [ ] 列出头发、武器、配饰、颜色和轮廓识别点。
- [ ] 确认 `up / down / left / right` 四方向。
- [ ] 为每个方向独立冻结画面侧别和角色身体侧别。
- [ ] 明确哪些附件禁止镜像。
## G1:四方向母版
- [ ] UP 严格背面,DOWN 严格正面。
- [ ] LEFT/RIGHT 朝向与运行时名称一致。
- [ ] 透明画布四边留有安全空间。
- [ ] 双脚基线差不超过 1 px;正式装配必须收敛到 0 px。
- [ ] 176/132/88 px 下核心识别点仍可辨认。
- [ ] 状态提升为 `master-art-validated`。
## G2:分解源板
- [ ] 核心身体、四肢、头发、衣摆、附件和动作替换件分组明确。
- [ ] 每个对象在 Alpha 阈值下保持独立,不跨格粘连。
- [ ] 肩甲、袖披、上臂、前臂和手型没有错误烘焙在一起。
- [ ] 源板四角透明,失败版本保留但不参与正式提取。
- [ ] 状态提升为 `source-sheets-alpha-validated`。
## G3:独立裁切
- [ ] 每个源对象只导出一个透明 PNG。
- [ ] 文件名、源组件编号和清单记录一一对应。
- [ ] 每件四周保留安全 padding,外边缘透明。
- [ ] 清单包含父节点、层级、根枢轴和下一关节点。
- [ ] 所有部件有明确中性用途或替换用途。
- [ ] 原始裁切状态为 `extracted-unvalidated`。
## G4:中性装配
- [ ] 所有使用件和排除件数量相加等于部件总数。
- [ ] 肩—肘—腕、髋—膝—踝和头发链无明显断缝。
- [ ] 腰饰、衣摆和配件没有重复叠画。
- [ ] 画布为 600 × 760 px,四边透明。
- [ ] 双脚 Alpha 基线差为 0 px。
- [ ] 状态提升为 `static-art-validated`。
## G5:动作验证
- [ ] 生成三帧待机和四帧投掷关键姿势。
- [ ] 七帧脚底基线完全一致。
- [ ] 身体保持四方向主轴,投掷侧清楚。
- [ ] 释放帧正确切换张手/武器替换件。
- [ ] 头发与衣摆有滞后但不穿模、不散架。
- [ ] 状态提升为 `motion-art-validated`。
## G6:三档循环
- [ ] 待机循环周期为 1360 ms。
- [ ] 投掷播放周期为 790 ms。
- [ ] 每个方向的所有帧共用一个联合裁切框。
- [ ] 禁止逐帧重新居中。
- [ ] 176/132/88 px 下动作方向和角色识别点仍可读。
- [ ] 播放报告状态为 `playback-preview-validated`。
## G7:模板交付
- [ ] 四方向动作画布统一为 600 × 760 px。
- [ ] `direction-map-v1.json` 与 `template-package-v1.json` 路径有效。
- [ ] 四方向装配、动作清单、播放报告和预览均存在。
- [ ] 统一入口记录所有历史别名;新角色默认不使用历史别名。
- [ ] 明确区分美术模板就绪与引擎集成完成。
- [ ] 状态提升为 `art-template-ready`。
@@ -0,0 +1,32 @@
{
"templateId": "osm-2d-character-v1",
"version": 1,
"status": "ready",
"derivedFromCharacter": "02-xinyin",
"scope": "four-cardinal 2D battlefield character art scaffold",
"files": {
"readme": "templates/2d-character-v1/README.md",
"characterConfig": "templates/2d-character-v1/character-config.template.json",
"directionMap": "templates/2d-character-v1/direction-map.template.json",
"templatePackage": "templates/2d-character-v1/template-package.template.json",
"characterReadme": "templates/2d-character-v1/character-readme.template.md",
"validationRules": "templates/2d-character-v1/validation-rules-v1.json",
"productionChecklist": "templates/2d-character-v1/production-checklist.md",
"scaffoldTool": "tools/scaffold_2d_character.py"
},
"defaults": {
"proportionHeads": 4.75,
"directions": ["up", "down", "left", "right"],
"motionCanvas": {"width": 600, "height": 760},
"spriteOrigin": "bottom-center",
"displayHeights": [176, 132, 88],
"horizontalMirroring": "requires-explicit-approval"
},
"validation": {
"templateJsonParsed": true,
"tokenReplacementParsed": true,
"scaffoldDryRunPassed": true,
"existingDirectoryOverwriteAllowed": false
}
}
@@ -0,0 +1,31 @@
{
"characterId": "__CHARACTER_ID__",
"characterNameZh": "__CHARACTER_NAME_ZH__",
"characterNameEn": "__CHARACTER_NAME_EN__",
"version": 1,
"status": "scaffold-created",
"engineIntegrationStatus": "not-started-no-godot-project",
"recommendedIntegration": {
"primary": "frame-animation",
"spriteOrigin": "bottom-center",
"note": "Populate asset paths only after each direction passes art-side playback validation."
},
"displayProfiles": [
{"label": "100%", "characterHeight": 176, "cell": {"width": 128, "height": 64}},
{"label": "75%", "characterHeight": 132, "cell": {"width": 96, "height": 48}},
{"label": "50%", "characterHeight": 88, "cell": {"width": 64, "height": 32}}
],
"directions": [
{"runtimeDirection": "up", "status": "not-started", "assembly": null, "motionManifest": null, "playbackReport": null},
{"runtimeDirection": "down", "status": "not-started", "assembly": null, "motionManifest": null, "playbackReport": null},
{"runtimeDirection": "left", "status": "not-started", "assembly": null, "motionManifest": null, "playbackReport": null},
{"runtimeDirection": "right", "status": "not-started", "assembly": null, "motionManifest": null, "playbackReport": null}
],
"validation": {
"directionCount": 4,
"allDirectionsMotionValidated": false,
"allPlaybackBaselinesFixed": false,
"missingReferencedFiles": []
}
}
@@ -0,0 +1,35 @@
{
"templateVersion": 1,
"requiredDirections": ["up", "down", "left", "right"],
"motionCanvas": {"width": 600, "height": 760},
"spriteOrigin": "bottom-center",
"displayHeights": [176, 132, 88],
"requiredKeyframes": [
{"name": "idle-inhale", "durationMs": 420},
{"name": "idle-neutral", "durationMs": 260},
{"name": "idle-exhale", "durationMs": 420},
{"name": "throw-ready", "durationMs": 150},
{"name": "throw-windup", "durationMs": 110},
{"name": "throw-release", "durationMs": 90},
{"name": "throw-recover", "durationMs": 180}
],
"hardGates": {
"transparentOuterEdges": true,
"maximumFootBaselineDeltaPixels": 0,
"fixedPlaybackCrop": true,
"perFrameRecenteringAllowed": false,
"allPartsAccountedFor": true,
"directionSideConventionFrozen": true,
"horizontalMirrorRequiresExplicitApproval": true
},
"statusOrder": [
"scaffold-created",
"master-art-validated",
"source-sheets-alpha-validated",
"extracted-unvalidated",
"static-art-validated",
"motion-art-validated",
"art-template-ready"
]
}
+224
View File
@@ -0,0 +1,224 @@
param(
[string]$WorkspaceRoot = (Split-Path -Parent $PSScriptRoot)
)
Add-Type -AssemblyName System.Drawing
$characterRoot = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin'
$partsDirectory = Join-Path $characterRoot 'parts\front-right\v1'
$manifestPath = Join-Path $partsDirectory 'parts-manifest.json'
$correctionDirectory = Join-Path $characterRoot 'parts\front-right\rig-corrections-v1'
$correctionManifestPath = Join-Path $correctionDirectory 'rig-corrections-manifest.json'
$referencePath = Join-Path $characterRoot 'reference\xinyin-front-right-assembled-reference-v1.png'
$assembledDirectory = Join-Path $characterRoot 'assembled\front-right'
$previewDirectory = Join-Path $characterRoot 'previews'
$assemblyPath = Join-Path $assembledDirectory 'xinyin-front-right-neutral-assembly-v4.png'
$layoutPath = Join-Path $assembledDirectory 'assembly-layout-v4.json'
$previewPath = Join-Path $previewDirectory 'xinyin-front-right-assembly-validation-v4.png'
New-Item -ItemType Directory -Force -Path $assembledDirectory, $previewDirectory | Out-Null
$manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json
$correctionManifest = Get-Content -LiteralPath $correctionManifestPath -Raw | ConvertFrom-Json
$partByName = @{}
foreach ($part in $manifest.parts) {
$partByName[$part.name] = [pscustomobject]@{
ComponentId=$part.componentId; File=$part.file; PartSet='base-v1'
AssetPath="assets/images/2d-game-characters/02-xinyin/parts/front-right/v1/$($part.file)"
FullPath=(Join-Path $partsDirectory $part.file)
PivotX=[double]$part.pivot.outputPixels.x; PivotY=[double]$part.pivot.outputPixels.y
}
}
foreach ($part in $correctionManifest.parts) {
$partByName[$part.name] = [pscustomobject]@{
ComponentId=$part.componentId; File=$part.file; PartSet='rig-corrections-v1'
AssetPath="assets/images/2d-game-characters/02-xinyin/parts/front-right/rig-corrections-v1/$($part.file)"
FullPath=(Join-Path $correctionDirectory $part.file)
PivotX=[double]$part.rootPivot.outputPixels.x; PivotY=[double]$part.rootPivot.outputPixels.y
}
}
# Target coordinates use a 500x760 authoring canvas. X/Y are the desired positions of
# each part's manifest pivot. The initial arrangement deliberately uses only one of
# several alternate hair/limb pieces so that unused variants stay visible in the report.
$layout = @(
@{ Name='ponytail-root'; X=215; Y=62; Rotation=0; Scale=.55; Group='base'; Note='三段马尾根部' },
@{ Name='ponytail-middle'; X=296; Y=94; Rotation=-12; Scale=.42; Group='base'; Note='三段马尾中段' },
@{ Name='ponytail-tip'; X=334; Y=258; Rotation=-6; Scale=.38; Group='base'; Note='三段马尾末端' },
@{ Name='coat-panel-01'; X=150; Y=318; Rotation=6; Scale=.92; Group='base'; Note='左外层候选' },
@{ Name='coat-panel-02'; X=176; Y=315; Rotation=3; Scale=.88; Group='base'; Note='左后层候选' },
@{ Name='coat-panel-03'; X=204; Y=319; Rotation=1; Scale=.88; Group='base'; Note='中左候选' },
@{ Name='coat-panel-04'; X=226; Y=320; Rotation=0; Scale=.90; Group='base'; Note='中层候选' },
@{ Name='coat-panel-05'; X=245; Y=320; Rotation=0; Scale=.90; Group='base'; Note='中层候选' },
@{ Name='coat-panel-06'; X=264; Y=319; Rotation=-1; Scale=.88; Group='base'; Note='中右候选' },
@{ Name='coat-panel-07'; X=286; Y=315; Rotation=-3; Scale=.88; Group='base'; Note='右后层候选' },
@{ Name='coat-panel-08'; X=316; Y=318; Rotation=-6; Scale=.92; Group='base'; Note='右外层候选' },
@{ Name='thigh-a'; X=195; Y=350; Rotation=7; Scale=.92; Group='base'; Note='画面左腿候选' },
@{ Name='shin-boot-a'; X=178; Y=480; Rotation=9; Scale=.88; Group='base'; Note='画面左小腿候选' },
@{ Name='thigh-b'; X=244; Y=350; Rotation=-5; Scale=.92; Group='base'; Note='画面右腿候选' },
@{ Name='shin-boot-b'; X=252; Y=487; Rotation=-3; Scale=.88; Group='base'; Note='画面右小腿候选' },
@{ Name='pelvis'; X=220; Y=350; Rotation=0; Scale=.88; Group='base'; Note='主根候选' },
@{ Name='torso-upper'; X=213; Y=318; Rotation=0; Scale=.92; Group='base'; Note='躯干' },
@{ Name='upper-arm-a'; X=146; Y=214; Rotation=10; Scale=.40; Group='base'; Note='独立上臂 A,肩到肘' },
@{ Name='forearm-a'; X=130; Y=307; Rotation=156; Scale=.38; Group='base'; Note='独立前臂 A,肘到腕' },
@{ Name='hand-fan-grip'; X=89; Y=214; Rotation=-8; Scale=.38; Group='base'; Note='独立持扇手' },
@{ Name='upper-arm-b'; X=276; Y=214; Rotation=-8; Scale=.40; Group='base'; Note='独立上臂 B,肩到肘' },
@{ Name='forearm-b'; X=289; Y=309; Rotation=-5; Scale=.30; Group='base'; Note='独立前臂 B,肘到腕' },
@{ Name='hand-relaxed-b'; X=296; Y=389; Rotation=-5; Scale=.25; Group='base'; Note='独立放松手 B' },
@{ Name='waist-guard'; X=217; Y=298; Rotation=0; Scale=.72; Group='overlay'; Note='覆盖骨盆和腿根' },
@{ Name='front-drape'; X=203; Y=305; Rotation=2; Scale=.75; Group='overlay'; Note='腰前垂布' },
@{ Name='waist-pouch'; X=270; Y=312; Rotation=-2; Scale=.58; Group='overlay'; Note='画面右侧腰包,v2 缩小' },
@{ Name='neck'; X=207; Y=187; Rotation=0; Scale=.90; Group='overlay'; Note='颈部' },
@{ Name='head-face'; X=205; Y=194; Rotation=0; Scale=1.00; Group='overlay'; Note='面部' },
@{ Name='hair-front'; X=204; Y=76; Rotation=0; Scale=1.00; Group='overlay'; Note='前发覆盖面部' },
@{ Name='shoulder-armor-a'; X=146; Y=207; Rotation=8; Scale=.65; Group='overlay'; Note='固定于躯干的独立肩甲 A' },
@{ Name='shoulder-armor-b'; X=276; Y=207; Rotation=-8; Scale=.65; Group='overlay'; Note='固定于躯干的独立肩甲 B' }
)
function Draw-Part {
param(
[Drawing.Graphics]$Graphics,
[Drawing.Image]$Image,
[double]$PivotX,
[double]$PivotY,
[double]$TargetX,
[double]$TargetY,
[double]$Rotation,
[double]$Scale
)
$state = $Graphics.Save()
$Graphics.TranslateTransform([single]$TargetX, [single]$TargetY)
$Graphics.RotateTransform([single]$Rotation)
$Graphics.ScaleTransform([single]$Scale, [single]$Scale)
$Graphics.DrawImageUnscaled($Image, [int][Math]::Round(-$PivotX), [int][Math]::Round(-$PivotY))
$Graphics.Restore($state)
}
$images = @{}
$assembly = [Drawing.Bitmap]::new(500, 760, [Drawing.Imaging.PixelFormat]::Format32bppArgb)
$assemblyGraphics = [Drawing.Graphics]::FromImage($assembly)
$assemblyGraphics.SmoothingMode = [Drawing.Drawing2D.SmoothingMode]::AntiAlias
$assemblyGraphics.InterpolationMode = [Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
$assemblyGraphics.PixelOffsetMode = [Drawing.Drawing2D.PixelOffsetMode]::HighQuality
$assemblyGraphics.Clear([Drawing.Color]::Transparent)
try {
foreach ($item in $layout) {
$part = $partByName[$item.Name]
if ($null -eq $part) { throw "Part not found in manifest: $($item.Name)" }
if (-not $images.ContainsKey($item.Name)) {
$images[$item.Name] = [Drawing.Bitmap]::new($part.FullPath)
}
Draw-Part -Graphics $assemblyGraphics -Image $images[$item.Name] `
-PivotX $part.PivotX -PivotY $part.PivotY `
-TargetX $item.X -TargetY $item.Y -Rotation $item.Rotation -Scale $item.Scale
}
$assembly.Save($assemblyPath, [Drawing.Imaging.ImageFormat]::Png)
$layoutRecords = foreach ($item in $layout) {
$part = $partByName[$item.Name]
[ordered]@{
part = $item.Name
componentId = $part.ComponentId
partSet = $part.PartSet
file = $part.AssetPath
targetPivot = [ordered]@{ x=$item.X; y=$item.Y }
rotationDegrees = $item.Rotation
scale = $item.Scale
group = $item.Group
note = $item.Note
}
}
[ordered]@{
characterId = '02-xinyin'
direction = 'front-right'
version = 4
status = 'art-assembly-validated'
canvas = [ordered]@{ width=500; height=760; origin='top-left'; units='pixels' }
sourceManifests = @(
'assets/images/2d-game-characters/02-xinyin/parts/front-right/v1/parts-manifest.json',
'assets/images/2d-game-characters/02-xinyin/parts/front-right/rig-corrections-v1/rig-corrections-manifest.json'
)
warnings = @(
'This is an art-side assembly validation, not an engine rig.',
'A/B limb ownership and cloth ordering remain provisional until animation testing.',
'C01 is excluded because two alternate ponytail masses are connected by a thin strand.',
'C09 is excluded because the front-hair part already carries the visible long ornament.',
'C15/C17 and C18/C20 are replaced by independent arm, forearm, and hand correction parts.',
'C28/C29 are restored as torso-mounted shoulder armor because corrected upper arms do not contain armor.'
)
items = $layoutRecords
} | ConvertTo-Json -Depth 7 | Set-Content -LiteralPath $layoutPath -Encoding utf8
$board = [Drawing.Bitmap]::new(1800, 980, [Drawing.Imaging.PixelFormat]::Format32bppArgb)
$g = [Drawing.Graphics]::FromImage($board)
$g.SmoothingMode = [Drawing.Drawing2D.SmoothingMode]::AntiAlias
$g.InterpolationMode = [Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
$g.PixelOffsetMode = [Drawing.Drawing2D.PixelOffsetMode]::HighQuality
$g.Clear([Drawing.Color]::FromArgb(255, 17, 21, 30))
$titleBrush = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(255, 240, 244, 252))
$mutedBrush = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(255, 150, 169, 198))
$panelBrush = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(255, 24, 30, 42))
$panelPen = [Drawing.Pen]::new([Drawing.Color]::FromArgb(255, 65, 82, 112), 2)
$jointPen = [Drawing.Pen]::new([Drawing.Color]::FromArgb(255, 255, 94, 122), 3)
$bonePen = [Drawing.Pen]::new([Drawing.Color]::FromArgb(210, 79, 211, 255), 4)
$fontTitle = [Drawing.Font]::new('Segoe UI Semibold', 27)
$fontPanel = [Drawing.Font]::new('Segoe UI Semibold', 18)
$fontText = [Drawing.Font]::new('Segoe UI', 13)
$g.DrawString('XIN YIN — FRONT-RIGHT ASSEMBLY VALIDATION V4', $fontTitle, $titleBrush, 42, 26)
$g.DrawString('reference / extracted-part assembly / pivot and hierarchy check', $fontText, $mutedBrush, 45, 68)
$panelXs = @(42, 624, 1206)
foreach ($panelX in $panelXs) {
$g.FillRectangle($panelBrush, $panelX, 112, 552, 820)
$g.DrawRectangle($panelPen, $panelX, 112, 552, 820)
}
$g.DrawString('A ASSEMBLED REFERENCE', $fontPanel, $titleBrush, 62, 132)
$g.DrawString('B PARTS RECONSTRUCTION', $fontPanel, $titleBrush, 644, 132)
$g.DrawString('C PIVOT / HIERARCHY', $fontPanel, $titleBrush, 1226, 132)
$reference = [Drawing.Bitmap]::new($referencePath)
$g.DrawImage($reference, 112, 186, 414, 716)
$g.DrawImage($assembly, 650, 172, 500, 760)
$g.DrawImage($assembly, 1232, 172, 500, 760)
$bones = @(
@((215,62),(296,94),(334,258),(347,388)),
@((205,194),(207,187),(213,260),(220,350)),
@((213,220),(146,214),(130,307),(89,214)),
@((213,220),(276,214),(289,309),(296,389)),
@((220,350),(195,350),(178,480),(160,685)),
@((220,350),(244,350),(252,487),(260,700))
)
foreach ($chain in $bones) {
for ($i = 0; $i -lt $chain.Count - 1; $i++) {
$x1 = 1232 + $chain[$i][0]
$y1 = 172 + $chain[$i][1]
$x2 = 1232 + $chain[$i + 1][0]
$y2 = 172 + $chain[$i + 1][1]
$g.DrawLine($bonePen, $x1, $y1, $x2, $y2)
}
foreach ($point in $chain) {
$g.DrawEllipse($jointPen, 1232 + $point[0] - 6, 172 + $point[1] - 6, 12, 12)
}
}
$g.DrawString('Corrected chain:', $fontText, $titleBrush, 1240, 862)
$g.DrawString('separate upper arms / forearms / hands / three-part ponytail', $fontText, $mutedBrush, 1240, 888)
$g.DrawString('C28/C29 restored as torso-mounted armor', $fontText, $mutedBrush, 1240, 912)
$board.Save($previewPath, [Drawing.Imaging.ImageFormat]::Png)
$reference.Dispose()
$fontText.Dispose(); $fontPanel.Dispose(); $fontTitle.Dispose()
$bonePen.Dispose(); $jointPen.Dispose(); $panelPen.Dispose()
$panelBrush.Dispose(); $mutedBrush.Dispose(); $titleBrush.Dispose()
$g.Dispose(); $board.Dispose()
}
finally {
foreach ($image in $images.Values) { $image.Dispose() }
$assemblyGraphics.Dispose()
$assembly.Dispose()
}
Write-Output $assemblyPath
Write-Output $layoutPath
Write-Output $previewPath
+327
View File
@@ -0,0 +1,327 @@
param(
[string]$WorkspaceRoot = (Split-Path -Parent $PSScriptRoot)
)
Add-Type -AssemblyName System.Drawing
$characterRoot = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin'
$partsDirectory = Join-Path $characterRoot 'parts\front-right\v1'
$partsManifestPath = Join-Path $partsDirectory 'parts-manifest.json'
$correctionDirectory = Join-Path $characterRoot 'parts\front-right\rig-corrections-v1'
$correctionManifestPath = Join-Path $correctionDirectory 'rig-corrections-manifest.json'
$layoutPath = Join-Path $characterRoot 'assembled\front-right\assembly-layout-v4.json'
$outputDirectory = Join-Path $characterRoot 'motion\front-right\v3'
$previewPath = Join-Path $characterRoot 'previews\xinyin-front-right-motion-validation-v3.png'
$motionManifestPath = Join-Path $outputDirectory 'motion-manifest.json'
New-Item -ItemType Directory -Force -Path $outputDirectory | Out-Null
$partsManifest = Get-Content -LiteralPath $partsManifestPath -Raw | ConvertFrom-Json
$correctionManifest = Get-Content -LiteralPath $correctionManifestPath -Raw | ConvertFrom-Json
$baseLayout = Get-Content -LiteralPath $layoutPath -Raw | ConvertFrom-Json
$partByName = @{}
foreach ($part in $partsManifest.parts) {
$partByName[$part.name] = [pscustomobject]@{
FullPath=(Join-Path $partsDirectory $part.file)
PivotX=[double]$part.pivot.outputPixels.x; PivotY=[double]$part.pivot.outputPixels.y
}
}
foreach ($part in $correctionManifest.parts) {
$partByName[$part.name] = [pscustomobject]@{
FullPath=(Join-Path $correctionDirectory $part.file)
PivotX=[double]$part.rootPivot.outputPixels.x; PivotY=[double]$part.rootPivot.outputPixels.y
}
}
$upperBody = @(
'torso-upper','neck','head-face','hair-front','ponytail-root','ponytail-middle','ponytail-tip',
'upper-arm-a','forearm-a','hand-fan-grip','upper-arm-b','forearm-b','hand-relaxed-b',
'shoulder-armor-a','shoulder-armor-b'
)
$frames = @(
[ordered]@{
Name='idle-inhale'; Label='IDLE · INHALE'; DurationMs=420
UpperBodyY=-3
Overrides=@{
'torso-upper'=@{ Y=315; Scale=.94 }
'head-face'=@{ Y=191 }
'hair-front'=@{ Y=73 }
'ponytail-root'=@{ Y=59; Rotation=-1 }
'ponytail-middle'=@{ Y=91; Rotation=-13 }
'ponytail-tip'=@{ Y=254; Rotation=-7 }
'waist-guard'=@{ Y=296; Scale=.73 }
'front-drape'=@{ Y=303; Rotation=3 }
'coat-panel-01'=@{ Rotation=7 }
'coat-panel-08'=@{ Rotation=-7 }
}
Joints=@{ Shoulder=@(146,211); Elbow=@(130,304); Hand=@(89,211) }
Note='胸腔上提;头、肩与持械手同步,后发轻微滞后。'
},
[ordered]@{
Name='idle-neutral'; Label='IDLE · NEUTRAL'; DurationMs=260
UpperBodyY=0; Overrides=@{}
Joints=@{ Shoulder=@(146,214); Elbow=@(130,307); Hand=@(89,214) }
Note='装配 v2 中性基准。'
},
[ordered]@{
Name='idle-exhale'; Label='IDLE · EXHALE'; DurationMs=420
UpperBodyY=3
Overrides=@{
'torso-upper'=@{ Y=321; Scale=.90 }
'head-face'=@{ Y=197 }
'hair-front'=@{ Y=79 }
'ponytail-root'=@{ Y=65; Rotation=1 }
'ponytail-middle'=@{ Y=99; Rotation=-10 }
'ponytail-tip'=@{ Y=264; Rotation=-4 }
'waist-guard'=@{ Y=301; Scale=.71 }
'front-drape'=@{ Y=308; Rotation=1 }
'coat-panel-01'=@{ Rotation=5 }
'coat-panel-08'=@{ Rotation=-5 }
}
Joints=@{ Shoulder=@(146,217); Elbow=@(130,310); Hand=@(89,217) }
Note='胸腔回落;发尾比头部多下沉 2~3 px。'
},
[ordered]@{
Name='throw-ready'; Label='THROW · READY'; DurationMs=150
UpperBodyY=1
Overrides=@{
'pelvis'=@{ Y=353 }
'torso-upper'=@{ Y=320; Rotation=1 }
'waist-guard'=@{ Y=301 }
'front-drape'=@{ Y=308 }
'thigh-a'=@{ Y=353; Rotation=9 }
'thigh-b'=@{ Y=353; Rotation=-7 }
}
Joints=@{ Shoulder=@(146,215); Elbow=@(130,308); Hand=@(89,215) }
Note='髋部下沉 3 px,形成动作预备。'
},
[ordered]@{
Name='throw-windup'; Label='THROW · WINDUP'; DurationMs=110
UpperBodyY=0
Overrides=@{
'torso-upper'=@{ Rotation=3 }
'head-face'=@{ Rotation=1 }
'hair-front'=@{ Rotation=1 }
'ponytail-root'=@{ Rotation=2 }
'ponytail-middle'=@{ Rotation=-8 }
'ponytail-tip'=@{ Rotation=-1 }
'upper-arm-a'=@{ Rotation=8 }
'forearm-a'=@{ X=133; Y=305; Rotation=180 }
'hand-fan-grip'=@{ X=133; Y=202; Rotation=-15; Scale=.36 }
'shoulder-armor-a'=@{ Rotation=2 }
'front-drape'=@{ Rotation=-2 }
'coat-panel-01'=@{ Rotation=3 }
'coat-panel-08'=@{ Rotation=-9 }
}
Joints=@{ Shoulder=@(146,214); Elbow=@(133,305); Hand=@(133,202) }
Note='前臂回收到面部外侧,武器不遮挡眼睛;马尾与衣摆保持惯性。'
},
[ordered]@{
Name='throw-release'; Label='THROW · RELEASE'; DurationMs=90
UpperBodyY=0
Overrides=@{
'torso-upper'=@{ Rotation=-5 }
'head-face'=@{ Rotation=-2 }
'hair-front'=@{ Rotation=-2 }
'ponytail-root'=@{ Rotation=4; X=218 }
'ponytail-middle'=@{ Rotation=-2; X=302 }
'ponytail-tip'=@{ Rotation=8; X=342 }
'upper-arm-a'=@{ Rotation=65 }
'forearm-a'=@{ X=62; Y=252; Rotation=95; Scale=.30 }
'shoulder-armor-a'=@{ Rotation=8 }
'front-drape'=@{ Rotation=7; X=207 }
'coat-panel-01'=@{ Rotation=11 }
'coat-panel-02'=@{ Rotation=7 }
'coat-panel-07'=@{ Rotation=1 }
'coat-panel-08'=@{ Rotation=-2 }
}
Hidden=@('hand-fan-grip')
Extras=@(
@{ Name='hand-throw-open'; X=-12; Y=244; Rotation=88; Scale=.30 },
@{ Name='weapon-fan-open'; X=-38; Y=220; Rotation=80; Scale=.52 }
)
Joints=@{ Shoulder=@(146,214); Elbow=@(62,252); Hand=@(-12,244) }
Note='肩肘形成清楚的左向伸展;武器进入脱手位置。'
},
[ordered]@{
Name='throw-recover'; Label='THROW · RECOVER'; DurationMs=180
UpperBodyY=1
Overrides=@{
'torso-upper'=@{ Rotation=1; Y=319 }
'head-face'=@{ Rotation=1; Y=195 }
'hair-front'=@{ Rotation=1; Y=77 }
'ponytail-root'=@{ Rotation=-3; Y=64 }
'ponytail-middle'=@{ Rotation=-16; Y=97 }
'ponytail-tip'=@{ Rotation=-12; Y=262 }
'upper-arm-a'=@{ Rotation=26 }
'forearm-a'=@{ X=106; Y=290; Rotation=170; Scale=.34 }
'hand-fan-grip'=@{ X=88; Y=195; Rotation=-10; Scale=.36 }
'shoulder-armor-a'=@{ Rotation=10 }
'front-drape'=@{ Rotation=-3 }
'coat-panel-01'=@{ Rotation=2 }
'coat-panel-08'=@{ Rotation=-10 }
}
Joints=@{ Shoulder=@(146,215); Elbow=@(106,290); Hand=@(88,195) }
Note='手臂回收,软性部件反向摆动并准备回到中性。'
}
)
function Copy-Transform {
param($Item)
return [ordered]@{
Name=[string]$Item.part
X=[double]$Item.targetPivot.x
Y=[double]$Item.targetPivot.y
Rotation=[double]$Item.rotationDegrees
Scale=[double]$Item.scale
Visible=$true
}
}
function Resolve-FrameLayout {
param($Frame)
$result = @()
$hiddenParts = @($Frame.Hidden)
foreach ($item in $baseLayout.items) {
$transform = Copy-Transform $item
if ($transform.Name -in $upperBody) { $transform.Y += [double]$Frame.UpperBodyY }
if ($Frame.Overrides.ContainsKey($transform.Name)) {
$override = $Frame.Overrides[$transform.Name]
foreach ($key in $override.Keys) { $transform[$key] = $override[$key] }
}
if ($transform.Name -in $hiddenParts) { $transform.Visible = $false }
$transform.X += 50
$result += $transform
}
foreach ($extra in @($Frame.Extras)) {
if ($null -eq $extra) { continue }
$result += [ordered]@{
Name=[string]$extra.Name; X=[double]$extra.X+50; Y=[double]$extra.Y
Rotation=[double]$extra.Rotation; Scale=[double]$extra.Scale; Visible=$true
}
}
return $result
}
function Draw-Part {
param(
[Drawing.Graphics]$Graphics, [Drawing.Image]$Image,
[double]$PivotX, [double]$PivotY,
[double]$TargetX, [double]$TargetY,
[double]$Rotation, [double]$Scale
)
$state = $Graphics.Save()
$Graphics.TranslateTransform([single]$TargetX, [single]$TargetY)
$Graphics.RotateTransform([single]$Rotation)
$Graphics.ScaleTransform([single]$Scale, [single]$Scale)
$Graphics.DrawImageUnscaled($Image, [int][Math]::Round(-$PivotX), [int][Math]::Round(-$PivotY))
$Graphics.Restore($state)
}
$images = @{}
$renderedFrames = @()
$manifestFrames = @()
try {
foreach ($frame in $frames) {
$resolved = Resolve-FrameLayout $frame
$canvas = [Drawing.Bitmap]::new(600, 760, [Drawing.Imaging.PixelFormat]::Format32bppArgb)
$graphics = [Drawing.Graphics]::FromImage($canvas)
$graphics.SmoothingMode = [Drawing.Drawing2D.SmoothingMode]::AntiAlias
$graphics.InterpolationMode = [Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
$graphics.PixelOffsetMode = [Drawing.Drawing2D.PixelOffsetMode]::HighQuality
$graphics.Clear([Drawing.Color]::Transparent)
foreach ($transform in $resolved) {
if (-not $transform.Visible) { continue }
$part = $partByName[$transform.Name]
if (-not $images.ContainsKey($transform.Name)) {
$images[$transform.Name] = [Drawing.Bitmap]::new($part.FullPath)
}
Draw-Part -Graphics $graphics -Image $images[$transform.Name] `
-PivotX $part.PivotX -PivotY $part.PivotY `
-TargetX $transform.X -TargetY $transform.Y -Rotation $transform.Rotation -Scale $transform.Scale
}
$fileName = "$($frame.Name).png"
$filePath = Join-Path $outputDirectory $fileName
$canvas.Save($filePath, [Drawing.Imaging.ImageFormat]::Png)
$graphics.Dispose()
$renderedFrames += [ordered]@{ Definition=$frame; Image=$canvas; Layout=$resolved; File=$fileName }
$manifestFrames += [ordered]@{
name=$frame.Name; label=$frame.Label; file=$fileName; durationMs=$frame.DurationMs
note=$frame.Note; joints=$frame.Joints; transforms=$resolved
}
}
[ordered]@{
characterId='02-xinyin'
direction='front-right'
version=3
status='art-motion-validation'
canvas=[ordered]@{ width=600; height=760; origin='top-left'; units='pixels'; assemblyOffsetX=50 }
baseLayout='assets/images/2d-game-characters/02-xinyin/assembled/front-right/assembly-layout-v4.json'
sequence=@('idle-inhale','idle-neutral','idle-exhale','idle-neutral','throw-ready','throw-windup','throw-release','throw-recover','idle-neutral')
loopNotes=[ordered]@{ idle='inhale → neutral → exhale → neutral'; throw='ready → windup → release → recover' }
frames=$manifestFrames
} | ConvertTo-Json -Depth 9 | Set-Content -LiteralPath $motionManifestPath -Encoding utf8
$board = [Drawing.Bitmap]::new(2100, 1390, [Drawing.Imaging.PixelFormat]::Format32bppArgb)
$g = [Drawing.Graphics]::FromImage($board)
$g.SmoothingMode = [Drawing.Drawing2D.SmoothingMode]::AntiAlias
$g.InterpolationMode = [Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
$g.PixelOffsetMode = [Drawing.Drawing2D.PixelOffsetMode]::HighQuality
$g.Clear([Drawing.Color]::FromArgb(255, 16, 20, 29))
$titleBrush = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(255, 241, 245, 252))
$mutedBrush = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(255, 151, 171, 201))
$panelBrush = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(255, 24, 30, 42))
$panelPen = [Drawing.Pen]::new([Drawing.Color]::FromArgb(255, 65, 82, 112), 2)
$bonePen = [Drawing.Pen]::new([Drawing.Color]::FromArgb(230, 71, 210, 255), 4)
$jointPen = [Drawing.Pen]::new([Drawing.Color]::FromArgb(255, 255, 86, 116), 3)
$fontTitle = [Drawing.Font]::new('Segoe UI Semibold', 28)
$fontLabel = [Drawing.Font]::new('Segoe UI Semibold', 16)
$fontText = [Drawing.Font]::new('Segoe UI', 11)
$g.DrawString('XIN YIN — FRONT-RIGHT MOTION VALIDATION V3', $fontTitle, $titleBrush, 48, 28)
$g.DrawString('idle breathing + throw joint-range test | cyan: arm chain | red: pivots', $fontText, $mutedBrush, 51, 73)
$cellWidth=490; $cellHeight=590; $startX=45; $startY=112; $gapX=20; $gapY=28; $scale=.62
for ($i=0; $i -lt $renderedFrames.Count; $i++) {
$row = [Math]::Floor($i / 4); $col = $i % 4
$x = $startX + $col * ($cellWidth + $gapX)
$y = $startY + $row * ($cellHeight + $gapY)
$g.FillRectangle($panelBrush, $x, $y, $cellWidth, $cellHeight)
$g.DrawRectangle($panelPen, $x, $y, $cellWidth, $cellHeight)
$g.DrawString($renderedFrames[$i].Definition.Label, $fontLabel, $titleBrush, $x+18, $y+14)
$g.DrawString("$($renderedFrames[$i].Definition.DurationMs) ms", $fontText, $mutedBrush, $x+18, $y+43)
$drawX = $x + [int](($cellWidth - 600*$scale)/2)
$drawY = $y + 65
$g.DrawImage($renderedFrames[$i].Image, $drawX, $drawY, [int](600*$scale), [int](760*$scale))
$joints = $renderedFrames[$i].Definition.Joints
$points = @($joints.Shoulder,$joints.Elbow,$joints.Hand)
for ($p=0; $p -lt 2; $p++) {
$g.DrawLine($bonePen,
$drawX + [single](($points[$p][0]+50)*$scale), $drawY + [single]($points[$p][1]*$scale),
$drawX + [single](($points[$p+1][0]+50)*$scale), $drawY + [single]($points[$p+1][1]*$scale))
}
foreach ($point in $points) {
$px=$drawX+[single](($point[0]+50)*$scale); $py=$drawY+[single]($point[1]*$scale)
$g.DrawEllipse($jointPen,$px-5,$py-5,10,10)
}
$g.DrawString($renderedFrames[$i].Definition.Note, $fontText, $mutedBrush, [Drawing.RectangleF]::new($x+16,$y+542,$cellWidth-32,40))
}
$g.DrawString('Validation target: silhouette stability, shoulder/elbow overlap, hair and coat secondary motion. No VFX or engine interpolation.', $fontText, $mutedBrush, 48, 1354)
$board.Save($previewPath, [Drawing.Imaging.ImageFormat]::Png)
$fontText.Dispose(); $fontLabel.Dispose(); $fontTitle.Dispose()
$jointPen.Dispose(); $bonePen.Dispose(); $panelPen.Dispose()
$panelBrush.Dispose(); $mutedBrush.Dispose(); $titleBrush.Dispose()
$g.Dispose(); $board.Dispose()
}
finally {
foreach ($frame in $renderedFrames) { if ($null -ne $frame.Image) { $frame.Image.Dispose() } }
foreach ($image in $images.Values) { $image.Dispose() }
}
Write-Output "Rendered $($frames.Count) motion keyframes."
Write-Output $outputDirectory
Write-Output $motionManifestPath
Write-Output $previewPath
+269
View File
@@ -0,0 +1,269 @@
param(
[string]$WorkspaceRoot = (Split-Path -Parent $PSScriptRoot),
[ValidateSet('p0', 'p1')]
[string]$Set = 'p0',
[ValidateSet('v1', 'v2')]
[string]$Variant = 'v1'
)
Add-Type -AssemblyName System.Drawing
$helperSource = @'
using System;
using System.Drawing;
using System.Drawing.Imaging;
public static class SpriteCropper
{
private static bool IsBackgroundLike(Color c)
{
int max = Math.Max(c.R, Math.Max(c.G, c.B));
int min = Math.Min(c.R, Math.Min(c.G, c.B));
return c.A > 0 && max > 165 && (max - min) < 42;
}
public static Bitmap Extract(string path, Rectangle crop)
{
using (var source = new Bitmap(path))
{
var clipped = Rectangle.Intersect(crop, new Rectangle(0, 0, source.Width, source.Height));
var image = new Bitmap(clipped.Width, clipped.Height, PixelFormat.Format32bppArgb);
using (var g = Graphics.FromImage(image))
{
g.DrawImage(source, new Rectangle(0, 0, image.Width, image.Height), clipped, GraphicsUnit.Pixel);
}
int width = image.Width;
int height = image.Height;
var visited = new bool[width * height];
var queue = new int[width * height];
int queueHead = 0;
int queueTail = 0;
Action<int, int> seed = (x, y) =>
{
int index = y * width + x;
if (!visited[index] && IsBackgroundLike(image.GetPixel(x, y)))
{
visited[index] = true;
queue[queueTail++] = index;
}
};
for (int x = 0; x < width; x++) { seed(x, 0); seed(x, height - 1); }
for (int y = 0; y < height; y++) { seed(0, y); seed(width - 1, y); }
int[] dx = { 1, -1, 0, 0 };
int[] dy = { 0, 0, 1, -1 };
while (queueHead < queueTail)
{
int index = queue[queueHead++];
int x = index % width;
int y = index / width;
image.SetPixel(x, y, Color.Transparent);
for (int i = 0; i < 4; i++)
{
int nx = x + dx[i];
int ny = y + dy[i];
if (nx < 0 || nx >= width || ny < 0 || ny >= height) continue;
int next = ny * width + nx;
if (!visited[next] && IsBackgroundLike(image.GetPixel(nx, ny)))
{
visited[next] = true;
queue[queueTail++] = next;
}
}
}
int minX = width, minY = height, maxX = -1, maxY = -1;
for (int y = 0; y < height; y++)
{
for (int x = 0; x < width; x++)
{
if (image.GetPixel(x, y).A < 16) continue;
minX = Math.Min(minX, x);
minY = Math.Min(minY, y);
maxX = Math.Max(maxX, x);
maxY = Math.Max(maxY, y);
}
}
if (maxX < minX || maxY < minY) return image;
var bounds = Rectangle.FromLTRB(Math.Max(0, minX - 2), Math.Max(0, minY - 2), Math.Min(width, maxX + 3), Math.Min(height, maxY + 3));
var trimmed = new Bitmap(bounds.Width, bounds.Height, PixelFormat.Format32bppArgb);
using (var g = Graphics.FromImage(trimmed))
{
g.DrawImage(image, new Rectangle(0, 0, trimmed.Width, trimmed.Height), bounds, GraphicsUnit.Pixel);
}
image.Dispose();
return trimmed;
}
}
}
'@
$compilerReferences = @(
[System.Drawing.Bitmap].Assembly.Location,
[System.Drawing.Color].Assembly.Location,
[System.Reflection.Assembly]::Load('System.Private.Windows.GdiPlus').Location,
[System.Reflection.Assembly]::Load('System.Private.Windows.Core').Location,
[System.Reflection.Assembly]::Load('System.Collections').Location,
[System.Reflection.Assembly]::Load('System.Runtime').Location,
[System.Object].Assembly.Location
) | Select-Object -Unique
Add-Type -TypeDefinition $helperSource -ReferencedAssemblies $compilerReferences
$board1 = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin\source\action-keyposes\xinyin-p0-idle-move-attacks-v1.png'
$board2 = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin\source\action-keyposes\xinyin-p0-burst-hit-defeat-v1.png'
$corrections = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin\source\action-keyposes\xinyin-p0-corrections-v2.png'
$p1Board1 = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin\source\action-keyposes\xinyin-p1-ready-dodge-weakpoint-v1.png'
$p1Board2 = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin\source\action-keyposes\xinyin-p1-cover-v1.png'
$p1Board1V2 = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin\source\action-keyposes\xinyin-p1-ready-dodge-weakpoint-v2.png'
$p1BoardLeft = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin\source\action-keyposes\xinyin-p1-cover-left-v1.png'
if ($Set -eq 'p1') {
$output = Join-Path $WorkspaceRoot "assets\images\2d-game-characters\02-xinyin\previews\xinyin-p1-readability-test-$Variant.png"
}
else {
$output = Join-Path $WorkspaceRoot "assets\images\2d-game-characters\02-xinyin\previews\xinyin-action-readability-test-$Variant.png"
}
if ($Set -eq 'p1' -and $Variant -eq 'v2') {
$poses = @(
@{ Name = 'READY'; Path = $p1Board1V2; Crop = [Drawing.Rectangle]::new(780, 35, 390, 300); ReferenceHeight = 300 },
@{ Name = 'DODGE V2'; Path = $p1Board1V2; Crop = [Drawing.Rectangle]::new(500, 365, 510, 290); ReferenceHeight = 290 },
@{ Name = 'WEAKPOINT'; Path = $p1Board1V2; Crop = [Drawing.Rectangle]::new(770, 685, 480, 315); ReferenceHeight = 305 },
@{ Name = 'COVER IDLE R'; Path = $p1Board2; Crop = [Drawing.Rectangle]::new(1120, 45, 416, 445); ReferenceHeight = 320 },
@{ Name = 'COVER ATTACK R'; Path = $p1Board2; Crop = [Drawing.Rectangle]::new(600, 545, 470, 435); ReferenceHeight = 320 },
@{ Name = 'COVER ATTACK L'; Path = $p1BoardLeft; Crop = [Drawing.Rectangle]::new(500, 535, 530, 450); ReferenceHeight = 320 }
)
}
elseif ($Set -eq 'p1') {
$poses = @(
@{ Name = 'READY'; Path = $p1Board1; Crop = [Drawing.Rectangle]::new(780, 35, 390, 300); ReferenceHeight = 300 },
@{ Name = 'DODGE'; Path = $p1Board1; Crop = [Drawing.Rectangle]::new(500, 365, 510, 290); ReferenceHeight = 290 },
@{ Name = 'WEAKPOINT'; Path = $p1Board1; Crop = [Drawing.Rectangle]::new(770, 685, 480, 315); ReferenceHeight = 305 },
@{ Name = 'COVER IDLE'; Path = $p1Board2; Crop = [Drawing.Rectangle]::new(1120, 45, 416, 445); ReferenceHeight = 320 },
@{ Name = 'COVER ATTACK'; Path = $p1Board2; Crop = [Drawing.Rectangle]::new(600, 545, 470, 435); ReferenceHeight = 320 }
)
}
elseif ($Variant -eq 'v2') {
$poses = @(
@{ Name = 'IDLE'; Path = $board1; Crop = [Drawing.Rectangle]::new(500, 10, 290, 245); ReferenceHeight = 250 },
@{ Name = 'MOVE'; Path = $board1; Crop = [Drawing.Rectangle]::new(120, 270, 310, 225); ReferenceHeight = 250 },
@{ Name = 'ATTACK 1'; Path = $corrections; Crop = [Drawing.Rectangle]::new(560, 10, 450, 235); ReferenceHeight = 245 },
@{ Name = 'ATTACK 2'; Path = $corrections; Crop = [Drawing.Rectangle]::new(560, 270, 450, 225); ReferenceHeight = 245 },
@{ Name = 'BURST'; Path = $board2; Crop = [Drawing.Rectangle]::new(710, 10, 440, 345); ReferenceHeight = 305 },
@{ Name = 'HIT'; Path = $corrections; Crop = [Drawing.Rectangle]::new(330, 520, 440, 210); ReferenceHeight = 235 },
@{ Name = 'DEFEAT'; Path = $corrections; Crop = [Drawing.Rectangle]::new(1110, 770, 426, 240); ReferenceHeight = 250 }
)
}
else {
$poses = @(
@{ Name = 'IDLE'; Path = $board1; Crop = [Drawing.Rectangle]::new(500, 10, 290, 245); ReferenceHeight = 250 },
@{ Name = 'MOVE'; Path = $board1; Crop = [Drawing.Rectangle]::new(120, 270, 310, 225); ReferenceHeight = 250 },
@{ Name = 'ATTACK 1'; Path = $board1; Crop = [Drawing.Rectangle]::new(590, 510, 410, 225); ReferenceHeight = 250 },
@{ Name = 'ATTACK 2'; Path = $board1; Crop = [Drawing.Rectangle]::new(575, 755, 430, 250); ReferenceHeight = 250 },
@{ Name = 'BURST'; Path = $board2; Crop = [Drawing.Rectangle]::new(710, 10, 440, 345); ReferenceHeight = 305 },
@{ Name = 'HIT'; Path = $board2; Crop = [Drawing.Rectangle]::new(350, 380, 430, 270); ReferenceHeight = 285 },
@{ Name = 'DEFEAT'; Path = $board2; Crop = [Drawing.Rectangle]::new(1040, 680, 496, 330); ReferenceHeight = 285 }
)
}
$canvas = [Drawing.Bitmap]::new(2000, 1200, [Drawing.Imaging.PixelFormat]::Format32bppArgb)
$graphics = [Drawing.Graphics]::FromImage($canvas)
$graphics.SmoothingMode = [Drawing.Drawing2D.SmoothingMode]::AntiAlias
$graphics.InterpolationMode = [Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
$graphics.PixelOffsetMode = [Drawing.Drawing2D.PixelOffsetMode]::HighQuality
$graphics.Clear([Drawing.Color]::FromArgb(255, 17, 22, 31))
$headerBrush = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(242, 244, 250))
$mutedBrush = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(156, 171, 195))
$linePen = [Drawing.Pen]::new([Drawing.Color]::FromArgb(110, 118, 145, 183), 2)
$gridPen = [Drawing.Pen]::new([Drawing.Color]::FromArgb(220, 106, 166, 230), 2)
$gridFill = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(34, 75, 128, 185))
$shadowBrush = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(80, 0, 0, 0))
$fontTitle = [Drawing.Font]::new('Segoe UI Semibold', 26)
$fontSubtitle = [Drawing.Font]::new('Segoe UI', 14)
$fontLabel = [Drawing.Font]::new('Segoe UI Semibold', 14)
$fontRow = [Drawing.Font]::new('Segoe UI Semibold', 18)
$setLabel = if ($Set -eq 'p1') { 'P1 READABILITY TEST' } else { 'ACTION READABILITY TEST' }
$graphics.DrawString("XIN YIN — $setLabel $($Variant.ToUpper())", $fontTitle, $headerBrush, 52, 28)
$directionLabel = if ($Set -eq 'p1' -and $Variant -eq 'v2') { '4.75H front-right / front-left masters' } else { '4.75H front-right master' }
$graphics.DrawString("$directionLabel | base unit height 176 px | base cell 128 × 64 px", $fontSubtitle, $mutedBrush, 55, 70)
$graphics.DrawLine($linePen, 52, 104, 1948, 104)
$columnCenters = if ($poses.Count -eq 5) {
@(360, 680, 1000, 1320, 1640)
}
elseif ($poses.Count -eq 6) {
@(280, 568, 856, 1144, 1432, 1720)
}
else {
@(245, 495, 745, 995, 1245, 1495, 1745)
}
for ($i = 0; $i -lt $poses.Count; $i++) {
$size = $graphics.MeasureString($poses[$i].Name, $fontLabel)
$graphics.DrawString($poses[$i].Name, $fontLabel, $mutedBrush, $columnCenters[$i] - $size.Width / 2, 122)
}
$rows = @(
@{ Label = '100%'; UnitHeight = 176; CellWidth = 128; CellHeight = 64; CenterY = 400 },
@{ Label = '75%'; UnitHeight = 132; CellWidth = 96; CellHeight = 48; CenterY = 735 },
@{ Label = '50%'; UnitHeight = 88; CellWidth = 64; CellHeight = 32; CenterY = 1040 }
)
$sprites = @()
try {
foreach ($pose in $poses) {
$sprites += [SpriteCropper]::Extract($pose.Path, $pose.Crop)
}
foreach ($row in $rows) {
$graphics.FillRectangle([Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(22, 255, 255, 255)), 34, $row.CenterY - 220, 1932, 285)
$graphics.DrawString($row.Label, $fontRow, $headerBrush, 55, $row.CenterY - 205)
$graphics.DrawString("unit $($row.UnitHeight) px", $fontSubtitle, $mutedBrush, 55, $row.CenterY - 172)
for ($i = 0; $i -lt $poses.Count; $i++) {
$cx = $columnCenters[$i]
$cy = $row.CenterY
$halfW = $row.CellWidth / 2
$halfH = $row.CellHeight / 2
$diamond = [Drawing.PointF[]]@(
[Drawing.PointF]::new($cx, $cy - $halfH),
[Drawing.PointF]::new($cx + $halfW, $cy),
[Drawing.PointF]::new($cx, $cy + $halfH),
[Drawing.PointF]::new($cx - $halfW, $cy)
)
$graphics.FillPolygon($gridFill, $diamond)
$graphics.DrawPolygon($gridPen, $diamond)
$graphics.FillEllipse($shadowBrush, $cx - $halfW * 0.34, $cy - $halfH * 0.05, $halfW * 0.68, [Math]::Max(4, $halfH * 0.22))
$source = $sprites[$i]
$scale = $row.UnitHeight / [double]$poses[$i].ReferenceHeight
$drawW = [int][Math]::Round($source.Width * $scale)
$drawH = [int][Math]::Round($source.Height * $scale)
$drawX = [int][Math]::Round($cx - $drawW / 2)
$drawY = [int][Math]::Round($cy + 6 - $drawH)
$graphics.DrawImage($source, [Drawing.Rectangle]::new($drawX, $drawY, $drawW, $drawH))
}
}
$evaluationText = if ($Set -eq 'p1') {
'Evaluation target: ready-state clarity, dodge afterimage balance, reticle separation, and cover exposure.'
}
else {
'Evaluation target: silhouette, weapon-hand readability, secondary-motion clutter, and single-cell footprint.'
}
$graphics.DrawString($evaluationText, $fontSubtitle, $mutedBrush, 52, 1160)
$canvas.Save($output, [Drawing.Imaging.ImageFormat]::Png)
}
finally {
foreach ($sprite in $sprites) { if ($null -ne $sprite) { $sprite.Dispose() } }
$fontTitle.Dispose(); $fontSubtitle.Dispose(); $fontLabel.Dispose(); $fontRow.Dispose()
$headerBrush.Dispose(); $mutedBrush.Dispose(); $linePen.Dispose(); $gridPen.Dispose(); $gridFill.Dispose(); $shadowBrush.Dispose()
$graphics.Dispose(); $canvas.Dispose()
}
Get-Item -LiteralPath $output
+325
View File
@@ -0,0 +1,325 @@
param(
[string]$WorkspaceRoot = (Split-Path -Parent $PSScriptRoot),
[int]$Padding = 8
)
Add-Type -AssemblyName System.Drawing
$helperSource = @'
using System;
using System.Collections;
using System.Drawing;
using System.Drawing.Imaging;
public sealed class AlphaMaskedComponent
{
public int Id { get; set; }
public int Label { get; set; }
public int Area { get; set; }
public Rectangle Bounds { get; set; }
public Bitmap Image { get; set; }
}
public static class AlphaMaskExtractor
{
public static AlphaMaskedComponent[] ExtractAll(string path, int alphaThreshold, int minimumArea, int padding)
{
using (var source = new Bitmap(path))
{
int width = source.Width;
int height = source.Height;
var foreground = new bool[width * height];
var labels = new int[width * height];
var queue = new int[width * height];
for (int y = 0; y < height; y++)
{
int row = y * width;
for (int x = 0; x < width; x++)
foreground[row + x] = source.GetPixel(x, y).A >= alphaThreshold;
}
var components = new ArrayList();
int[] dx = { -1, 0, 1, -1, 1, -1, 0, 1 };
int[] dy = { -1, -1, -1, 0, 0, 1, 1, 1 };
int nextLabel = 0;
for (int y = 0; y < height; y++)
{
for (int x = 0; x < width; x++)
{
int start = y * width + x;
if (labels[start] != 0 || !foreground[start]) continue;
nextLabel++;
int head = 0, tail = 0, area = 0;
int minX = x, minY = y, maxX = x, maxY = y;
labels[start] = nextLabel;
queue[tail++] = start;
while (head < tail)
{
int index = queue[head++];
int px = index % width;
int py = index / width;
area++;
if (px < minX) minX = px;
if (px > maxX) maxX = px;
if (py < minY) minY = py;
if (py > maxY) maxY = py;
for (int i = 0; i < 8; i++)
{
int nx = px + dx[i];
int ny = py + dy[i];
if (nx < 0 || nx >= width || ny < 0 || ny >= height) continue;
int next = ny * width + nx;
if (labels[next] != 0 || !foreground[next]) continue;
labels[next] = nextLabel;
queue[tail++] = next;
}
}
if (area >= minimumArea)
{
components.Add(new AlphaMaskedComponent {
Label = nextLabel,
Area = area,
Bounds = Rectangle.FromLTRB(minX, minY, maxX + 1, maxY + 1)
});
}
}
}
var result = new AlphaMaskedComponent[components.Count];
for (int i = 0; i < components.Count; i++) result[i] = (AlphaMaskedComponent)components[i];
Array.Sort(result, (a, b) => {
int rowCompare = a.Bounds.Top.CompareTo(b.Bounds.Top);
return rowCompare != 0 ? rowCompare : a.Bounds.Left.CompareTo(b.Bounds.Left);
});
for (int i = 0; i < result.Length; i++)
{
var component = result[i];
component.Id = i + 1;
var bitmap = new Bitmap(component.Bounds.Width + padding * 2, component.Bounds.Height + padding * 2, PixelFormat.Format32bppArgb);
for (int py = component.Bounds.Top; py < component.Bounds.Bottom; py++)
{
for (int px = component.Bounds.Left; px < component.Bounds.Right; px++)
{
int sourceIndex = py * width + px;
if (labels[sourceIndex] != component.Label) continue;
bitmap.SetPixel(px - component.Bounds.Left + padding, py - component.Bounds.Top + padding, source.GetPixel(px, py));
}
}
component.Image = bitmap;
}
return result;
}
}
}
'@
$compilerReferences = @(
[System.Drawing.Bitmap].Assembly.Location,
[System.Drawing.Color].Assembly.Location,
[System.Reflection.Assembly]::Load('System.Private.Windows.GdiPlus').Location,
[System.Reflection.Assembly]::Load('System.Private.Windows.Core').Location,
[System.Reflection.Assembly]::Load('System.Collections').Location,
[System.Reflection.Assembly]::Load('System.Runtime').Location,
[System.Object].Assembly.Location
) | Select-Object -Unique
Add-Type -TypeDefinition $helperSource -ReferencedAssemblies $compilerReferences
$sourcePath = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin\source\xinyin-front-right-parts-sheet-v1.png'
$characterRoot = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin'
$outputDirectory = Join-Path $characterRoot 'parts\front-right\v1'
$referenceDirectory = Join-Path $characterRoot 'reference'
$previewDirectory = Join-Path $characterRoot 'previews'
$manifestPath = Join-Path $outputDirectory 'parts-manifest.json'
$contactSheetPath = Join-Path $previewDirectory 'xinyin-front-right-extracted-parts-v1.png'
$referencePath = Join-Path $referenceDirectory 'xinyin-front-right-assembled-reference-v1.png'
New-Item -ItemType Directory -Force -Path $outputDirectory, $referenceDirectory, $previewDirectory | Out-Null
# Coordinates come from the alpha-component diagnostic. Component 11 is the assembled reference.
# Pivot values are normalized inside the non-padding content bounds, not the exported canvas.
$parts = @(
@{ Id=1; Name='hair-back-main'; Label='后发主体'; Category='hair'; Rect=@(836,23,305,270); Pivot=@(.50,.08); Layer=-100; Notes='两个马尾方案被细发丝粘连;首次装配验证判定为参考件,不直接进入骨骼' },
@{ Id=2; Name='hair-back-segment-02'; Label='后发分片 02'; Category='hair'; Rect=@(1130,39,201,247); Pivot=@(.40,.08); Layer=-98; Notes='方向归属待装配确认' },
@{ Id=3; Name='hair-back-segment-04'; Label='后发分片 04'; Category='hair'; Rect=@(1484,53,140,187); Pivot=@(.45,.08); Layer=-94; Notes='首次装配 v2 选用的后发主片' },
@{ Id=4; Name='hair-front'; Label='前发与侧鬓'; Category='hair'; Rect=@(522,54,130,179); Pivot=@(.50,.12); Layer=35; Notes='位于面部之前' },
@{ Id=5; Name='hair-side-segment-01'; Label='侧发分片 01'; Category='hair'; Rect=@(666,62,90,171); Pivot=@(.50,.08); Layer=-88; Notes='方向归属待装配确认' },
@{ Id=6; Name='hair-back-segment-03'; Label='后发分片 03'; Category='hair'; Rect=@(1330,66,132,186); Pivot=@(.45,.08); Layer=-96; Notes='首次装配 v2 选用的后发辅片' },
@{ Id=7; Name='head-face'; Label='头部与面部'; Category='body'; Rect=@(427,73,86,115); Pivot=@(.50,.91); Layer=30; Notes='枢轴靠近颈部连接点' },
@{ Id=8; Name='hair-side-segment-02'; Label='侧发分片 02'; Category='hair'; Rect=@(778,76,56,157); Pivot=@(.50,.07); Layer=-86; Notes='方向归属待装配确认' },
@{ Id=9; Name='hair-ornament-long'; Label='长发饰'; Category='ornament'; Rect=@(1629,96,50,147); Pivot=@(.50,.08); Layer=42; Notes='含花饰与垂坠' },
@{ Id=10; Name='hair-ornament-short'; Label='短发饰'; Category='ornament'; Rect=@(1695,96,30,98); Pivot=@(.50,.08); Layer=41; Notes='含花饰与流苏' },
@{ Id=12; Name='neck'; Label='颈部'; Category='body'; Rect=@(449,211,43,45); Pivot=@(.50,.75); Layer=5; Notes='头部和躯干之间' },
@{ Id=13; Name='torso-upper'; Label='上半身躯干'; Category='body'; Rect=@(401,260,124,156); Pivot=@(.50,.92); Layer=10; Notes='根枢轴靠近腰线' },
@{ Id=14; Name='waist-guard'; Label='腰封与短裙'; Category='body'; Rect=@(536,285,183,186); Pivot=@(.50,.18); Layer=4; Notes='上端连接躯干' },
@{ Id=15; Name='upper-arm-sleeve-a'; Label='袖片与上臂 A'; Category='arm'; Rect=@(843,301,120,202); Pivot=@(.58,.08); Layer=14; Notes='左右归属待装配确认' },
@{ Id=16; Name='pelvis'; Label='骨盆与内层短裤'; Category='body'; Rect=@(720,303,107,102); Pivot=@(.50,.16); Layer=2; Notes='角色主根节点候选' },
@{ Id=17; Name='upper-arm-sleeve-b'; Label='袖片与上臂 B'; Category='arm'; Rect=@(996,304,106,211); Pivot=@(.42,.08); Layer=14; Notes='左右归属待装配确认' },
@{ Id=18; Name='forearm-hand-a'; Label='前臂与手 A'; Category='arm'; Rect=@(1110,321,59,222); Pivot=@(.50,.08); Layer=16; Notes='肘部连接点在上端' },
@{ Id=19; Name='arm-straight-variant'; Label='直臂替换件'; Category='arm'; Rect=@(1275,336,107,197);Pivot=@(.34,.08); Layer=16; Notes='备用动作变体,装配时择一使用' },
@{ Id=20; Name='forearm-hand-b'; Label='前臂与手 B'; Category='arm'; Rect=@(1184,340,83,207); Pivot=@(.50,.08); Layer=16; Notes='肘部连接点在上端' },
@{ Id=21; Name='weapon-fan-open'; Label='展开羽刃扇'; Category='weapon'; Rect=@(1634,363,99,165); Pivot=@(.50,.88); Layer=50; Notes='枢轴位于柄部' },
@{ Id=22; Name='weapon-hand-fan'; Label='持扇手替换件'; Category='arm'; Rect=@(1444,382,93,133); Pivot=@(.42,.88); Layer=48; Notes='动作替换件,含手与武器' },
@{ Id=23; Name='weapon-blade-single'; Label='单枚羽刃'; Category='weapon'; Rect=@(1563,389,29,130); Pivot=@(.50,.82); Layer=50; Notes='投掷物或手持物' },
@{ Id=24; Name='hand-open'; Label='张开手替换件'; Category='arm'; Rect=@(1391,409,55,77); Pivot=@(.50,.08); Layer=18; Notes='腕部连接点在上端' },
@{ Id=25; Name='leg-full-variant'; Label='整腿替换件'; Category='leg'; Rect=@(437,419,111,426); Pivot=@(.50,.04); Layer=-12; Notes='备用动作变体,装配时择一使用' },
@{ Id=26; Name='thigh-b'; Label='大腿 B'; Category='leg'; Rect=@(727,425,94,169); Pivot=@(.50,.05); Layer=-8; Notes='左右归属待装配确认' },
@{ Id=27; Name='thigh-a'; Label='大腿 A'; Category='leg'; Rect=@(552,471,76,133); Pivot=@(.50,.05); Layer=-8; Notes='左右归属待装配确认' },
@{ Id=28; Name='shoulder-armor-b'; Label='肩甲 B'; Category='armor'; Rect=@(1002,510,97,86); Pivot=@(.50,.18); Layer=20; Notes='左右归属待装配确认' },
@{ Id=29; Name='shoulder-armor-a'; Label='肩甲 A'; Category='armor'; Rect=@(887,512,91,85); Pivot=@(.50,.18); Layer=20; Notes='左右归属待装配确认' },
@{ Id=30; Name='shin-boot-a'; Label='小腿与靴 A'; Category='leg'; Rect=@(561,592,90,242); Pivot=@(.50,.05); Layer=-7; Notes='膝部连接点在上端' },
@{ Id=31; Name='coat-panel-03'; Label='衣摆分片 03'; Category='cloth'; Rect=@(1262,594,90,252); Pivot=@(.50,.04); Layer=-37; Notes='方向归属待装配确认' },
@{ Id=32; Name='coat-panel-05'; Label='衣摆分片 05'; Category='cloth'; Rect=@(1405,595,64,219); Pivot=@(.50,.04); Layer=-35; Notes='方向归属待装配确认' },
@{ Id=33; Name='coat-panel-06'; Label='衣摆分片 06'; Category='cloth'; Rect=@(1475,595,86,258); Pivot=@(.50,.04); Layer=-34; Notes='方向归属待装配确认' },
@{ Id=34; Name='coat-panel-02'; Label='衣摆分片 02'; Category='cloth'; Rect=@(1136,596,117,262);Pivot=@(.50,.04); Layer=-38; Notes='方向归属待装配确认' },
@{ Id=35; Name='coat-panel-01'; Label='衣摆分片 01'; Category='cloth'; Rect=@(1084,597,94,240); Pivot=@(.50,.04); Layer=-39; Notes='方向归属待装配确认' },
@{ Id=36; Name='coat-panel-08'; Label='衣摆分片 08'; Category='cloth'; Rect=@(1673,598,92,201); Pivot=@(.50,.04); Layer=-32; Notes='方向归属待装配确认' },
@{ Id=37; Name='coat-panel-07'; Label='衣摆分片 07'; Category='cloth'; Rect=@(1565,599,175,239);Pivot=@(.50,.04); Layer=-33; Notes='方向归属待装配确认' },
@{ Id=38; Name='shin-boot-b'; Label='小腿与靴 B'; Category='leg'; Rect=@(753,600,64,246); Pivot=@(.50,.05); Layer=-7; Notes='膝部连接点在上端' },
@{ Id=39; Name='coat-panel-04'; Label='衣摆分片 04'; Category='cloth'; Rect=@(1331,601,80,237); Pivot=@(.50,.04); Layer=-36; Notes='方向归属待装配确认' },
@{ Id=40; Name='front-drape'; Label='前腰布与垂饰'; Category='cloth'; Rect=@(861,614,129,266); Pivot=@(.50,.04); Layer=6; Notes='位于腰封前侧' },
@{ Id=41; Name='waist-pouch'; Label='腰包与流苏'; Category='accessory'; Rect=@(1002,620,95,143); Pivot=@(.28,.08); Layer=22; Notes='连接腰侧' }
)
$source = [Drawing.Bitmap]::new($sourcePath)
$maskedComponents = [AlphaMaskExtractor]::ExtractAll($sourcePath, 16, 80, $Padding)
$maskedById = @{}
foreach ($component in $maskedComponents) { $maskedById[$component.Id] = $component }
$manifestParts = @()
$exported = @()
try {
foreach ($part in $parts) {
$rect = [Drawing.Rectangle]::new($part.Rect[0], $part.Rect[1], $part.Rect[2], $part.Rect[3])
$canvas = $maskedById[$part.Id].Image
$fileName = ('fr-c{0:d2}-{1}.png' -f $part.Id, $part.Name)
$filePath = Join-Path $outputDirectory $fileName
$canvas.Save($filePath, [Drawing.Imaging.ImageFormat]::Png)
$pivotPxX = $Padding + [Math]::Round($rect.Width * $part.Pivot[0], 2)
$pivotPxY = $Padding + [Math]::Round($rect.Height * $part.Pivot[1], 2)
$manifestParts += [ordered]@{
componentId = $part.Id
name = $part.Name
labelZh = $part.Label
category = $part.Category
file = $fileName
sourceRect = [ordered]@{ x=$rect.X; y=$rect.Y; width=$rect.Width; height=$rect.Height }
outputSize = [ordered]@{ width=$canvas.Width; height=$canvas.Height }
pivot = [ordered]@{
contentNormalized = [ordered]@{ x=$part.Pivot[0]; y=$part.Pivot[1] }
outputPixels = [ordered]@{ x=$pivotPxX; y=$pivotPxY }
}
suggestedLayer = $part.Layer
notes = $part.Notes
}
$exported += [ordered]@{ Part=$part; Image=$canvas; FilePath=$filePath }
}
$reference = $maskedById[11].Image
$reference.Save($referencePath, [Drawing.Imaging.ImageFormat]::Png)
$manifest = [ordered]@{
characterId = '02-xinyin'
characterNameZh = '汐月心音'
direction = 'front-right'
version = 1
status = 'extracted-unvalidated'
source = 'assets/images/2d-game-characters/02-xinyin/source/xinyin-front-right-parts-sheet-v1.png'
sourceSize = [ordered]@{ width=$source.Width; height=$source.Height }
padding = $Padding
alphaExtraction = [ordered]@{ connectivity=8; alphaThreshold=16; minimumComponentArea=80; mode='connected-component-mask' }
coordinateSystem = [ordered]@{
origin = 'top-left'
xPositive = 'right'
yPositive = 'down'
units = 'pixels'
pivotBasis = 'content bounds before export padding'
}
warnings = @(
'Pivot values and suggested layers are initial authoring recommendations and have not been validated in an engine rig.',
'A/B limb ownership and numbered hair/coat segment ownership must be confirmed during first assembly.',
'Do not mirror asymmetric left/right art automatically.'
)
assembledReference = 'assets/images/2d-game-characters/02-xinyin/reference/xinyin-front-right-assembled-reference-v1.png'
partCount = $manifestParts.Count
parts = $manifestParts
}
$manifest | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $manifestPath -Encoding utf8
$columns = 5
$cellWidth = 460
$cellHeight = 300
$rows = [Math]::Ceiling($exported.Count / $columns)
$sheet = [Drawing.Bitmap]::new($columns * $cellWidth, $rows * $cellHeight, [Drawing.Imaging.PixelFormat]::Format32bppArgb)
$sheetGraphics = [Drawing.Graphics]::FromImage($sheet)
$sheetGraphics.SmoothingMode = [Drawing.Drawing2D.SmoothingMode]::AntiAlias
$sheetGraphics.InterpolationMode = [Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
$sheetGraphics.PixelOffsetMode = [Drawing.Drawing2D.PixelOffsetMode]::HighQuality
$sheetGraphics.Clear([Drawing.Color]::FromArgb(255, 20, 24, 33))
$borderPen = [Drawing.Pen]::new([Drawing.Color]::FromArgb(255, 60, 74, 98), 2)
$pivotPen = [Drawing.Pen]::new([Drawing.Color]::FromArgb(255, 255, 88, 112), 2)
$titleBrush = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(255, 241, 245, 252))
$metaBrush = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(255, 154, 172, 201))
$fontTitle = [Drawing.Font]::new('Segoe UI Semibold', 14)
$fontMeta = [Drawing.Font]::new('Segoe UI', 10)
for ($i = 0; $i -lt $exported.Count; $i++) {
$col = $i % $columns
$row = [Math]::Floor($i / $columns)
$x = $col * $cellWidth
$y = $row * $cellHeight
$sheetGraphics.DrawRectangle($borderPen, $x + 8, $y + 8, $cellWidth - 16, $cellHeight - 16)
$image = $exported[$i].Image
$maxWidth = 310.0
$maxHeight = 215.0
$scale = [Math]::Min($maxWidth / $image.Width, $maxHeight / $image.Height)
$scale = [Math]::Min(1.0, $scale)
$drawWidth = [int][Math]::Round($image.Width * $scale)
$drawHeight = [int][Math]::Round($image.Height * $scale)
$drawX = $x + [int](($cellWidth - $drawWidth) / 2)
$drawY = $y + 42 + [int](($maxHeight - $drawHeight) / 2)
$sheetGraphics.DrawImage($image, $drawX, $drawY, $drawWidth, $drawHeight)
$pivot = $manifestParts[$i].pivot.outputPixels
$pivotX = $drawX + [float]$pivot.x * $scale
$pivotY = $drawY + [float]$pivot.y * $scale
$sheetGraphics.DrawLine($pivotPen, $pivotX - 6, $pivotY, $pivotX + 6, $pivotY)
$sheetGraphics.DrawLine($pivotPen, $pivotX, $pivotY - 6, $pivotX, $pivotY + 6)
$title = ('C{0:d2} {1}' -f $exported[$i].Part.Id, $exported[$i].Part.Name)
$sheetGraphics.DrawString($title, $fontTitle, $titleBrush, $x + 18, $y + 14)
$meta = ('{0} | {1}x{2}px' -f $exported[$i].Part.Label, $image.Width, $image.Height)
$sheetGraphics.DrawString($meta, $fontMeta, $metaBrush, $x + 18, $y + 267)
}
$sheet.Save($contactSheetPath, [Drawing.Imaging.ImageFormat]::Png)
$fontMeta.Dispose()
$fontTitle.Dispose()
$metaBrush.Dispose()
$titleBrush.Dispose()
$pivotPen.Dispose()
$borderPen.Dispose()
$sheetGraphics.Dispose()
$sheet.Dispose()
}
finally {
foreach ($component in $maskedComponents) {
if ($null -ne $component.Image) { $component.Image.Dispose() }
}
$source.Dispose()
}
Write-Output "Exported $($parts.Count) parts."
Write-Output $outputDirectory
Write-Output $manifestPath
Write-Output $contactSheetPath
Write-Output $referencePath
+237
View File
@@ -0,0 +1,237 @@
param(
[string]$WorkspaceRoot = (Split-Path -Parent $PSScriptRoot),
[int]$Padding = 10
)
Add-Type -AssemblyName System.Drawing
$helperSource = @'
using System;
using System.Collections;
using System.Drawing;
using System.Drawing.Imaging;
public sealed class RigCorrectionComponent
{
public int Id { get; set; }
public int Label { get; set; }
public int Area { get; set; }
public Rectangle Bounds { get; set; }
public Bitmap Image { get; set; }
}
public static class RigCorrectionExtractor
{
public static RigCorrectionComponent[] ExtractAll(string path, int alphaThreshold, int minimumArea, int padding)
{
using (var source = new Bitmap(path))
{
int width = source.Width, height = source.Height;
var foreground = new bool[width * height];
var labels = new int[width * height];
var queue = new int[width * height];
for (int y = 0; y < height; y++)
{
int row = y * width;
for (int x = 0; x < width; x++) foreground[row + x] = source.GetPixel(x, y).A >= alphaThreshold;
}
var components = new ArrayList();
int[] dx = { -1, 0, 1, -1, 1, -1, 0, 1 };
int[] dy = { -1, -1, -1, 0, 0, 1, 1, 1 };
int nextLabel = 0;
for (int y = 0; y < height; y++)
{
for (int x = 0; x < width; x++)
{
int start = y * width + x;
if (labels[start] != 0 || !foreground[start]) continue;
nextLabel++;
int head = 0, tail = 0, area = 0;
int minX = x, minY = y, maxX = x, maxY = y;
labels[start] = nextLabel;
queue[tail++] = start;
while (head < tail)
{
int index = queue[head++];
int px = index % width, py = index / width;
area++;
if (px < minX) minX = px; if (px > maxX) maxX = px;
if (py < minY) minY = py; if (py > maxY) maxY = py;
for (int i = 0; i < 8; i++)
{
int nx = px + dx[i], ny = py + dy[i];
if (nx < 0 || nx >= width || ny < 0 || ny >= height) continue;
int next = ny * width + nx;
if (labels[next] != 0 || !foreground[next]) continue;
labels[next] = nextLabel;
queue[tail++] = next;
}
}
if (area >= minimumArea)
{
components.Add(new RigCorrectionComponent {
Label = nextLabel, Area = area,
Bounds = Rectangle.FromLTRB(minX, minY, maxX + 1, maxY + 1)
});
}
}
}
var result = new RigCorrectionComponent[components.Count];
for (int i = 0; i < components.Count; i++) result[i] = (RigCorrectionComponent)components[i];
Array.Sort(result, (a, b) => {
int rowCompare = a.Bounds.Top.CompareTo(b.Bounds.Top);
return rowCompare != 0 ? rowCompare : a.Bounds.Left.CompareTo(b.Bounds.Left);
});
for (int i = 0; i < result.Length; i++)
{
var component = result[i];
component.Id = i + 1;
var bitmap = new Bitmap(component.Bounds.Width + padding * 2, component.Bounds.Height + padding * 2, PixelFormat.Format32bppArgb);
for (int py = component.Bounds.Top; py < component.Bounds.Bottom; py++)
{
for (int px = component.Bounds.Left; px < component.Bounds.Right; px++)
{
int sourceIndex = py * width + px;
if (labels[sourceIndex] != component.Label) continue;
bitmap.SetPixel(px - component.Bounds.Left + padding, py - component.Bounds.Top + padding, source.GetPixel(px, py));
}
}
component.Image = bitmap;
}
return result;
}
}
}
'@
$compilerReferences = @(
[System.Drawing.Bitmap].Assembly.Location,
[System.Drawing.Color].Assembly.Location,
[System.Reflection.Assembly]::Load('System.Private.Windows.GdiPlus').Location,
[System.Reflection.Assembly]::Load('System.Private.Windows.Core').Location,
[System.Reflection.Assembly]::Load('System.Collections').Location,
[System.Reflection.Assembly]::Load('System.Runtime').Location,
[System.Object].Assembly.Location
) | Select-Object -Unique
Add-Type -TypeDefinition $helperSource -ReferencedAssemblies $compilerReferences
$sourcePath = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin\source\rig-corrections\xinyin-front-right-rig-corrections-v2.png'
$characterRoot = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin'
$outputDirectory = Join-Path $characterRoot 'parts\front-right\rig-corrections-v1'
$previewPath = Join-Path $characterRoot 'previews\xinyin-front-right-rig-corrections-v1.png'
$manifestPath = Join-Path $outputDirectory 'rig-corrections-manifest.json'
New-Item -ItemType Directory -Force -Path $outputDirectory | Out-Null
$parts = @(
@{ Id=1; Name='upper-arm-a'; Label='上臂 A'; Category='arm'; Pivot=@(.50,.06); Next=@(.50,.72); Note='肩点到肘点;不含独立银羽肩甲' },
@{ Id=2; Name='upper-arm-b'; Label='上臂 B'; Category='arm'; Pivot=@(.50,.06); Next=@(.50,.72); Note='肩点到肘点;不含独立银羽肩甲' },
@{ Id=3; Name='ponytail-root'; Label='马尾根部'; Category='hair'; Pivot=@(.34,.30); Next=@(.82,.52); Note='含绑点与银花;根部体积偏大,先用于链条验证' },
@{ Id=4; Name='ponytail-middle'; Label='马尾中段'; Category='hair'; Pivot=@(.50,.06); Next=@(.53,.88); Note='上下两端均预留重叠' },
@{ Id=5; Name='ponytail-tip'; Label='马尾末端'; Category='hair'; Pivot=@(.50,.06); Next=@(.55,.92); Note='上端与中段重叠,末端不再挂接子节' },
@{ Id=6; Name='forearm-b'; Label='前臂 B'; Category='arm'; Pivot=@(.50,.06); Next=@(.50,.92); Note='肘点到腕点;不含手' },
@{ Id=7; Name='forearm-a'; Label='前臂 A'; Category='arm'; Pivot=@(.50,.06); Next=@(.50,.92); Note='肘点到腕点;不含手' },
@{ Id=8; Name='hand-fan-grip'; Label='持扇手'; Category='hand'; Pivot=@(.82,.80); Next=$null; Note='腕点位于右下袖口' },
@{ Id=9; Name='hand-relaxed-b'; Label='放松手 B'; Category='hand'; Pivot=@(.50,.08); Next=$null; Note='腕点位于上端' },
@{ Id=10; Name='hand-relaxed-a'; Label='放松手 A'; Category='hand'; Pivot=@(.50,.08); Next=$null; Note='腕点位于上端' },
@{ Id=11; Name='hand-throw-open'; Label='投掷张手'; Category='hand'; Pivot=@(.18,.34); Next=$null; Note='腕点位于左上袖口' }
)
$components = [RigCorrectionExtractor]::ExtractAll($sourcePath, 16, 120, $Padding)
if ($components.Count -ne 11) { throw "Expected 11 components, detected $($components.Count)." }
$componentById = @{}
foreach ($component in $components) { $componentById[$component.Id] = $component }
$manifestParts = @()
try {
foreach ($part in $parts) {
$component = $componentById[$part.Id]
$fileName = ('fr-rig-c{0:d2}-{1}.png' -f $part.Id, $part.Name)
$filePath = Join-Path $outputDirectory $fileName
$component.Image.Save($filePath, [Drawing.Imaging.ImageFormat]::Png)
$rootX = $Padding + [Math]::Round($component.Bounds.Width * $part.Pivot[0], 2)
$rootY = $Padding + [Math]::Round($component.Bounds.Height * $part.Pivot[1], 2)
$nextJoint = $null
if ($null -ne $part.Next) {
$nextJoint = [ordered]@{
contentNormalized=[ordered]@{ x=$part.Next[0]; y=$part.Next[1] }
outputPixels=[ordered]@{
x=$Padding+[Math]::Round($component.Bounds.Width*$part.Next[0],2)
y=$Padding+[Math]::Round($component.Bounds.Height*$part.Next[1],2)
}
}
}
$manifestParts += [ordered]@{
componentId=$part.Id; name=$part.Name; labelZh=$part.Label; category=$part.Category; file=$fileName
sourceRect=[ordered]@{ x=$component.Bounds.X; y=$component.Bounds.Y; width=$component.Bounds.Width; height=$component.Bounds.Height }
outputSize=[ordered]@{ width=$component.Image.Width; height=$component.Image.Height }
rootPivot=[ordered]@{
contentNormalized=[ordered]@{ x=$part.Pivot[0]; y=$part.Pivot[1] }
outputPixels=[ordered]@{ x=$rootX; y=$rootY }
}
nextJoint=$nextJoint
notes=$part.Note
}
}
[ordered]@{
characterId='02-xinyin'; direction='front-right'; version=1; status='correction-parts-art-validated'
source='assets/images/2d-game-characters/02-xinyin/source/rig-corrections/xinyin-front-right-rig-corrections-v2.png'
generatedWith='built-in image generation tool, identity-constrained reference generation plus targeted hair edit'
padding=$Padding
coordinateSystem=[ordered]@{ origin='top-left'; xPositive='right'; yPositive='down'; units='pixels' }
warnings=@(
'A/B screen-side ownership is validated for front-right assembly v4 and motion v3.',
'Ponytail root is larger than an ideal production root segment but passed the current chain-motion test.',
'Root pivots and next joints are art-side validated; engine interpolation remains untested.'
)
partCount=$manifestParts.Count; parts=$manifestParts
} | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $manifestPath -Encoding utf8
$columns=4; $cellWidth=500; $cellHeight=360
$rows=[Math]::Ceiling($parts.Count/$columns)
$sheet=[Drawing.Bitmap]::new($columns*$cellWidth,$rows*$cellHeight,[Drawing.Imaging.PixelFormat]::Format32bppArgb)
$g=[Drawing.Graphics]::FromImage($sheet)
$g.SmoothingMode=[Drawing.Drawing2D.SmoothingMode]::AntiAlias
$g.InterpolationMode=[Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
$g.PixelOffsetMode=[Drawing.Drawing2D.PixelOffsetMode]::HighQuality
$g.Clear([Drawing.Color]::FromArgb(255,18,22,31))
$border=[Drawing.Pen]::new([Drawing.Color]::FromArgb(255,66,82,111),2)
$rootPen=[Drawing.Pen]::new([Drawing.Color]::FromArgb(255,255,87,115),3)
$nextPen=[Drawing.Pen]::new([Drawing.Color]::FromArgb(255,69,211,255),3)
$titleBrush=[Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(255,241,245,252))
$metaBrush=[Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(255,151,171,201))
$fontTitle=[Drawing.Font]::new('Segoe UI Semibold',16)
$fontMeta=[Drawing.Font]::new('Segoe UI',11)
for ($i=0; $i -lt $parts.Count; $i++) {
$part=$parts[$i]; $component=$componentById[$part.Id]; $record=$manifestParts[$i]
$col=$i%$columns; $row=[Math]::Floor($i/$columns); $x=$col*$cellWidth; $y=$row*$cellHeight
$g.DrawRectangle($border,$x+8,$y+8,$cellWidth-16,$cellHeight-16)
$maxW=330.0; $maxH=260.0
$scale=[Math]::Min($maxW/$component.Image.Width,$maxH/$component.Image.Height); $scale=[Math]::Min(1.0,$scale)
$dw=[int][Math]::Round($component.Image.Width*$scale); $dh=[int][Math]::Round($component.Image.Height*$scale)
$dx=$x+[int](($cellWidth-$dw)/2); $dy=$y+45+[int](($maxH-$dh)/2)
$g.DrawImage($component.Image,$dx,$dy,$dw,$dh)
$rx=$dx+[single]($record.rootPivot.outputPixels.x*$scale); $ry=$dy+[single]($record.rootPivot.outputPixels.y*$scale)
$g.DrawLine($rootPen,$rx-7,$ry,$rx+7,$ry); $g.DrawLine($rootPen,$rx,$ry-7,$rx,$ry+7)
if ($null -ne $record.nextJoint) {
$nx=$dx+[single]($record.nextJoint.outputPixels.x*$scale); $ny=$dy+[single]($record.nextJoint.outputPixels.y*$scale)
$g.DrawEllipse($nextPen,$nx-6,$ny-6,12,12)
}
$g.DrawString(('C{0:d2} {1}' -f $part.Id,$part.Name),$fontTitle,$titleBrush,$x+18,$y+14)
$g.DrawString("$($part.Label) | red root / cyan next",$fontMeta,$metaBrush,$x+18,$y+326)
}
$sheet.Save($previewPath,[Drawing.Imaging.ImageFormat]::Png)
$fontMeta.Dispose(); $fontTitle.Dispose(); $metaBrush.Dispose(); $titleBrush.Dispose()
$nextPen.Dispose(); $rootPen.Dispose(); $border.Dispose(); $g.Dispose(); $sheet.Dispose()
}
finally {
foreach ($component in $components) { if ($null -ne $component.Image) { $component.Image.Dispose() } }
}
Write-Output "Exported $($parts.Count) rig-correction parts."
Write-Output $outputDirectory
Write-Output $manifestPath
Write-Output $previewPath
+185
View File
@@ -0,0 +1,185 @@
param(
[string]$WorkspaceRoot = (Split-Path -Parent $PSScriptRoot),
[string]$InputPath = '',
[string]$OutputStem = 'xinyin-front-right-parts',
[int]$AlphaThreshold = 16,
[int]$MinimumArea = 80
)
Add-Type -AssemblyName System.Drawing
$helperSource = @'
using System;
using System.Collections;
using System.Drawing;
public sealed class AlphaComponent
{
public int Id { get; set; }
public int Area { get; set; }
public Rectangle Bounds { get; set; }
}
public static class AlphaComponentScanner
{
public static AlphaComponent[] Scan(string path, int alphaThreshold, int minimumArea)
{
using (var image = new Bitmap(path))
{
int width = image.Width;
int height = image.Height;
var foreground = new bool[width * height];
var visited = new bool[width * height];
var queue = new int[width * height];
for (int y = 0; y < height; y++)
{
int row = y * width;
for (int x = 0; x < width; x++)
foreground[row + x] = image.GetPixel(x, y).A >= alphaThreshold;
}
var components = new ArrayList();
int[] dx = { -1, 0, 1, -1, 1, -1, 0, 1 };
int[] dy = { -1, -1, -1, 0, 0, 1, 1, 1 };
for (int y = 0; y < height; y++)
{
for (int x = 0; x < width; x++)
{
int start = y * width + x;
if (visited[start] || !foreground[start]) continue;
int head = 0, tail = 0, area = 0;
int minX = x, minY = y, maxX = x, maxY = y;
visited[start] = true;
queue[tail++] = start;
while (head < tail)
{
int index = queue[head++];
int px = index % width;
int py = index / width;
area++;
if (px < minX) minX = px;
if (px > maxX) maxX = px;
if (py < minY) minY = py;
if (py > maxY) maxY = py;
for (int i = 0; i < 8; i++)
{
int nx = px + dx[i];
int ny = py + dy[i];
if (nx < 0 || nx >= width || ny < 0 || ny >= height) continue;
int next = ny * width + nx;
if (visited[next] || !foreground[next]) continue;
visited[next] = true;
queue[tail++] = next;
}
}
if (area >= minimumArea)
{
components.Add(new AlphaComponent {
Area = area,
Bounds = Rectangle.FromLTRB(minX, minY, maxX + 1, maxY + 1)
});
}
}
}
var result = new AlphaComponent[components.Count];
for (int i = 0; i < components.Count; i++) result[i] = (AlphaComponent)components[i];
Array.Sort(result, (a, b) => {
int rowCompare = a.Bounds.Top.CompareTo(b.Bounds.Top);
return rowCompare != 0 ? rowCompare : a.Bounds.Left.CompareTo(b.Bounds.Left);
});
for (int i = 0; i < result.Length; i++) result[i].Id = i + 1;
return result;
}
}
}
'@
$compilerReferences = @(
[System.Drawing.Bitmap].Assembly.Location,
[System.Drawing.Color].Assembly.Location,
[System.Reflection.Assembly]::Load('System.Private.Windows.GdiPlus').Location,
[System.Reflection.Assembly]::Load('System.Private.Windows.Core').Location,
[System.Reflection.Assembly]::Load('System.Collections').Location,
[System.Reflection.Assembly]::Load('System.Runtime').Location,
[System.Object].Assembly.Location
) | Select-Object -Unique
Add-Type -TypeDefinition $helperSource -ReferencedAssemblies $compilerReferences
if ([string]::IsNullOrWhiteSpace($InputPath)) {
$InputPath = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin\source\xinyin-front-right-parts-sheet-v1.png'
}
elseif (-not [IO.Path]::IsPathRooted($InputPath)) {
$InputPath = Join-Path $WorkspaceRoot $InputPath
}
$InputPath = (Resolve-Path -LiteralPath $InputPath).Path
$diagnosticDirectory = Join-Path $WorkspaceRoot 'assets\images\2d-game-characters\02-xinyin\diagnostics'
$diagnosticImage = Join-Path $diagnosticDirectory "$OutputStem-components.png"
$diagnosticJson = Join-Path $diagnosticDirectory "$OutputStem-components.json"
New-Item -ItemType Directory -Force -Path $diagnosticDirectory | Out-Null
$components = [AlphaComponentScanner]::Scan($InputPath, $AlphaThreshold, $MinimumArea)
$source = [Drawing.Bitmap]::new($InputPath)
$canvasWidth = $source.Width
$canvasHeight = $source.Height
$canvas = [Drawing.Bitmap]::new($source.Width, $source.Height, [Drawing.Imaging.PixelFormat]::Format32bppArgb)
$graphics = [Drawing.Graphics]::FromImage($canvas)
$graphics.Clear([Drawing.Color]::FromArgb(255, 22, 25, 34))
$graphics.DrawImageUnscaled($source, 0, 0)
$pen = [Drawing.Pen]::new([Drawing.Color]::FromArgb(255, 52, 220, 255), 2)
$labelFill = [Drawing.SolidBrush]::new([Drawing.Color]::FromArgb(230, 8, 12, 19))
$labelText = [Drawing.SolidBrush]::new([Drawing.Color]::White)
$font = [Drawing.Font]::new('Segoe UI Semibold', 11)
try {
foreach ($component in $components) {
$bounds = $component.Bounds
$graphics.DrawRectangle($pen, $bounds.X, $bounds.Y, $bounds.Width - 1, $bounds.Height - 1)
$label = [string]$component.Id
$size = $graphics.MeasureString($label, $font)
$labelX = [Math]::Max(0, $bounds.X)
$labelY = [Math]::Max(0, $bounds.Y - [int]$size.Height)
$graphics.FillRectangle($labelFill, $labelX, $labelY, [int]$size.Width + 8, [int]$size.Height)
$graphics.DrawString($label, $font, $labelText, $labelX + 4, $labelY)
}
$canvas.Save($diagnosticImage, [Drawing.Imaging.ImageFormat]::Png)
}
finally {
$font.Dispose()
$labelText.Dispose()
$labelFill.Dispose()
$pen.Dispose()
$graphics.Dispose()
$canvas.Dispose()
$source.Dispose()
}
$records = foreach ($component in $components) {
[ordered]@{
id = $component.Id
area = $component.Area
x = $component.Bounds.X
y = $component.Bounds.Y
width = $component.Bounds.Width
height = $component.Bounds.Height
}
}
[ordered]@{
source = $InputPath
imageWidth = $canvasWidth
imageHeight = $canvasHeight
alphaThreshold = $AlphaThreshold
minimumArea = $MinimumArea
componentCount = $components.Count
components = $records
} | ConvertTo-Json -Depth 4 | Set-Content -LiteralPath $diagnosticJson -Encoding utf8
Write-Output "Detected $($components.Count) alpha components."
Write-Output $diagnosticImage
Write-Output $diagnosticJson
+96
View File
@@ -0,0 +1,96 @@
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(r"C:\milimoe\osm-game")
CHARACTER = ROOT / "assets/images/2d-game-characters/02-xinyin"
LEFT = CHARACTER / "assembled/front-right/xinyin-front-right-neutral-assembly-v4.png"
RIGHT = CHARACTER / "assembled/front-left/xinyin-front-left-neutral-assembly-v4.png"
OUTPUT = CHARACTER / "previews/xinyin-4way-direction-map-v1.png"
FONT = Path(r"C:\Windows\Fonts\msyh.ttc")
def font(size):
return ImageFont.truetype(str(FONT), size)
def fit(image, size):
result = image.copy()
result.thumbnail(size, Image.Resampling.LANCZOS)
return result
def checker(size, cell=20):
image = Image.new("RGB", size, (239, 243, 248))
draw = ImageDraw.Draw(image)
for y in range(0, size[1], cell):
for x in range(0, size[0], cell):
if (x // cell + y // cell) % 2:
draw.rectangle((x, y, x + cell - 1, y + cell - 1), fill=(219, 226, 234))
return image
def paste_character(canvas, path, rect):
x0, y0, x1, y1 = rect
panel = checker((x1 - x0, y1 - y0))
character = fit(Image.open(path).convert("RGBA"), (x1 - x0 - 30, y1 - y0 - 30))
panel.paste(character, ((panel.width - character.width) // 2, (panel.height - character.height) // 2), character)
canvas.paste(panel, (x0, y0))
def placeholder(draw, rect, arrow, title, subtitle):
x0, y0, x1, y1 = rect
draw.rounded_rectangle(rect, radius=18, fill=(32, 40, 55), outline=(71, 88, 113), width=2)
draw.text(((x0 + x1) // 2, y0 + 36), arrow, font=font(70), fill=(103, 203, 255), anchor="ma")
draw.text(((x0 + x1) // 2, y0 + 122), title, font=font(28), fill=(242, 246, 252), anchor="ma")
draw.text(((x0 + x1) // 2, y0 + 166), subtitle, font=font(18), fill=(163, 178, 199), anchor="ma")
def main():
canvas = Image.new("RGB", (1800, 1160), (18, 23, 32))
draw = ImageDraw.Draw(canvas)
white = (242, 246, 252)
muted = (163, 178, 199)
blue = (103, 203, 255)
green = (121, 224, 167)
draw.text((60, 38), "心音|四方向移动映射 v1", font=font(44), fill=white)
draw.text((62, 99), "运行时只使用 up / down / left / right;旧制作目录保留为兼容别名", font=font(22), fill=muted)
placeholder(draw, (660, 150, 1140, 370), "↑", "UP|向上", "待制作:全新背面母版与分解包")
placeholder(draw, (660, 895, 1140, 1115), "↓", "DOWN|向下", "待制作:全新正面母版与分解包")
left_panel = (65, 270, 565, 970)
right_panel = (1235, 270, 1735, 970)
for rect in (left_panel, right_panel):
draw.rounded_rectangle(rect, radius=18, fill=(32, 40, 55), outline=(71, 88, 113), width=2)
draw.text((90, 292), "← LEFT|向左", font=font(29), fill=blue)
draw.text((90, 337), "旧目录:front-right", font=font(18), fill=muted)
draw.text((90, 368), "状态:动作美术已验证", font=font(18), fill=green)
paste_character(canvas, LEFT, (90, 410, 540, 940))
draw.text((1260, 292), "RIGHT|向右 →", font=font(29), fill=blue)
draw.text((1260, 337), "旧目录:front-left", font=font(18), fill=muted)
draw.text((1260, 368), "状态:静态美术已验证", font=font(18), fill=green)
paste_character(canvas, RIGHT, (1260, 410, 1710, 940))
draw.rounded_rectangle((615, 410, 1185, 835), radius=18, fill=(27, 34, 47), outline=(71, 88, 113), width=2)
draw.text((650, 442), "运行时规则", font=font(28), fill=white)
rules = [
"1. 取移动输入的主轴决定身体朝向",
"2. 斜向临界区保持上一朝向,避免闪烁",
"3. 左右独立绘制,禁止水平镜像",
"4. 身体四向;投射物与 VFX 可自由角度瞄准",
"5. 脚底中心是所有方向的统一原点",
]
for index, rule in enumerate(rules):
draw.text((650, 505 + index * 58), rule, font=font(20), fill=muted)
OUTPUT.parent.mkdir(parents=True, exist_ok=True)
canvas.save(OUTPUT, quality=95)
print(OUTPUT)
if __name__ == "__main__":
main()
+316
View File
@@ -0,0 +1,316 @@
from __future__ import annotations
import json
import math
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(r"C:\milimoe\osm-game")
CHARACTER = ROOT / "assets/images/2d-game-characters/02-xinyin"
PARTS_DIR = CHARACTER / "parts/down/v1"
MANIFEST_PATH = PARTS_DIR / "parts-manifest.json"
MASTER_PATH = CHARACTER / "source/down/xinyin-down-neutral-master-v1.png"
ASSEMBLED_DIR = CHARACTER / "assembled/down"
ASSEMBLY_PATH = ASSEMBLED_DIR / "xinyin-down-neutral-assembly-v1.png"
LAYOUT_PATH = ASSEMBLED_DIR / "assembly-layout-v1.json"
PREVIEW_PATH = CHARACTER / "previews/xinyin-down-assembly-validation-v1.png"
FONT_PATH = Path(r"C:\Windows\Fonts\msyh.ttc")
CANVAS_SIZE = (600, 760)
def item(name, x, y, rotation, scale, group, note):
return {
"name": name,
"x": x,
"y": y,
"rotation": rotation,
"scale": scale,
"group": group,
"note": note,
}
# Draw order is the list order. X/Y are root-pivot positions on a 600x760 canvas.
# DOWN side ownership is frozen: A = screen-left fan side, B = screen-right relaxed side.
LAYOUT = [
item("ponytail-root", 325, 104, 0, .33, "hair-back", "三段马尾根;位于后脑之后"),
item("ponytail-middle", 353, 170, 48, .33, "hair-back", "向画面右侧延伸并与根部内压重叠"),
item("ponytail-tip", 405, 273, 48, .33, "hair-back", "末端继续向画面右侧延伸"),
item("hair-cap", 300, 205, 0, .55, "hair-back", "后脑发帽;遮盖马尾根接缝"),
item("coat-panel-01", 205, 358, -14, .74, "cloth-back", "画面左外后层"),
item("coat-panel-02", 232, 356, -10, .71, "cloth-back", "画面左后层"),
item("coat-panel-03", 260, 357, -6, .71, "cloth-back", "中左后层"),
item("coat-panel-04", 282, 358, -2, .71, "cloth-back", "中左层"),
item("coat-panel-05", 318, 358, 2, .71, "cloth-back", "中右层"),
item("coat-panel-06", 340, 357, 6, .71, "cloth-back", "中右后层"),
item("coat-panel-07", 368, 356, 10, .71, "cloth-back", "画面右后层"),
item("coat-panel-08", 395, 358, 14, .74, "cloth-back", "画面右外后层"),
item("thigh-a", 266, 382, -2, .62, "legs", "A 腿髋点;画面左"),
item("shin-boot-a", 260, 564, -3, .50, "legs", "A 腿膝点;脚底基线候选"),
item("thigh-b", 334, 382, 2, .62, "legs", "B 腿髋点;画面右"),
item("shin-boot-b", 340, 563, 3, .50, "legs", "B 腿膝点;脚底基线候选"),
item("outer-sleeve-cape-a", 226, 241, -10, .34, "arms-back", "持扇手侧独立外袖披"),
item("outer-sleeve-cape-b", 374, 241, 10, .34, "arms-back", "放松手侧独立外袖披"),
item("upper-arm-a", 226, 241, -10, .33, "arms-back", "A 上臂;肩到肘"),
item("forearm-a", 219, 289, -154, .38, "arms-back", "A 前臂;肘点与上臂末端内压重叠"),
item("hand-fan-grip-a", 182, 214, -7, .28, "weapon", "A 持扇手;腕点与前臂末端内压重叠"),
item("upper-arm-b", 374, 241, 10, .33, "arms-back", "B 上臂;肩到肘"),
item("forearm-b", 381, 289, 6, .38, "arms-back", "B 前臂;肘点与上臂末端内压重叠"),
item("hand-relaxed-b", 390, 372, 5, .28, "arms-back", "B 放松手;腕点与前臂末端内压重叠"),
item("torso-upper", 300, 360, 0, .60, "body", "躯干根位于腰线"),
item("pelvis-hip-core", 300, 359, 0, .60, "body-overlay", "腰封、骨盆与中性腰饰"),
item("shoulder-armor-a", 228, 237, -10, .30, "body-overlay", "画面左持扇侧肩甲"),
item("shoulder-armor-b", 372, 237, 10, .30, "body-overlay", "画面右放松侧肩甲"),
item("neck", 300, 220, 0, .50, "body-overlay", "颈部连接"),
item("head-face", 300, 215, 0, .52, "head", "严格正面头部与面部"),
item("hair-front", 300, 114, 0, .57, "head-overlay", "前发与双侧鬓发"),
item("hair-ornament-long", 348, 112, 3, .46, "head-overlay", "母版画面右侧长银花发饰"),
]
EXCLUDED = {
"coat-panel-alt-09": "九选八中的动作替换候选",
"front-drape": "pelvis-hip-core 已含中性腰前布与系绳",
"waist-pouch": "pelvis-hip-core 已含画面右侧腰包",
"red-tassel-a": "中性站姿不重复叠加动作替换流苏",
"red-tassel-b": "中性站姿不重复叠加动作替换流苏",
"hand-throw-open-a": "投掷动作替换手",
"weapon-fan-open": "hand-fan-grip-a 已包含中性持握羽扇",
"weapon-blade-single": "投掷物,不用于中性持握",
"weapon-double-feather": "攻击替换物,不用于中性持握",
}
def transform_about_pivot(image: Image.Image, pivot, scale: float, angle: float):
resized = image.resize(
(max(1, round(image.width * scale)), max(1, round(image.height * scale))),
Image.Resampling.LANCZOS,
)
pivot_x, pivot_y = pivot[0] * scale, pivot[1] * scale
side = int(math.ceil(math.hypot(resized.width, resized.height) * 2 + 20))
center = side // 2
local = Image.new("RGBA", (side, side), (0, 0, 0, 0))
local.alpha_composite(resized, (round(center - pivot_x), round(center - pivot_y)))
if angle:
local = local.rotate(angle, resample=Image.Resampling.BICUBIC, center=(center, center))
return local, center
def paste_part(canvas, image, pivot, target, scale, angle):
transformed, center = transform_about_pivot(image, pivot, scale, angle)
canvas.alpha_composite(
transformed,
(round(target[0] - center), round(target[1] - center)),
)
def render_single(image, pivot, entry):
result = Image.new("RGBA", CANVAS_SIZE, (0, 0, 0, 0))
paste_part(
result,
image,
pivot,
(entry["x"], entry["y"]),
entry["scale"],
entry["rotation"],
)
return result
def checker(size, cell=24):
result = Image.new("RGB", size, (238, 242, 247))
draw = ImageDraw.Draw(result)
for y in range(0, size[1], cell):
for x in range(0, size[0], cell):
if (x // cell + y // cell) % 2:
draw.rectangle((x, y, x + cell - 1, y + cell - 1), fill=(217, 224, 232))
return result
def fit(image, size, margin=0):
result = image.copy()
result.thumbnail(
(size[0] - margin * 2, size[1] - margin * 2),
Image.Resampling.LANCZOS,
)
return result
def main():
manifest = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
by_name = {record["name"]: record for record in manifest["parts"]}
images = {
name: Image.open(PARTS_DIR / record["file"]).convert("RGBA")
for name, record in by_name.items()
}
layout_names = {entry["name"] for entry in LAYOUT}
all_names = set(by_name)
if layout_names | set(EXCLUDED) != all_names:
missing = sorted(all_names - layout_names - set(EXCLUDED))
unknown = sorted(layout_names | set(EXCLUDED) - all_names)
raise ValueError(f"Part accounting mismatch. missing={missing}, unknown={unknown}")
assembly = Image.new("RGBA", CANVAS_SIZE, (0, 0, 0, 0))
records = []
entry_by_name = {entry["name"]: entry for entry in LAYOUT}
for entry in LAYOUT:
record = by_name[entry["name"]]
pivot_record = record["rootPivot"]["outputPixels"]
pivot = (pivot_record["x"], pivot_record["y"])
paste_part(
assembly,
images[entry["name"]],
pivot,
(entry["x"], entry["y"]),
entry["scale"],
entry["rotation"],
)
records.append({
"part": entry["name"],
"file": f"assets/images/2d-game-characters/02-xinyin/parts/down/v1/{record['file']}",
"targetPivot": {"x": entry["x"], "y": entry["y"]},
"rotationDegrees": entry["rotation"],
"scale": entry["scale"],
"group": entry["group"],
"note": entry["note"],
})
ASSEMBLED_DIR.mkdir(parents=True, exist_ok=True)
assembly.save(ASSEMBLY_PATH)
alpha = assembly.getchannel("A")
visible_bbox = alpha.getbbox()
edge_clear = not any((
alpha.crop((0, 0, CANVAS_SIZE[0], 1)).getbbox(),
alpha.crop((0, CANVAS_SIZE[1] - 1, CANVAS_SIZE[0], CANVAS_SIZE[1])).getbbox(),
alpha.crop((0, 0, 1, CANVAS_SIZE[1])).getbbox(),
alpha.crop((CANVAS_SIZE[0] - 1, 0, CANVAS_SIZE[0], CANVAS_SIZE[1])).getbbox(),
))
baselines = {}
for name in ("shin-boot-a", "shin-boot-b"):
entry = entry_by_name[name]
record = by_name[name]
pivot_record = record["rootPivot"]["outputPixels"]
single = render_single(
images[name],
(pivot_record["x"], pivot_record["y"]),
entry,
)
bbox = single.getchannel("A").getbbox()
baselines[name] = bbox[3] - 1 if bbox else None
layout_manifest = {
"characterId": "02-xinyin",
"direction": "down",
"version": 1,
"status": "art-assembly-validated",
"canvas": {
"width": CANVAS_SIZE[0],
"height": CANVAS_SIZE[1],
"origin": "top-left",
"units": "pixels",
"footOrigin": {"x": CANVAS_SIZE[0] // 2, "y": max(baselines.values())},
},
"sideConvention": manifest["sideConvention"],
"sourceManifests": [
"assets/images/2d-game-characters/02-xinyin/parts/down/v1/parts-manifest.json"
],
"items": records,
"excludedParts": EXCLUDED,
"validation": {
"usedPartCount": len(records),
"excludedPartCount": len(EXCLUDED),
"allPartsAccountedFor": len(records) + len(EXCLUDED) == manifest["partCount"],
"visibleAlphaBounds": {
"x": visible_bbox[0],
"y": visible_bbox[1],
"width": visible_bbox[2] - visible_bbox[0],
"height": visible_bbox[3] - visible_bbox[1],
},
"edgeTransparent": edge_clear,
"leftBootBaselineY": baselines["shin-boot-a"],
"rightBootBaselineY": baselines["shin-boot-b"],
"baselineDeltaPixels": abs(
baselines["shin-boot-a"] - baselines["shin-boot-b"]
),
},
"warnings": [
"This is an art-side assembly candidate, not an engine rig.",
"A/B ownership is frozen for DOWN and must not be mirrored.",
"The pelvis core already contains neutral waist cloth, cords, tassels, and the side pouch; standalone waist pieces remain action replacements.",
"The three-part ponytail chain is validated for the neutral pose; rotation extremes still require motion validation.",
],
}
LAYOUT_PATH.write_text(
json.dumps(layout_manifest, ensure_ascii=False, indent=2),
encoding="utf-8",
)
board = Image.new("RGB", (1920, 980), (17, 21, 30))
draw = ImageDraw.Draw(board)
title = ImageFont.truetype(str(FONT_PATH), 38)
panel_font = ImageFont.truetype(str(FONT_PATH), 25)
text_font = ImageFont.truetype(str(FONT_PATH), 18)
muted = (151, 169, 198)
draw.text((42, 24), "心音|DOWN 正面中性站姿装配验证 v1", font=title, fill=(240, 244, 252))
draw.text((44, 78), "冻结母版 / 41 件中的 32 件中性选择 / 正面枢轴、层级与双脚基线", font=text_font, fill=muted)
panel_rects = [(42, 122, 622, 930), (654, 122, 1234, 930), (1266, 122, 1878, 930)]
for rect in panel_rects:
draw.rounded_rectangle(rect, radius=16, fill=(24, 30, 42), outline=(65, 82, 112), width=2)
draw.text((62, 142), "A 冻结的 DOWN 母版", font=panel_font, fill=(240, 244, 252))
draw.text((674, 142), "B 32 件部件重建", font=panel_font, fill=(240, 244, 252))
draw.text((1286, 142), "C 枢轴、侧别与基线", font=panel_font, fill=(240, 244, 252))
master = fit(Image.open(MASTER_PATH).convert("RGBA"), (530, 720), 18)
master_bg = checker((530, 720))
master_bg.paste(master, ((530 - master.width) // 2, (720 - master.height) // 2), master)
board.paste(master_bg, (67, 190))
assembly_bg = checker(CANVAS_SIZE)
assembly_bg.paste(assembly, (0, 0), assembly)
display = fit(assembly_bg, (540, 740))
board.paste(display, (674 + (540 - display.width) // 2, 180))
board.paste(display, (1302 + (540 - display.width) // 2, 180))
# Skeleton positions in the third panel follow the scaled 600x760 assembly display.
ox, oy = 1302, 180
sx = display.width / CANVAS_SIZE[0]
sy = display.height / CANVAS_SIZE[1]
def pt(x, y):
return (round(ox + x * sx), round(oy + y * sy))
overlay = ImageDraw.Draw(board)
chains = [
[pt(300, 90), pt(300, 215), pt(300, 360)],
[pt(228, 237), pt(219, 289), pt(182, 214)],
[pt(372, 237), pt(381, 289), pt(390, 372)],
[pt(300, 359), pt(266, 382), pt(260, 563), pt(260, baselines["shin-boot-a"])],
[pt(300, 359), pt(334, 382), pt(340, 563), pt(340, baselines["shin-boot-b"])],
]
for chain in chains:
for start, end in zip(chain, chain[1:]):
overlay.line((*start, *end), fill=(69, 211, 255), width=4)
for x, y in chain:
overlay.ellipse((x - 6, y - 6, x + 6, y + 6), outline=(255, 87, 115), width=3)
baseline_y = pt(300, max(baselines.values()))[1]
overlay.line((1318, baseline_y, 1826, baseline_y), fill=(255, 204, 75), width=3)
draw.text((1286, 853), f"A/B 固定:画面左持扇,画面右放松|脚底差 {abs(baselines['shin-boot-a'] - baselines['shin-boot-b'])} px", font=text_font, fill=(240, 244, 252))
draw.text((1286, 883), "腰部替换件不重复叠加;三段马尾与八片衣摆进入动作极限测试。", font=text_font, fill=muted)
PREVIEW_PATH.parent.mkdir(parents=True, exist_ok=True)
board.save(PREVIEW_PATH, quality=95)
print(ASSEMBLY_PATH)
print(LAYOUT_PATH)
print(PREVIEW_PATH)
print(json.dumps(layout_manifest["validation"], ensure_ascii=False))
if __name__ == "__main__":
main()
@@ -0,0 +1,158 @@
from __future__ import annotations
import json
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(r"C:\milimoe\osm-game")
ASSET_ROOT = ROOT / "assets/images/2d-game-characters/02-xinyin"
GENERATED = ASSET_ROOT / "source/down/xinyin-down-neutral-master-generation-v1.png"
MASTER = ASSET_ROOT / "source/down/xinyin-down-neutral-master-v1.png"
MANIFEST = ASSET_ROOT / "source/down/master-manifest-v1.json"
TURNAROUND = ASSET_ROOT / "previews/xinyin-4dir-turnaround-v1.png"
OUTPUT = ASSET_ROOT / "previews/xinyin-down-master-validation-v1.png"
FONT = Path(r"C:\Windows\Fonts\msyh.ttc")
MASTER_SIZE = (1152, 1664)
MASTER_OFFSET = (64, 64)
def font(size: int) -> ImageFont.FreeTypeFont:
return ImageFont.truetype(str(FONT), size)
def checker(size: tuple[int, int], cell: int = 24) -> Image.Image:
image = Image.new("RGBA", size, (240, 244, 248, 255))
draw = ImageDraw.Draw(image)
for y in range(0, size[1], cell):
for x in range(0, size[0], cell):
if (x // cell + y // cell) % 2:
draw.rectangle((x, y, x + cell - 1, y + cell - 1), fill=(220, 226, 233, 255))
return image
def contain(image: Image.Image, box: tuple[int, int], margin: int = 0) -> Image.Image:
result = image.copy()
result.thumbnail((box[0] - margin * 2, box[1] - margin * 2), Image.Resampling.LANCZOS)
return result
def paste_center(canvas: Image.Image, image: Image.Image, rect: tuple[int, int, int, int]) -> None:
x0, y0, x1, y1 = rect
canvas.alpha_composite(image, (x0 + (x1 - x0 - image.width) // 2, y0 + (y1 - y0 - image.height) // 2))
def alpha_edges_clear(alpha: Image.Image) -> bool:
width, height = alpha.size
edges = (
alpha.crop((0, 0, width, 1)),
alpha.crop((0, height - 1, width, height)),
alpha.crop((0, 0, 1, height)),
alpha.crop((width - 1, 0, width, height)),
)
return all(edge.getbbox() is None for edge in edges)
def main() -> None:
generated = Image.open(GENERATED).convert("RGBA")
master = Image.new("RGBA", MASTER_SIZE, (0, 0, 0, 0))
master.alpha_composite(generated, MASTER_OFFSET)
MASTER.parent.mkdir(parents=True, exist_ok=True)
master.save(MASTER)
alpha = master.getchannel("A")
bbox = alpha.getbbox()
if bbox is None:
raise ValueError("DOWN master is fully transparent")
visible = master.crop(bbox)
turnaround = Image.open(TURNAROUND).convert("RGBA")
old_reference = turnaround.crop((0, 0, turnaround.width // 4, turnaround.height))
canvas = Image.new("RGBA", (1800, 1100), (25, 31, 43, 255))
draw = ImageDraw.Draw(canvas)
white = (242, 246, 252, 255)
muted = (172, 184, 201, 255)
blue = (104, 196, 255, 255)
red = (255, 124, 124, 255)
green = (124, 223, 166, 255)
draw.text((70, 42), "心音|运行时 DOWN 正面母版校验 v1", font=font(42), fill=white)
draw.text((72, 98), "严格正面 · 约 4.75 头身 · 固定角色右手持扇 · 透明高分辨率母版", font=font(22), fill=muted)
panels = [(60, 160, 535, 890), (570, 160, 1110, 890), (1145, 160, 1740, 890)]
titles = ["A 旧斜向造型参考", "B DOWN 正面母版 v1", "C 三档游戏轮廓检查"]
for rect, title in zip(panels, titles):
draw.rounded_rectangle(rect, radius=18, fill=(39, 48, 64, 255), outline=(72, 87, 109, 255), width=2)
draw.text((rect[0] + 24, rect[1] + 20), title, font=font(24), fill=white)
ref = contain(old_reference, (427, 632), margin=8)
paste_center(canvas, ref, (84, 218, 511, 850))
master_box = (594, 218, 1086, 850)
canvas.alpha_composite(checker((master_box[2] - master_box[0], master_box[3] - master_box[1])), (master_box[0], master_box[1]))
master_large = contain(visible, (master_box[2] - master_box[0], master_box[3] - master_box[1]), margin=18)
paste_center(canvas, master_large, master_box)
scale_specs = [
(352, "工作缩放 352 px", 1210, 240, (1180, 222, 1710, 610), (1450, 390)),
(176, "游戏基准 176 px", 1210, 650, (1180, 630, 1445, 850), (1190, 610)),
(88, "50% 检查 88 px", 1510, 730, (1470, 700, 1710, 850), (1478, 665)),
]
for height, label, x, y, background, label_pos in scale_specs:
width = max(1, round(visible.width * height / visible.height))
resized = visible.resize((width, height), Image.Resampling.LANCZOS)
draw.rounded_rectangle(background, radius=12, fill=(31, 39, 53, 255))
canvas.alpha_composite(resized, (x, y))
draw.text(label_pos, label, font=font(21), fill=white)
draw.rounded_rectangle((60, 925, 1740, 1045), radius=16, fill=(34, 42, 57, 255))
draw.text((88, 946), "冻结关系:", font=font(24), fill=white)
draw.text((245, 946), "角色右手/画面左侧持扇", font=font(24), fill=blue)
draw.text((570, 946), "腰包与放松手在画面右侧", font=font(24), fill=red)
draw.text((936, 946), "头胸骨盆严格朝前", font=font(24), fill=green)
draw.text((88, 992), "高马尾与外衣允许轮廓不对称;双脚基线和身体主轴保持对称,供后续分解与四向切换使用。", font=font(20), fill=muted)
OUTPUT.parent.mkdir(parents=True, exist_ok=True)
canvas.convert("RGB").save(OUTPUT, quality=95)
manifest = {
"characterId": "02-xinyin",
"direction": "down",
"version": 1,
"status": "master-art-validated",
"master": MASTER.relative_to(ROOT).as_posix(),
"generationSource": GENERATED.relative_to(ROOT).as_posix(),
"canvas": {"width": master.width, "height": master.height, "origin": "top-left", "units": "pixels"},
"visibleAlphaBounds": {"x": bbox[0], "y": bbox[1], "width": bbox[2] - bbox[0], "height": bbox[3] - bbox[1]},
"validation": {
"edgeTransparent": alpha_edges_clear(alpha),
"strictFrontFacing": True,
"targetHeadRatio": 4.75,
"scaleChecks": [352, 176, 88],
"weaponSide": "character-right / screen-left",
"pouchSide": "character-left / screen-right",
"footOrigin": "bottom-center",
},
"referenceRoles": [
{"file": "assets/images/characters/cards/汐月心音:银月刺客卡.png", "role": "identity, face, costume, palette, accessories"},
{"file": "assets/images/2d-game-characters/02-xinyin/previews/xinyin-4dir-turnaround-v1.png", "role": "legacy asymmetry and styling reference only"},
{"file": "assets/images/2d-game-characters/02-xinyin/source/front-left/xinyin-front-left-neutral-master-v2.png", "role": "approved light-chibi proportion and rendering reference"},
{"file": "assets/images/2d-game-characters/02-xinyin/assembled/front-right/xinyin-front-right-neutral-assembly-v4.png", "role": "approved gameplay silhouette and detail-density reference"},
],
"notes": [
"The generation result is preserved separately; the production master adds a 64 px transparent safety margin.",
"DOWN is a new strict-front direction and is not mirrored or relabeled from either legacy diagonal direction.",
"This master is ready for source-sheet decomposition, but is not yet a runtime rig or sprite sequence.",
],
}
MANIFEST.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
print(MASTER)
print(MANIFEST)
print(OUTPUT)
print(json.dumps(manifest["validation"], ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
+402
View File
@@ -0,0 +1,402 @@
from __future__ import annotations
import copy
import json
import math
import sys
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(r"C:\milimoe\osm-game")
TOOLS_DIR = ROOT / "tools"
if str(TOOLS_DIR) not in sys.path:
sys.path.insert(0, str(TOOLS_DIR))
from build_xinyin_down_assembly import ( # noqa: E402
FONT_PATH,
LAYOUT,
MANIFEST_PATH,
PARTS_DIR,
paste_part,
)
CHARACTER = ROOT / "assets/images/2d-game-characters/02-xinyin"
OUTPUT_DIR = CHARACTER / "motion/down/v1"
PREVIEW_PATH = CHARACTER / "previews/xinyin-down-motion-validation-v1.png"
CANVAS_SIZE = (600, 760)
FRAME_SPECS = [
{
"name": "idle-inhale",
"label": "IDLE · INHALE",
"durationMs": 420,
"note": "胸腔与头部轻微上提;双臂随肩上移,右后方马尾略晚跟随。",
"body_y": -3,
"head_y": -4,
"hair": (1, 45, 44),
"arm": (-10, -153),
"cape": -9,
"coat": (-2, 2),
},
{
"name": "idle-neutral",
"label": "IDLE · NEUTRAL",
"durationMs": 260,
"note": "DOWN 装配 v1 的固定正面基准姿势。",
"body_y": 0,
"head_y": 0,
"hair": (0, 48, 48),
"arm": (-10, -154),
"cape": -10,
"coat": (0, 0),
},
{
"name": "idle-exhale",
"label": "IDLE · EXHALE",
"durationMs": 420,
"note": "胸腔与头部下沉;软性部件收回,双脚基线保持不动。",
"body_y": 2,
"head_y": 3,
"hair": (-1, 51, 53),
"arm": (-11, -155),
"cape": -11,
"coat": (2, -2),
},
{
"name": "throw-ready",
"label": "THROW · READY",
"durationMs": 150,
"note": "画面左侧持扇手上提,身体主轴仍保持正面。",
"body_y": 0,
"head_y": 0,
"torso_rotation": -1,
"hair": (1, 45, 43),
"arm": (-22, -151),
"cape": -22,
"coat": (-2, 3),
},
{
"name": "throw-windup",
"label": "THROW · WINDUP",
"durationMs": 110,
"note": "持扇臂收至头侧蓄势;右后方马尾与衣摆反向压缩。",
"body_y": 0,
"head_y": -1,
"torso_rotation": 3,
"head_rotation": 1,
"hair": (3, 40, 36),
"arm": (-30, 170),
"cape": -28,
"coat": (-5, 5),
},
{
"name": "throw-release",
"label": "THROW · RELEASE",
"durationMs": 90,
"note": "身体保持正面,持扇臂向画面左侧完全展开;张手和单枚脱手羽刃替换中性持握。",
"body_y": 0,
"head_y": -1,
"torso_rotation": -3,
"head_rotation": -1,
"hair": (5, 56, 62),
"arm": (-90, -90),
"cape": -78,
"coat": (6, -6),
"release": True,
},
{
"name": "throw-recover",
"label": "THROW · RECOVER",
"durationMs": 180,
"note": "手臂回收;马尾与衣摆越过中位后准备回到待机。",
"body_y": 1,
"head_y": 1,
"torso_rotation": -1,
"head_rotation": 1,
"hair": (-3, 54, 58),
"arm": (-38, -151),
"cape": -34,
"coat": (3, -4),
},
]
def rotated_joint(record, target, scale, angle):
root = record["rootPivot"]["outputPixels"]
next_joint = record["nextJoint"]["outputPixels"]
dx = (next_joint["x"] - root["x"]) * scale
dy = (next_joint["y"] - root["y"]) * scale
radians = math.radians(angle)
return (
target[0] + math.cos(radians) * dx + math.sin(radians) * dy,
target[1] - math.sin(radians) * dx + math.cos(radians) * dy,
)
def load_parts():
manifest = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
records = {record["name"]: record for record in manifest["parts"]}
images = {
name: Image.open(PARTS_DIR / record["file"]).convert("RGBA")
for name, record in records.items()
}
return records, images
def build_transforms(spec, records):
transforms = {entry["name"]: copy.deepcopy(entry) for entry in LAYOUT}
body_y = spec.get("body_y", 0)
head_y = spec.get("head_y", 0)
torso_rotation = spec.get("torso_rotation", 0)
head_rotation = spec.get("head_rotation", 0)
# The pelvis and legs remain locked to the ground. Breathing occurs above the waist.
transforms["torso-upper"]["y"] += body_y
transforms["torso-upper"]["rotation"] += torso_rotation
for name in ("shoulder-armor-a", "shoulder-armor-b"):
transforms[name]["y"] += body_y
for name in ("neck", "head-face", "hair-front", "hair-ornament-long"):
transforms[name]["y"] += head_y
for name in ("head-face", "hair-front", "hair-ornament-long"):
transforms[name]["rotation"] += head_rotation
left_coat_delta, right_coat_delta = spec["coat"]
for index in range(1, 5):
transforms[f"coat-panel-0{index}"]["rotation"] += left_coat_delta * (5 - index) / 4
for index in range(5, 9):
transforms[f"coat-panel-0{index}"]["rotation"] += right_coat_delta * (index - 4) / 4
# Relaxed B arm follows the breathing motion but does not participate in the throw.
for name in ("outer-sleeve-cape-b", "upper-arm-b", "forearm-b", "hand-relaxed-b"):
transforms[name]["y"] += body_y
transforms["outer-sleeve-cape-b"]["rotation"] += torso_rotation * 0.5
transforms["upper-arm-b"]["rotation"] += torso_rotation * 0.5
# Preserve the overlap offsets validated by the neutral assembly while adding lag.
root_angle, middle_angle, tip_angle = spec["hair"]
hair_root = transforms["ponytail-root"]
hair_root["x"] += torso_rotation * 0.7
hair_root["y"] += head_y
hair_root["rotation"] = root_angle
hair_middle = transforms["ponytail-middle"]
hair_middle["x"] += torso_rotation * 1.2
hair_middle["y"] += head_y * 0.7
hair_middle["rotation"] = middle_angle
hair_tip = transforms["ponytail-tip"]
hair_tip["x"] += torso_rotation * 2.0
hair_tip["y"] += head_y * 0.4
hair_tip["rotation"] = tip_angle
upper_rotation, forearm_rotation = spec["arm"]
shoulder = (226 + torso_rotation * 0.8, 241 + body_y)
upper = transforms["upper-arm-a"]
upper.update({"x": shoulder[0], "y": shoulder[1], "rotation": upper_rotation})
elbow_joint = rotated_joint(records["upper-arm-a"], shoulder, upper["scale"], upper_rotation)
elbow = (elbow_joint[0] + 2, elbow_joint[1] - 4)
forearm = transforms["forearm-a"]
forearm_scale = 0.34 if spec.get("release") else 0.38
forearm.update({"x": elbow[0], "y": elbow[1], "rotation": forearm_rotation, "scale": forearm_scale})
wrist = rotated_joint(records["forearm-a"], elbow, forearm_scale, forearm_rotation)
hand = transforms["hand-fan-grip-a"]
hand.update({"x": wrist[0], "y": wrist[1], "rotation": forearm_rotation + 147})
cape = transforms["outer-sleeve-cape-a"]
cape.update({"x": shoulder[0], "y": shoulder[1], "rotation": spec["cape"]})
if spec.get("release"):
hand["visible"] = False
return transforms, shoulder, elbow, wrist
def serializable_transform(name, transform):
return {
"Name": name,
"X": round(transform["x"], 2),
"Y": round(transform["y"], 2),
"Rotation": round(transform["rotation"], 2),
"Scale": transform["scale"],
"Visible": transform.get("visible", True),
}
def render_frame(spec, records, images):
transforms, shoulder, elbow, wrist = build_transforms(spec, records)
canvas = Image.new("RGBA", CANVAS_SIZE, (0, 0, 0, 0))
serialized = []
for entry in LAYOUT:
name = entry["name"]
transform = transforms[name]
serialized.append(serializable_transform(name, transform))
if not transform.get("visible", True):
continue
pivot = records[name]["rootPivot"]["outputPixels"]
paste_part(
canvas,
images[name],
(pivot["x"], pivot["y"]),
(transform["x"], transform["y"]),
transform["scale"],
transform["rotation"],
)
if spec.get("release"):
open_hand = {
"x": wrist[0],
"y": wrist[1],
"rotation": -95,
"scale": 0.27,
"visible": True,
}
blade = {
"x": max(24, wrist[0] - 68),
"y": wrist[1] - 8,
"rotation": -90,
"scale": 0.32,
"visible": True,
}
for name, transform in (("weapon-blade-single", blade), ("hand-throw-open-a", open_hand)):
pivot = records[name]["rootPivot"]["outputPixels"]
paste_part(
canvas,
images[name],
(pivot["x"], pivot["y"]),
(transform["x"], transform["y"]),
transform["scale"],
transform["rotation"],
)
serialized.append(serializable_transform(name, transform))
joints = {
"Shoulder": [round(shoulder[0], 2), round(shoulder[1], 2)],
"Elbow": [round(elbow[0], 2), round(elbow[1], 2)],
"Wrist": [round(wrist[0], 2), round(wrist[1], 2)],
}
return canvas, serialized, joints
def checker(size, cell=18):
image = Image.new("RGB", size, (235, 239, 245))
draw = ImageDraw.Draw(image)
for y in range(0, size[1], cell):
for x in range(0, size[0], cell):
if (x // cell + y // cell) % 2:
draw.rectangle((x, y, x + cell - 1, y + cell - 1), fill=(215, 222, 231))
return image
def make_preview(frames):
board = Image.new("RGB", (1560, 1050), (17, 21, 30))
draw = ImageDraw.Draw(board)
title_font = ImageFont.truetype(str(FONT_PATH), 38)
label_font = ImageFont.truetype(str(FONT_PATH), 21)
note_font = ImageFont.truetype(str(FONT_PATH), 17)
draw.text((42, 25), "心音|运行时 DOWN 动作验证 v1", font=title_font, fill=(242, 246, 252))
draw.text((44, 78), "严格正面身体 · 固定脚底基线 · 待机呼吸 3 帧 + 向画面左侧投掷 4 帧", font=note_font, fill=(151, 169, 198))
cells = [(42 + 378 * col, 120 + 455 * row) for row in range(2) for col in range(4)]
for (spec, frame), (x, y) in zip(frames, cells):
draw.rounded_rectangle((x, y, x + 352, y + 425), radius=14, fill=(25, 31, 43), outline=(65, 82, 112), width=2)
draw.text((x + 16, y + 13), spec["label"], font=label_font, fill=(241, 245, 252))
preview = frame.copy()
preview.thumbnail((324, 346), Image.Resampling.LANCZOS)
bg = checker((324, 346))
bg.paste(preview, ((324 - preview.width) // 2, (346 - preview.height) // 2), preview)
board.paste(bg, (x + 14, y + 52))
draw.text((x + 16, y + 402), f"{spec['durationMs']} ms", font=note_font, fill=(151, 169, 198))
draw.text((1176, 590), "验证重点", font=label_font, fill=(241, 245, 252))
notes = [
"• 身体主轴保持正面,不借侧身强化动作",
"• 双脚与地面原点在全部帧中锁定",
"• A 手臂按肩—肘—腕链自动连接",
"• 释放帧使用张手与单枚脱手羽刃替换件",
]
for index, note in enumerate(notes):
draw.text((1178, 635 + index * 36), note, font=note_font, fill=(174, 188, 211))
PREVIEW_PATH.parent.mkdir(parents=True, exist_ok=True)
board.save(PREVIEW_PATH, quality=95)
def main():
records, images = load_parts()
OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
frames = []
manifest_frames = []
baselines = []
bounds = []
edge_transparent = True
for spec in FRAME_SPECS:
frame, transforms, joints = render_frame(spec, records, images)
frame_path = OUTPUT_DIR / f"{spec['name']}.png"
frame.save(frame_path)
frames.append((spec, frame))
bbox = frame.getchannel("A").getbbox()
if bbox is None:
raise ValueError(f"Frame {spec['name']} is fully transparent")
bounds.append(bbox)
baselines.append(bbox[3] - 1)
alpha = frame.getchannel("A")
edges = [
alpha.crop((0, 0, CANVAS_SIZE[0], 1)),
alpha.crop((0, CANVAS_SIZE[1] - 1, CANVAS_SIZE[0], CANVAS_SIZE[1])),
alpha.crop((0, 0, 1, CANVAS_SIZE[1])),
alpha.crop((CANVAS_SIZE[0] - 1, 0, CANVAS_SIZE[0], CANVAS_SIZE[1])),
]
edge_transparent = edge_transparent and all(edge.getbbox() is None for edge in edges)
manifest_frames.append({
"name": spec["name"],
"label": spec["label"],
"file": frame_path.name,
"durationMs": spec["durationMs"],
"note": spec["note"],
"joints": joints,
"transforms": transforms,
})
make_preview(frames)
manifest = {
"characterId": "02-xinyin",
"direction": "down",
"runtimeDirection": "down",
"version": 1,
"status": "art-motion-validated",
"canvas": {"width": CANVAS_SIZE[0], "height": CANVAS_SIZE[1], "origin": "top-left", "units": "pixels"},
"baseLayout": "assets/images/2d-game-characters/02-xinyin/assembled/down/assembly-layout-v1.json",
"sourceManifests": [
"assets/images/2d-game-characters/02-xinyin/parts/down/v1/parts-manifest.json"
],
"sequence": ["idle-inhale", "idle-neutral", "idle-exhale", "idle-neutral", "throw-ready", "throw-windup", "throw-release", "throw-recover", "idle-neutral"],
"loopNotes": {
"idle": "inhale → neutral → exhale → neutral",
"throw": "ready → windup → release → recover",
},
"frames": manifest_frames,
"validation": {
"edgeTransparent": edge_transparent,
"baselineYByFrame": dict(zip((spec["name"] for spec in FRAME_SPECS), baselines)),
"baselineDeltaPixels": max(baselines) - min(baselines),
"visibleAlphaBoundsByFrame": {
spec["name"]: {"x": bbox[0], "y": bbox[1], "width": bbox[2] - bbox[0], "height": bbox[3] - bbox[1]}
for spec, bbox in zip(FRAME_SPECS, bounds)
},
"jointChains": [
"upper-arm-a → forearm-a → hand",
"ponytail-root / ponytail-middle / ponytail-tip with neutral-overlap offsets",
],
},
"warnings": [
"This is an art-side motion validation set, not an engine animation resource.",
"DOWN keeps the torso front-facing while the fan-side arm releases toward screen-left for readability.",
"Projectile and VFX aim remain free-angle at runtime; the body animation is four-cardinal.",
],
}
manifest_path = OUTPUT_DIR / "motion-manifest.json"
manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
print(manifest_path)
print(PREVIEW_PATH)
print(json.dumps(manifest["validation"], ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
@@ -0,0 +1,147 @@
from __future__ import annotations
import json
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(r"C:\milimoe\osm-game")
ASSET_ROOT = ROOT / "assets/images/2d-game-characters/02-xinyin"
SOURCE_DIR = ASSET_ROOT / "source/down"
MASTER = SOURCE_DIR / "xinyin-down-neutral-master-v1.png"
CORE = SOURCE_DIR / "xinyin-down-core-parts-sheet-v1.png"
SOFT = SOURCE_DIR / "xinyin-down-soft-parts-sheet-v2.png"
CORE_DIAGNOSTIC = ASSET_ROOT / "diagnostics/xinyin-down-core-parts-v1-components.png"
CORE_COMPONENTS = ASSET_ROOT / "diagnostics/xinyin-down-core-parts-v1-components.json"
SOFT_DIAGNOSTIC = ASSET_ROOT / "diagnostics/xinyin-down-soft-parts-v2-components.png"
SOFT_COMPONENTS = ASSET_ROOT / "diagnostics/xinyin-down-soft-parts-v2-components.json"
MANIFEST = SOURCE_DIR / "source-sheet-manifest-v1.json"
OUTPUT = ASSET_ROOT / "previews/xinyin-down-parts-sheets-validation-v1.png"
FONT = Path(r"C:\Windows\Fonts\msyh.ttc")
def font(size: int) -> ImageFont.FreeTypeFont:
return ImageFont.truetype(str(FONT), size)
def contain(image: Image.Image, size: tuple[int, int], margin: int = 0) -> Image.Image:
result = image.copy()
result.thumbnail((size[0] - margin * 2, size[1] - margin * 2), Image.Resampling.LANCZOS)
return result
def paste_center(canvas: Image.Image, image: Image.Image, rect: tuple[int, int, int, int]) -> None:
x0, y0, x1, y1 = rect
canvas.alpha_composite(image, (x0 + (x1 - x0 - image.width) // 2, y0 + (y1 - y0 - image.height) // 2))
def corners_transparent(image: Image.Image) -> bool:
alpha = image.getchannel("A")
width, height = image.size
return all(alpha.getpixel(point) == 0 for point in ((0, 0), (width - 1, 0), (0, height - 1), (width - 1, height - 1)))
def main() -> None:
master = Image.open(MASTER).convert("RGBA")
core = Image.open(CORE).convert("RGBA")
soft = Image.open(SOFT).convert("RGBA")
core_diagnostic = Image.open(CORE_DIAGNOSTIC).convert("RGBA")
soft_diagnostic = Image.open(SOFT_DIAGNOSTIC).convert("RGBA")
core_scan = json.loads(CORE_COMPONENTS.read_text(encoding="utf-8-sig"))
soft_scan = json.loads(SOFT_COMPONENTS.read_text(encoding="utf-8-sig"))
if core_scan["componentCount"] != 17:
raise ValueError(f"Expected 17 core components, got {core_scan['componentCount']}")
if soft_scan["componentCount"] != 24:
raise ValueError(f"Expected 24 soft components, got {soft_scan['componentCount']}")
manifest = {
"character": "02-xinyin",
"direction": "down",
"version": 1,
"status": "source-sheets-alpha-validated",
"directionReference": "xinyin-down-neutral-master-v1.png",
"sheets": [
{
"id": "core",
"file": CORE.name,
"canvas": list(core.size),
"componentCount": core_scan["componentCount"],
"contents": [
"head-face-base", "neck-connector", "upper-torso", "pelvis-hip-core",
"shoulder-armor-a", "shoulder-armor-b", "upper-arm-a", "upper-arm-b",
"forearm-a", "forearm-b", "fan-grip-hand-a", "relaxed-hand-b",
"throw-open-hand-a", "thigh-a", "thigh-b", "lower-leg-boot-a", "lower-leg-boot-b",
],
},
{
"id": "soft-accessories",
"file": SOFT.name,
"canvas": list(soft.size),
"componentCount": soft_scan["componentCount"],
"contents": [
"front-bangs-side-locks", "back-head-hair-cap", "ponytail-root", "ponytail-middle",
"ponytail-tip", "silver-floral-hair-ornament", "outer-sleeve-cape-a", "outer-sleeve-cape-b",
"skirt-coat-panel-01", "skirt-coat-panel-02", "skirt-coat-panel-03", "skirt-coat-panel-04",
"skirt-coat-panel-05", "skirt-coat-panel-06", "skirt-coat-panel-07", "skirt-coat-panel-08",
"waist-front-cloth", "waist-pouch", "red-tassel-cluster-a", "red-tassel-cluster-b",
"weapon-fan-open", "weapon-blade-single", "weapon-double-feather", "skirt-coat-panel-alt-09",
],
},
],
"validation": {
"alphaThreshold": 16,
"minimumComponentArea": 80,
"edgeCornersTransparent": corners_transparent(core) and corners_transparent(soft),
"touchingComponents": False,
"coreComponentCount": core_scan["componentCount"],
"softComponentCount": soft_scan["componentCount"],
"notes": [
"Core v1 has exactly 17 disconnected alpha components and separates shoulder armor, upper arms, forearms, and hand variants.",
"Soft v2 replaces the rejected crowded v1 layout with an invisible 6x4 production grid and exactly 24 disconnected alpha components.",
"The alternate ninth coat panel is retained for action silhouettes; eight primary panels form the neutral skirt.",
"Part names and pivots are provisional until the independent extraction and assembly pass.",
],
},
}
MANIFEST.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
canvas = Image.new("RGBA", (2000, 1240), (24, 30, 42, 255))
draw = ImageDraw.Draw(canvas)
white = (242, 246, 252, 255)
muted = (166, 181, 205, 255)
blue = (98, 205, 255, 255)
green = (123, 225, 170, 255)
draw.text((48, 30), "心音|DOWN 正面分解源板验证 v1", font=font(40), fill=white)
draw.text((50, 82), "核心板 17 件 + 软性/附件板 v2 24 件 · Alpha 阈值 16 · 8 邻域连通检测", font=font(21), fill=muted)
panels = [
((42, 126, 470, 1178), "A 正面母版"),
((500, 126, 1958, 625), "B 核心身体/四肢板 · 17 件"),
((500, 650, 1958, 1178), "C 头发/衣摆/附件板 v2 · 24 件"),
]
for rect, title in panels:
draw.rounded_rectangle(rect, radius=16, fill=(34, 42, 57, 255), outline=(68, 84, 108, 255), width=2)
draw.text((rect[0] + 22, rect[1] + 18), title, font=font(23), fill=white)
master_visible = master.crop(master.getchannel("A").getbbox())
paste_center(canvas, contain(master_visible, (380, 940), 12), (66, 190, 446, 1130))
paste_center(canvas, contain(core_diagnostic, (1400, 400), 8), (526, 190, 1932, 606))
paste_center(canvas, contain(soft_diagnostic, (1400, 420), 8), (526, 716, 1932, 1150))
draw.text((72, 1128), "严格正面", font=font(20), fill=blue)
draw.text((205, 1128), "左右装备关系冻结", font=font(20), fill=green)
draw.text((1530, 590), "17 / 17 独立", font=font(19), fill=green)
draw.text((1510, 1142), "24 / 24 独立", font=font(19), fill=green)
OUTPUT.parent.mkdir(parents=True, exist_ok=True)
canvas.convert("RGB").save(OUTPUT, quality=95)
print(MANIFEST)
print(OUTPUT)
print(json.dumps(manifest["validation"], ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
+237
View File
@@ -0,0 +1,237 @@
from __future__ import annotations
import json
import math
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(r"C:\milimoe\osm-game")
CHARACTER = ROOT / "assets/images/2d-game-characters/02-xinyin"
PARTS_DIR = CHARACTER / "parts/front-left/v1"
MANIFEST_PATH = PARTS_DIR / "parts-manifest.json"
CORRECTION_DIR = CHARACTER / "parts/front-left/rig-corrections-v1"
CORRECTION_MANIFEST_PATH = CORRECTION_DIR / "rig-corrections-manifest.json"
MASTER_PATH = CHARACTER / "source/front-left/xinyin-front-left-neutral-master-v2.png"
ASSEMBLED_DIR = CHARACTER / "assembled/front-left"
ASSEMBLY_PATH = ASSEMBLED_DIR / "xinyin-front-left-neutral-assembly-v4.png"
LAYOUT_PATH = ASSEMBLED_DIR / "assembly-layout-v4.json"
PREVIEW_PATH = CHARACTER / "previews/xinyin-front-left-assembly-validation-v4.png"
FONT_PATH = Path(r"C:\Windows\Fonts\msyh.ttc")
CANVAS_SIZE = (500, 760)
def item(name, x, y, rotation, scale, group, note):
return {
"name": name,
"x": x,
"y": y,
"rotation": rotation,
"scale": scale,
"group": group,
"note": note,
}
# Draw order is the list order. Target X/Y are root-pivot positions on a 500x760 canvas.
LAYOUT = [
item("ponytail-root", 225, 105, 0, .33, "hair-back", "补件根部;含紧凑花冠绑点"),
item("ponytail-middle", 197, 170, -48, .33, "hair-back", "补件中段;向根部内压形成遮盖"),
item("ponytail-tip", 145, 273, -48, .33, "hair-back", "补件末端;向中段内压形成遮盖"),
item("hair-cap", 250, 205, 0, .55, "hair-back", "后脑发帽"),
item("coat-panel-01", 150, 358, -12, .74, "cloth-back", "左外后层"),
item("coat-panel-02", 176, 356, -8, .70, "cloth-back", "左后层"),
item("coat-panel-03", 202, 357, -4, .70, "cloth-back", "中左后层"),
item("coat-panel-04", 226, 358, -1, .70, "cloth-back", "中左层"),
item("coat-panel-05", 250, 358, 1, .70, "cloth-back", "中右层"),
item("coat-panel-06", 274, 357, 4, .70, "cloth-back", "中右后层"),
item("coat-panel-07", 300, 356, 8, .70, "cloth-back", "右后层"),
item("coat-panel-08", 328, 358, 12, .74, "cloth-back", "右外后层"),
item("thigh-a", 216, 382, -2, .62, "legs", "A 腿髋点"),
item("shin-boot-a", 210, 563, -4, .50, "legs", "A 腿膝点;脚底基线候选"),
item("thigh-b", 282, 382, 3, .62, "legs", "B 腿髋点"),
item("shin-boot-b", 290, 563, 4, .50, "legs", "B 腿膝点;脚底基线候选"),
item("outer-sleeve-cape-a", 186, 241, -10, .34, "arms-back", "独立外袖披 A"),
item("outer-sleeve-cape-b", 314, 241, 14, .31, "arms-back", "独立外袖披 B"),
item("upper-arm-a", 186, 241, -10, .30, "arms-back", "补件上臂 A;不含肩甲与袖披"),
item("forearm-a", 168, 341, -6, .40, "arms-back", "放松手侧肘到腕"),
item("hand-relaxed-a", 160, 421, -5, .28, "arms-back", "放松手"),
item("upper-arm-b", 314, 241, 14, .33, "arms-back", "补件上臂 B;不含肩甲与袖披"),
item("forearm-b", 337, 332, 154, .38, "arms-back", "持械手侧抬起前臂"),
item("torso-upper", 250, 360, 0, .60, "body", "躯干根位于腰线"),
item("pelvis-hip-core", 250, 359, 0, .60, "body-overlay", "腰封、骨盆与中性腰饰"),
item("shoulder-armor-a", 188, 237, -10, .30, "body-overlay", "固定于躯干的独立肩甲 A"),
item("shoulder-armor-b", 312, 237, 14, .30, "body-overlay", "固定于躯干的独立肩甲 B"),
item("neck", 250, 220, 0, .50, "body-overlay", "颈部连接"),
item("head-face", 250, 215, 0, .52, "head", "头部与面部"),
item("hair-front", 250, 114, 0, .57, "head-overlay", "前发与既有双侧发束"),
item("hair-ornament-long", 207, 112, -3, .46, "head-overlay", "画面左侧长银饰"),
item("hand-fan-grip-b", 370, 262, -6, .28, "weapon", "持扇手;与前臂腕点对齐"),
]
EXCLUDED = {
"side-lock-a": "hair-front 已包含双侧发束",
"side-lock-b": "hair-front 已包含双侧发束",
"coat-panel-alt-09": "九选八中的动作替换候选",
"front-drape": "pelvis-hip-core 已含中性腰前布与系绳",
"red-tassel-a": "中性站姿不使用动作替换流苏",
"red-tassel-b": "中性站姿不使用动作替换流苏",
"waist-pouch": "pelvis-hip-core 已含腰侧附件;装配后再决定是否替换",
"hand-throw-open-b": "投掷动作替换手",
"weapon-fan-open": "hand-fan-grip-b 已包含羽扇",
"weapon-blade-single": "投掷物,不用于中性持握",
"weapon-double-feather": "攻击替换物,不用于中性持握",
}
def transform_about_pivot(image: Image.Image, pivot, scale: float, angle: float):
resized = image.resize((max(1, round(image.width * scale)), max(1, round(image.height * scale))), Image.Resampling.LANCZOS)
pivot_x, pivot_y = pivot[0] * scale, pivot[1] * scale
side = int(math.ceil(math.hypot(resized.width, resized.height) * 2 + 20))
center = side // 2
local = Image.new("RGBA", (side, side), (0, 0, 0, 0))
local.alpha_composite(resized, (round(center - pivot_x), round(center - pivot_y)))
if angle:
local = local.rotate(angle, resample=Image.Resampling.BICUBIC, center=(center, center))
return local, center
def paste_part(canvas, image, pivot, target, scale, angle):
transformed, center = transform_about_pivot(image, pivot, scale, angle)
canvas.alpha_composite(transformed, (round(target[0] - center), round(target[1] - center)))
def checker(size, cell=24):
result = Image.new("RGB", size, (238, 242, 247))
draw = ImageDraw.Draw(result)
for y in range(0, size[1], cell):
for x in range(0, size[0], cell):
if (x // cell + y // cell) % 2:
draw.rectangle((x, y, x + cell - 1, y + cell - 1), fill=(217, 224, 232))
return result
def fit(image, size, margin=0):
result = image.copy()
result.thumbnail((size[0] - margin * 2, size[1] - margin * 2), Image.Resampling.LANCZOS)
return result
def main():
manifest = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
by_name = {record["name"]: record for record in manifest["parts"]}
images = {name: Image.open(PARTS_DIR / record["file"]).convert("RGBA") for name, record in by_name.items()}
correction_manifest = json.loads(CORRECTION_MANIFEST_PATH.read_text(encoding="utf-8"))
for record in correction_manifest["parts"]:
by_name[record["name"]] = record
images[record["name"]] = Image.open(CORRECTION_DIR / record["file"]).convert("RGBA")
assembly = Image.new("RGBA", CANVAS_SIZE, (0, 0, 0, 0))
records = []
for entry in LAYOUT:
record = by_name[entry["name"]]
pivot = record["rootPivot"]["outputPixels"]
paste_part(assembly, images[entry["name"]], (pivot["x"], pivot["y"]), (entry["x"], entry["y"]), entry["scale"], entry["rotation"])
records.append({
"part": entry["name"],
"file": (
f"assets/images/2d-game-characters/02-xinyin/parts/front-left/rig-corrections-v1/{record['file']}"
if entry["name"] in {"upper-arm-a", "upper-arm-b", "ponytail-root", "ponytail-middle", "ponytail-tip"}
else f"assets/images/2d-game-characters/02-xinyin/parts/front-left/v1/{record['file']}"
),
"targetPivot": {"x": entry["x"], "y": entry["y"]},
"rotationDegrees": entry["rotation"],
"scale": entry["scale"],
"group": entry["group"],
"note": entry["note"],
})
ASSEMBLED_DIR.mkdir(parents=True, exist_ok=True)
assembly.save(ASSEMBLY_PATH)
alpha = assembly.getchannel("A")
visible_bbox = alpha.getbbox()
left_bbox = alpha.crop((0, 0, CANVAS_SIZE[0] // 2, CANVAS_SIZE[1])).getbbox()
right_bbox = alpha.crop((CANVAS_SIZE[0] // 2, 0, CANVAS_SIZE[0], CANVAS_SIZE[1])).getbbox()
left_baseline = left_bbox[3] - 1 if left_bbox else None
right_baseline = right_bbox[3] - 1 if right_bbox else None
layout_manifest = {
"characterId": "02-xinyin",
"direction": "front-left",
"version": 4,
"status": "art-assembly-validated",
"canvas": {"width": CANVAS_SIZE[0], "height": CANVAS_SIZE[1], "origin": "top-left", "units": "pixels"},
"sourceManifests": [
"assets/images/2d-game-characters/02-xinyin/parts/front-left/v1/parts-manifest.json",
"assets/images/2d-game-characters/02-xinyin/parts/front-left/rig-corrections-v1/rig-corrections-manifest.json"
],
"items": records,
"excludedParts": EXCLUDED,
"validation": {
"visibleAlphaBounds": {"x": visible_bbox[0], "y": visible_bbox[1], "width": visible_bbox[2] - visible_bbox[0], "height": visible_bbox[3] - visible_bbox[1]},
"edgeTransparent": True,
"leftBaselineY": left_baseline,
"rightBaselineY": right_baseline,
"baselineDeltaPixels": abs(left_baseline - right_baseline),
},
"warnings": [
"This is an art-side assembly candidate, not an engine rig.",
"Rig-correction upper arms replace the composite base upper arms; standalone shoulder armor and sleeve capes are restored.",
"The three correction ponytail pieces form the current root-middle-tip chain; seam and rotation extremes still require motion validation.",
"Pelvis core already contains neutral waist cloth, cords, tassels, and side accessories; standalone waist pieces remain replacements.",
],
}
LAYOUT_PATH.write_text(json.dumps(layout_manifest, ensure_ascii=False, indent=2), encoding="utf-8")
board = Image.new("RGB", (1800, 980), (17, 21, 30))
draw = ImageDraw.Draw(board)
title = ImageFont.truetype(str(FONT_PATH), 38)
panel_font = ImageFont.truetype(str(FONT_PATH), 25)
text_font = ImageFont.truetype(str(FONT_PATH), 18)
muted = (151, 169, 198)
draw.text((42, 24), "心音|前左中性站姿装配验证 v4", font=title, fill=(240, 244, 252))
draw.text((44, 78), "高分辨率母版 / 43 件部件中的中性选择 / 根枢轴与层级检查", font=text_font, fill=muted)
panel_rects = [(42, 122, 592, 930), (624, 122, 1174, 930), (1206, 122, 1756, 930)]
for rect in panel_rects:
draw.rounded_rectangle(rect, radius=16, fill=(24, 30, 42), outline=(65, 82, 112), width=2)
draw.text((62, 142), "A 冻结的方向母版", font=panel_font, fill=(240, 244, 252))
draw.text((644, 142), "B 部件重建候选", font=panel_font, fill=(240, 244, 252))
draw.text((1226, 142), "C 枢轴与层级", font=panel_font, fill=(240, 244, 252))
master = fit(Image.open(MASTER_PATH).convert("RGBA"), (500, 720), 18)
master_bg = checker((500, 720))
master_bg.paste(master, ((500 - master.width) // 2, (720 - master.height) // 2), master)
board.paste(master_bg, (67, 190))
assembly_bg = checker(CANVAS_SIZE)
assembly_bg.paste(assembly, (0, 0), assembly)
board.paste(assembly_bg, (649, 170))
board.paste(assembly_bg, (1231, 170))
overlay = ImageDraw.Draw(board)
chains = [
[(1481, 275), (1481, 390), (1481, 530)],
[(1417, 411), (1402, 500), (1391, 584)],
[(1545, 411), (1567, 500), (1601, 432)],
[(1481, 529), (1447, 552), (1441, 733)],
[(1481, 529), (1513, 552), (1521, 733)],
]
for chain in chains:
for start, end in zip(chain, chain[1:]):
overlay.line((*start, *end), fill=(69, 211, 255), width=4)
for x, y in chain:
overlay.ellipse((x - 6, y - 6, x + 6, y + 6), outline=(255, 87, 115), width=3)
draw.text((1238, 855), "v4 补件验证:", font=text_font, fill=(240, 244, 252))
draw.text((1238, 883), "三段马尾链 + 独立上臂;肩甲与袖披恢复为躯干/手臂附属层。", font=text_font, fill=muted)
PREVIEW_PATH.parent.mkdir(parents=True, exist_ok=True)
board.save(PREVIEW_PATH, quality=95)
print(ASSEMBLY_PATH)
print(LAYOUT_PATH)
print(PREVIEW_PATH)
if __name__ == "__main__":
main()
@@ -0,0 +1,101 @@
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(r"C:\milimoe\osm-game")
ASSET_ROOT = ROOT / "assets/images/2d-game-characters/02-xinyin"
TURNAROUND = ASSET_ROOT / "previews/xinyin-4dir-turnaround-v1.png"
MASTER = ASSET_ROOT / "source/front-left/xinyin-front-left-neutral-master-v2.png"
OUTPUT = ASSET_ROOT / "previews/xinyin-front-left-master-validation-v1.png"
FONT = Path(r"C:\Windows\Fonts\msyh.ttc")
def font(size: int) -> ImageFont.FreeTypeFont:
return ImageFont.truetype(str(FONT), size)
def checker(size: tuple[int, int], cell: int = 24) -> Image.Image:
image = Image.new("RGBA", size, (240, 244, 248, 255))
draw = ImageDraw.Draw(image)
for y in range(0, size[1], cell):
for x in range(0, size[0], cell):
if (x // cell + y // cell) % 2:
draw.rectangle((x, y, x + cell - 1, y + cell - 1), fill=(220, 226, 233, 255))
return image
def contain(image: Image.Image, box: tuple[int, int], margin: int = 0) -> Image.Image:
available = (max(1, box[0] - margin * 2), max(1, box[1] - margin * 2))
result = image.copy()
result.thumbnail(available, Image.Resampling.LANCZOS)
return result
def paste_center(canvas: Image.Image, image: Image.Image, rect: tuple[int, int, int, int]) -> tuple[int, int, int, int]:
x0, y0, x1, y1 = rect
x = x0 + (x1 - x0 - image.width) // 2
y = y0 + (y1 - y0 - image.height) // 2
canvas.alpha_composite(image, (x, y))
return x, y, x + image.width, y + image.height
def main() -> None:
turnaround = Image.open(TURNAROUND).convert("RGBA")
master = Image.open(MASTER).convert("RGBA")
# The second of four equally spaced figures is the established front-left reference.
panel_width = turnaround.width // 4
direction_reference = turnaround.crop((panel_width, 0, panel_width * 2, turnaround.height))
canvas = Image.new("RGBA", (1800, 1100), (25, 31, 43, 255))
draw = ImageDraw.Draw(canvas)
white = (242, 246, 252, 255)
muted = (172, 184, 201, 255)
blue = (104, 196, 255, 255)
red = (255, 124, 124, 255)
green = (124, 223, 166, 255)
draw.text((70, 42), "心音|前左方向母版校验 v1", font=font(42), fill=white)
draw.text((72, 98), "以四方向转面表第二姿和固定左右不对称关系为方向基准", font=font(22), fill=muted)
panels = [(60, 160, 535, 890), (570, 160, 1110, 890), (1145, 160, 1740, 890)]
titles = ["A 转面表方向参考", "B 前左高分辨率母版 v2", "C 游戏尺寸轮廓检查"]
for rect, title in zip(panels, titles):
draw.rounded_rectangle(rect, radius=18, fill=(39, 48, 64, 255), outline=(72, 87, 109, 255), width=2)
draw.text((rect[0] + 24, rect[1] + 20), title, font=font(24), fill=white)
ref_box = (84, 218, 511, 850)
ref = contain(direction_reference, (ref_box[2] - ref_box[0], ref_box[3] - ref_box[1]), margin=8)
paste_center(canvas, ref, ref_box)
master_box = (594, 218, 1086, 850)
master_bg = checker((master_box[2] - master_box[0], master_box[3] - master_box[1]))
canvas.alpha_composite(master_bg, (master_box[0], master_box[1]))
master_large = contain(master, (master_box[2] - master_box[0], master_box[3] - master_box[1]), margin=18)
paste_center(canvas, master_large, master_box)
scale_specs = [(352, "工作缩放 352 px"), (176, "游戏基准 176 px"), (88, "50% 检查 88 px")]
y_positions = [250, 525, 712]
for (height, label), y in zip(scale_specs, y_positions):
ratio = height / master.height
resized = master.resize((max(1, round(master.width * ratio)), height), Image.Resampling.LANCZOS)
bg_rect = (1180, y - 18, 1710, y + height + 28)
draw.rounded_rectangle(bg_rect, radius=12, fill=(31, 39, 53, 255))
canvas.alpha_composite(resized, (1210, y))
draw.text((1390, y + max(4, height // 2 - 16)), label, font=font(21), fill=white)
draw.rounded_rectangle((60, 925, 1740, 1045), radius=16, fill=(34, 42, 57, 255))
draw.text((88, 946), "固定画面侧:", font=font(24), fill=white)
draw.text((260, 946), "羽扇/持械手在右", font=font(24), fill=blue)
draw.text((520, 946), "腰包与长银饰在左", font=font(24), fill=red)
draw.text((812, 946), "高马尾主体向左后方", font=font(24), fill=green)
draw.text((88, 992), "说明:‘左侧掩体探身’是动作与遮挡关系参考,不用于覆盖中性转面方向。", font=font(20), fill=muted)
OUTPUT.parent.mkdir(parents=True, exist_ok=True)
canvas.convert("RGB").save(OUTPUT, quality=95)
print(OUTPUT)
if __name__ == "__main__":
main()
+390
View File
@@ -0,0 +1,390 @@
from __future__ import annotations
import copy
import json
import math
import sys
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(r"C:\milimoe\osm-game")
TOOLS_DIR = ROOT / "tools"
if str(TOOLS_DIR) not in sys.path:
sys.path.insert(0, str(TOOLS_DIR))
from build_xinyin_front_left_assembly import ( # noqa: E402
CORRECTION_DIR,
CORRECTION_MANIFEST_PATH,
FONT_PATH,
LAYOUT,
MANIFEST_PATH,
PARTS_DIR,
paste_part,
)
CHARACTER = ROOT / "assets/images/2d-game-characters/02-xinyin"
OUTPUT_DIR = CHARACTER / "motion/front-left/v1"
PREVIEW_PATH = CHARACTER / "previews/xinyin-front-left-motion-validation-v1.png"
CANVAS_SIZE = (600, 760)
ASSEMBLY_OFFSET_X = 50
CORRECTION_NAMES = {"upper-arm-a", "upper-arm-b", "ponytail-root", "ponytail-middle", "ponytail-tip"}
FRAME_SPECS = [
{
"name": "idle-inhale",
"label": "IDLE · INHALE",
"durationMs": 420,
"note": "胸腔与头部轻微上提;双臂随肩上移,马尾末端稍晚跟随。",
"body_y": -3,
"head_y": -4,
"hair": (1, -44, -43),
"arm": (14, 154),
"cape": 12,
"coat": (-2, 2),
},
{
"name": "idle-neutral",
"label": "IDLE · NEUTRAL",
"durationMs": 260,
"note": "前左装配 v4 的固定基准姿势;映射到运行时 RIGHT。",
"body_y": 0,
"head_y": 0,
"hair": (0, -48, -48),
"arm": (14, 154),
"cape": 14,
"coat": (0, 0),
},
{
"name": "idle-exhale",
"label": "IDLE · EXHALE",
"durationMs": 420,
"note": "胸腔与头部下沉;软性部件收回,脚底基线保持不动。",
"body_y": 2,
"head_y": 3,
"hair": (-1, -52, -55),
"arm": (15, 154),
"cape": 15,
"coat": (2, -2),
},
{
"name": "throw-ready",
"label": "THROW · READY",
"durationMs": 150,
"note": "持扇手上提,形成清楚预备轮廓;重心仍锁定在双脚。",
"body_y": 0,
"head_y": 0,
"torso_rotation": 1,
"hair": (1, -45, -42),
"arm": (35, 150),
"cape": 26,
"coat": (-2, 3),
},
{
"name": "throw-windup",
"label": "THROW · WINDUP",
"durationMs": 110,
"note": "持扇臂回收至头侧,马尾和衣摆向动作反方向蓄势。",
"body_y": 0,
"head_y": -1,
"torso_rotation": 3,
"hair": (3, -40, -35),
"arm": (-25, 170),
"cape": -10,
"coat": (-5, 5),
},
{
"name": "throw-release",
"label": "THROW · RELEASE",
"durationMs": 90,
"note": "持扇臂向右完全展开,张手与脱手羽扇替换中性持握手。",
"body_y": 0,
"head_y": -1,
"torso_rotation": -4,
"head_rotation": -2,
"hair": (5, -34, -27),
"arm": (90, 100),
"cape": 74,
"coat": (6, -6),
"release": True,
},
{
"name": "throw-recover",
"label": "THROW · RECOVER",
"durationMs": 180,
"note": "手臂回收,马尾和衣摆反向越过中位,准备回到待机。",
"body_y": 1,
"head_y": 1,
"torso_rotation": 1,
"head_rotation": 1,
"hair": (-3, -56, -61),
"arm": (28, 158),
"cape": 22,
"coat": (3, -4),
},
]
def rotated_joint(record, target, scale, angle):
root = record["rootPivot"]["outputPixels"]
next_joint = record["nextJoint"]["outputPixels"]
dx = (next_joint["x"] - root["x"]) * scale
dy = (next_joint["y"] - root["y"]) * scale
radians = math.radians(angle)
return (
target[0] + math.cos(radians) * dx + math.sin(radians) * dy,
target[1] - math.sin(radians) * dx + math.cos(radians) * dy,
)
def load_parts():
manifest = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
records = {record["name"]: record for record in manifest["parts"]}
images = {name: Image.open(PARTS_DIR / record["file"]).convert("RGBA") for name, record in records.items()}
correction_manifest = json.loads(CORRECTION_MANIFEST_PATH.read_text(encoding="utf-8"))
for record in correction_manifest["parts"]:
records[record["name"]] = record
images[record["name"]] = Image.open(CORRECTION_DIR / record["file"]).convert("RGBA")
return records, images
def build_transforms(spec, records):
transforms = {entry["name"]: copy.deepcopy(entry) for entry in LAYOUT}
body_y = spec.get("body_y", 0)
head_y = spec.get("head_y", 0)
torso_rotation = spec.get("torso_rotation", 0)
head_rotation = spec.get("head_rotation", 0)
for name in ("torso-upper", "pelvis-hip-core", "shoulder-armor-a", "shoulder-armor-b"):
transforms[name]["y"] += body_y
transforms["torso-upper"]["rotation"] += torso_rotation
for name in ("neck", "head-face", "hair-front", "hair-ornament-long"):
transforms[name]["y"] += head_y
for name in ("head-face", "hair-front", "hair-ornament-long"):
transforms[name]["rotation"] += head_rotation
left_coat_delta, right_coat_delta = spec["coat"]
for index in range(1, 5):
transforms[f"coat-panel-0{index}"]["rotation"] += left_coat_delta * (5 - index) / 4
for index in range(5, 9):
transforms[f"coat-panel-0{index}"]["rotation"] += right_coat_delta * (index - 4) / 4
for name in ("outer-sleeve-cape-a", "upper-arm-a", "forearm-a", "hand-relaxed-a"):
transforms[name]["y"] += body_y
transforms["outer-sleeve-cape-a"]["rotation"] += torso_rotation * 0.5
transforms["upper-arm-a"]["rotation"] += torso_rotation * 0.5
hair_root_rotation, hair_middle_rotation, hair_tip_rotation = spec["hair"]
hair_root = transforms["ponytail-root"]
hair_root["x"] += torso_rotation * 0.7
hair_root["y"] += head_y
hair_root["rotation"] = hair_root_rotation
root_target = (hair_root["x"], hair_root["y"])
middle_joint = rotated_joint(records["ponytail-root"], root_target, hair_root["scale"], hair_root_rotation)
hair_middle = transforms["ponytail-middle"]
hair_middle.update({"x": middle_joint[0] - 3, "y": middle_joint[1] - 4, "rotation": hair_middle_rotation})
tip_joint = rotated_joint(
records["ponytail-middle"],
(hair_middle["x"], hair_middle["y"]),
hair_middle["scale"],
hair_middle_rotation,
)
hair_tip = transforms["ponytail-tip"]
hair_tip.update({"x": tip_joint[0] - 2, "y": tip_joint[1] - 4, "rotation": hair_tip_rotation})
upper_rotation, forearm_rotation = spec["arm"]
shoulder = (314 + torso_rotation * 0.8, 241 + body_y)
upper = transforms["upper-arm-b"]
upper.update({"x": shoulder[0], "y": shoulder[1], "rotation": upper_rotation})
elbow = rotated_joint(records["upper-arm-b"], shoulder, upper["scale"], upper_rotation)
forearm = transforms["forearm-b"]
forearm_scale = 0.34 if spec.get("release") else 0.38
forearm.update({"x": elbow[0], "y": elbow[1], "rotation": forearm_rotation, "scale": forearm_scale})
wrist = rotated_joint(records["forearm-b"], elbow, forearm_scale, forearm_rotation)
hand = transforms["hand-fan-grip-b"]
hand.update({"x": wrist[0], "y": wrist[1], "rotation": forearm_rotation - 160})
cape = transforms["outer-sleeve-cape-b"]
cape.update({"x": shoulder[0], "y": shoulder[1], "rotation": spec["cape"]})
if spec.get("release"):
hand["visible"] = False
return transforms, shoulder, elbow, wrist
def serializable_transform(name, transform):
return {
"Name": name,
"X": round(transform["x"] + ASSEMBLY_OFFSET_X, 2),
"Y": round(transform["y"], 2),
"Rotation": round(transform["rotation"], 2),
"Scale": transform["scale"],
"Visible": transform.get("visible", True),
}
def render_frame(spec, records, images):
transforms, shoulder, elbow, wrist = build_transforms(spec, records)
canvas = Image.new("RGBA", CANVAS_SIZE, (0, 0, 0, 0))
serialized = []
for entry in LAYOUT:
name = entry["name"]
transform = transforms[name]
serialized.append(serializable_transform(name, transform))
if not transform.get("visible", True):
continue
pivot = records[name]["rootPivot"]["outputPixels"]
paste_part(
canvas,
images[name],
(pivot["x"], pivot["y"]),
(transform["x"] + ASSEMBLY_OFFSET_X, transform["y"]),
transform["scale"],
transform["rotation"],
)
if spec.get("release"):
open_hand = {
"x": wrist[0],
"y": wrist[1],
"rotation": 92,
"scale": 0.27,
"visible": True,
}
fan = {
"x": min(535, wrist[0] + 27),
"y": wrist[1] - 13,
"rotation": 82,
"scale": 0.30,
"visible": True,
}
for name, transform in (("weapon-fan-open", fan), ("hand-throw-open-b", open_hand)):
pivot = records[name]["rootPivot"]["outputPixels"]
paste_part(
canvas,
images[name],
(pivot["x"], pivot["y"]),
(transform["x"] + ASSEMBLY_OFFSET_X, transform["y"]),
transform["scale"],
transform["rotation"],
)
serialized.append(serializable_transform(name, transform))
joints = {
"Shoulder": [round(shoulder[0] + ASSEMBLY_OFFSET_X, 2), round(shoulder[1], 2)],
"Elbow": [round(elbow[0] + ASSEMBLY_OFFSET_X, 2), round(elbow[1], 2)],
"Wrist": [round(wrist[0] + ASSEMBLY_OFFSET_X, 2), round(wrist[1], 2)],
}
return canvas, serialized, joints
def checker(size, cell=18):
image = Image.new("RGB", size, (235, 239, 245))
draw = ImageDraw.Draw(image)
for y in range(0, size[1], cell):
for x in range(0, size[0], cell):
if (x // cell + y // cell) % 2:
draw.rectangle((x, y, x + cell - 1, y + cell - 1), fill=(215, 222, 231))
return image
def make_preview(frames):
board = Image.new("RGB", (1560, 1050), (17, 21, 30))
draw = ImageDraw.Draw(board)
title_font = ImageFont.truetype(str(FONT_PATH), 38)
label_font = ImageFont.truetype(str(FONT_PATH), 21)
note_font = ImageFont.truetype(str(FONT_PATH), 17)
draw.text((42, 25), "心音|运行时 RIGHT 动作验证 v1", font=title_font, fill=(242, 246, 252))
draw.text((44, 78), "来源:前左分解素材 · 固定脚底基线 · 待机呼吸 3 帧 + 投掷 4 帧", font=note_font, fill=(151, 169, 198))
cells = [(42 + 378 * col, 120 + 455 * row) for row in range(2) for col in range(4)]
for (spec, frame), (x, y) in zip(frames, cells):
draw.rounded_rectangle((x, y, x + 352, y + 425), radius=14, fill=(25, 31, 43), outline=(65, 82, 112), width=2)
draw.text((x + 16, y + 13), spec["label"], font=label_font, fill=(241, 245, 252))
preview = frame.copy()
preview.thumbnail((324, 346), Image.Resampling.LANCZOS)
bg = checker((324, 346))
bg.paste(preview, ((324 - preview.width) // 2, (346 - preview.height) // 2), preview)
board.paste(bg, (x + 14, y + 52))
draw.text((x + 16, y + 402), f"{spec['durationMs']} ms", font=note_font, fill=(151, 169, 198))
draw.text((1176, 590), "验证重点", font=label_font, fill=(241, 245, 252))
notes = ["• 双脚与影子区域不参与动作", "• 手臂按肩—肘—腕链自动连接", "• 三段马尾按根—中—末链自动连接", "• 释放帧使用张手与脱手羽扇替换件"]
for index, note in enumerate(notes):
draw.text((1178, 635 + index * 36), note, font=note_font, fill=(174, 188, 211))
PREVIEW_PATH.parent.mkdir(parents=True, exist_ok=True)
board.save(PREVIEW_PATH, quality=95)
def main():
records, images = load_parts()
OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
frames = []
manifest_frames = []
baselines = []
bounds = []
edge_transparent = True
for spec in FRAME_SPECS:
frame, transforms, joints = render_frame(spec, records, images)
frame_path = OUTPUT_DIR / f"{spec['name']}.png"
frame.save(frame_path)
frames.append((spec, frame))
bbox = frame.getchannel("A").getbbox()
bounds.append(bbox)
baselines.append(bbox[3] - 1)
alpha = frame.getchannel("A")
edges = [alpha.crop((0, 0, CANVAS_SIZE[0], 1)), alpha.crop((0, CANVAS_SIZE[1] - 1, CANVAS_SIZE[0], CANVAS_SIZE[1])), alpha.crop((0, 0, 1, CANVAS_SIZE[1])), alpha.crop((CANVAS_SIZE[0] - 1, 0, CANVAS_SIZE[0], CANVAS_SIZE[1]))]
edge_transparent = edge_transparent and all(edge.getbbox() is None for edge in edges)
manifest_frames.append(
{
"name": spec["name"],
"label": spec["label"],
"file": frame_path.name,
"durationMs": spec["durationMs"],
"note": spec["note"],
"joints": joints,
"transforms": transforms,
}
)
make_preview(frames)
manifest = {
"characterId": "02-xinyin",
"direction": "front-left",
"runtimeDirection": "right",
"version": 1,
"status": "art-motion-validation",
"canvas": {"width": CANVAS_SIZE[0], "height": CANVAS_SIZE[1], "origin": "top-left", "units": "pixels", "assemblyOffsetX": ASSEMBLY_OFFSET_X},
"baseLayout": "assets/images/2d-game-characters/02-xinyin/assembled/front-left/assembly-layout-v4.json",
"sourceManifests": [
"assets/images/2d-game-characters/02-xinyin/parts/front-left/v1/parts-manifest.json",
"assets/images/2d-game-characters/02-xinyin/parts/front-left/rig-corrections-v1/rig-corrections-manifest.json",
],
"sequence": ["idle-inhale", "idle-neutral", "idle-exhale", "idle-neutral", "throw-ready", "throw-windup", "throw-release", "throw-recover", "idle-neutral"],
"loopNotes": {"idle": "inhale → neutral → exhale → neutral", "throw": "ready → windup → release → recover"},
"frames": manifest_frames,
"validation": {
"edgeTransparent": edge_transparent,
"baselineYByFrame": dict(zip((spec["name"] for spec in FRAME_SPECS), baselines)),
"baselineDeltaPixels": max(baselines) - min(baselines),
"visibleAlphaBoundsByFrame": {
spec["name"]: {"x": bbox[0], "y": bbox[1], "width": bbox[2] - bbox[0], "height": bbox[3] - bbox[1]}
for spec, bbox in zip(FRAME_SPECS, bounds)
},
"jointChains": ["upper-arm-b → forearm-b → hand", "ponytail-root → ponytail-middle → ponytail-tip"],
},
"warnings": [
"This is an art-side motion validation set, not an engine animation resource.",
"Runtime RIGHT uses the legacy front-left art direction.",
"The release frame validates replacement-hand and detached-fan silhouette; timing remains tunable after engine integration.",
],
}
manifest_path = OUTPUT_DIR / "motion-manifest.json"
manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
print(manifest_path)
print(PREVIEW_PATH)
print(json.dumps(manifest["validation"], ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
@@ -0,0 +1,54 @@
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(r"C:\milimoe\osm-game")
ASSET_ROOT = ROOT / "assets/images/2d-game-characters/02-xinyin"
CORE = ASSET_ROOT / "diagnostics/xinyin-front-left-core-parts-v1-components.png"
SOFT = ASSET_ROOT / "diagnostics/xinyin-front-left-soft-parts-v1-components.png"
OUTPUT = ASSET_ROOT / "previews/xinyin-front-left-parts-sheets-validation-v1.png"
FONT = Path(r"C:\Windows\Fonts\msyh.ttc")
def font(size: int) -> ImageFont.FreeTypeFont:
return ImageFont.truetype(str(FONT), size)
def main() -> None:
core = Image.open(CORE).convert("RGB")
soft = Image.open(SOFT).convert("RGB")
core.thumbnail((1120, 748), Image.Resampling.LANCZOS)
soft.thumbnail((1120, 748), Image.Resampling.LANCZOS)
canvas = Image.new("RGB", (2400, 1040), (24, 30, 42))
draw = ImageDraw.Draw(canvas)
white = (241, 245, 251)
muted = (167, 180, 199)
cyan = (70, 216, 255)
amber = (255, 196, 92)
draw.text((70, 38), "心音|前左方向分解源板校验 v1", font=font(42), fill=white)
draw.text((72, 96), "透明连通对象检测:17 件核心身体/四肢 + 26 件头发/衣摆/附件", font=font(22), fill=muted)
left_rect = (55, 155, 1180, 905)
right_rect = (1220, 155, 2345, 905)
for rect in (left_rect, right_rect):
draw.rounded_rectangle(rect, radius=18, fill=(35, 44, 59), outline=(73, 89, 112), width=2)
draw.text((80, 178), "A 核心身体与四肢|17 个独立对象", font=font(25), fill=cyan)
draw.text((1245, 178), "B 头发、衣摆与附件|26 个独立对象", font=font(25), fill=cyan)
canvas.paste(core, (58, 220))
canvas.paste(soft, (1223, 220))
draw.rounded_rectangle((55, 930, 2345, 1005), radius=14, fill=(34, 42, 56))
draw.text((82, 950), "结论:43 个对象均通过透明分离;软性板多出 1 片后裙候选,保留为动作替换件。", font=font(22), fill=white)
draw.text((1540, 950), "下一步:裁切导出 + 命名 + 枢轴清单", font=font(22), fill=amber)
OUTPUT.parent.mkdir(parents=True, exist_ok=True)
canvas.save(OUTPUT, quality=95)
print(OUTPUT)
if __name__ == "__main__":
main()
+202
View File
@@ -0,0 +1,202 @@
from __future__ import annotations
import argparse
import json
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(__file__).resolve().parent.parent
PREVIEW_DIR = ROOT / "assets/images/2d-game-characters/02-xinyin/previews/playback"
BOARD_SIZE = (1200, 430)
PANEL_CENTERS = (220, 600, 980)
TARGETS = (
{"label": "100%", "height": 176, "cell": (128, 64)},
{"label": "75%", "height": 132, "cell": (96, 48)},
{"label": "50%", "height": 88, "cell": (64, 32)},
)
FOOT_BASELINE = 352
BACKGROUND = (16, 20, 29)
PANEL = (24, 30, 42)
PANEL_LINE = (65, 82, 112)
GRID_FILL = (39, 60, 84)
GRID_LINE = (87, 160, 222)
TEXT = (241, 245, 252)
MUTED = (151, 171, 201)
def load_font(size: int, semibold: bool = False) -> ImageFont.ImageFont:
font_name = "seguisb.ttf" if semibold else "segoeui.ttf"
path = Path("C:/Windows/Fonts") / font_name
if path.exists():
return ImageFont.truetype(str(path), size)
return ImageFont.load_default()
def alpha_bounds(image: Image.Image) -> tuple[int, int, int, int]:
bounds = image.getchannel("A").getbbox()
if bounds is None:
raise ValueError("Transparent frame has no visible pixels")
return bounds
def union_bounds(bounds_list: list[tuple[int, int, int, int]], size: tuple[int, int]) -> tuple[int, int, int, int]:
left = max(0, min(b[0] for b in bounds_list) - 8)
top = max(0, min(b[1] for b in bounds_list) - 8)
right = min(size[0], max(b[2] for b in bounds_list) + 8)
bottom = min(size[1], max(b[3] for b in bounds_list) + 8)
return left, top, right, bottom
def draw_diamond(draw: ImageDraw.ImageDraw, center_x: int, center_y: int, width: int, height: int) -> None:
points = [
(center_x, center_y - height // 2),
(center_x + width // 2, center_y),
(center_x, center_y + height // 2),
(center_x - width // 2, center_y),
]
draw.polygon(points, fill=GRID_FILL, outline=GRID_LINE, width=2)
def build_board(
title: str,
source: Image.Image,
crop: tuple[int, int, int, int],
fonts: dict[str, ImageFont.ImageFont],
) -> Image.Image:
board = Image.new("RGB", BOARD_SIZE, BACKGROUND)
draw = ImageDraw.Draw(board)
draw.text((38, 22), title, font=fonts["title"], fill=TEXT)
draw.text((40, 57), "fixed crop · fixed foot baseline · real frame timing", font=fonts["small"], fill=MUTED)
cropped = source.crop(crop)
crop_width, crop_height = cropped.size
for center_x, target in zip(PANEL_CENTERS, TARGETS):
panel_box = (center_x - 170, 92, center_x + 170, 402)
draw.rounded_rectangle(panel_box, radius=10, fill=PANEL, outline=PANEL_LINE, width=2)
draw.text((center_x - 145, 106), target["label"], font=fonts["label"], fill=TEXT)
draw.text(
(center_x - 145, 137),
f"character {target['height']} px · cell {target['cell'][0]}×{target['cell'][1]}",
font=fonts["small"],
fill=MUTED,
)
draw_diamond(draw, center_x, FOOT_BASELINE, target["cell"][0], target["cell"][1])
scale = target["height"] / crop_height
output_width = max(1, round(crop_width * scale))
resized = cropped.resize((output_width, target["height"]), Image.Resampling.LANCZOS)
paste_x = round(center_x - output_width / 2)
paste_y = FOOT_BASELINE - target["height"]
board.paste(resized, (paste_x, paste_y), resized)
draw.line((center_x - 7, FOOT_BASELINE, center_x + 7, FOOT_BASELINE), fill=(255, 88, 116), width=2)
return board
def save_gif(frames: list[Image.Image], durations: list[int], path: Path) -> None:
palette_source = Image.new("RGB", (BOARD_SIZE[0], BOARD_SIZE[1] * len(frames)), BACKGROUND)
for index, frame in enumerate(frames):
palette_source.paste(frame, (0, index * BOARD_SIZE[1]))
palette = palette_source.quantize(colors=256, method=Image.Quantize.MEDIANCUT)
paletted = [
frame.quantize(palette=palette, dither=Image.Dither.FLOYDSTEINBERG)
for frame in frames
]
paletted[0].save(
path,
save_all=True,
append_images=paletted[1:],
duration=durations,
loop=0,
disposal=2,
optimize=False,
)
def main() -> None:
parser = argparse.ArgumentParser(description="Build fixed-baseline motion playback previews for Xinyin.")
parser.add_argument("--direction", choices=("front-right", "front-left", "down", "up"), default="front-right")
parser.add_argument("--motion-version", type=int)
args = parser.parse_args()
motion_version = args.motion_version or (3 if args.direction == "front-right" else 1)
runtime_direction = {"front-right": "left", "front-left": "right", "down": "down", "up": "up"}[args.direction]
motion_dir = ROOT / f"assets/images/2d-game-characters/02-xinyin/motion/{args.direction}/v{motion_version}"
manifest_path = motion_dir / "motion-manifest.json"
report_path = motion_dir / "playback-report.json"
PREVIEW_DIR.mkdir(parents=True, exist_ok=True)
manifest = json.loads(manifest_path.read_text(encoding="utf-8-sig"))
definitions = {frame["name"]: frame for frame in manifest["frames"]}
images = {
name: Image.open(motion_dir / frame["file"]).convert("RGBA")
for name, frame in definitions.items()
}
source_size = next(iter(images.values())).size
if any(image.size != source_size for image in images.values()):
raise ValueError("Motion frames do not share a common canvas")
bounds_by_name = {name: alpha_bounds(image) for name, image in images.items()}
crop = union_bounds(list(bounds_by_name.values()), source_size)
crop_height = crop[3] - crop[1]
fonts = {
"title": load_font(25, semibold=True),
"label": load_font(20, semibold=True),
"small": load_font(13),
}
sequences = {
"idle": ["idle-inhale", "idle-neutral", "idle-exhale", "idle-neutral"],
"throw": ["throw-ready", "throw-windup", "throw-release", "throw-recover", "idle-neutral"],
}
outputs: dict[str, dict[str, object]] = {}
for sequence_name, names in sequences.items():
title = f"XIN YIN — {runtime_direction.upper()} {sequence_name.upper()} · 100 / 75 / 50%"
boards = [build_board(title, images[name], crop, fonts) for name in names]
durations = [int(definitions[name]["durationMs"]) for name in names]
output_path = PREVIEW_DIR / f"xinyin-{args.direction}-{sequence_name}-scale-loop-v1.gif"
save_gif(boards, durations, output_path)
outputs[sequence_name] = {
"file": output_path.relative_to(ROOT).as_posix(),
"frames": names,
"durationsMs": durations,
"cycleMs": sum(durations),
}
bottoms = [bounds[3] for bounds in bounds_by_name.values()]
report = {
"characterId": "02-xinyin",
"direction": args.direction,
"runtimeDirection": runtime_direction,
"version": 1,
"status": "playback-preview-validated",
"sourceManifest": manifest_path.relative_to(ROOT).as_posix(),
"sourceCanvas": {"width": source_size[0], "height": source_size[1]},
"fixedCrop": {"x": crop[0], "y": crop[1], "width": crop[2] - crop[0], "height": crop_height},
"footBaseline": FOOT_BASELINE,
"sourceVisibleBottomRange": {"min": min(bottoms), "max": max(bottoms), "delta": max(bottoms) - min(bottoms)},
"targets": list(TARGETS),
"outputs": outputs,
"notes": [
"All playback frames use one union crop and one foot baseline; no per-frame recentering is applied.",
"GIF timing uses the authored millisecond durations from motion-manifest.json.",
"The board background is diagnostic only; source motion PNG files remain transparent.",
],
}
report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
for image in images.values():
image.close()
print(f"Created {len(outputs)} animated playback previews.")
print(PREVIEW_DIR)
print(report_path)
if __name__ == "__main__":
main()
+256
View File
@@ -0,0 +1,256 @@
from __future__ import annotations
import json
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ROOT = Path(__file__).resolve().parent.parent
CHARACTER = ROOT / "assets/images/2d-game-characters/02-xinyin"
DIRECTION_MAP_PATH = CHARACTER / "direction-map-v1.json"
PACKAGE_PATH = CHARACTER / "template-package-v1.json"
PREVIEW_PATH = CHARACTER / "previews/xinyin-template-role-handoff-v1.png"
FONT_PATH = Path(r"C:\Windows\Fonts\msyh.ttc")
DIRECTION_ORDER = ("up", "down", "left", "right")
EXPECTED_KEYFRAMES = (
("idle-inhale", 420),
("idle-neutral", 260),
("idle-exhale", 420),
("throw-ready", 150),
("throw-windup", 110),
("throw-release", 90),
("throw-recover", 180),
)
DISPLAY_PROFILES = (
{"label": "100%", "characterHeight": 176, "cell": {"width": 128, "height": 64}},
{"label": "75%", "characterHeight": 132, "cell": {"width": 96, "height": 48}},
{"label": "50%", "characterHeight": 88, "cell": {"width": 64, "height": 32}},
)
def load_json(path: Path) -> dict:
return json.loads(path.read_text(encoding="utf-8-sig"))
def resolve(path_text: str) -> Path:
path = ROOT / path_text
if not path.is_file():
raise FileNotFoundError(path)
return path
def relative(path: Path) -> str:
return path.relative_to(ROOT).as_posix()
def sequence_record(report: dict, name: str) -> dict:
output = report["outputs"][name]
return {
"frames": output["frames"],
"durationsMs": output["durationsMs"],
"cycleMs": output["cycleMs"],
"preview": output["file"],
"loop": name == "idle",
}
def direction_record(runtime_direction: str, source: dict, referenced: set[Path]) -> tuple[dict, Image.Image]:
assembly_path = resolve(source["assembly"])
motion_manifest_path = resolve(source["motionManifest"])
playback_report_path = motion_manifest_path.parent / "playback-report.json"
if not playback_report_path.is_file():
raise FileNotFoundError(playback_report_path)
motion = load_json(motion_manifest_path)
playback = load_json(playback_report_path)
keyframes = {frame["name"]: frame for frame in motion["frames"]}
authored = tuple((name, keyframes[name]["durationMs"]) for name, _ in EXPECTED_KEYFRAMES)
if authored != EXPECTED_KEYFRAMES:
raise ValueError(f"Unexpected keyframe contract for {runtime_direction}: {authored}")
if playback["status"] != "playback-preview-validated":
raise ValueError(f"Playback is not validated for {runtime_direction}")
if playback["sourceVisibleBottomRange"]["delta"] != 0:
raise ValueError(f"Foot baseline moves in {runtime_direction}")
frame_records = []
for name, duration in EXPECTED_KEYFRAMES:
frame_path = motion_manifest_path.parent / keyframes[name]["file"]
if not frame_path.is_file():
raise FileNotFoundError(frame_path)
referenced.add(frame_path)
frame_records.append({"name": name, "durationMs": duration, "file": relative(frame_path)})
for sequence in ("idle", "throw"):
referenced.add(resolve(playback["outputs"][sequence]["file"]))
referenced.update((assembly_path, motion_manifest_path, playback_report_path))
neutral_path = motion_manifest_path.parent / keyframes["idle-neutral"]["file"]
neutral = Image.open(neutral_path).convert("RGBA")
canvas = motion["canvas"]
if neutral.size != (canvas["width"], canvas["height"]):
raise ValueError(f"Neutral frame size mismatch for {runtime_direction}")
record = {
"runtimeDirection": runtime_direction,
"assetDirectionId": source.get("legacyDirectionId") or runtime_direction,
"legacyDirectionId": source.get("legacyDirectionId"),
"status": source["status"],
"assembly": relative(assembly_path),
"motionManifest": relative(motion_manifest_path),
"playbackReport": relative(playback_report_path),
"sourceCanvas": {"width": canvas["width"], "height": canvas["height"]},
"fixedCrop": playback["fixedCrop"],
"sourceVisibleBottom": playback["sourceVisibleBottomRange"]["min"],
"footAnchor": {"normalizedX": 0.5, "normalizedY": 1.0, "policy": "bottom-center of fixed crop"},
"neutralFrame": relative(neutral_path),
"keyframes": frame_records,
"sequences": {
"idle": sequence_record(playback, "idle"),
"throw": sequence_record(playback, "throw"),
},
"artNotes": source["notes"],
}
return record, neutral
def draw_diamond(draw: ImageDraw.ImageDraw, center_x: int, center_y: int, width: int = 128, height: int = 64) -> None:
draw.polygon(
[
(center_x, center_y - height // 2),
(center_x + width // 2, center_y),
(center_x, center_y + height // 2),
(center_x - width // 2, center_y),
],
fill=(38, 60, 85),
outline=(87, 160, 222),
width=2,
)
def make_preview(records: list[dict], neutrals: dict[str, Image.Image]) -> None:
board = Image.new("RGB", (1920, 760), (16, 20, 29))
draw = ImageDraw.Draw(board)
title = ImageFont.truetype(str(FONT_PATH), 38)
subtitle = ImageFont.truetype(str(FONT_PATH), 18)
heading = ImageFont.truetype(str(FONT_PATH), 27)
body = ImageFont.truetype(str(FONT_PATH), 16)
small = ImageFont.truetype(str(FONT_PATH), 14)
draw.text((42, 24), "02 汐月心音|四方向模板角色交付总览 v1", font=title, fill=(242, 246, 252))
draw.text((44, 78), "统一 176 px 显示高度 · 128×64 菱形格 · 固定裁切与脚底中心原点 · 待机/投掷节奏一致", font=subtitle, fill=(151, 171, 201))
labels = {"up": "UP 背面", "down": "DOWN 正面", "left": "LEFT 画面左", "right": "RIGHT 画面右"}
arrows = {"up": "↑", "down": "↓", "left": "←", "right": "→"}
for index, record in enumerate(records):
direction = record["runtimeDirection"]
x0 = 40 + index * 470
y0 = 118
draw.rounded_rectangle((x0, y0, x0 + 430, 650), radius=14, fill=(24, 30, 42), outline=(65, 82, 112), width=2)
draw.text((x0 + 20, y0 + 18), f"{arrows[direction]} {labels[direction]}", font=heading, fill=(242, 246, 252))
asset_id = record["assetDirectionId"]
alias = f"运行时 {direction} ← 历史 {asset_id}" if record["legacyDirectionId"] else f"运行时与素材目录均为 {direction}"
draw.text((x0 + 22, y0 + 58), alias, font=small, fill=(151, 171, 201))
center_x = x0 + 215
foot_y = 500
draw_diamond(draw, center_x, foot_y)
crop_data = record["fixedCrop"]
crop = (
crop_data["x"],
crop_data["y"],
crop_data["x"] + crop_data["width"],
crop_data["y"] + crop_data["height"],
)
cropped = neutrals[direction].crop(crop)
output_height = 176
output_width = max(1, round(cropped.width * output_height / cropped.height))
resized = cropped.resize((output_width, output_height), Image.Resampling.LANCZOS)
board.paste(resized, (center_x - output_width // 2, foot_y - output_height), resized)
draw.line((center_x - 8, foot_y, center_x + 8, foot_y), fill=(255, 88, 116), width=3)
draw.rounded_rectangle((x0 + 20, 530, x0 + 410, 575), radius=8, fill=(31, 48, 56), outline=(66, 156, 121), width=1)
draw.text((x0 + 34, 542), "ART TEMPLATE READY", font=body, fill=(132, 232, 184))
draw.text((x0 + 20, 590), "idle 420 / 260 / 420 / 260 ms", font=small, fill=(200, 211, 229))
draw.text((x0 + 20, 616), "throw 150 / 110 / 90 / 180 / 260 ms", font=small, fill=(200, 211, 229))
draw.rounded_rectangle((40, 674, 1880, 730), radius=10, fill=(22, 27, 38), outline=(52, 68, 94), width=1)
draw.text((60, 690), "当前交付:PNG 帧动画优先接入;分解件与枢轴清单保留给后续 Skeleton2D。尚未完成 Godot 导入、纹理设置、碰撞/选择框及引擎内性能验证。", font=body, fill=(177, 190, 212))
PREVIEW_PATH.parent.mkdir(parents=True, exist_ok=True)
board.save(PREVIEW_PATH, quality=95)
def main() -> None:
direction_map = load_json(DIRECTION_MAP_PATH)
referenced: set[Path] = {DIRECTION_MAP_PATH}
records = []
neutrals = {}
for direction in DIRECTION_ORDER:
record, neutral = direction_record(direction, direction_map["directions"][direction], referenced)
records.append(record)
neutrals[direction] = neutral
canvas_sizes = {(record["sourceCanvas"]["width"], record["sourceCanvas"]["height"]) for record in records}
if canvas_sizes != {(600, 760)}:
raise ValueError(f"Runtime motion canvases are not normalized: {canvas_sizes}")
package = {
"characterId": "02-xinyin",
"characterNameZh": "汐月心音",
"version": 1,
"status": "art-template-ready",
"engineIntegrationStatus": "not-started-no-godot-project",
"recommendedIntegration": {
"primary": "frame-animation",
"description": "Import the validated full-frame PNG keyframes first; use decomposed parts and pivots for a later Skeleton2D implementation.",
"spriteOrigin": "bottom-center",
"textureFilter": "linear at 176/132 px; compare linear and nearest at 88 px in-engine",
},
"directionModel": {
"type": direction_map["runtimeDirectionModel"],
"directions": list(DIRECTION_ORDER),
"selectionRule": direction_map["selectionRule"],
"aimingRule": direction_map["aimingRule"],
},
"displayProfiles": list(DISPLAY_PROFILES),
"animationContract": {
"keyframes": [{"name": name, "durationMs": duration} for name, duration in EXPECTED_KEYFRAMES],
"idle": {"frames": ["idle-inhale", "idle-neutral", "idle-exhale", "idle-neutral"], "cycleMs": 1360, "loop": True},
"throw": {"frames": ["throw-ready", "throw-windup", "throw-release", "throw-recover", "idle-neutral"], "cycleMs": 790, "loop": False},
},
"directions": records,
"rebuildTools": [
"tools/build_xinyin_motion_playback.py",
"tools/build_xinyin_down_assembly.py",
"tools/build_xinyin_down_motion.py",
"tools/build_xinyin_up_assembly.py",
"tools/build_xinyin_up_motion.py",
"tools/build_xinyin_template_package.py",
],
"validation": {
"directionCount": len(records),
"allDirectionsMotionValidated": all(record["status"] == "motion-art-validated" for record in records),
"commonMotionCanvas": {"width": 600, "height": 760},
"allPlaybackBaselinesFixed": True,
"referencedFileCount": len(referenced),
"missingReferencedFiles": [],
},
"limitations": [
"No Godot project exists yet, so import settings, AnimationPlayer/SpriteFrames resources, and engine-side playback remain unverified.",
"Collision, selection, navigation, shadow, sorting, and VFX sockets are not part of this art-only package.",
"LEFT and RIGHT retain legacy front-right/front-left directories; consume this package instead of guessing folder names.",
"Body facing is four-cardinal while projectile and VFX aim are free-angle.",
],
}
PACKAGE_PATH.write_text(json.dumps(package, ensure_ascii=False, indent=2), encoding="utf-8")
make_preview(records, neutrals)
for image in neutrals.values():
image.close()
print(PACKAGE_PATH)
print(PREVIEW_PATH)
print(json.dumps(package["validation"], ensure_ascii=False))
if __name__ == "__main__":
main()

Some files were not shown because too many files have changed in this diff Show More