phaser4-game-asset-integration

Phaser 4 game art production and integration

Global control access

Control-plane boundary: may propose, may review, may modify within the Work Item scope of the current user task, and must return to $phaser4-game-workflow-control risk gate.

This domain may propose, review, and produce or integrate assets within the current user task, Implementation Package, A level, and path scope; when the in-task plan, paths, and asset list change, update the plan synchronously and re-verify affected parts. All conclusions return to phaser4-game-workflow-control auditing and state transitions. V0-V5 are stageId, and must not bypass global state, side-effecting A4-A6 precise operation approval, diff auditing, and evidence gates.

Workflow

Before generating global candidates, scene effect images, or host context images, must followin-game copySeparate internal specifications from player-visible expression, and send the visible text scope and the constraint prohibiting drawing internal explanations to the generator. Decomposition and formal interfaces only use the current visible expression; frozen atomic assets still faithfully reproduce the target, and no text is added from the GDD or frozen text deleted on one's own initiative.

When art direction, effect images, formal assets, or dynamic visuals are involved, first readgame art experience and quality contract. Production input must carry the applicable theme, audience, experience goals, visual hierarchy, and normal/operational/peak budgets; the three global candidates are manually evaluated item by item, and if any quality item of the selected candidate fails or is unverified, it must not be frozen. Formal assets follow the existing V3/V4/V5 acceptance, continuous gameplay segments are checked by the user, and no per-asset confirmation chain is added.

Scene reproduction contract (mandatory for effect-image)

V2 decomposition first complies withfunctional semantic grouping constraints: confirm the positional dependencies, information grouping, and rationale of regions, functional components, parts, and independent elements; positional dependents are classified as child elements of the layout container corresponding to the depended-upon element, and elements that jointly express the same information and have no positional dependency on each other are listed as same-group siblings. Layouts must not be regrouped by text type or geometric containment; unclear attribution remains in decomposition confirmation, and no releasable layout is automatically generated.

effect-image represents the reproduction of the visual facts and structural relationships of a formal Scene, not independent PNG production. A scene Work Item only records its own persistent HUD; modals/popups and similar dialogs followindependent work item rulesto establish a DISPLAY_LAYER Work Item, and freeze the host same-screen image in the required state. Incomplete popups do not block scene V5; the popup itself must still complete V2/V3 and the V5 trajectory of open→interact→close/restore. In runtime state, use by default visual_validation.mode=usability, and only enable strict pixel/full-matrix verification when there is an explicit precise requirement.

Whether an effect image/reference image applies depends only on whether the current scene Work Item designates it as the visual target of the formal runtime frame, and has nothing to do with whether assets are generated, produced, or added. When applicable, reference reproduction is a visual mode and contract overlay within the same scene implementation lifecycle, and must enter effect-image the V1→V5 reproduction chain, including scene_reconstruction_contract, layout binding, coverage, host scene same-screen composition, and fidelity acceptance; even if all regions use reuse-existing/runtime-program Implementation, zero new resources, and zero generative bitmaps are no exception. Do not create a second scene Work Item or a second V1→V5. Merely generating new resources, or using images only as inspiration, illustration, or temporary reference, is not sufficient to trigger effect-image, and they are still classified under the normal asset, component, or scene path.image_generation_required、generate-now, the number of resources, and production_method can only be used by V2 to decide the production route after triggering has already occurred, and cannot participate in the V0 applicability determination.

The complete prompt template for effect-image generative bitmaps, asset_prompt fact inheritance rules, transparency production requirements, and generation_record structured fields are uniformly specified inthe "Effect-image Generative Bitmap Faithful Reproduction Prompt Contract". Production classification uniformly uses production_method=image-generation, and the specific generator/generator_version is selected and faithfully recorded by the system based on the prompt, reference input, subject material, transparency requirements, and verified capabilities; when the tool version is not exposed, record not-provided, and do not fabricate it. The transparency route selects controlled solid-color keying, verified true Alpha, or an independent mask/manual creation based on frozen edge facts; prompt or tool parameter declarations cannot replace PNG pixel decoding verification. Existing true transparent images are integrated under the asset reuse contract; this Skill only retains routing and hard invariants, and does not copy templates here.

