SuperAPI AI Directory

threejs-game-asset-integration

General & other

View repository

Updated 10-16 09:30

About this skill

three.js game art production and integration

The real 3D world and characters are produced according to models, materials, lighting, Camera, level/collision data, and runtime logic; skeletal characters use imported mesh animation clips and AnimationMixer. 2D effect-image decomposition, UI layout, nine-slice, and frame-by-frame textures only constrain applicable content such as HUD, DOM, billboards, and flat textures, and must not replace the 3D environment or characters with full-screen/full-character images; see3D model and level pipeline。

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, review, and produce or integrate assets within the scope of the current user task, Implementation Package, A level, and paths; when the plan, paths, or asset list within the task change, update the plan synchronously and re-verify the affected parts. All conclusions return to the threejs-game-workflow-control audit and state transitions. V0, V1, V2, V3, V4 are stageId, and must not bypass global state, side-effecting A4-A6 precise operation approval, diff audit, 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 reuse 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.

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/operation/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 are accepted at V3, and V4 accepts the actual scene composition and dynamic performance; continuous play segments are checked by the user, without adding a per-asset confirmation chain.

Scene reproduction contract (effect-image mandatory)

V2 decomposition first complies withFunctional semantic grouping constraints: confirm the positional dependencies, information grouping, and rationale of regions, functional components, parts, and independent elements; positionally dependent parties 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 sibling items. 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 the formal Scene, not independent PNG production. A scene Work Item only records its own persistent HUD; modal/popup and other popups follow theindependent work item rulesto create a DISPLAY_LAYER Work Item, and freeze the host same-screen image in the required state. An incomplete popup does not block scene V4; the popup itself must still complete V2/V3 and the V4 trajectory of open→interact→close/restore. Runtime defaults to using visual_validation.mode=usability, and strict pixel/full-matrix verification is enabled only 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 for the official runtime frame; it is unrelated to whether resources are generated, produced, or added. When applicable, reference restoration is the visual mode and contract overlay within the implementation lifecycle of the same scene, and must enter the effect-image V1→V2→V3→V4 restoration chain, including scene_reconstruction_contract, layout binding, coverage, same-screen composition of the host scene, and fidelity acceptance; this holds even if all regions are implemented with reuse-existing/runtime-program , with zero new resources and zero generative bitmaps. Do not create a second scene Work Item or a second lifecycle. Merely generating new resources, or using images only as inspiration, explanation, or temporary reference, is not sufficient to trigger effect-image, and they are still classified under the ordinary asset, component, or scene path.image_generation_required、generate-now, resource count, and production_method can only determine the production route via V2 after triggering has already occurred, and cannot participate in the V0 applicability determination.

For the complete prompt template for effect-image generative bitmaps, asset_prompt fact inheritance rules, transparency production requirements, and generation_record structured fields, see"Effect-image Generative Bitmap Faithful Restoration Prompt Contract". Production classification uniformly uses production_method=image-generation, and the specific generator/generator_version is selected by the system based on the prompt, reference input, subject material, transparency requirements, and verified capabilities, and recorded truthfully; when the tool version is not exposed, record not-provided, and do not fabricate it. The transparency route selects controlled solid-color background removal, 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 according to the resource reuse contract; this Skill only retains routing and hard invariants, and does not copy templates here.

V3 aggregates the mutually independent static component × required state images to be generated within the currently confirmed production scope into one batch task, submitted in a single orchestration; creating tasks one by one or waiting for the previous image to pass acceptance before generating the next is prohibited; each item still outputs an independent bitmap, seeBatch Image Generation. After the batch is complete, directly provide an image gallery or contact sheet, where each item can be enlarged individually for viewing; text reports only failures, missing items, and differences that still need handling, and does not first send a text plan and wait for confirmation. Image frame animations with parent-image dependencies proceed according to theFrame Animation Contractwith confirmation item by item; the static image batch rules cannot be used to skip confirmation; independent intervals that already satisfy the parent image and confirmation prerequisites may proceed in parallel according to that contract. V4 directly implements and accepts the resource combination in the official scene, and by default verifies a representative complete frame, key content usability, actual interaction, and official Scene consumption evidence; only exact mode requires complete region-by-region precise measurement and difference materials. Resource loaded/used, missing=0, and resize stability belong only to engineering sub-gates and cannot alone drive COMPLETE.

