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

OpenSpec Change: enterprise-gaming-r3f-vegetation

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

---

Summary

Deliver @suaveplan/r3f-vegetation on the genesis branch from scratch at enterprise quality. The package provides R3F procedural vegetation with biome rules, LOD, and instanced placement. An InstancedMesh-backed placement engine scatters trees, grass, and rocks according to configurable biome rules (height/slope thresholds → vegetation type); LOD reduces instance count at distance; a wind animation vertex shader applies sinusoidal sway. Genesis adds Zod biome config schemas, structured errors, OTel instance-count gauge, and 100% coverage.

---

Available workspace deps

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

---

Public API surface

function Vegetation(props: VegetationProps): JSX.Element
// biomeRules, density, maxDistance, windStrength

function VegetationLayer(props: VegetationLayerProps): JSX.Element
// type, mesh, count, scatterRadius

function useVegetation(): VegetationCon```text

---

## File layout

```text
gaming/scene/r3f-vegetation/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts / constants/index.ts
    types/common.ts + md
    core/
      biome-rules/ (ts + md + test + index)
      instance-placer/ (ts + md + types + test + index)
    shaders/
      wind.glsl + wind.ts (glsl string export)
    components/
      Vegetation/ (tsx + md + test + stories + index)
      VegetationLayer/ (tsx + md + test + stories + index)
    hooks/use-vegetation.ts + md + test
  tests/integration.test.ts