phaser4-game-ui-layout

Phaser 4 game UI layout

Formal display objects, UI, and independent display layers all comply uniformlyDisplay object anchors and display layer stratification: objects that can set an origin use the center explicitly by default (0.5, 0.5); exceptions are recorded per object with reason and conversion. Scenes must declare the actual layer order, input, and lifecycle ownership of background, world, effects, HUD, and transient layers, and verify runtime occlusion in V4 formal Scenes.

UI layout reference is determined uniformly byScene and popup size referencedetermined uniformly: for full-screen UI, the parent is the scene, laid out relative to the scene logical size; when a popup has a backing panel, content is laid out relative to the width and height of the functional container corresponding to the backing panel; when a popup has no backing panel, it is laid out relative to the host scene logical size. The popup backing panel container itself is positioned relative to the scene, and the backing panel bitmap belongs to that container together with the content; the full-screen decorative background is still an independent display layer. Safe area constrains the visible range of key content and does not replace these three size references.

Effect image V2 decomposition and layout complianceFunctional semantic grouping constraintsandPhaser UI node organization: first confirm positional dependencies and information grouping on the numbered decomposition diagram, then let the agent automatically organize the docking plan and show a layout diagram/preview for confirmation; do not first send a text plan and ask for confirmation. A positionally dependent party must become a child element of the layout container corresponding to the depended-on element; elements that jointly express the same information and have no positional dependency on each other are listed as same-group sibling items. Parent container responsibilities, layout ownership, size, overflow, safe area, and input ownership are still maintained in the technical contract; automatically assigning parentage by text type or minimal geometric containment is prohibited.

Global control integration

Control plane boundary: may propose, review, and modify within the Work Item scope of the current user task, and must return to $phaser4-game-workflow-control audit and state transition; only A4-A6 operations involving external writes, payment, real devices, destructive effects, or release side effects request approval, while ordinary recoverable local file cleanup proceeds along the task.

This domain may propose, review, and modify layout within the current user task, Implementation Package, A level, and path scope; all actions and evidence return to phaser4-game-workflow-control audit and state transition. The layout contract and V phase cannot bypass approval for A4-A6 operations with side effects or global state.

Convert UI layout from page coordinate patching into a traceable layout contract, and connect the contract, implementation, and runtime evidence to the global control plane. Responsible only for layout relationships, coordinate spaces, size strategies, responsive reflow, and layout evidence; does not own global state, approvals, gameplay rules, asset production, visual direction, or release clearance.

Global viewport and high-DPI screen contract

All visible Scenes, HUD, popups, and DISPLAY_LAYER must fill in the layout contract logicalViewportSpace、designResolutionPolicy、canvasBackingPolicy、runtimeDprPolicy、maxRuntimeDpr、scaleMode、cameraViewportPolicy、cameraZoomPolicy、cameraOriginPolicy、inputCoordinatePolicy、safeAreaPolicy、resizePolicy、orientationPolicy、textResolutionPolicy、assetResolutionPolicy、performanceBudget、representativeViewports and requiredRuntimeEvidence。orientationPolicy.allowed declares the orientations supported by the project;designResolutionPolicy only needs to provide branches for these orientations,targets.orientations is consistent with it. Portrait uses 1080×1920 as the design baseline and adapts by width; landscape uses 1920×1080 as the design baseline and adapts by height; the other axis expands or crops with the viewport. Canvas fills the CSS viewport, decorative backgrounds use proportional cover, and black bars are prohibited. Canvas backing is obtained by multiplying the CSS size by the effective DPR (rounded up), and physical pixels must not be used directly for layout or hit testing.

At runtime, DPR is read dynamically from the device; invalid input falls back to 1, positive finite values are capped at 2, and it must cover resize, display density changes, and orientation switching for bidirectional projects, and listeners must be cleaned up. The fixed baseline for asset production DPR is 1 (logical size 1:1), and it must be separated from runtime DPR. ScaleMode uses RESIZE or an equivalent fill-screen custom, and the implementation package must prove gameSize, Camera viewport/zoom/origin, and CSS/physical mapping; declaring the mode or a successful build cannot alone serve as evidence for high-DPI screens. Popups inherit the host logical viewport, DPR, safe area, Camera, and input contract by default, and V4 must independently record their runtime trajectory.