V3 aggregates the currently confirmed production scope's mutually independent static component × required state images to be generated into a single batch task, submitting them in one orchestration; creating tasks one image at a time or waiting for the previous image to pass acceptance before generating the next is prohibited; each item still outputs an independent bitmap, seebatch image generationfor details. After the batch is complete, directly provide an image gallery or contact sheet, where each item can be enlarged and viewed individually; text only reports failures, missing items, and differences that still need to be handled, and does not first send a text plan and wait for confirmation. Image frame animations that depend on a parent image advance according to theframe animation contractafter item-by-item confirmation, and the static image batching rules cannot be used to skip confirmation; independent intervals that already satisfy the parent image and confirmation prerequisites can be parallelized according to that contract. V4 uses formal resources to generate draft compositions and obtains user confirmation; V5 by default verifies a representative complete frame, key content usability, actual interaction, and formal Scene consumption evidence, and only exact mode requires complete region-by-region precise measurement and difference materials. Resource loaded/used, missing=0, and resize stability only belong to engineering sub-gates and cannot independently drive COMPLETE.

Read the project configuration, GDD, visual-design, TDD, control plane, and asset registry; execute the V0-V5 visual production pipeline。
V0 first determines whether the task belongs to an atomic asset, a component/asset set, or a scene/full UI/visual system/rework; whether reference reproduction applies is determined solely by the formal runtime visual target declaration of the current scene Work Item, not by new resource or image generation needs. An atomic asset can skip V1/V2 only when the structure, layout, interaction, and viewport behavior remain unchanged and an applicable visual contract, visual deliverable conclusion, and budget baseline already exist; minor in-task adaptation can update the plan and re-verify without needing re-authorization.
After the foundation-only basic implementation is complete, V1 establishes functional specifications, gameplay visual contracts, necessary low-fidelity/graybox, and budget, defining only contracts and not writing formal scene feature code; when the Work Item specifies an effect image as the reproduction target, V1 simultaneously followsvisual reproductionto generate or receive and freeze the scene master/reference target, host-context effect image, reference identity, comparison conditions, observable visual facts, and an initial reproduction draft. When requirements or the baseline are already clear, V1 records AUTO and directly provide a preview of the scene goal/host context; ask only when there is substantive ambiguity in product direction, gameplay semantics, or structure. V2 maintains the serial hard gates of "exploded-view diagram confirmation → layout diagram confirmation": Stage A internally completes state analysis, components/placements, production route, technical JSON, and decomposition_elements, directly displays the exploded-view PNGs numbered in confirmation order, and only asks the user to confirm by looking at the images; technical records are for the agent and machine gates and do not separately require reading or confirmation. Stage B automatically generates element-by-element alignment decisions, layout PNGs, and review.htmlafter the exploded-view diagram is confirmed, and directly asks the user to inspect the final layout diagram/preview and confirm; there is no need to submit a textual layout plan first. If the user finds genuine ambiguity in the images, clarify then. The layout only overlays parent-child boxes and descriptions on the frozen original image; it does not regenerate or replace the visual reference image, nor does it provide multiple layout options.
schema 1.5 visual-assets.json First declare effect_image_reconstruction: ordinary assets are not-applicable, and reconstruction artifacts are not required; effect-image reconstruction is effect-image. For the latter, after freezing the target and before entering V3, use v2-ready to complete contract cross-check and coverage; V2/V3 may temporarily have no fidelity case; only when V5 verification is complete is it v5-complete and requires all cases to pass. For effect-image coverage, register per region annotation_number and implementation_plan; first complete ownership/implementation classification, then perform the state_analysiswith actual evidence files, frozen target files, analysis ID, and completion time, strictly completed before the component inventory, and finally fill in by unique atomic part component_inventory, placements, and expected_assets; the number is not a unit of asset quantity. Visual source and assembly method must be kept separate:visual_route_analysis can only select on an independent coverage region image-asset or phaser-native，assembly_analysis and then independently declare atomic Scene assembly, prohibit full-screen capture, and allow independent image assets; one must not infer from "no full-screen texture" that runtime-program. If the same visual fact simultaneously contains program logic and independent visual assets, one must return to V1/PROPOSAL to redivide coverage/annotation: image appearance enters an independent image-asset region, program behavior enters an independent phaser-native/runtime region, and each enters its respective production and runtime logic contract. It is prohibited to use a single composite region or composite_parts to produce and accept within one region as a closed loop. When all regions are phaser-native , one must provide the all_native_justificationbound to the target file, the complete region set, and an independent JSON artifact; the file gate will read the actual files and verify eligibility facts region by region. State analysis must cover normal, selected/active, disabled, pressed/hover, victory/defeat/paused; write requiredfor actually applicable, and write not-applicable+reasonfor not applicable. ② The 6 buttons at the top must be 6 components; the 3 identical bottom surfaces in ⑧ may be registered as 1 component + 3 placements; the action icons in ⑨ are registered according to the actual reuse relationship; ③, ④, and ⑦ remain a single image only when they are clearly a single part and the remaining states are not applicable. By default, individual mode prohibits horizontal group images;image_generation_required=true generative bitmaps use individual + atlas_allowed=false, whose expected_assets.width/height is automatically calculated by the validator according to logical pixels ceil(max placement width/height × intended_scale_range.max) , and must be exactly the minimum size;scene_asset_usage.max_dpr must be strictly the number 1，padding_policy must be none, and the size contract itself does not require human_review. The 1 here means the image is produced 1:1 at the maximum agreed logical display size; the actual runtime DPR is dynamically read according to the device and capped at 2. Historical 1.5x/2x production evidence must be regenerated or marked stale. Other production methods may use the full atlas_slice atlas only under an explicit contract. Every placement must declare interaction_required, and the actual interaction_hotspots can only be bound one-to-one per placement and is not counted as a visual asset. The confirmation image still simultaneously presents generate-now、reuse-existing and runtime-program, but the PNG draws only the user summary and the labels "Create New Image Asset / Reuse Existing Image / Programmatic Drawing or Dynamic Logic"; the placement ID, coordinate dimensions, and component/state/asset technical fields do not enter the visible rows. When running --proposal , these technical fields are written in full into the decomposition analysis technical JSON and bound to the PNG metadata, the actual region definition, and the existing confirmation business fields. The system decides whether to use image generation based on the prompt, reference input, material, transparency requirements, and available capabilities;independent-production and generate-now do not undergo any generator inference. V2 then follows the asset production route to select the route. The route is judged by observable visual facts and Phaser's actual rendering capabilities, not by semantics such as "button" or "panel", nor is static/dynamic the sole criterion. Text, solid-color rectangles, basic geometry, regular borders, simple regular gradients that can be deterministically expressed, masks, and progress fills may use phaser-nativewhen Phaser's native capabilities can precisely express the frozen appearance; distinctive illustrations, complex ornamentation, irregular contours, complex materials, and decorations with obvious artistic characteristics use the independent image route. The native route freezes native_suitability.render_contract 's renderer, dimensions, color, line width, corner radius, gradient, transparency, applicable states, and unsupported features; visual features that cannot be supported must block, and must not pass after being approximated as a substitute. Images, image parts, and text use the samefull programmatic reproduction eligibility: only parts that the program can fully implement are marked as program elements, and fixed appearances that cannot be fully implemented are split into independent bitmaps; when the subject and effect cannot be reliably separated, the complete atomic visual part is retained. Dynamic/localized text follows thetext route determinationto retain variable capability, and is not approximated by ordinary text or simplified graphics. Appearance source and behavior assembly are recorded and bound separately; for example, a button may consist of a native frame, an independent icon image, and Phaser.Text text, and is connected to interaction through explicit component/node references, not merged into the composite region.image_generation_required=true Once frozen, it must not be automatically switched to the native route, and may only be changed by following an explicitly accepted Change Request.
V2 can run node scripts/validate_visual_manifest.mjs docs/visual-assets.json --stage V2; V3 formal acceptance runs node scripts/validate_visual_manifest.mjs docs/visual-assets.json --stage V3 --check-files --project-root ., and V5 formal acceptance runs the same command but uses --stage V5. Independent popup work items must additionally pass --work-item-type DISPLAY_LAYER, and scene work items are validated by default according to SCENE ; this parameter only changes the display-layer scope and does not bring the popup into host scene acceptance. V3 verifies item by item the real resource files, source/license information (if applicable), budget, frozen baseline, coverage, and production_contract_audit; V4 independently completes page sketch saving and manual confirmation; V5 then verifies formal Scene consumption, combined pre-acceptance, the two types of F2 machine evidence, F3 runtime replay, and applicable fidelity cases.
The current scene Work Item advances through the V1→V5 stages defined by the control plane; this domain is responsible for, at V2, completing two independent manual confirmations—the decomposition PNG and the layout PNG—in sequence and then producing the formal resources, completing resource-level acceptance at V3, generating the sketch, previewing adjustments, and manually confirming according topage restoration sketchat V4, and providing runtime visual evidence at V5. Formal code only consumes the current scene or compliant shared and V3 accepted resources; public formal resources are only allowed if they are stably reused across at least two scenarios or are required for operation. Before joint scenario acceptance, gray boxes, placeholders, and fallbacks must be cleared.

