phaser4-spine-generative-reskin

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phaser 4 Spine 生成式换皮

Phaser 4 Spine Generative Reskinning

全局控制接入

Global Control Integration

控制面边界：可提议、可审查、可在已建立且任务授权有效的 Work Item 范围内修改，且必须回到

$phaser4-game-workflow-control

审计和状态迁移；仅实际 A4-A6 操作请求批准。

Spine 换皮是资源生产域，不得旁路全局控制。只在已建立且任务授权有效的 Work Item、冻结 Implementation Package、A 等级和 Atlas/输出路径内修改；每次恢复、生成、重建与验证都按

phaser4-game-workflow-control

提交证据和状态，仅实际 A4-A6 操作请求批准。

先将

<skill-dir>

解析为本

SKILL.md

所在的 Skill 根目录；以下所有工具命令都使用

node <skill-dir>/scripts/spine_reskin_progress.mjs

，不依赖当前工作目录。复制安装器会在该 Skill 目录安装 Sharp，不会修改目标游戏项目的依赖清单。

按以下顺序完成整套换皮。任何一个 Cell 未完成、校验失败或状态不明，都不得宣称交付完成。

Control Plane Boundaries: Proposals, reviews, and modifications are allowed within the scope of established and task-authorized valid Work Items, and must return to

$phaser4-game-workflow-control

for audit and state migration; only actual A4-A6 operation requests require approval.

Spine reskinning belongs to the resource production domain and must not bypass global control. Modifications are only permitted within established and task-authorized valid Work Items, frozen Implementation Packages, A-level tiers, and Atlas/output paths; every recovery, generation, reconstruction, and verification must submit evidence and update status in accordance with

phaser4-game-workflow-control

, with only actual A4-A6 operation requests requiring approval.

First resolve

<skill-dir>

to the root directory of the Skill where this

SKILL.md

is located; all tool commands below use

node <skill-dir>/scripts/spine_reskin_progress.mjs

and do not depend on the current working directory. The copy installer will install Sharp in this Skill directory and will not modify the dependency manifest of the target game project.

Complete the entire reskinning process in the following order. Do not claim delivery completion if any Cell is unfinished, fails verification, or has an unknown status.

1. 审计输入并建立候选目录

1. Audit Inputs and Establish Candidate Directory

找到
```
.atlas
```
、所有 Page 图片和配套 Skeleton JSON/Binary；记录 Phaser 4、Spine runtime 版本、纹理加载器、PMA 约定和运行入口。

运行

node <skill-dir>/scripts/spine_reskin_progress.mjs init --atlas <source.atlas> --output <candidate>/progress.json

。默认把候选写入新目录，禁止覆盖原 Atlas、Page 或 Skeleton；需要源 Cell 参考时增加

--reference-dir <candidate>/source-cells

。

审核清单中的每一页尺寸、格式、filter、repeat、pma、scale，以及每个 Region 的
```
xy/size/orig/offset/index/rotate
```
或
```
bounds/offsets
```
。发现重复 ID、缺页、越界或字段无法解析时立即停止。
用清单列出全部 Cell，不以 Attachment 数量、首个 Page 或可见角色数量代替总数。记录源 Atlas、全部 Page 和配套 Skeleton 文件的 SHA-256，确保后续不会误用旧候选。

详细的多 Page、trim/offset/UV、padding/extrusion、PMA 和透明空白页规则见 references/atlas-rebuild.md。

Locate the
```
.atlas
```
, all Page images, and matching Skeleton JSON/Binary; record Phaser 4, Spine runtime version, texture loader, PMA conventions, and runtime entry point.
Run
```
node <skill-dir>/scripts/spine_reskin_progress.mjs init --atlas <source.atlas> --output <candidate>/progress.json
```
. By default, candidates are written to a new directory; overwriting the original Atlas, Page, or Skeleton is prohibited. Add
```
--reference-dir <candidate>/source-cells
```
when source Cell references are needed.
Review the size, format, filter, repeat, pma, scale of each page in the checklist, as well as
```
xy/size/orig/offset/index/rotate
```
or
```
bounds/offsets
```
of each Region. Stop immediately if duplicate IDs, missing pages, out-of-bounds issues, or unparseable fields are found.
List all Cells in the checklist; do not replace the total count with the number of Attachments, first Page, or visible characters. Record the SHA-256 of the source Atlas, all Pages, and matching Skeleton files to ensure old candidates are not misused later.