Default principles for visual language

Player-visible content is expressed byin-game copypreferring images, icons, numbers, symbols, and visual states; if a coin icon +100 already expresses the reward, do not write "Get 100 coins" again. When text is necessary, keep only essential short names, short actions, or short states. When icons are ambiguous, when first-time necessary guidance is needed, or when the consequences of an action cannot be understood directly, add minimal explanation; precise values themselves do not require explanatory sentences. Accessibility names are retained but need not become visible labels. F2 checks for duplicate explanations, value attribution, generic icon stacking, and functional self-explanatoriness.

Procedural text must be delivered simultaneously in English, Simplified Chinese, Japanese, Russian, and Spanish, and glyph width, font fallback, baseline, and container fit must be verified per language. Each language independently declares single-line or wrap, allowing some languages to be single-line and some to wrap, but none may be truncated; when space is insufficient, streamline the necessary copy according to that language's strategy, adjust letter spacing/font size, expand the container, or wrap reasonably, and do not reduce to an unreadable font size. Multipliers use x{value}, and value changes use the corresponding icon and +10 and similar expressions; localization should not re-expand icons and values into explanatory sentences.

Layout acceptance uses by default visual_validation.mode=usability: differences in position, size, margins, wrapping, and a small amount of alignment pass as long as they remain clear, readable, operable, and do not go out of bounds, clip, or cause key occlusion; effect-image also does not automatically enable exact. Only when the user explicitly requests pixel-level restoration or the project contract explicitly specifies it should exactbe chosen, enabling strict tolerances, item-by-item deltas, and a full viewport/full state matrix. V2 must still preserve decomposition order, parent-child attribution, anchor semantics, and internal geometric consistency.

When the user explicitly requests consistency with a reference layout, declare the applicable viewport and geometric tolerances among the existing key items; declared key rectangle constraints must be satisfied even in usability mode. This only tightens the declared item requirements and does not automatically enable full-screen pixel diffs or a full matrix. Differences in the actually visible subject, glyphs, and layout rectangles are checked by the user against the calibrated reference.

For nine-slice UI, the source image production size, slice edge widths, and target display frame are declared separately; when readingduring decomposition, determine the nine-slice. V2 nodes and V3 expected assets use the same contract, and V4 assembles directly according to this contract; by default, actual text content is prohibited from exceeding the target frame, and when overflow is explicitly allowed, adjacent items and whitespace still require manual checking.

Core flow

Layout calibration and key geometric acceptance for formal scenes readlayout calibration and reference restoration. V4 directly consumes the frozen V2 layout and V3 formal assets, adjusts and re-verifies the affected scope in the actual Phaser Scene; layout rectangles and visible asset boundaries are checked separately, and usability passing cannot replace reference restoration.

