Customizing

Customizing

The canonical, always-current version of this page lives in the repository: docs/CUSTOMIZING.md, with full code examples. This page is the map.

Most of what makes LuminaReef this reef is data, not code.

Where things live

Want to change	File
The fish roster — species, colours, counts, where they start	components/3d/fishGeometry.ts
Garden names, promises, arrival lines	lib/restoration.ts
Which rescue count wakes which garden	zonesForRescues() in stores/useReefStore.ts
Achievements, combo window, Swift Tide threshold	lib/achievements.ts
Fog, lights, camera framing	components/3d/LuminaReefScene.tsx
Water and caustic colours	components/3d/Water.tsx
God rays	components/3d/LightShafts.tsx
Bloom threshold, vignette	components/3d/Effects.tsx
Coral species, counts, colours	components/3d/Corals.tsx
The finale's shape and timing	components/3d/finaleConfig.ts

Three things that will bite you

The roster total is the campaign. Twelve fish isn't a coincidence — the rescue goal and the Heart Constellation are sized to it. Change count on any species and you must also update RESCUE_GOAL in the store and add matching points to HEART_CONSTELLATION_POINTS, which the finale indexes into directly.

Adding a light is not free. Every light multiplies the cost of every MeshStandardMaterial pixel in the scene. The reef runs five on purpose. Want a glow? Reach for emissive + bloom first.

Never set vertexColors on the fish material. Their GLBs ship no COLOR_0 attribute, so the unbound colour attribute reads black. Tint via instanceColor.

Bloom is selective without a selective pass

The base scene deliberately sits below luminanceThreshold; emissive corals and shafts are pushed above it. That's the whole trick. If you brighten the scene generally, everything starts blooming — raise the threshold rather than dimming the corals.

After you change anything

npm run shots     # regenerate the README screenshots (dev server must be up)
npm run perf      # if you touched a shader or added a light

Then play it. A real-time scene can typecheck perfectly and still look wrong.