Reference
Library issues fixed
Building the island on the prebuilt libraries turned up nine problems in Sky, Water and NatureGL Grass. All nine were fixed upstream in the 1.1.0 releases, and every workaround has been removed from the game.
NatureGL Island consumes the libraries' build/ folders without modifying them. When something didn't work, 1.0.0 worked around it in game code and the issue was written up in docs/LIBRARY-ISSUES.md. That file is kept as a record: symptom, old workaround, fix.
drone-lagoon: the lagoon-wide foam rings (issue 3) are gone with the 1.1.0 libraries.#Status
| # | Library | Upstream fix (1.1.0) | What NatureGL Island does now |
|---|---|---|---|
| 1 | Water | water.setSky() accepts a SkySystem (reads ambient.color) | makeSkyAdapter() deleted; water.setSky(this.sky, { moonIntensityScale: 1 }), re-called on the sky's quality event |
| 2 | Water | Moonlight from sky.moon (moonIntensityScale, moonTint) | Moonlight uniform override deleted; physical moon (scale 1) |
| 3 | Water | Shore steepness scales with shoreWaves; new shoreSteepness param | Private water._shore.steep deleted; default shoreSteepness 0.92 kept. Only real breakers on the beach and reef edge remain. |
| 4 | Water | bathymetry.shoreTrainMinRadius (40 m) | No change needed; the bull's-eye rings round the islets are gone |
| 5 | Water | bindLights() takes the ground colour from the external sky | Not applicable: the game calls sky.bindLights() |
| 6 | Weather | weather.setLayer() / create({ layer }) | rain.js passes layer: water.overlayLayer |
| 7 | Sky | SkySystem.create({ maxExposure, nightExposure }) + water's syncExposure | Manual cap deleted; the sky is created with { maxExposure: 2.4, nightExposure: 5 } and the game writes only water.params.exposure |
| 8 | Sky | SkyPostPass.composite() + water.renderHDR() | Optional game.setSkyPost(true) / demo/?skypost, off by default |
| 9 | Grass | Scatter layers forward filter, maskPower, … | addBushes({ …, filter }), addRocks({ …, maskPower: 0, filter }) |
#The issues
#NatureGL Water
1. setSky() could not take a SkySystem directly (blocking)
NatureGL Sky exposes ambient = { skyColor, groundColor, intensity, color }. NatureGL Water read amb.sky, which was undefined, so Color.copy(undefined) threw on the first water.update().
1.0.0 workaround: a makeSkyAdapter() with live getters and ambient.sky = skyColor × intensity. Without the intensity the water body was lit about 300× too bright at night.
Fix: _updateSky accepts amb.color, or amb.skyColor × amb.intensity, with a fallback.
2. External-sky moonlight was hard-coded
With NatureGL Sky's real moon (moon.intensity ≈ 0.017) the sea at night was about 25× brighter than the moonlit terrain; glitter and foam glowed electric blue.
1.0.0 workaround: overwrite uLightCol / uSunGlow after water.update().
Fix: use sky.moon.color × sky.moon.intensity when the external sky provides them.
3. Shore-wave steepness did not scale with shoreWaves
The steepness floor was independent of the amplitude, so the shore-wave term alone pushed crests under the whitecap threshold within 130 m of land. On a wide lagoon that drew concentric white rings everywhere, even with shoreWaves at 0.3.
1.0.0 workaround: set the private water._shore.steep = 0.55.
Fix: the floor scales with shoreWaves, and shoreSteepness is a public param.
4. Shore-wave trains formed bull's-eye rings round small islets
Round a 20–40 m rock the shore-wave trains were perfect concentric circles, visible from the drone.
1.0.0 workaround: steep islet flanks kept the rings faint.
Fix: bathymetry.shoreTrainMinRadius (40 m).
5. bindLights() with an external sky used the built-in sky's ground colour
Not blocking: the game drives its lights with sky.bindLights().
Fix: take the ground colour from the external sky's ambient when present.
6. Particles need the overlay layer
Transparent objects in the main pass are drawn under the water. NatureGL Weather's rain, splash and lightning meshes, and the game's bird splashes, go on water.overlayLayer.
Fix: weather.setLayer() and WeatherSystem.create({ layer }).
#NatureGL Sky
7. Auto exposure had no ceiling, so moonlit nights rendered like day
The metered exposure went from about 1.3 at noon to 34–61 at night, so the moonlit island read as an overcast day and the lamps bloomed out.
1.0.0 workaround: hand NatureGL Water min(metered, lerp(2.4, 5, night)).
Fix: maxExposure and nightExposure options.
8. The post pass and NatureGL Water's depth pipeline were exclusive
Both SkyPostPass.render() and WaterSystem.render() render the scene into their own HDR target and tone-map, so the island couldn't use NatureGL Sky's height fog, god rays or clouds over geometry.
Fix: SkyPostPass.composite(texture, depthTexture, camera) takes NatureGL Water's renderHDR() output. See Composing the libraries.
#NatureGL Grass
9. Ready-made scatter layers ignored filter and maskPower
addBushes({ filter }) silently ignored the filter (same for addRocks, addTrees, addFlowers).
1.0.0 workaround: scatter.addBushes({…}).set({ filter, maskPower }).
Fix: unknown options are forwarded to addLayer().
#NatureGL Weather
Nothing blocking. Next to NatureGL Water, set fog.sceneFog = false (NatureGL Water manages scene.fog) and put the rain on the water's overlay layer (issue 6).
#Before and after
drone-island, 1.0.0 librariesdrone-island, 1.1.0 libraries: no rings round the isletspier-night, 1.0.0 librariespier-night, 1.1.0 libraries