Detailed rules for multi-Page, trim/offset/UV, padding/extrusion, PMA, and transparent blank pages can be found in references/atlas-rebuild.md.

2. 冻结全局风格与结构参考

2. Freeze Global Style and Structure References

在清单中登记全局角色/材质/光照/色彩/轮廓参考和排除项；每个 Cell 同时传入原 Cell 参考图与同一份全局参考。
原 Cell 只能用于结构、比例、透明轮廓、裁剪边界和 Mesh 语义参考，或作为生成模型的蒙版。禁止复制原图 RGB、抠取原图像素、以原 Page 作为输出底图或在失败时回退到原纹理。
对每个 Cell 标注是否为刚体、可变形 Mesh、附件点缀、阴影/高光或透明特效。不要改变 Attachment 名称、Skeleton 绑定、Mesh 顶点顺序或 UV 语义。

Register global character/material/lighting/color/outline references and exclusions in the checklist; pass both the original Cell reference image and the same global reference to each Cell simultaneously.
Original Cells can only be used for references to structure, proportions, transparent outlines, cropping boundaries, and Mesh semantics, or as masks for generation models. Copying original image RGB values, extracting original image pixels, using original Pages as output base maps, or falling back to original textures upon failure is prohibited.
Mark whether each Cell is a rigid body, deformable Mesh, attachment ornament, shadow/highlight, or transparent effect. Do not change Attachment names, Skeleton bindings, Mesh vertex order, or UV semantics.

3. 逐 Cell 生成并持久化

3. Generate and Persist Cell by Cell

先把 Cell 标为

generating

：

node <skill-dir>/scripts/spine_reskin_progress.mjs mark --manifest <candidate>/progress.json --cell <cell-id> --status generating

。

使用当前可用的图片生成能力逐 Cell 生图。每次请求都传入该 Cell 的原图参考、全局风格/角色参考和清单中的
```
orig
```
/
```
size
```
/
```
rotate
```
约束；保持同一角色跨 Cell 的脸、材质、光向、颜色和透明边缘一致。不要在初始化 Skill 时实际生图。
让输出图符合清单的结构契约：可提供未裁剪的
```
orig
```
尺寸（工具会按
```
offset
```
/
```
size
```
提取），或直接提供正向的裁剪
```
size
```
尺寸；旋转 Cell 必须按正向尺寸提供，再由打包器旋回 Atlas 方向。保留真实透明度，不用纯色背景填充。

生成后立即写入不可变候选路径并标记：

node <skill-dir>/scripts/spine_reskin_progress.mjs mark --manifest <candidate>/progress.json --cell <cell-id> --status generated --image <candidate>/generated/<file>.png

。工具会记录 SHA-256、尝试次数和状态历史；不要手改 JSON。失败则用

--status failed --error <原因>

，修复后从

failed

重新进入

generating

。

每批生成后运行
```
status
```
，需要审阅完整字段时运行
```
read
```
；进程中断时运行
```
recover
```
，把
```
generating/validating/packing
```
安全退回
```
pending
```
，再继续，禁止把旧图冒充新图。

First mark the Cell as

generating

node <skill-dir>/scripts/spine_reskin_progress.mjs mark --manifest <candidate>/progress.json --cell <cell-id> --status generating