When determining functionality and splitting scenes, first followShared Planning for the Function and Scene Stageto summarize shared resources and local parts, consumption locations, common specifications, and differences that need to be preserved; when it is already clear that the same part can be planned once for production and referenced in multiple places in advance, do so, while those with insufficient basis remain candidates. After official images are generated and transparency processing and size normalization are completed, then followSharing and Reuse After Official Image Generationto review the early plan and newly discovered requirements, and record the authoritative resource identity, consumption locations, usage restrictions, and basis, so that subsequent tasks can check first and then reuse. Identical functionality or visual similarity cannot alone determine sharing; those awaiting manual visual inspection remain candidates, and existing independent production contracts and true generation records are not rewritten.

  1. Read project configuration, GDD, visual-design, TDD, control plane, and resource registry; executevisual production pipeline。
  2. V0 first determines whether the task belongs to an atomic asset, a component/asset set, or a scene/full UI/visual system/redo; whether reference restoration applies is determined solely by the formal runtime visual goal declaration of the current scenario Work Item, not by new asset or image generation requirements. An atomic asset can skip V1/V2 only when structure, layout, interaction, and viewport behavior remain unchanged, and an applicable visual contract, visual deliverable conclusion, and budget baseline already exist; minor in-task adaptations may update the plan and be re-verified without re-authorization.
  3. After foundation-only basic implementation is complete, V1 establishes functional specifications, gameplay visual contracts, necessary low-fidelity/graybox and budgets, defining only contracts, without writing formal scenario feature code; when the Work Item specifies a mockup as the restoration target, V1 simultaneously followsvisual restorationto generate or receive and freeze the scene master/reference target, host context mockup, reference identity, comparison conditions, observable visual facts, and a preliminary restoration draft. When requirements or baselines are already clear, V1 records AUTO and directly provides the scenario target/host context preview; only ask when there is substantive ambiguity in product direction, gameplay semantics, or structure. V2 maintains the serial hard gate of "decomposition image confirmation → layout image confirmation": Phase A internally completes state analysis, components/placement, production route, technical JSON, and decomposition_elements, directly displays the decomposition PNG numbered in confirmation order, and only asks the user to confirm by viewing the image; technical records are for agent and machine gates and do not separately require reading or confirmation. Phase B automatically generates per-element alignment decisions, layout PNG, and review.htmlafter decomposition image confirmation, and directly asks the user to inspect and confirm the final layout image/preview; there is no need to submit a textual layout plan first. Clarify only when the user discovers genuine ambiguity in the image. The layout only overlays parent-child boxes and annotations on the frozen original image, does not regenerate or replace the visual reference image, and does not provide multiple layout options.
  4. schema 1.5 visual-assets.json first declare effect_image_reconstruction: ordinary assets are not-applicable, and restoration artifacts are not required; mockup restoration is effect-image. For the latter, after freezing the target and before entering V3, use v2-ready to complete contract reconciliation and coverage; V2/V3 may temporarily have no fidelity case; only after V4 verification is complete is it v4-complete and all cases are required to pass. Mockup coverage is registered region by region as annotation_number and implementation_plan, first completing ownership/implementation classification, then performing state_analysiswith actual evidence files, frozen target files, analysis ID, and completion time, strictly before component inventory, and finally filling in component_inventory, placements, and expected_assetsaccording to unique atomic parts; numbering is not a unit of asset quantity. Visual source and assembly method must be separated:visual_route_analysis can only select image-asset or threejs-native,assembly_analysis on independent coverage regions, then independently declare atomic Scene assembly, prohibit full-screen capture, and allow independent image assets; it must not be inferred from "full-screen texture not allowed" that runtime-program. If the same visual fact contains both program logic and independent visual assets, it must return to V1/PROPOSAL to re-partition coverage/annotation: image appearance enters an independent image-asset region, program behavior enters an independent threejs-native/runtime region, and each enters its own production and runtime logic contract. It is prohibited to use a single composite region or composite_parts to produce and accept within one region in a closed loop. When all regions are threejs-native bound to target files, the complete region set, and an independent JSON artifact. all_native_justification, the file gate reads the actual files and verifies qualification facts region by region. The state analysis must cover normal, selected/active, disabled, pressed/hover, victory/defeat/paused; write requiredwhere actually applicable, and write not-applicable+reasonwhere 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 their actual reuse relationships; ③, ④, and ⑦ remain single images only when they are clearly single parts and the remaining states are not applicable. In the default individual mode, horizontal grouped images are prohibited;image_generation_required=true the generative bitmap of individual + atlas_allowed=falseuses expected_assets.width/height , whose ceil(max placement width/height × intended_scale_range.max) is automatically calculated by the validator in logical pixels, 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. Here 1 means the image is produced at the maximum agreed logical display size 1:1; the actual DPR at runtime 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 a complete atlas_slice atlas only under an explicit contract. Each placement must declare interaction_required, and real interaction_hotspots can only be bound one-to-one by placement and is not counted as a visual asset. The confirmation image still presents both generate-now、reuse-existing and runtime-program, but the PNG only draws the user summary and the labels "new image asset / reuse existing image / programmatically drawn or dynamic logic"; placement IDs, coordinate sizes, and component/state/asset technical fields do not enter the visible rows. When running --proposal , these technical fields are fully written into the breakdown analysis technical JSON and bound to the PNG metadata, actual region definitions, and 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 make any generator inference. V2 then follows asset production route to select the route. The route is judged by observable visual facts and the actual rendering capabilities of ThreeJS, not by semantics such as "button" or "panel", nor is static/dynamic the sole condition. Text, solid-color rectangles, basic geometry, regular borders, simple regular gradients that can be deterministically expressed, masks, and progress fills may choose threejs-nativewhen ThreeJS native capabilities can precisely express the frozen appearance; featured illustrations, complex ornaments, irregular contours, complex materials, and decorations with obvious artistic characteristics use the independent image route. The native route freezes native_suitability.render_contract the renderer, size, color, line width, corner radius, gradient, transparency, applicable states, and unsupported features; visual features that cannot be supported must block, and cannot be approximately substituted and then pass. Images, image parts, and text first followcomplete breakdown and visual salienceto register independently identifiable parts, maintaining function, interaction, and state linkage; obvious artistic appearances prioritize bitmaps, low-salience operation text considers system text, and simple fills consider native drawing. Then verifycomplete programmatic restoration qualification: the program must completely implement the appearance that the plan requires to be preserved; when the subject and effect cannot be reliably separated, preserve the complete atomic visual part. Dynamic/localized text followstext route determinationto preserve variable capability, and does not silently simplify confirmed artistic effects during implementation. Color fills likewise followcolor fill route determinationSplit: obvious materials and lighting retain independent bitmaps, stylized repetitive surfaces prioritize reused textures, and low-salience base fills consider native drawing; dynamic proportions and states remain variable, and fills must not be mixed with borders, glows, or ornamentation as solid-color regions. Appearance sources and behavior assembly are recorded and bound separately; for example, a button may consist of a native frame, an independent icon image, and DOM/CSS2D text, and is wired into interaction through explicit component/node references, not merged into composite regions.image_generation_required=true Once frozen, it must not be automatically switched to the native route and may only change according to an explicitly accepted Change Request.
  5. V2 runnable node scripts/validate_visual_manifest.mjs docs/visual-assets.json --stage V2; V3 formal acceptance run node scripts/validate_visual_manifest.mjs docs/visual-assets.json --stage V3 --check-files --project-root ., V4 formal acceptance runs the same command but uses --stage V4. 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 popups into host scene acceptance. V3 item-by-item verifies real asset files, source/license information (if applicable), budget, frozen baseline, coverage, and production_contract_audit; V4 verifies formal Scene consumption, runtime composition, two types of F2 machine evidence, F3 runtime replay, and applicable fidelity cases.
  6. The current scene Work Item advances through the V1→V2→V3→V4 stages defined by the control plane; this domain is responsible for producing formal assets at V2 after completing two independent manual confirmations, first for the split PNG and then for the layout PNG, completing asset-level acceptance at V3, and directly implementing, calibrating, and accepting the runtime visuals in the formal scene at V4. Formal code only consumes resources from the current scene or compliant shared with V3 accepted ; public formal assets are only allowed if they are stably reused by at least two scenes or are required for runtime. Grayboxes, placeholders, and fallbacks must be removed before joint scene acceptance.

