phaser4-game-asset-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phaser 4 游戏美术生产与接入

Phaser 4 Game Art Production and Integration

全局控制接入

Global Control Integration

控制面边界：可提议、可审查、可在 Work Item 任务授权或显式批准范围内修改，且必须回到

$phaser4-game-workflow-control

风险门。

本领域可提议、审查，并仅在已建立且任务授权有效的 Work Item、Implementation Package、A 等级和路径内生产或接入资源；所有结论回到

phaser4-game-workflow-control

审计和状态迁移。V0-V5 是

stageId

，不得旁路全局状态、A4-A6 精确操作批准、diff 审计和证据门。

Control Plane Boundaries: Proposals, reviews, and modifications are allowed within the scope of Work Item task authorization or explicit approval, and must return to the

$phaser4-game-workflow-control

risk gate.

Within this domain, proposals and reviews are allowed, and resources can only be produced or integrated within established and task-validated Work Items, Implementation Packages, Level A and paths; all conclusions are subject to audit and state migration in

phaser4-game-workflow-control

. V0-V5 are

stageId

s, and bypassing global states, Level A4-A6 precise operation approvals, diff audits and evidence gates is prohibited.

工作流

Workflow

场景还原合同（effect-image 强制）

Scene Reconstruction Contract (effect-image Mandatory)

effect-image

表示完整正式 Scene 的忠实还原，不是独立 PNG 生产。进入 V3 前必须有

scene_reconstruction_contract

：冻结目标条件、整屏构图、逐 coverage region 视觉事实（runtime-data/runtime-rendered/runtime-program 也必须有

fidelity_obligations

）、目标绑定布局、响应式关系、预声明容差和资源/布局/运行时对象/组合实现计划。合同缺失或 layout contract 未绑定当前 target SHA 时，必须返回

V1/PROPOSAL

。

V4 需要使用正式 Scene 结构的同屏组合预验收；V5 需要结构化 fidelity case、逐区域测量与差异证据、确定性机器 F2、F3 runtime replay 和正式 Scene 消费证据。资源 loaded/used、missing=0、resize 稳定只属于工程子门，不能单独驱动 COMPLETE。

