SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsthreejs-game-architecture

threejs-game-architecture

Coding & development

View repository

Updated 10-16 09:30

About this skill

three.js technical architecture

Global control access

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 or external deletion, or release side effects require approval.

This domain may propose, review, and modify within the scope of the current user task, Implementation Package, A level, and path; any result must return to the threejs-game-workflow-control risk gate. Changes to the approach and path within a task can continue by simply updating the plan; for the first module or boundary change, close the facts first, and only stop and grill for substantive architectural trade-offs.

Establish maintainable, testable, and buildable Web 3D engineering boundaries. The browser is the default runtime environment; only add mini program, desktop wrapper, or mobile native host adaptation when the target channel explicitly requires it.

Inputs and boundaries

Read the global Work Item, module audit, dependency capability tier, service boundaries, and project authoritative artifacts. Submit results according to F0 scope and process, F1 specification consistency, F2 architecture quality, F3 engineering verification, and F4 integration/release decisions, without changing global state on your own.

  • Implement the browser core with three.js, TypeScript, and the Web build tool selected by the project; WebGL 2's WebGLRenderer is the default renderer. Only after the project explicitly chooses WebGPU and verifies the target browser, materials, and deployment requirements should WebGPURenderer。
  • three.js Scene is the Object3D tree, responsible for organizing visible objects, and does not serve as a game state container. An independent scene controller owns gameplay state and lifecycle, and provides enter、update、exit、dispose; the render loop advances gameplay/physics at a fixed step, then uses render interpolation to display the current state.
  • The browser is the default platform. Use Capacitor or the corresponding host only when the target channel truly requires a native host; platform plugins are selected item by item according to capability and encapsulated in the adaptation layer, and non-essential plugins are not preinstalled.
  • Mini games must be verified separately; optional commercial capabilities must have explicit interfaces and approved switches.
  • Base modules followAudio lifecycle constraintsHandle browser page visibility and audio context restrictions; only add corresponding platform lifecycle adaptation when a native host is used.
  • Base modules followBase display constraintsMake the Canvas adapt to the actual CSS viewport and keep Camera, HUD, and input coordinates consistent. Native window themes, immersive fullscreen, and platform safe areas are implemented only when the corresponding host is selected.

Native platform plugin selection

Apply this section only when the project has selected an Android/iOS native host or explicitly needs native platform capabilities; browser projects do not thereby introduce Capacitor, native projects, or platform plugins.

  • Before implementing native platform functionality, first check the plugins already adopted by the project; reuse them directly if they meet the requirements. When new capabilities are needed, first evaluate Capacitor official plugins or the capability provider's official plugins, then evaluate community plugins that are actively maintained, have applicable licenses, and meet the requirements; when a domain Skill has specified a plugin, follow that domain contract.
  • Verify plugin support for the project's current host framework version, target Android/iOS versions, required APIs, permissions, and lifecycle behavior; when using Capacitor, explicitly verify its version. Record dependency versions, maintenance status, licenses, platform limitations, and verification methods, and only install plugins actually used by current requirements.
  • Plugin calls are uniformly encapsulated in the platform adaptation layer, exposing capabilities to the business through the project's public interfaces; business and scene controllers do not call plugins directly. Web/mini-game adaptations explicitly declare support status and failure semantics, and do not disguise native capability success with empty implementations.
  • Only when existing plugins cannot satisfy a clear requirement should custom native plugins or direct native implementations be added; record the evaluated plugins, specific capability gaps, and minimal custom scope in the TDD and implementation package, avoiding reimplementing capabilities already provided by plugins.
  • Necessary host configurations such as the launch theme, Manifest, and permission declarations are still maintained in the native project. Runtime capabilities such as immersive fullscreen, system bar control, and lifecycle restoration should also preferentially use plugins, and only the parts that plugins cannot cover should be supplemented with minimal native code; plugin-first does not lower the acceptance requirements for cold-start first frame and restoration behavior.

Execution and Handover