The transparency route is defined 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; the generation record top-level generator/generator_version is the actual identity, andcapability.tool/tool_version must be identical to it.mask-composition must be bound to an independent mask or manually created actual inputs and tool parameters. When capability is insufficient, report the gap; do not increase tolerance, hard-cut contours, delete light effects, or falsify results. Generation records register the generator identity, parameters, input/output SHA, and post-processing according to the actual route; normalization preserves proportions, Alpha, and subject boundaries, and baking checkerboard previews into assets is prohibited. Each candidate generates light-background and dark-background previews, and V4 completes the visual inspection of subject defects, residual background, color fringing, and semi-transparent regions. Existing real transparent images are integrated according to the asset reuse contract, without falsifying generation or background-removal records.image_generation_required=true 's frozen contract cannot be automatically replaced by transparency route judgment or the prompt generator. 7. Grayboxes or visual samples before V2 must be isolated from the formal runtime chain, must not register formal entry points or implement formal business logic; after V2 confirmation, produce V3 formal assets; V4 implements functionality in the formal ThreeJS Scene and consumes accepted assets, and one-off screenshot Scenes, full-screen image laying, hidden overlay layers, and absolute stacking to fake pixels are prohibited. After formal functionality is implemented, V4 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 change is the corresponding fidelity case invalidated and re-collected, while other unit evidence remains valid.

