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

OpenSpec Change: enterprise-gaming-r3f-buildings

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

---

Summary

Deliver @suaveplan/r3f-buildings on the genesis branch from scratch at enterprise quality. The package provides instanced city-scale 3D building and road rendering for React Three Fiber. A BuildingTileLoader fetches building footprint + height data (GeoJSON or procedural tile); InstancedBuildings renders all buildings in a tile as a single draw call using InstancedMesh with per-instance world transform; Roads extrudes road segments as ribbon geometry. LOD degrades to billboard sprites at far distances. Genesis adds structured errors, OTel draw-call counter, and 100% coverage.

---

Available workspace deps

@suaveplan/error, @suaveplan/types, react, @react-three/fiber, @react-three/drei, three.

---

Public API surface

function Buildings(props: BuildingsProps): JSX.Element
// tiles, lodDistance, meshes

function Roads(props: RoadsProps): JSX.Element
// segments, width, material

function useBuildings(): BuildingsCon```text

---

## File layout

```text
gaming/scene/r3f-buildings/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    core/
      tile-loader/ (ts + md + test + index)
      instancer/ (ts + md + test + index)
    components/
      Buildings/ (tsx + md + test + stories + index)
      Roads/ (tsx + md + test + stories + index)
    hooks/use-buildings.ts + md + test
  tests/integration.test.ts