The transparency route is determined by expected_assets.transparency_requirements frozen policy and edge_profile. Only when hard-edge and the subject is clearly distinguishable from a solid-color background may background-removalbe used; threshold-based background removal is prohibited for complex edges.direct-alpha must match the verified tool, version, and edge type, and PNG decoding must prove real transparent pixels; generation record top-level generator/generator_version is the actual identity,capability.tool/tool_version must be the same as it.mask-composition must bind the actual inputs and tool parameters of an independent mask or manual creation. When capability is insufficient, report the gap; do not increase tolerance, hard-cut outlines, delete light effects, or falsify results. Generation records shall register the generator identity, parameters, input/output SHA, and post-processing according to the actual route; normalization shall preserve aspect ratio, Alpha, and subject boundaries, and baking checkerboard previews into assets is prohibited. For each candidate, generate previews on light and dark backgrounds; V5 completes visual inspection of subject defects, residual background, color fringing, and semi-transparent areas. Existing real transparent images shall be integrated according to the resource reuse contract; do not falsify generation or background-removal records.image_generation_required=true frozen contracts cannot be automatically replaced by the transparency route decision or prompt generator. 7. Gray boxes or visual samples before V2 must be isolated from the formal runtime chain, and must not register formal entry points or implement formal business logic; after V2 confirmation, produce V3 formal resources; after V4 sketch confirmation, V5 formal functionality lands along the production Scene entry/skeleton, and one-off screenshot Scenes, full-screen image tiling, hidden overlays, and absolute layering to match pixels are prohibited. After formal functionality is implemented, V5 collaborates with gameplay to complete structured integration, dynamic acceptance, and low-fidelity cleanup; only when upstream facts or the identity of the currently affected candidate changes shall the corresponding fidelity case be invalidated and re-collected, while evidence for other units remains valid.