读取项目配置、GDD、visual-design、TDD、控制面和资源登记；执行 V0-V5 视觉生产管线。
V0 先判断任务属于原子资源、组件/资源集，还是场景/整套 UI/视觉系统/参考还原。原子资源只有在结构、布局、交互和视口行为不变，且已有适用视觉契约、
```
AUTO
```
或
```
USER_DECISION
```
记录、视觉可交付结论与预算基线时才能跳过 V1/V2。
V1 建立玩法视觉契约、必要低保真/灰盒与预算，V2 执行方向基准、动态样片、机器结构化检查和唯一一次真人视觉方向审批。Work Item 指定效果图为还原目标时按视觉还原启用忠实还原模式，将参考身份、对比条件和可观察视觉事实冻结为视觉目标；容差内且不改变视觉事实的适配可
```
AUTO
```
，任何可见偏差或实质取舍必须记录一次精确
```
USER_DECISION
```
和已批准例外。不得以专业修复或提升游戏感为由自动改变冻结视觉目标。
schema 1.5
```
visual-assets.json
```
先声明
```
effect_image_reconstruction
```
：普通资产为
```
not-applicable
```
，不要求还原工件；效果图还原为
```
effect-image
```
。后者冻结目标后、进入 V3 前以
```
v3-ready
```
完成合同回对和 coverage，V3/V4 可暂无 fidelity case；只有 V5 验证完成才为
```
v5-complete
```
并要求全部 case 通过。效果图 coverage 逐区登记
```
annotation_number
```
与
```
implementation_plan
```
，先完成 ownership/实现分类，再做带证据 SHA、冻结目标 SHA、分析 ID 和完成时间的
```
state_analysis
```
，严格在 component inventory 之前完成，最后按唯一原子部件填写
```
component_inventory
```
、placements 与
```
expected_assets
```
；编号不是资产数量单位。状态分析必须覆盖普通、selected/active、disabled、pressed/hover、victory/defeat/paused，实际适用写
```
required
```
，不适用写
```
not-applicable+reason
```
。② 顶部 6 个按钮必须 6 个 component；⑧ 的 3 个相同底部表面可登记 1 个 component+3 个 placements，⑨ 的动作图标按实际复用关系登记；③、④、⑦ 只有在明确单部件且其余状态不适用时才保持单图。默认 individual 模式禁止横向组图；ImageGen 无条件要求
```
individual + atlas_allowed=false
```
，其
```
expected_assets.width/height
```
由验证器按逻辑像素
```
ceil(max placement width/height × intended_scale_range.max × 1.5)
```
自动计算，必须精确为最小尺寸；
```
scene_asset_usage.max_dpr
```
必须严格为数字
```
1.5
```
，
```
padding_policy
```
必须为
```
none
```
，尺寸合同本身不需要 human_review。这里的 1.5 是最大生产 DPR；运行时实际 DPR 按设备动态读取并封顶为 1.5。只有 authored-raster/authored-svg/reuse 等非 ImageGen 方法才可在显式合同下使用完整
```
atlas_slice
```
图集。每个 placement 必须声明
```
interaction_required
```
，真实
```
interaction_hotspots
```
只能按 placement 一一绑定且不计入视觉资产。确认图仍同时呈现
```
generate-now
```
、
```
reuse-existing
```
和
```
runtime-program
```
，但 PNG 仅绘制用户摘要与“本次生成 / 复用既有资源 / 程序实现”标签；placement ID、坐标尺寸、组件/状态/资产技术字段不进入可见行。运行
```
--proposal
```
时，这些技术字段完整写入拆解分析技术 JSON，并与 PNG 元数据、区域定义 SHA 及现有 confirmation 字段绑定。ImageGen 只有在合同显式声明
```
image_generation_required=true
```
时才启用，并且必须使用
```
imagegen+raster-image
```
、完整提示词/生成记录、输出元数据和运行时消费证据；
```
independent-production
```
与
```
generate-now
```
不作任何 ImageGen 推断。V3 再按资产生产路线选择路线。
V3 可运行
```
node scripts/validate_visual_manifest.mjs docs/visual-assets.json --stage V3
```
；V4 正式验收运行
```
node scripts/validate_visual_manifest.mjs docs/visual-assets.json --stage V4 --check-files --project-root .
```
，V5 正式验收运行同命令但使用
```
--stage V5
```
。两阶段均逐项验证真实文件、授权、预算、冻结基线、coverage、
```
production_contract_audit
```
、F2 两类机器证据、F3 runtime replay 和 freshness-bound fidelity cases。效果图清单根节点必须绑定单一 camelCase 的
```
workItemId
```
与
```
candidateVersion
```
，并与
```
candidate_identity.sha256/diff_fingerprint
```
及当前实施包一致。
按 G1 场景序列先完成全部 gameplay 场景的 V3-V5 闭环，再完成 supporting 场景；公共正式资源只允许至少两个场景稳定复用或运行必需。只将 V4
```
accepted
```
资源接入 V5，并在当前场景联合验收前清除灰盒、占位和 fallback。
V1 灰盒、V2 可玩视觉切片和 V5 正式场景沿用同一生产 Scene 入口/骨架逐步重构；禁止一次性截图 Scene、整屏铺图、隐藏覆盖层和绝对叠层凑像素。V5 与玩法协作完成结构化集成、动态验收和低保真清理，fidelity case 任一目标、代码、布局或基线身份变化都必须失效重采。

正式效果图标注命令必须带

--proposal <file>.json

；省略该参数直接失败，不生成只有用户图示的成功产物。

effect-image

refers to the faithful reconstruction of a complete formal Scene, not independent PNG production. A

scene_reconstruction_contract

must be in place before entering V3: freeze target conditions, full-screen composition, visual facts per coverage region (runtime-data/runtime-rendered/runtime-program must also have

fidelity_obligations

), target-bound layout, responsive relationships, pre-declared tolerances and resource/layout/runtime object/composition implementation plan. If the contract is missing or the layout contract is not bound to the current target SHA, it must return to

V1/PROPOSAL

V4 requires pre-acceptance of same-screen composition using formal Scene structure; V5 requires structured fidelity cases, region-by-region measurement and difference evidence, deterministic machine F2, F3 runtime replay and formal Scene consumption evidence. Resources loaded/used, missing=0, and stable resize are only part of engineering sub-gates and cannot independently drive COMPLETE.