Use the currently available image generation capability to generate images for each Cell individually. Pass the original Cell reference image, global style/character reference, and
```
orig
```
/
```
size
```
/
```
rotate
```
constraints from the checklist with each request; maintain consistency in face, material, light direction, color, and transparent edges of the same character across Cells. Do not generate images during Skill initialization.
Ensure the output image complies with the structural contract of the checklist: you can provide the uncropped
```
orig
```
size (the tool will extract it according to
```
offset
```
/
```
size
```
), or directly provide the cropped
```
size
```
in positive orientation; rotated Cells must be provided in positive orientation size, then rotated back to the Atlas orientation by the packer. Retain real transparency; do not fill with a solid color background.
Immediately write the generated image to an immutable candidate path and mark the status:
```
node <skill-dir>/scripts/spine_reskin_progress.mjs mark --manifest <candidate>/progress.json --cell <cell-id> --status generated --image <candidate>/generated/<file>.png
```
. The tool will record the SHA-256, number of attempts, and status history; do not manually modify the JSON. If failed, use
```
--status failed --error <reason>
```
, then re-enter
```
generating
```
from
```
failed
```
after fixing.
Run
```
status
```
after each batch of generation; run
```
read
```
when full field review is needed; run
```
recover
```
when the process is interrupted to safely revert
```
generating/validating/packing
```
statuses back to
```
pending
```
before continuing. Do not pass off old images as new ones.

4. 逐 Cell 透明度、形状和 Mesh 语义检查

4. Cell-by-Cell Transparency, Shape, and Mesh Semantics Check

对照原 Cell 参考检查可见轮廓、透明边缘、锚点、方向、阴影层级和可读性；检查生成图的 alpha 是否有意外背景、孔洞或裁切。
对 Mesh/九宫格/变形附件，确认关键形状、透明区域和局部细节仍落在原
```
orig
```
/
```
offset
```
语义内；不要通过改 Atlas 坐标“修图”。
将 Cell 标为
```
validating
```
；不通过就标为
```
failed
```
并记录原因。只有所有 Cell 都通过，才允许进入
```
packing
```
。

Check visible outlines, transparent edges, anchors, directions, shadow layers, and readability against the original Cell reference; check if the generated image's alpha has unexpected backgrounds, holes, or cropping issues.
For Mesh/9-slice/deformable attachments, confirm that key shapes, transparent areas, and local details still fall within the original
```
orig
```
/
```
offset
```
semantics; do not "fix images" by modifying Atlas coordinates.
Mark the Cell as
```
validating
```
; mark it as
```
failed
```
and record the reason if it fails. Only when all Cells pass can you proceed to
```
packing
```
.

5. 从透明空白 Page 重建

5. Rebuild from Transparent Blank Pages

使用
```
node <skill-dir>/scripts/spine_reskin_progress.mjs pack --manifest <candidate>/progress.json --output-dir <candidate>/atlas
```
。工具会为每个原 Page 创建全透明 RGBA 空白页，只将已生成图按原
```
xy/size
```
放回；不会读取源 Page 像素。
保留原 Region 名称、Page 顺序、坐标、trim/orig/offset、rotate、index、filter、repeat、scale 和 Skeleton 所需字段。按原旋转方向写回；根据 Page 的
```
pma
```
将生成图做 straight-alpha 到 premultiplied-alpha 转换。
按项目约定设置
```
--padding
```
与
```
--extrusion
```
；填充和边缘扩展只能来自当前生成图，且必须落在原 Region 矩形内，不能改变 UV 坐标。多 Page 必须逐页输出并在新 Atlas 中保持对应 Page 引用。
任一 Cell 缺图、尺寸不符、旋转/裁剪越界、Sharp 不可用或写盘失败，都保持候选不完成，记录
```
failed
```
，修复后重试。不要发布部分 Page。

Use
```
node <skill-dir>/scripts/spine_reskin_progress.mjs pack --manifest <candidate>/progress.json --output-dir <candidate>/atlas
```
. The tool will create fully transparent RGBA blank pages for each original Page, and only place the generated images back according to the original
```
xy/size
```
; it will not read pixels from the source Pages.
Retain the original Region names, Page order, coordinates, trim/orig/offset, rotate, index, filter, repeat, scale, and fields required by the Skeleton. Write back according to the original rotation direction; convert the generated image from straight-alpha to premultiplied-alpha based on the Page's
```
pma
```
.
Set
```
--padding
```
and
```
--extrusion
```
according to project conventions; padding and edge expansion can only come from the current generated image and must fall within the original Region rectangle, without changing UV coordinates. Multi-Page outputs must be generated page by page and maintain corresponding Page references in the new Atlas.
If any Cell is missing an image, has mismatched dimensions, is out of bounds due to rotation/cropping, has unavailable Sharp, or fails to write to disk, keep the candidate incomplete, record
```
failed
```
, and retry after fixing. Do not release partial Pages.