Formal effect image annotation commands must include --proposal <file>.json; omitting this parameter fails directly, and no successful artifact containing only the user's diagram shall be generated.

Effect image production must first reference the frozen global visual baseline; global candidate selection, freeze status, and cross-Work Item reference rules are governed bycontrol modelandglobal visual control. This domain only supplements generation records, anchor inheritance, and resource contract requirements; scenarios are still completed within the same Work Item in V1→V5 order.

The standard deliverable for layout generation must include, in addition to PNG, the same candidate directory's layout-nodes.json、layout-decision.json, self-contained review.html and generation-result.json. The layout review page is only for readable manual work and cannot replace disassembly confirmation, independent layout confirmation, or the PNG/F2 machine gate; its templates, real file and business bindings, candidate status, and offline boundaries are described in 离线布局审阅产物。

When disassembling UI base plates, button skins, and frames in V2, the nine-slice must be evaluated based on observable fixed corners/edges and stretchable areas, recording the reasons for applicability/non-applicability as well as the source image size and four-side slice values; when nine-slice is adopted, the selection is frozen together with the existing disassembly confirmation and runs through V3 small-image production and V4/V5 shared rendering. For the specific contract, readNine-slice UI, and do not wait until V4 to manually try slicing.

Conditional reference

Reference screenshots, screen recordings, running projects, or source restoration: read visual restoration。
Decorative full-screen screen-space background: read full-screen background; for world-space levels, Tilemaps, or gameplay environment changes, read the asset production route instead.
UI: also read phaser4-game-ui-layout 's layout contract, Phaser adapter, and evidence matrix; resource origin, layout anchors, and animation offsets are separated per the contract, and asset integration must not reinvent layout rules.
QA measurement, dynamic resize, full viewport screenshots, and read-only Hook: read responsive visual verification, and its fields or thresholds must not be copied in asset documentation; viewing comfort and continued-play acceptance use the shared art contract.