The formal effect image annotation command must include --proposal <file>.json; omitting this parameter fails directly, and no successful artifact containing only the user's illustration is generated.

Effect image production must first reference the frozen global visual baseline; the global candidate selection, frozen state, and cross-Work Item reference rules are governed byControl ModelandGlobal Visual Control. This domain only supplements the generation record, anchor inheritance, and asset contract requirements; the scenario is still completed within the same Work Item in the order V1→V2→V3→V4.

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; see 离线布局审阅产物。

When disassembling UI base plates, button skins, and frames for V2, the nine-slice must be evaluated based on observable fixed corners and edges and stretchable regions, recording the applicable/not applicable reason as well as the source image dimensions and four-edge slice values; when nine-slice is adopted, the selection freezes together with the existing disassembly confirmation and runs through V3 small image production and V4 formal scenario implementation. For the specific contract, readNine-Slice UI, and V3 production executes according to the frozen slice parameters.

Conditional References

  • Reference screenshots, screen recordings, running projects, or source restoration: read Visual Restoration。
  • Decorative screen-space full-bleed background: read Full-Bleed Background; world-space levels, project-built maps/tiles, or gameplay environments instead switch to the asset production route and model pipeline.
  • UI: simultaneously read threejs-game-ui-layout 's layout contract, ThreeJS adapter, and evidence matrix; asset origin, layout anchors, and animation offsets are separated according to the contract, and asset integration must not reinvent layout rules.
  • QA measurement, dynamic resize, full viewport screenshots, and read-only Hooks: read Responsive Visual Verification, and do not copy its fields or thresholds in asset documents; viewing comfort and sustained play acceptance use the shared art contract.

Review and Delivery

All candidates must first pass F0-F3; F4 only handles A4-A6 operations with external writes, payment, real devices, destructive or external deletion, or release side effects. Side-effect-free local A4 integration does not additionally wait for approval due to its level label. V1/V2 deterministic machine checks must be executed; when requirements are clear, automatically adopt AUTO and directly produce a preview, and record once only for genuine direction/gameplay/structure trade-offs USER_DECISION. At V2, users only need to separately confirm the disassembly PNG and the layout PNG; static asset batches and in-scope rework are reviewed through galleries/before-after comparison images. Technical JSON, state analysis, coverage, contracts, and evidence are continuously maintained by the agent, without initiating additional text confirmations. 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→V1→V2→V3→V4 chain of the same scenario Work Item, at V2 the disassembly image confirmation and the layout image confirmation are completed in sequence, freezing the restoration plan. What the user faces are numbered disassembly PNGs and layout PNG/review.html; technical JSON, proposals, and decision files are used in the background for machine verification and identity binding, and do not constitute an additional text confirmation gate.visual-decomposition-confirmation/1.0 Bind annotation/proposal/decision SHA, target, V2 candidate, diff, baseline, all numbering, and the user's original text; when a confirmed target or plan undergoes a substantive change, reconfirm the affected parts; ordinary runtime layout fine-tuning does not reopen V2. The V2 breakdown diagram, technical JSON, contract reconciliation, coverage, and structured machine checks must all be complete; layout confirmation separately binds the final layout diagram and decision file. V3 resource acceptance and V4 formal-scenario representative complete frames 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, boolean values, AI reviewer fields, or old human_review can none of them replace the two V2 image confirmations.

F2 machine evidence checks files, structure, binding, and actual parameters, and cannot on its own give an art-pass conclusion. The agent may provide screenshots, screen recordings, and check points; when automatic visual verification is not explicitly authorized, it does not automatically analyze the frames. The user's actual evaluation of theme, degree of completion, and comfort is incorporated into the existing image selection, V2 layout confirmation, and V4 runtime acceptance materials, and cannot be filled in on the user's behalf or overridden by old confirmations for frames that have changed.