6. 完成门与 Phaser 运行态验证

6. Completion Gate and Phaser Runtime Verification

打包成功后工具将 Cell 标为
```
completed
```
并记录候选 Page/Atlas 哈希。运行
```
node <skill-dir>/scripts/spine_reskin_progress.mjs verify --manifest <candidate>/progress.json
```
；未完成、哈希不匹配或产物缺失必须返回非零。
在隔离的 Phaser 4 候选场景加载新 Atlas 与原 Skeleton，逐一播放待测动画、Attachment 和 Mesh 变形；检查无缺图、错位、翻转、PMA 黑边、透明底色、UV 断裂和跨 Page 问题。至少保留整体预览截图/录屏和控制台日志。
运行态验证失败时保留失败候选，创建新的进度清单并从受影响 Cell 重新生成、验证和打包；禁止修改已
```
completed
```
的清单或把失败状态覆盖掉。不得只改运行时代码或宣称“视觉上差不多”。手工比较原 Skeleton 文件 SHA-256 及 Skeleton/Attachment/Mesh UV 是否保持不变；工具
```
verify
```
不自动校验 Skeleton。只有新清单全 Cell
```
completed
```
、验证证据绑定当前候选哈希且手工比较通过，才可交付。

After successful packing, the tool will mark the Cell as
```
completed
```
and record the hash of the candidate Page/Atlas. Run
```
node <skill-dir>/scripts/spine_reskin_progress.mjs verify --manifest <candidate>/progress.json
```
; return a non-zero code if incomplete, hash mismatch, or product missing.
Load the new Atlas and original Skeleton in an isolated Phaser 4 candidate scene, play each animation, Attachment, and Mesh deformation to be tested one by one; check for missing images, misalignment, flipping, PMA black edges, transparent backgrounds, UV breaks, and cross-Page issues. Retain at least the overall preview screenshot/screen recording and console logs.
If runtime verification fails, keep the failed candidate, create a new progress checklist, and regenerate, verify, and pack from the affected Cells; do not modify the already
```
completed
```
checklist or overwrite failed statuses. Do not only modify runtime code or claim "visually similar". Manually compare the SHA-256 of the original Skeleton file and confirm that Skeleton/Attachment/Mesh UV remain unchanged; the
```
verify
```
tool does not automatically check the Skeleton. Delivery is only allowed when all Cells in the new checklist are
```
completed
```
, verification evidence is bound to the current candidate hash, and manual comparison passes.

7. 最终工件与恢复

7. Final Artifacts and Recovery

交付新

.atlas

、全部新 Page PNG、进度清单、生成图/参考图索引、全局参考、哈希清单、整体预览和 Phaser 运行态验证记录。保留原 Atlas 与原 Page 只作回滚对照；任何 Cell 失败都公开报告 ID、原因、重试次数和下一步，不得静默跳过。

进度状态和字段约束见 references/progress-state.md。

Deliver the new

.atlas

, all new Page PNGs, progress checklist, generated/reference image index, global references, hash checklist, overall preview, and Phaser runtime verification records. Retain the original Atlas and Pages only for rollback comparison; publicly report the ID, reason, number of retries, and next steps for any failed Cell, do not silently skip it.

Progress status and field constraints can be found in references/progress-state.md.

工具命令

Tool Commands

在仓库根目录运行：

powershell

node <skill-dir>/scripts/spine_reskin_progress.mjs --help
node --test <skill-dir>/scripts/spine_reskin_progress.test.mjs

工具缺少 Sharp 时会由 Node.js 给出依赖解析错误并返回非零；通过官方复制安装器安装时依赖会放在 Skill 自身目录。

Run in the repository root directory:

powershell

node <skill-dir>/scripts/spine_reskin_progress.mjs --help
node --test <skill-dir>/scripts/spine_reskin_progress.test.mjs

If Sharp is missing, Node.js will return a dependency resolution error with a non-zero code; dependencies will be placed in the Skill's own directory when installed via the official copy installer.