1. Read the project's GDD/TDD, current candidates, master-control review funnel, and applicable visual stage; determine stable UI IDs, coordinate spaces, references, states, and platform inputs.
2. Copy schema 1.2.0 contract template. For normal layouts use not-applicable not-applicable and keep layout_nodes: []layout_nodes: []; for frozen visual targets first use frozen-target/specifiedfrozen-target/specified. At the same time, freeze the above root-level viewport/DPR/Camera/Input/performance fields; using the old targets.scale targets.scale field to bypass the new gate is prohibited. V2 first establishes parent-child relationships based on positional dependencies and sibling groups based on shared information; the agent internally maintains the complete technical JSON and decomposition_elementsdecomposition_elements, and directly displays a numbered decomposition diagram for manual confirmation; the screen UI's ui_layout ui_layout responsibility field is also retained in the technical contract. After the decomposition diagram is confirmed, intelligent visual judgment generates per-element left/center/right × top/center/bottom left/center/right × top/center/bottom decisions, and then the same entry point synchronously generates the layout PNG,layout-nodes.json、layout-decision.jsonlayout-nodes.json, offline review.html layout-decision.json, and generation-result.jsonr; the user directly inspects the final layout diagram/review page and confirms independently. There is no need to confirm the text proposal or technical record first. Then register the non-empty layout_nodes derived jointly from the confirmed elements and visual decisions, along with the key alignment contract.
3. After V3 formal asset acceptance, proceed directly to V4: according toformal scene visual restoration and calibrationin the formal Scene, consume the V2 nodes and layout contract and the V3 accepted assets, and connect actual interactions, dynamic data, and required state. Coordinate, size, and responsive adjustments are written into the formal layout configuration; the frozen V2 node structure is still managed according to the upstream contract. For specific Phaser viewport, Camera, input, and idempotent reflow rules, seePhaser adaptation reference。
4. specified stage runs the structure check node scripts/validate_ui_layout_contract.mjs <contract>; verified formal acceptance must run node scripts/validate_ui_layout_contract.mjs <contract> --check-files --project-root ., read the frozen original image, and check the target/runtime/parity evidence files.
5. According to evidence matrix generate orientationPolicy.allowed corresponding representative viewports, key states, and narrow/wide size evidence; when only a single orientation is supported, do not verify the other orientation, but still cover same-orientation sizes, DPR, and continuous same-page resize. Key UI/HUD records stable element/reference IDs, dual-axis relationships, target/runtime measurements, actual test IDs/status, visual evidence, and project-defined tolerances. V4 must also record CSS/backing sizes, raw/effective DPR, Camera, input hit testing, same-page resize, and independent DISPLAY_LAYER traces.exact or an explicit full-coverage requirement only then expand to the complete matrix and strict delta; the orientation axis covers only project-supported orientations.
6. According to workflow gate connect V0, V1, V2, V3, V4, F0–F4, and G0–G3; only when the layout structure, parent-child ownership, or reference relationships actually change should you fall back to the earliest affected V1/V2; ordinary position/size adjustments update the formal layout configuration and re-verify the affected areas; F3 accepts only engineering evidence bound to the current candidate.

Formal scenes are implemented according to the project's existing Phaser Scene structure and layout contract. V2 anchors, parent-child bounds, asset origins, and Phaser parent local coordinates are handled separately, and ancestor offsets are accumulated only once. V4 directly loads accepted assets and composes them in a real Phaser Scene; background coverage is calculated from the actual visible viewport, and images are presented according to the frozen fit/crop rules, and must not be inset into the safe area, leave margins, or pan to expose gaps. Image fit and Phaser text fields are executed according to the adaptation reference; assets/fonts not being ready, layout or rendering anomalies must cause runtime acceptance to fail. Scene creation, wake, and resize use the same idempotent layout entry point; published frames contain no editing auxiliary content. Runtime evidence comes from the actual consumption and frames of the formal scene.

The design canvas size of the formal scene, and the expansion or cropping rules of the main axis and the other axis, are defined by the project layout contract; when the contract uses a fixed design viewport, assets/fixed-design-viewport.mjsmay be used. Device CSS pixels only determine the display size. The background must cover the complete visible scene, and its position is determined jointly by the contract and the actual viewport; the frozen target must not be changed by dragging in the editor or temporary offsets.

effect-image scene binding

When the Work Item's effect_image_reconstruction.applicability=effect-image , the layout contract must carry scene_reconstruction_binding: records the frozen target file, scene/state, visual baseline, reconstruction contract version,layout_decomposition_version and the target viewport.layout_nodes Each node in regions/scope.ui_ids region and a declared coordinate space, recording the reference, dual-axis anchors, target bounds, sizing strategy, hierarchy, cropping, responsive rules, and planned test ID; the same coverage region may carry multiple layout nodes, but a unique layout_node_idmust be used between nodes, and multi-node regions must not use the region ID as an ambiguous reference; key alignments reuse these geometric facts through layout_node_id . This binding describes the target relationships of the formal Scene and must not be replaced by an old generic layout contract, full-screen screenshot, hidden overlay, or absolute overlay; only when the actual target content, parent-child ownership, composition relationships, or responsive invariants genuinely change does V2→V3 fall back to V1/PROPOSAL. Other viewports by default verify the invariants and usability declared by the contract; only visual_validation.mode=exact or explicit exact requirements require strict restoration of the target viewport.