Review and delivery

All candidates first pass F0-F3; F4 only handles A4-A6 operations with external writes, payment, real devices, destructive or external deletions, and release side effects. Side-effect-free local A4 integration does not wait for additional approval because of its level label. V1/V2 deterministic machine checks must be executed; when requirements are clear, automatically adopt AUTO and directly produce a preview, and only record once for genuine direction/gameplay/structural trade-offs USER_DECISION. At V2, the user only needs to separately confirm the exploded PNG and the layout PNG; static asset batches and in-scope rework are reviewed via gallery/before-and-after comparison images. Technical JSON, state analysis, coverage, contracts, and evidence are continuously maintained by the agent, without initiating additional text confirmation. Each delivery package records the current task scope, candidate identity, baseline, source/license (if applicable), budget, and evidence; ordinary tasks do not require independent authorization records.

Visual confirmation boundary

For the V0→V5 chain of the same scene Work Item, at V2 the exploded diagram confirmation and the layout diagram confirmation are completed in sequence, freezing the restoration plan. The user faces the numbered exploded PNG and layout PNG/review.html; technical JSON, proposals, and decision files are used in the background for machine validation and identity binding, and do not constitute additional text confirmation gates.visual-decomposition-confirmation/1.0 binds annotation/proposal/decision SHA, target, V2 candidate, diff, baseline, all numbering, and the user's original text; when a confirmed target or plan undergoes substantive change, the affected parts are reconfirmed, and ordinary runtime layout fine-tuning does not reopen V2. V2 exploded diagrams, technical JSON, contract reconciliation, coverage, and structured machine checks must be complete, and layout confirmation separately binds the final layout diagram and decision file. V3 asset acceptance, V4 sketch confirmation, V5 representative complete screens and key usability evidence bind the current identity; overlay, diff, and complete region-by-region precise fidelity are mandatory only in exact mode. Root node PASS, booleans, AI reviewer fields, or old human_review cannot replace the two V2 image confirmations.

F2 machine evidence checks files, structure, bindings, and actual parameters, and cannot alone give an art pass conclusion. The agent may provide screenshots, screen recordings, and inspection points; when automatic visual verification is not explicitly authorized, it does not automatically analyze the visuals. The user's actual evaluation of theme, completion, and comfort is incorporated into existing image selection, sketch, and runtime acceptance materials, and cannot be filled in on their behalf or overridden by old confirmations for changed visuals.