SuperAPI AI Directory

threejs-game-ui-layout

General & other

View repository

Updated 10-16 09:30

About this skill

three.js game UI layout

Formal Object3D, UI, and independent display layers uniformly followDisplay object anchors and display layer layering: three.js has no general 2D origin property;Sprite.center can explicitly use center (0.5, 0.5), model pivots are expressed by geometry local coordinates or parent Group , exceptions are recorded per object with reason and conversion. The scene must declare the actual layer order, input, and lifecycle ownership of background, world, effects, HUD, and transient layers, and verify runtime occlusion in the V4 formal Scene.

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

Effect image V2 decomposition and layout complianceFunctional semantic grouping constraintsandThreeJS UI node organization: first confirm position dependencies and information grouping on the numbered decomposition diagram, then the agent automatically organizes the docking plan and displays the layout diagram/preview for confirmation; do not first send a text plan for confirmation. Position-dependent parties must become child elements of the layout container corresponding to the depended-upon element; elements that jointly express the same information and have no position 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 geometric minimum containment relationship is prohibited.

Global control integration

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

This domain may propose, review, and modify layout within the scope of the current user task, Implementation Package, A level, and path; all actions and evidence return to threejs-game-workflow-control audit and state transitions. The layout contract and V phase cannot bypass approval of 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 contract

All visible Scene, HUD, popups, and DISPLAY_LAYER must fill in the layout contract with logicalViewportSpace、designResolutionPolicy、canvasBackingPolicy、runtimeDprPolicy、maxRuntimeDpr、scaleMode、cameraViewportPolicy、cameraZoomPolicy、cameraOriginPolicy、inputCoordinatePolicy、safeAreaPolicy、resizePolicy、orientationPolicy、textResolutionPolicy、assetResolutionPolicy、performanceBudget、representativeViewports and requiredRuntimeEvidence. These fields describe the project's viewport and coordinate strategy, not a built-in three.js layout API; Three.js projects use WebGLRenderer.setSize(), CSS viewport, and camera projection to implement the actual mapping.orientationPolicy.allowed declares the orientations supported by the project;designResolutionPolicy only needs to provide branches for these orientations,targets.orientations 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. The Canvas fills the CSS viewport, decorative backgrounds are proportionally cover-scaled, and black bars are prohibited. The Canvas backing is the CSS size multiplied by the effective DPR, rounded down; 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, with listeners cleaned up. For asset production, the fixed DPR baseline is 1 (logical size 1:1) and must be separated from runtime DPR.scaleMode is a project-custom viewport strategy field, using custom to indicate that the viewport is calculated by project code and updates WebGLRenderer and the camera projection;gameSizeSpace refers only to the logical layout space in the contract and does not represent what three.js provides for GameSize。cameraOriginPolicy records the coordinate system origin convention and does not correspond to the origin property on the camera. The implementation package must prove the real relationships among the logical viewport, Camera projection, input mapping, and CSS/physical sizes; declaring fields or a successful build cannot alone serve as evidence for high-DPI screens. Popups inherit the host's logical viewport, DPR, safe area, Camera, and input contract by default, and V4 must independently record their runtime traces.

Default principles of visual language

Player-visible content is expressed within-game textprioritizing images, icons, numbers, symbols, and visual states; if a gold coin icon +100 already expresses the reward, do not also write "Gained 100 gold coins." When text is necessary, keep only essential short names, short actions, or short states. When an icon is ambiguous, when first-time necessary guidance is needed, or when the consequence 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 repeated explanations, value attribution, generic icon stacking, and self-explanatory functionality.

Programmatic 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 others to wrap, but none may be truncated; when space is insufficient, streamline 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, line breaks, and minor alignment pass as long as they remain clear, readable, operable, and do not go out of bounds, get clipped, or cause key occlusion; effect-image also does not automatically enable exact. Only when the user explicitly requires pixel-perfect restoration or the project contract explicitly specifies it should exactbe chosen, enabling strict tolerance, item-by-item delta, and the full viewport/full state matrix. V2 must still preserve decomposition order, parent-child attribution, anchor semantics, and internal geometric consistency.

When the user explicitly requires consistency with a reference layout, declare the applicable viewport and geometric tolerance 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 the full matrix. Differences between the actually visible subject, glyphs, and layout rectangles are inspected by the user according to the calibration reference.

For nine-slice UI, the source image production size, slice edge widths, and target display frame are declared separately; when readingdetermine the nine-slice during decomposition. V2 nodes and V3 expected assets use the same contract, and V4 assembles directly according to this contract; by default, text is not allowed to have actual content exceed the target box, and when overflow is explicitly allowed, adjacent items and whitespace still need manual inspection.

Core Workflow

