Game-studio/references/three-webgl-architecture.md

Three WebGL Architecture

This is the default 3D structure for the plugin.

Recommended module split

src/
  game/
    simulation/
    content/
    input/
    save/
  render/
    app/
      createRenderer.ts
      createScene.ts
      createCamera.ts
      createLoop.ts
    loaders/
      loadGltf.ts
      loadEnvironment.ts
      loadTextures.ts
    objects/
    materials/
    lights/
    post/
    adapters/
      renderBridge.ts
  physics/
    world.ts
    colliders.ts
    sync.ts
  diagnostics/
    debugFlags.ts
    perf.ts
  ui/
    hud/
    menus/
    overlays/

Responsibilities

• simulation/: rules, state, AI, progression, save data
• render/app/: renderer, scene, camera, resize, context lifecycle
• render/loaders/: GLTF, compression, texture, and environment loading
• render/objects/: scene graph construction and disposal
• render/materials/: material setup and shader boundaries
• physics/: Rapier world and simulation bridge
• diagnostics/: performance probes and GPU debugging hooks
• ui/: DOM HUD and menus

Rules

• Scene graph objects are not the source of truth for game rules.
• Keep camera logic explicit and testable.
• Handle resize and context-loss as real browser concerns.
• Keep high-density UI in DOM even when the world is fully 3D.
• Treat GLB or glTF 2.0 as the default content format.
• Add physics and diagnostics as real subsystems, not temporary one-off utilities.