Read project configuration, GDD, visual-design, TDD, control plane and resource registration; execute V0-V5 Visual Production Pipeline.
At V0, first determine whether the task belongs to atomic resources, components/resource sets, or scenes/complete UI/visual systems/reference reconstruction. Atomic resources can skip V1/V2 only if their structure, layout, interaction and viewport behavior remain unchanged, and there are applicable visual contracts,
```
AUTO
```
or
```
USER_DECISION
```
records, visual deliverable conclusions and budget baselines.
At V1, establish gameplay visual contracts, necessary low-fidelity/graybox and budget; at V2, execute direction benchmarks, dynamic samples, machine structured checks and a single human visual direction approval. When the Work Item specifies a render as the reconstruction target, enable faithful reconstruction mode according to Visual Reconstruction, freezing the reference identity, comparison conditions and observable visual facts as visual targets; adaptations within tolerance that do not change visual facts can be
```
AUTO
```
, and any visible deviation or substantial trade-off must record an accurate
```
USER_DECISION
```
and approved exception. Do not automatically change frozen visual targets under the pretext of professional fixes or enhancing game feel.
Schema 1.5
```
visual-assets.json
```
first declares
```
effect_image_reconstruction
```
: ordinary assets are
```
not-applicable
```
, no reconstruction artifacts required; render reconstruction is
```
effect-image
```
. For the latter, after freezing the target and before entering V3, complete contract alignment and coverage with
```
v3-ready
```
, and fidelity cases can be absent in V3/V4; only after V5 verification is completed can it be marked as
```
v5-complete
```
with all cases required to pass. For render coverage, register
```
annotation_number
```
and
```
implementation_plan
```
region by region, first complete ownership/implementation classification, then conduct
```
state_analysis
```
with evidence SHA, frozen target SHA, analysis ID and completion time, strictly complete this before component inventory, and finally fill in
```
component_inventory
```
, placements and
```
expected_assets
```
by unique atomic parts; numbers are not units of asset quantity. State analysis must cover normal, selected/active, disabled, pressed/hover, victory/defeat/paused, mark
```
required
```
for applicable states, and
```
not-applicable+reason
```
for inapplicable ones. ② The 6 top buttons must be 6 components; ⑧ The 3 identical bottom surfaces can be registered as 1 component + 3 placements; ⑨ Action icons are registered according to actual reuse relationships; ③, ④, ⑦ can remain as single images only if they are clearly single parts and other states are not applicable. Default individual mode prohibits horizontal sprite sheets; ImageGen unconditionally requires
```
individual + atlas_allowed=false
```
, its
```
expected_assets.width/height
```
is automatically calculated by the validator as
```
ceil(max placement width/height × intended_scale_range.max × 1.5)
```
in logical pixels, which must be the exact minimum size;
```
scene_asset_usage.max_dpr
```
must be strictly the number
```
1.5
```
,
```
padding_policy
```
must be
```
none
```
, and the size contract itself does not require human_review. Here 1.5 is the maximum production DPR; the actual runtime DPR is dynamically read by the device and capped at 1.5. Only non-ImageGen methods such as authored-raster/authored-svg/reuse can use complete
```
atlas_slice
```
atlases under explicit contracts. Each placement must declare
```
interaction_required
```
, and real
```
interaction_hotspots
```
can only be bound one-to-one by placement and are not counted as visual assets. The confirmation image still displays
```
generate-now
```
,
```
reuse-existing
```
and
```
runtime-program
```
simultaneously, but the PNG only draws the user summary and the labels "Generate This Time / Reuse Existing Resources / Program Implementation"; placement ID, coordinate size, component/state/asset technical fields do not appear in visible rows. When running
```
--proposal
```
, these technical fields are fully written into the disassembly analysis technical JSON, and bound to PNG metadata, region definition SHA and existing confirmation fields. ImageGen is only enabled when the contract explicitly declares
```
image_generation_required=true
```
, and must use
```
imagegen+raster-image
```
, complete prompts/generation records, output metadata and runtime consumption evidence;
```
independent-production
```
and
```
generate-now
```
do not make any ImageGen inferences. At V3, select the route according to Asset Production Routes.
At V3, run
```
node scripts/validate_visual_manifest.mjs docs/visual-assets.json --stage V3
```
; for formal acceptance at V4, run
```
node scripts/validate_visual_manifest.mjs docs/visual-assets.json --stage V4 --check-files --project-root .
```
, and for formal acceptance at V5, run the same command with
```
--stage V5
```
. Both stages verify real files, authorization, budget, frozen baseline, coverage,
```
production_contract_audit
```
, two types of machine evidence for F2, F3 runtime replay and freshness-bound fidelity cases item by item. The root node of the render list must be bound to a single camelCase
```
workItemId
```
and
```
candidateVersion
```
, and consistent with
```
candidate_identity.sha256/diff_fingerprint
```
and the current implementation package.
Complete the V3-V5 closed loop for all gameplay scenes first according to the G1 scene sequence, then complete supporting scenes; public formal resources are only allowed to be stably reused by at least two scenes or required for runtime. Only V4
```
accepted
```
resources are integrated into V5, and grayboxes, placeholders and fallbacks are cleared before joint acceptance of the current scene.
V1 graybox, V2 playable visual slices and V5 formal scenes use the same production Scene entry/skeleton for gradual reconstruction; prohibit one-time screenshot Scene, full-screen image laying, hiding overlays and absolute stacking to match pixels. At V5, collaborate with gameplay to complete structured integration, dynamic acceptance and low-fidelity cleanup; any change to fidelity case targets, code, layout or baseline identity must invalidate and re-collect.

