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
+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"
]
}