threejs-game-qa-performance

three.js testing and performance

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 the $threejs-game-workflow-control risk gate.

This domain may propose validation plans and review candidates, and may write tests or evidence within the current user task, A level, and path scope; results return to threejs-game-workflow-control audit and state transitions. Passing tests cannot override task scope, path, baseline, or A4-A6 operation approval failures.

Evidence takes precedence over subjective conclusions. When the project has not defined quantitative metrics, report only measured results and decision gaps; do not invent generic thresholds.

In-game copy is checked and repaired according tocheck and repairverification: the actual prompts recorded in effect image generation records must separate internal notes from visible content; interface text configuration and binding must use the same expression, covering localization and applicable states such as rewards/costs/errors. Before effect images are frozen and during V4 formal scene runs, provide checkpoints for repeated explanations, specification descriptions, value attribution, and necessary information, with display effects left to user judgment;copy_style, word count, or successful build cannot replace this manual result.

1. Read the Work Item, user-clarified adjustments, quality gates, TDD, qa-plan, and current candidate, and for every task pending acceptance, judge one by one according toactual completion status, recording current requirements, actual results, impact of differences, and evidence. F0 verifies task scope and process; F1 checks actual functionality, interactions, public interfaces, and hard constraints; non-mandatory implementation details that differ from early contract descriptions are only recorded as necessary notes, not treated as failures, and do not require changing the contract first. F2 forms an independent QA domain conclusion; F3 binds actual commands, environment, data sources, files, judgments, and uncovered items; when independent review is lacking, mark as unverified.
2. Before starting the service, check the same project, service type, mode, port, and health status; reuse a healthy instance when one exists, and do not terminate processes with unclear ownership.
3. Visual tasks check V0 triage and V1/V2 conditional gates. When the Work Item specifies an effect image as the restoration target, QA checks according tovisual restorationthe frozen visual target, comparison conditions, and necessary regional relationships;visual_validation.mode defaults to usability, allowing reasonable differences in position, size, margins, and line wrapping, with focus on out-of-bounds, clipping, key occlusion, unreadability, and interaction failure. effect-image does not automatically enable exact; only when the user explicitly requires exact restoration should exact be used and strict tolerances and difference evidence checked.
4. When V1 applies, check visual targets, information hierarchy, sketches/grayboxes, interactions, layout, failure recovery, and budgets. When clear frozen facts already exist, verify according to the current mode; professional fixes, engineering adaptations, and resource updates within the task may directly update the plan and re-verify affected parts. Only when changing product direction, gameplay semantics, or frozen upstream facts should one request USER_DECISION, and do not escalate ordinary detail deviations into authorization blockers.
5. Ordinary assets/layout allow restoration not-applicable. Effect images after V2 v2-ready check targets, contract reconciliation, coverage with bounds, and condition-numbered evidence; V3 must also record one by one per annotation_number/region_id the explicit production_method、delivery_kind、image_generation_required、generation_record_required、substitution_policy and expected_assets. V3 implementation package's visualProductionUnits must map one-to-one with coverage; output paths, ownership, and formats must not conflict.
6. V3 must submit production_contract_audit, checking region by region the expected method versus the actual method, delivery type, output files, generation/prompt records, and runtime consumption; F2 accepts only validationMode=MACHINE current identity machine-verified facts. V4 then requires runtime measurements, F3 runtime replay, freshness-bound fidelity cases, actual consumption, and no unapproved substitutions; only changes in upstream facts or in the currently affected candidate identity invalidate the corresponding old evidence, while path-level results of other units remain valid, and unrelated disassembly and layout confirmations are not requested repeatedly. This machine exit only verifies deterministically checkable facts; theme, material completeness, audience fit, and viewing comfort are manually confirmed by the user according to thegame art experience and quality contract. The agent provides screenshots/screen recordings, actual measurements, and inspection points, does not automatically analyze visual display effects without explicit authorization, and does not state a machine PASS as art acceptance passed.
7. Same-condition screenshots record viewport, device pixel ratio, state, trajectory, language, random seed, ROI, validation mode, dynamic time sampling/stable frames, and mask reasons. By default, usability uses representative viewports and key states to check readability, boundaries, occlusion, interaction, and relational invariants; full viewports, strict tolerances, per-region deltas, overlay/pixel diffs, and full viewport/full state matrices are enabled only in exact mode or when the project explicitly requires it. Generative, animation, and VFX must not be judged by pixel diffs alone.
8. UI reads the threejs-game-ui-layout contract, and according to responsive visual validation collects real stable frames. By default, usability covers the corresponding representative viewports according to orientationPolicy.allowed : include narrow/standard portrait when portrait is supported; include landscape/desktop widescreen when landscape is supported; for single-orientation projects test only that orientation, but still cover narrow and wide sizes, DPR 1/1.25 or 1.5/2/>2 capped, continuous resize on the same page, fallback to DPR 1, resize with unchanged DPR, and representative modal trajectories. Only exact or explicit project requirements extend this to the full breakpoint and state matrix; the orientation axis is not extended to undeclared orientations. For each viewport, directly record the CSS rectangle, Canvas backing, raw/effective DPR, logical↔CSS↔physical ratios, Camera, input hits, safe area, key UI, screenshots, and resize trajectory; derived values must not be passed off as actual measurements. Formal reports record the candidate identifier, scene/state, layout contract version, and visual baseline version; a missing measurement is unverified, and host scene evidence cannot replace an independent DISPLAY_LAYER.
9. V4 checks structured integration, gameplay ownership, zero references for low fidelity, performance peaks, and functional contracts, and submits dynamic evidence for F3. Revised candidates rerun the affected F0-F3; only A4-A6 operations with external writes, payment, real devices, destructive or external deletion, or release side effects rerun the F4 approval gate. Module boundary changes enter grilling only when there are substantive trade-offs. When there is a dynamic art scope, collect applicable segments of normal operation, high-frequency repetition, key events, and overlay peaks according to the brief's typical single-session/continuous-play situations, record event counts, concurrency, duration, blending, and ending parameters, and have the user check focus and comfort. Reuse the current healthy service and do not automatically initiate real-device acceptance; static passing cannot be used to infer continuous-play passing, and when manual results are missing, record as unverified. When juice feel is involved, refer as needed toevent coverage and feedback rulesQA verifies triggering, results, duplicate merging, interruption, concurrency, resource lifecycle, and performance; dynamic display, viewing comfort, and actual feel continue to be manually accepted by the user.
10. After the shared foundation is complete, verify representative Vite/ThreeJS startup, Boot/first scene, resource loading, and applicable plugins; after the key gameplay flow is complete, smoke-test the core loop and failure recovery on the primary target platform; only final integration/G3/release executes the full channel/platform matrix. Local task evidence must not claim all-platform pass, and must not automatically initiate real-device acceptance.

Mark as "unverified" when there is no reproducible evidence. V1/V2 conditional gates must be bound to the current candidate; silence, continuing work, or old decisions cannot replace what is truly needed USER_DECISION, and user decisions cannot skip the deterministic machine F2 required for V2 decomposition and layout confirmation. FIT only proves proportional non-overflow, not full-screen or responsive reflow; it is forbidden to fake a pass with build success, element existence, or absence of console errors.

Reusable automation scripts are located in scripts/responsive-visual-validation.mjs, and pure computation tests are located in scripts/responsive-visual-validation.test.mjs. The scripts dynamically import Playwright via Node ESM; at runtime, DPR is read from the device and capped according to dynamic-capped-2 , and on the same page the viewport is adjusted via setViewportSize while preserving resize semantics; a valid declaration must be (0,2], the raw deviceScaleFactor is allowed to be greater than 2, and the report retains both the raw value and the effective value capped at 2; zero, negative numbers, non-finite numbers, and strings fail before validation. By default, the report outputs representative viewports and key states;exact mode or an explicit full-coverage requirement then outputs complete page screenshots, the measured matrix, and structured JSON.