The formal render annotation command must include

--proposal <file>.json

; omitting this parameter will directly fail, and no successful product with only user illustrations will be generated.

条件参考

Reference Conditions

参考截图、录屏、运行项目或源码还原：读取视觉还原。
装饰性屏幕空间满幅背景：读取满幅背景；世界空间关卡、Tilemap 或玩法环境改读资产生产路线。
UI：同时读取
```
phaser4-game-ui-layout
```
的布局合同、Phaser 适配器和证据矩阵；资源 origin、布局锚点与动画偏移按合同分离，资产接入不得重新发明布局规则。
QA 测量、动态 resize、完整 viewport 截图和只读 Hook：读取响应式视觉验证，不得在资产文档复制其字段或阈值。

Reference screenshots, screen recordings, running projects or source code reconstruction: read Visual Reconstruction.
Decorative full-screen background in screen space: read Full-Bleed Background; for world space levels, Tilemap or gameplay environment, read Asset Production Routes instead.
UI: read the layout contract, Phaser adapter and evidence matrix of
```
phaser4-game-ui-layout
```
simultaneously; resource origin, layout anchor and animation offset are separated according to the contract, and resource integration must not reinvent layout rules.
QA measurement, dynamic resize, full viewport screenshot and read-only Hook: read Responsive Visual Validation, and do not copy its fields or thresholds in asset documents.

审核与交付

Audit and Delivery

所有候选先通过 F0-F3，F4 只用于 A4-A6。V1/V2 确定性机器检查必须执行；用户选择是条件性的。自动路径记录

AUTO

决策依据，实质取舍记录一次

USER_DECISION

并回写权威工件。每个交付包记录任务授权或 A4-A6 操作批准、候选身份、基线、来源、预算和证据。

All candidates must pass F0-F3 first, and F4 is only used for A4-A6. Deterministic machine checks for V1/V2 must be executed; user selection is conditional. Automatic paths record the basis for

AUTO

decisions, and substantial trade-offs record one

USER_DECISION

and write back to authoritative artifacts. Each delivery package records task authorization or A4-A6 operation approval, candidate identity, baseline, source, budget and evidence.

唯一视觉人工审批硬门

Unique Visual Human Approval Hard Gate

整条 V0→V5 链只在 V2 视觉方向冻结时要求一次结构化真人审批

visual_human_approval

。它不采集

reviewer_type

、

reviewer_id

或 reviewer 字符串，仅以

review_id/reviewed_at/evidence/evidence_sha256

、PASS 及冻结 target、V2 candidate、diff、baseline SHA 表达一次人工通过事件；任一绑定漂移后审批失效并重新回到 V2。V2 代表画面、动态样片和结构化机器检查仍必须齐全。V4 actual asset/component×state/同屏组合以及 V5 full viewport、overlay、diff、逐区域 fidelity、F2 视觉一致性与生产合同检查全部使用绑定当前身份的确定性机器证据，不得再次要求或伪造真人审批。根节点 PASS、布尔值、AI reviewer 字段或后续重复

human_review

均不能代替这条唯一 V2 审批。

Only one structured human approval

visual_human_approval

is required when freezing the visual direction at V2 throughout the V0→V5 chain. It does not collect

reviewer_type

reviewer_id

or reviewer strings, and only expresses a human approval event with

review_id/reviewed_at/evidence/evidence_sha256

, PASS and frozen target, V2 candidate, diff, baseline SHA; if any binding drifts, the approval becomes invalid and returns to V2. V2 must still have complete screens, dynamic samples and structured machine checks. V4 actual asset/component×state/same-screen composition and V5 full viewport, overlay, diff, region-by-region fidelity, F2 visual consistency and production contract checks all use deterministic machine evidence bound to the current identity, and no further human approval can be required or forged. Root node PASS, boolean values, AI reviewer fields or subsequent repeated

human_review

cannot replace this unique V2 approval.