Layout calibration and key geometry acceptance reading for formal scenariosLayout 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 ThreeJS Scene; layout rectangles and asset visible boundaries are checked separately, and usability passing cannot replace reference restoration.

  1. Read the project's GDD/TDD, current candidate, master control review funnel, and applicable visual stage; determine stable UI IDs, coordinate spaces, reference objects, states, and platform inputs.
  2. Copy schema 1.2.0 Contract Template. Ordinary layouts use not-applicable and keep layout_nodes: []; frozen visual targets first use frozen-target/specified. At the same time, freeze the above root-level viewport/DPR/Camera/Input/performance fields, and do not use old targets.scale fields to bypass the new gate. V2 first establishes parent-child relationships based on positional dependencies and sibling groupings based on shared information, and the agent internally maintains the complete technical JSON and decomposition_elements, directly displaying the numbered decomposition diagram for manual confirmation; the screen UI's ui_layout responsibility fields are also retained in the technical contract. After the decomposition diagram is confirmed, intelligent visual judgment generates per-element left/center/right × top/center/bottom decisions, and then the same entry point synchronously generates the layout PNG,layout-nodes.json、layout-decision.json, offline review.html and generation-result.json, and the user directly checks the final layout diagram/review page and independently confirms. 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 calibrationConsume V2 nodes and layout contract, and V3 accepted assets in the formal Scene, 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 ThreeJS viewport, Camera, input, and idempotent reflow rules, seeThreeJS Adaptation Reference。
  4. In the specified stage, run 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 viewport, key state, and narrow/wide size evidence; when only a single orientation is supported, the other orientation is not verified, but sizes, DPR, and continuous resize on the same page in the same orientation are still covered. Key UI/HUD records stable element/reference ID, dual-axis relationships, target/runtime measurements, actual test ID/status, visual evidence, and project-defined tolerances. V4 must also record CSS/backing sizes, raw/effective DPR, Camera, input hit, same-page resize, and independent DISPLAY_LAYER traces.exact or explicit full-coverage requirements are required to extend to the complete matrix and strict delta, and the orientation axes only cover 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 truly change should it fall back to the earliest affected V1/V2. Ordinary position/size adjustments update the formal layout configuration and re-verify the affected area, and F3 only accepts engineering evidence bound to the current candidate.

The formal scene is implemented according to the project's existing ThreeJS Scene structure and layout contract. V2 anchors, parent-child bounds, asset origin, and ThreeJS parent local coordinates are handled separately, and ancestor offsets are accumulated only once. V4 directly loads accepted assets and composes them in the real ThreeJS Scene; background coverage is calculated according to the actual visible viewport, and images are presented according to the frozen fit/cropping rules, and must not be inset into the safe area, leave margins, or be translated to expose gaps. Image fit and ThreeJS text fields are executed according to the adaptation reference; if assets/fonts are not ready, or layout or rendering is abnormal, the runtime acceptance must fail. Scene creation, wake-up, and resize use the same idempotent layout entry point; the published image contains no editing auxiliary content. Runtime evidence comes from the actual consumption and image 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, it may use assets/fixed-design-viewport.mjs. 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 by 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: recording the frozen target file, scene/state, visual baseline, reconstruction contract version,layout_decomposition_version , and target viewport.layout_nodes Each node in must simultaneously bind a regions/scope.ui_ids region and a declared coordinate space, recording the reference, dual-axis anchors, target bounds, size strategy, hierarchy, cropping, responsive rules, and planned test ID; the same coverage region may carry multiple layout nodes, but nodes must use a unique layout_node_id, and a multi-node region must not use the region ID as an ambiguous reference; key alignment is achieved through layout_node_id to reuse these geometric facts. 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 precise requirements require strict restoration of the target viewport.

The layout decision order for V2 is fixed as: "the agent internally generates decomposition facts and technical JSON → display the numbered decomposition diagram and confirm manually → the agent automatically generates dual-axis alignment decisions and independent layout diagrams/review pages → display the layout diagram and confirm independently → freeze V2". Users may directly point out by diagram number that the decomposition or layout needs adjustment, and the agent updates the technical facts and reissues the corresponding images; it does not separately wait for textual proposal 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, the visual decision file, and the identity of the final layout diagram.

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 cannot be automatically inferred from the four-edge distances.relative_position is still measured from parent-child bounds, 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 specific node or viewport/safe-area, and must not cycle. The visual decision file and its ID will enter the layout diagram and confirmation records, and missing decisions 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 in their own V4 same-screen verification verify 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 syntax is needed, read references/layout-contract.md。
  • When Three.js Camera, Group, DOM Overlay, resize, or reflow boundaries are needed, read references/threejs-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 freezing Golden conditions are needed, read references/evidence-matrix.md。
  • When layout review pages, same-batch artifacts, coordinate mapping, digest tracking, or offline security boundaries are needed, read references/layout-review-artifacts.md。
  • When batch calibration in formal scenes, checking alignment/spacing, or determining the source of restoration deviation is 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 scene configuration; QA only reads and verifies reachability, truncation, occlusion, touch, scrolling, and evidence. Layout computation and Object3D/DOM HUD tests verify relationship invariants and do not treat isolated absolute coordinates as a universal acceptance criterion. Juice-feel tasks may refer as needed to theDynamic 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.