suaveplan/openspec/changes/enterprise-gaming-r3f-world/proposal.md

OpenSpec Change: enterprise-gaming-r3f-world

• Change ID: enterprise-gaming-r3f-world
• Package: @suaveplan/r3f-world
• Category: gaming/scene
• Target path: gaming/scene/r3f-world
• Status: PROPOSED
• Date: 2026-04-24
• Reference spec: /mnt/s/web/suaveplan/enterprise/r3f-world.md

---

Summary

Deliver @suaveplan/r3f-world on the genesis branch from scratch at enterprise quality. The package provides world management and scene composition for React Three Fiber. A WorldManager orchestrates scene layers (terrain, vegetation, water, buildings, NPCs, effects) in dependency order; a SceneGraph maintains a flat registry of mounted scene nodes with bounding volumes; a WorldProvider React context exposes the manager to all child R3F components. useWorld() accesses the context for scene queries and entity registration. Genesis adds structured errors, OTel scene-node gauge, and 100% coverage.

---

Available workspace deps

@suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/spatial-hash, @suaveplan/ecs, react, @react-three/fiber, @react-three/drei, three.

---

Public API surface

function WorldProvider(props: WorldProviderProps): JSX.Element
function useWorld(): WorldContext

interface WorldContext {
  register(node: SceneNode): () => void
  query(bounds: AABB3): SceneNode[]
  readonly nodeCount: number
}

// Components
function World(props: WorldProps): JSX.Element   // root scene orchestrator

---

File layout

gaming/scene/r3f-world/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts / constants/index.ts
    types/common.ts + md
    core/
      world-manager/ (ts + md + types + test + index)
      scene-graph/ (ts + md + types + test + index)
    context/
      world-provider.tsx + md + test
      use-world.ts + md + test
    components/
      World/ (tsx + md + test + stories + index)
  tests/integration.test.ts