The layout decision order of V2 is fixed as "the agent internally generates decomposition facts and technical JSON → display the numbered decomposition diagram and manually confirm → the agent automatically generates dual-axis alignment decisions and an independent layout diagram/review page → display the layout diagram and independently confirm → freeze V2". The user can directly point out by diagram number that the decomposition or layout needs adjustment, and the agent updates the technical facts and re-issues the corresponding images; it does not separately wait for textual plan confirmation. The layout generation entry point still rejects inputs with unconfirmed decomposition, missing decisions, unbound elements, or elements not bound to the current scene/state/target; the two image confirmations are respectively bound to the upstream decomposition, visual decision file, and final layout diagram identity.

Effect-image nodes must also declare parent_layout_node_id、parent_target_bounds、relative_position and axis_alignment. After decomposition confirmation, intelligent layout combines the original image composition, visual center of gravity, and element semantics to explicitly determine for each element the horizontal left/center/right and vertical top/center/bottom; this determination must not be automatically inferred from the distances to the four edges.relative_position is still measured from parent-child bounds, and is used to review containment relationships and geometric drift;offset、self_anchor、reference_anchor is calculated according to the selected axis_alignment .reference_id must equal the parent ID, and the parent may only be a concrete node or viewport/safe-area, and must not be cyclic. The visual decision file and its ID will enter the layout diagram and confirmation record, and a missing decision must block layout generation.

Resource Navigation

Scene display_layer_planning Only records the scene master and persistent HUD. Transient popups such as modal/popup establish an independent DISPLAY_LAYER Work Item, recording in their own contract the host scene, lifecycle, input blocking, layer, mask, focus restoration, and responsive facts, and verify in their own V4 same-screen validation the underlying layout restoration after open→interact→close. Popup evidence is still bound to scene/layer/host, but does not enter host scene acceptance.

• When field, relationship expression, or invariant notation is needed, read references/layout-contract.md。
• When Phaser Scale, Camera, Container, DOM Overlay, resize, or reflow boundaries are needed, read references/phaser-adapter.md。
• When object default anchors, exceptions, or cross-layer composition order are needed, read references/display-object-layering.md。
• When UI root node, parent container responsibilities,ui_layout fields, or V1/V2/V3/V4 node organization rules are needed, read references/layout-hierarchy.md。
• When V/F/G gates, rollback, and candidate binding rules are needed, read references/workflow-gates.md。
• When combinatorial testing, equivalence class reduction, or frozen Golden conditions are needed, read references/evidence-matrix.md。
• When layout review pages, same-batch artifacts, coordinate mapping, summary tracing, or offline safety boundaries are needed, read references/layout-review-artifacts.md。
• When batch calibration, alignment/spacing checks, or determining the source of restoration deviation in a formal scene are needed, read references/layout-calibration.md。
• The contract validator only accepts JSON-compatible YAML (a JSON subset of valid YAML 1.2), see the contract reference; directly use Node.js JSON.parse。

Ownership and Output

The layout skill outputs contract version, layout computation inputs/outputs, invariants, and evidence index. Gameplay continues to exclusively own rules, state, and interaction; architecture maintains coordinate spaces and module boundaries; art maintains pure presentation assets and prefab data; QA read-only verifies reachability, truncation, occlusion, touch, scrolling, and evidence. Layout computation and Phaser GameObject tests verify relationship invariants, and do not treat isolated absolute coordinates as a universal acceptance standard. Juice-feel tasks may reference as neededDynamic Feedback Design Guide; the visual offset of feedback objects should use an independent presentation offset, and must not override the base position, focus, and coordinate ownership in the layout contract.