When creating a new game project, implementing basic modules, or adjusting directories and module boundaries, first readGame Project Directory Specification, organize code by entry/basic service layering and scene feature aggregation, clarify ownership of resources, platforms, tests, and artifacts, and write the actual paths and ownership into the TDD and implementation package.

  1. Before implementation, divide and audit modules, recording responsibilities and non-goals, public inputs/outputs, state ownership, lifecycle, allowed/prohibited dependencies, failure boundaries, tests, and implementation order; for the first module, complete the module gate and grilling first, then write into the TDD according to F0-F4. Global phases, visual hard gates, and scene prerequisites are based onControl Model、State, Phase, and Stop Gatesand the corresponding Schema; this domain only supplements module boundaries.
  2. In the TDD, mark the SHARED/MODULE scope of foundation-only, the SCENE/DISPLAY_LAYER ownership of scenes, and the cross-scene INTEGRATION dependencies. Basic packages only provide stable contracts and do not implement specific scene gameplay, HUD/layout, formal visible asset consumption, or Boot→formal visible Scene integration; modules can proceed in parallel under mutually exclusive ownership, while shared contracts/entries remain serial. Scene controllers collaborate only through public services, state repositories, or message contracts, and must not directly access the internal state of other controllers.
  3. When adding modules, splitting responsibilities, or adjusting the implementation plan within a task, update the plan and ownership synchronously, and perform targeted verification of the affected parts. Only when the goals, external behavior, or substantive design trade-offs that the user needs to decide change should a Change Request be created and a decision requested; only A4-A6 operations with side effects enter the F4 approval gate.
  4. Decorative screen-space backgrounds are used only for non-interactive backgrounds. Levels, terrain, collision, gameplay environments, and camera trajectories use independent world data and coordinate contracts, and do not apply the HUD's fixed design resolution. According toDisplay Object Anchors and Display Layer Layeringdeclare the real Object3D root, Camera, render order, depth testing, input, lifecycle, and resource ownership; object pivots are expressed through geometric local coordinates or parent Group , and cross-layer composition is clarified by Camera/DOM/render pass contracts.
  5. When screen HUD is involved, use threejs-game-ui-layout Define the layout entry point, and record the CSS client rect, effective DPR (maximum 2), Canvas backing, Camera, input mapping, safe area, resize, representative viewport, performance budget, and evidence fields. Canvas dimensions are configured according to CSS width and height; physical pixels are not used as UI coordinates; after resizing, synchronously update the camera projection matrix. Traditional buttons/text are preferentially laid out by the DOM Overlay; HUDs that need to be drawn inside the 3D Canvas use an OrthographicCamera. The fixed 1080×1920 design baseline may only be used for the HUD; the perspective world establishes a separate world contract according to project units, level geometry, camera, and frustum. When DPR changes, update the CSS/backing and input mapping together, and clean up listeners according to the display module lifecycle. Popups/DISPLAY_LAYER inherit the host CSS viewport and input contract; an independent Camera or Canvas separately declares composition and hit mapping. Layout recalculation remains idempotent; contract verification belongs to F3, and special viewports and occlusion rules trigger the layout-specific F2.
  6. Separate core rules, presentation, platform, and third-party services. Public code and public production assets must be stably reused by at least two confirmed scenarios, or be required for operation; unbounded common/utils and public asset libraries are prohibited. In the foundation-only phase, SHARED provides only minimal startup, public contracts, and the Boot/Preload lifecycle,MODULE provides only scenario-agnostic data/state/input/asset infrastructure, the render loop, and test support; specific scenario business logic, HUD/layout, and production visible assets are still completed in the corresponding scenario phase. Each scenario completes gameplay, production visuals, all HUD/popup display layers, cleanup, and joint evidence together in its own phase. Gameplay exclusively owns rules, state, physics semantics, and interaction code; art may maintain pure-presentation asset configuration, scenario data, and visual integration adjustments, but must not change gameplay rules, collision semantics, or state ownership. Define verification strategies for browser input, page pause/resume, visibility, viewport, and target hardware.
  7. For component/asset sets and scenario paths, define at V1 the per-scenario textures, atlases, frame counts, animation sampling, texture memory, overdraw, Draw Calls, and maximum texture budget; at V3 write the budget into the machine manifest, and at V4 verify production assets and scenario combinations. Atomic assets must reference an existing applicable and valid gameplay visual contract and budget baseline, otherwise follow the upgrade path; they must not be temporarily relaxed at acceptance time.
  8. In the TDD, record as needed the core, mobile platform, data/API, complex gameplay, advanced visuals, and commercial capability tiers; each item includes the reason for enabling, the rejected lightweight option, runtime performance and platform risks, verification commands, and owner. When services are involved, record contract version, authentication and authorization, idempotency/retry/timeout, compatibility, migration/rollback, testing, monitoring, and backup and recovery; when the server side is out of scope, record only external dependencies, owner, and client boundaries.
  9. In the TDD, define the local service identity, default mode, host/port, and health check. Before starting a development or preview service, check the listening process, command line, project root directory, and health status; if the identity is consistent and healthy, reuse it directly and do not start it again.
  10. After the shared foundation is complete, verify representative browser/Vite startup, WebGL2 Renderer, Boot/first scenario, assets, and selected plugins; after the key gameplay flow is complete, verify the target browsers/hardware declared by the project; only final integration/G3/release executes the platform matrix of the channels actually adopted by the project. Partial evidence must not be used to claim passing on all platforms, and real-device acceptance must not be initiated automatically.
  11. After F0 is complete, submit scope and process facts; F1 submits specification mapping; F2 submits independent architecture conclusions; F3 submits the candidate SHA, actual command evidence, and uncovered items.

Hand over the gameplay development module entry point, data flow, and test entry point; hand over the build commands, versions, and log location methods to testing. Any newly added or modified classes, functions, and entity definitions must have simplified Chinese comments explaining the design boundaries.