# jungleKit
**Add a walkable tropical rainforest to any world with one component.** Pick a size, a jungle type (lowland, cloud forest, monsoon valley or temple grove), how thick it grows and a seed: jungleKit carves a river across the ground with muddy banks and a gravel and sand bed, drops it over a mossy escarpment as a tall waterfall (about 17 m in the lowland, 20 m in the cloud forest) into a plunge pool with a natural, wandering rim, narrows it into a rock gorge where a rope bridge crosses, opens a sunny clearing, levels a site for an overgrown stepped temple, and links them with footpaths cut into the hillside as level benches: **trailhead → riverbank under the falls → rope bridge → temple ruins → the clearing before the temple → temple summit**. The forest stands in layers the way a rainforest does: sparse giant emergents, a closed canopy, a dark understory of palms, tree ferns, monstera and heliconia (bananas, bamboo and elephant ears along the river), a dense floor of ferns, seedlings and moss, buttress and surface roots at the tree feet, lianas hanging from the limbs and strung between neighbouring trees, bromeliads and orchids on the branches, mossy fallen logs with fungi, boulders in the river. Villagers can walk the trail (`JungleWanderers`). **The same settings and seed build the same jungle for every player** (checked across desktop machines; the browser is not checked yet, see *Known limits*).
Version 1.2.2. The rain is drawn and played by **Cloudburst** (installed with the kit). Built on **jungleProps** (every plant, root, vine, epiphyte, fungus, rock, log, temple piece and the rope bridge) and **jungleMaterials** (the ground's terrain layers and the water), with **navKit** for the villagers. The ground is the engine's own terrain.
## Drop a jungle into your world
In `scenes/main.scene/build.luau`, inside `content()` (a world with no main scene yet gets one with a player in it from bash: `zero scene create --startup main player`):
```luau
local JUNGLE = { size = 400, jungleType = "lowland", density = "normal", seed = 7 }
entity.spawn("Jungle").component.add("jungleKit.Jungle", JUNGLE)
-- villagers walking the trail, shared by every player (optional)
entity.spawn("Wanderers").component.add("jungleKit.JungleWanderers", { count = 4 })
-- players arrive at the trailhead: the Jungle moves the scene's PlayerSpawns there by itself
```
Checked word for word on 2026-11-15 in a brand-new empty world (jungleKit 1.1.4 installed from ZeroMind with everything it needs, a main scene made with the command above, these lines pasted at the top of `content()`): a 400 m lowland jungle of 57,354 props built and the player walked down the trail from the trailhead. Then one setting at a time: `size = 250` gave 19,970 props on a 250 m square; `density` `sparse` / `normal` / `lush` gave 27,365 / 57,354 / 94,874 props on the same ground and walk; `river = false` removed the river, falls and bridge; `temple = false` removed the temple; `seed = 8` moved the trailhead, temple and every plant. To put the trailhead into the saved scene as well, see *Your own player at the trailhead* below.
The first build of a new setting shapes and paints the ground and saves it into your world as `jungles/jungle_<type>_<hash>.terrainData` (a few seconds of CPU, spread over frames, plus one engine terrain write). Every later build, every player's included, only loads it. **Build each setting once in the editor before you publish**, so no player's browser ever cooks ground.
### Start small or start big
The one-line start is `entity.spawn("Jungle").component.add("jungleKit.Jungle", {})`: with nothing set it builds the Emerald Falls jungle (500 m lowland, normal density, seed 7, a Maya temple above the canopy, river, falls and bridge), adds its own atmosphere with a shared clock starting at dusk, and puts the players on the trail.
| Level | Settings | Checked |
|---|---|---|
| **small** (crossed in a minute or two) | `{ size = 200, jungleType = "templeGrove", river = false, seed = 3 }` | built in play 2026-11-15 (with `templeStyle = "maya", density = "dense"`): 16,596 props, the trailhead, the clearing and the temple on its plateau about 20 m up |
| small with a stream | `{ size = 200, jungleType = "templeGrove", river = true, waterfall = false, seed = 3 }` | a stream with a rope bridge before the temple |
| **big** with the waterfall | `{}` (500 m lowland, seed 7) or `{ size = 400, seed = 7 }` | the showcase; 400 m gives 57,354 props (above) |
`templeGrove` is made for 200 m; `lowland`, `cloud` and `monsoon` want 400 m and up so the river has room to fall over its cliff.
### Your own player at the trailhead
Players come from the scene's player block (its `PlayerSpawn` names the `PlayerPrototype` every joining player is cloned from). With `spawnAtTrailhead` on (the default) the Jungle moves every PlayerSpawn to the trailhead, facing down the path, so your own prototype arrives there with no code. To put the trailhead into the saved scene too, set the spawn from `JungleBuilder.spawnPoint(settings)`, which answers the list `{ x, y, z, yaw }` (`sp[1]` to `sp[4]`); pass the same settings table as the Jungle (`{}` for the defaults):
```luau
local spawn = entity.spawn("DefaultSpawn", { parent = spawns })
spawn.component.add("PlayerSpawn", { prototype = prototype })
local sp = require("jungleKit.JungleBuilder").spawnPoint(JUNGLE)
spawn.localPosition = { sp[1], sp[2], sp[3] }
spawn.localRotation = { 0, math.sin(sp[4] / 2), 0, math.cos(sp[4] / 2) } -- facing down the path
```
### A goal, and your own messages on screen
A goal at the temple summit (or any stop) is one line: `entity.spawn("Goal").component.add("jungleKit.JungleGoal", {})`. Each player sees their own "Climb to the Temple Summit: 84 m" at the bottom centre, then "You reached the Temple Summit in 74 s!". Fields: `target` (a poi id, `templeTop` by default), `radius` (5 m), `below` (1.5 m), `message` / `doneMessage` (templates with `{target}`, `{distance}`, `{time}`), `corner` (`bottom`, `topLeft`, `topRight`), `showInEditor`. Methods `reached()`, `seconds()`, `reset()`, `targetPoi()`; the event `onReached { seconds, target }` and the log line `JungleGoal: reached <target> in <n> s`.
Where the kit draws, measured in play (1920x1080 at UI scale 1.5, i.e. 1280x720 points; numbers in points): the route guide's arrow and its distance label at the top centre from 14 to about 140, the "Next: ..." tracker under it to about 190 (navUiKit layer 110), the stop toasts at the bottom right, 320 wide, 84 to 144 above the bottom edge (stacked down the middle on a phone; layer 120), and JungleControls' "Time & Weather" button at the bottom left from 96 above the bottom upwards (layer 38). **Put your own message at the bottom centre, `paddingBottom = 40`, one line (under 52 tall, under 560 wide)**: free on every screen. The top corners (14 in) are free on a desktop for short labels. `JungleHud` does it: `require("jungleKit.JungleHud").message("myId", "text", { corner = "bottom" })`, `.clear(id)`; `JungleHud.SAFE.bottom` / `topLeft` / `topRight` are ready root styles, `JungleHud.STYLE` the label look and `JungleHud.LAYER` (90) the layer, above the world and under the route guide.
## What you set
| Setting | Values | What it does |
|---|---|---|
| `size` | 120–1200 (m) | the side of the square the jungle stands in (default 500, the Emerald Falls jungle; 200 for a small level) |
| `jungleType` | `lowland`, `cloud`, `monsoon`, `templeGrove` | lowland: gentle hills, a broad river, kapok and dipterocarp giants; cloud: steep ridges high up, a narrow stream, tree ferns, moss and epiphytes everywhere; monsoon: a broad river valley, a wide river, bamboo and wild bananas, a lighter canopy; templeGrove: a raised plateau the temple stands on, strangler figs |
| `density` | `sparse`, `light`, `normal`, `dense`, `lush` | how thickly everything grows (the ground and the walk stay the same) |
| `river`, `waterfall`, `bridge` | true/false | the river; the cliff, falls and plunge pool; the gorge crossing (the last two need the river) |
| `riverShape` | `meander`, `rapids`, `lake`, `gorge` | how the river runs: `meander` winds across the jungle as the jungle type has it (the default, unchanged); `rapids` is steeper, narrower and shallower, white water and foam over many more boulders, and its bed roars louder and farther; `lake` opens the river into a broad still lake below the falls (or mid-river without them) with muddy shores and reedy grass; `gorge` runs it through a long deep rock gorge, the rope bridge about 12 m over the water. Each shape is its own saved ground |
| `temple`, `templeStyle` | true/false; `auto`, `maya`, `khmer`, `candi`, `ruinField` | the temple ruin on its levelled site; `auto` picks a stepped style by seed; `ruinField` is a collapsed, overgrown ruined city instead of a pyramid (a half-buried two-terrace mound with a small shrine on top as the summit, a colonnade of standing and toppled columns, broken-walled rooms, a half-buried giant head), standing under the closed canopy with no view cut through it |
| `clearing` | true/false | the open clearing: with a temple, the ruined city's paved plaza in front of its stairs; without one, a glade on the near bank |
| `look` | `auto`, `real`, `painted`, `toon`, `lowpoly`, `pixel` | how every prop is drawn; `auto` follows the world look (jungleMaterials' JungleLook, the same switch as tropicalKit's) |
| `seed` | any whole number | each seed is a different jungle; the same seed is always the same one |
| `quality` | 0.3–2 | draw distance (the browser caps it at 0.6); placement never changes |
| `spawnAtTrailhead` | true/false | move the scene's PlayerSpawns to the trailhead (while the jungle builds in play, this machine's player waits on a landing at the trailhead) |
| `atmosphere` | true/false | when the scene has no `JungleAtmosphere`, the Jungle adds one by itself (light, haze, air, showers, ambience, footsteps, and in play a shared clock starting at dusk); one the scene has always wins (default true) |
| `route`, `routeGuide` | true/false | sign the walk with carved signposts and trail markers; show each player an on-screen guide to the next stop (see *The signed route*) |
| `climbing` | true/false | give every player body climbKit's ClimbMover |
| `emergentKinds`, `canopyKinds`, `understoryKinds`, `riversideKinds`, `floorKinds`, `clearingKinds`, `rootKinds`, `vineKinds`, `epiphyteKinds`, `fungusKinds`, `rockKinds`, `riverRockKinds`, `cliffKinds`, `logKinds` | comma lists of jungleProps kinds | replace one layer's kinds for every jungle type: `canopyKinds = "canopyFig"` makes the whole canopy figs |
Every layer's kinds per jungle type live in one table, `JungleKinds.MIX`; `JungleKinds.STANDIN` says which existing kind stands in for one jungleProps does not have yet.
One setting swaps the river's shape (the same seed keeps the rest of the jungle's plan):
```luau
entity.find("Jungle").component.get("jungleKit.Jungle").riverShape = "gorge" -- "meander" | "rapids" | "lake" | "gorge"
```
## Examples
```luau
-- a misty cloud forest, thick with moss and orchids, a khmer temple
entity.spawn("Jungle").component.add("jungleKit.Jungle", { size = 500, jungleType = "cloud", density = "lush", templeStyle = "khmer", seed = 21 })
-- a small temple grove level: no river, just the plateau, the clearing and the ruin
entity.spawn("Jungle").component.add("jungleKit.Jungle", { size = 200, jungleType = "templeGrove", river = false, seed = 3 })
-- a bamboo valley: every understory plant is bamboo
entity.spawn("Jungle").component.add("jungleKit.Jungle", { jungleType = "monsoon", understoryKinds = "bambooClump", seed = 9 })
```
## Ask the jungle about itself
```luau
local Site = require("jungleKit.JungleSite")
local site = Site.current() -- the jungle built on this machine (nil until built)
site:heightAt(x, z) -- the same heights the terrain stands
site:footstepAt(x, z, y) -- mud | leaves | stone | wood | water | moss | gravel
site:surfaceAt(x, z) -- the painted layer (jungleSoil, leafLitter, mossGround, mudRiverbank, gravelRiver, sandRiver, rockWetDark, templeFloorStones)
site:waterDepthAt(x, z), site:waterLevelAt(x, z), site:riverDistance(x, z), site:waterfallDistance(x, z), site:pathDistance(x, z)
for _, p in site.pois do print(p.id, p.name, p.x, p.y, p.z) end -- spawn, clearing, riverbank, waterfall, plungePool, bridge, temple (the outer ruins), templeStairs, templeTop
site.paths, site.canopyGaps, site.fireflyZones -- the walk; where light shafts fall; where fireflies gather at night
site.glowSpots -- { x, y, z, count }: one per glowing fungus group (the night glow lights stand at the nearest)
```
`JungleBuilder.planFor(settings)` answers the same pois and paths without building anything; `JungleBuilder.spawnPoint(settings)` the trailhead.
## Playing it
- The river's shallow edges wade; its middle and the plunge pool are deeper than chest height, and a player who walks in past **1.45 m** of water is set back where it was last 1 m deep (`JungleBuilder.WADE_STOP`, `WADE_SAFE`). A player who ends up under the ground is put back on top.
- **Climbable roots.** Every emergent giant's plank buttresses (kapok, dipterocarp, strangler fig lattice), wherever it stands, and the canopy figs', stilt and surface roots within `JungleBuilder.CLIMB_RANGE` (70 m) of a footpath carry `climbable = true` for climbKit, as do the temple's tiers and the waterfall's rock. Walk into a fin's flank holding forward: you start climbing after 0.3 s, and climbing past the top pulls you onto it (the fins' solid tops are flat and stepped, see jungleProps README "Colliders"). A buttress fin whose reach would cross the walk is left out so it never blocks the footpath; the trunk stays solid.
- **Solid rocks and logs.** Every scattered rock, cliff, log and stump has its collider at any distance from the path, and a rock's solid surface is its drawn surface (body and moss, within a few cm), so you stand on top of the boulder you see. Trunks are solid; the ground is the terrain. Every collider carries `jungleSurface` for footsteps.
- `JungleWanderers` (fields `count`, `style`, `rest`, `spacing`, `cellSize`): in play, every peer bakes a navKit multi-level map over the walk (the bridge deck over the river and the temple stairs included) with the river and pool fenced off; the host spawns synced NavAgents that walk trailhead → riverbank → bridge → temple ruins → clearing → temple (and up its stairs) and back, resting at each stop. Late joiners see the same villagers; if the host leaves, whoever navKit hands them to carries on from the nearest stop.
## Every player, the same jungle
Heights come from integer-hash noise and + − × ÷ and square roots only (JungleNoise), so they are bit-identical on every machine; the river, the walk and every placement are pure functions of those numbers and the seed (hash tables are never iterated where order matters). `jungle.stats.fingerprint` (from the Jungle component's `:jungle()`) is `<props>-<ground>`: a code of every placed instance and liana, and of the ground heights, pois and paths. Equal fingerprints mean the same jungle. The test suite builds the same settings twice and checks the codes match, and that seed, type and density changes give different ones (density changes only the props).
## The signed route
With `route = true` (the default) the walk is signed from start to end, so a player can follow it without a map. The stops, in order: **Trailhead → Riverbank → The Falls** (a short spur along the bank to the edge of the misty plunge pool) **→ Rope Bridge → Temple Ruins** (broken walls, a stela, snapped pillars and fallen blocks where the walk comes off the bridge) **→ The Clearing** (the ruined city's paved plaza in front of the temple) **→ Temple Summit** (up the temple stairs, on the top terrace outside the shrine door, looking out over the canopy). A jungle with no temple keeps the clearing as a glade on the near bank and walks it before the river.
**Over the canopy.** On jungles of 400 m and more the temple has five tiers (four from 280 m, three below, so a small site still fits; `JungleLayout.tiersFor`), and no canopy crown anywhere in the jungle rises above a line just under the summit's eye that climbs gently with distance (`JungleRules.TEMPLE_VIEW`); only scattered emergent giants farther than 230 m stand out of the canopy, the way they do around real jungle temples. The tiers collide as solid boxes, so the stairs walk straight up and the tier faces climb with climbKit.
- **Signposts:** a carved wooden signpost stands beside the path at every stop, facing it: the stop's name on a board and arrows to the next and the previous stop (the riverbank's sign also points to the falls), lettered on both faces. They are jungleProps' `TrailSign` built from the baked kinds `trailSignpost`, `trailSignBoard` and `trailSignArrow` (three variants each, every look).
- **Trail markers** every 22 m beside the path between stops: carved posts with an ochre band and a chevron blaze on the forest floor (`trailMarkerPost`), stone cairns on rock, gravel and sand (`trailCairn`), red rope-and-flag poles at the rope bridge and the temple (`trailFlag`).
- **The guide** (`routeGuide = true`): navUiKit's HUD for this machine's player only: one arrow at the top of the screen pointing at the next stop with its name and distance, a light beam on it, a one-line tracker ("Next: The Clearing"), and a toast at each stop. A stop counts as reached within 9 m (the summit within 7 m and on its floor); reaching a later stop first skips ahead. It needs no input, so it works the same on keyboard, gamepad and touch, and every player in a multiplayer game follows their own progress.
```luau
local Route = require("jungleKit.JungleRoute")
local r = Route.layout(require("jungleKit.JungleSite").current()) -- r.stops, r.signs, r.markers (the same on every machine)
print(Route.fingerprint(r))
local j = jungleComponent:jungle(); print(j.guide and j.guide:state().nextName) -- this player's next stop
```
Checked by walking it as the player with inputSim (walking, 500 m lowland seed 7, quality 1, 2026-11-14, jungleKit 1.1.2): trailhead at t = 0 s, the riverbank at 163 s, the falls (on the dry bank, 1.5 m before the water) at 173 s, back along the bank and the bridge at 260 s, across the deck, the temple ruins at 277 s, the clearing at 297 s, then up the stairs to the summit terrace outside the shrine door at 355 s, the guide counting 6 of 6 stops.
**A walker on its own, river to temple.** A navKit agent (style `walker`, on the villagers' `jungleWalk` map) sent from the riverbank stop to the temple stop walks the trail, crosses the rope bridge on a walked link and arrives **0.25 m** from the temple stop after **62 s** (measured 2026-11-15, the Emerald Falls seed; a second run took 64 s). The baked map is not one piece along the walk: the bridge deck is not on it, the two landings and the bench off the far landing come out as separate islands, and the bake leaves the odd seam (one crosses the trail 1 m short of the near bridge end). Before 1.1.7 that seam stopped a walker about 18 m short of the temple, near the bridge end, as "unreachable". Now, when `JungleWanderers` bakes, it plans between every pair of consecutive route waypoints (about 6 m apart, the deck included) and from each stop to the walk, and wherever navKit's answer is not "ok" (a "partial" plan only gets as close as it can) it adds a short walked link across the break. A waypoint whose nearest map point lies more than 1.5 m below it (the hollow under the far landing) is not aimed at; the villagers cross it on the link. The four villagers watched for 90 s in play: always moving, arriving or briefly planning, never unreachable.
## Never freezing the game
Everything heavy runs in slices: the ground grid, the river's distance field, the plan and footpath routing (a heap A*), the paint, the scatter, building the instanced draws and far-canopy tiles, the colliders (one compound per surface per 32 m chunk), the temple, the route, the fingerprints and the villagers' nav bake. A slice gives the frame back once it has done `JungleNoise.BUDGET_PLAY_MS` (5 ms) of work in play or `BUDGET_EDIT_MS` (12 ms) in the editor, **or once it has allocated `ALLOC_PLAY_KB` (512 KB) / `ALLOC_EDIT_KB` (1 MB) of Luau heap**. The allocation budget matters as much as the time budget: the Luau collector pays for what a frame allocates, and a slice that allocated several MB in one frame got a 50 to 260 ms collector stall at a 450 MB heap, while one that allocated about 1 MB stayed under 5 ms (measured with a 64-allocation loop, 2026-11-14). `jungle.stats.longestSliceMs` and `longestSliceAt` report the longest stretch between two yields and the first caller outside JungleNoise that ended it.
Measured for the showcase (500 m lowland, seed 7, 2026-11-14), `longestSliceMs`:
| build | before | after |
|---|---|---|
| editor rebuild | 176 to 509 ms (collector stalls landing in the plan, the river field and `groundPrint`) | 25 to 30 ms (the rope bridge's component add) |
| play, the build at play start | not measured | 57.6 ms |
| play, a rebuild | not measured | 21 ms |
What still runs over the budget is one engine call each, which a yield cannot cut (Emerald Falls issue #6): one temple piece's prop add (14 to 20 ms in the editor, 57.6 ms once at play start), the rope bridge component add (21 to 30 ms), one route signpost with its lettering (12 to 18 ms) and one far-canopy tile mesh (15 to 19 ms). A whole build takes about 8.5 s in the editor, 15 s for a rebuild in play and about 30 s at play start (sharing the frames with everything else that starts).
- **Terrain:** adding the saved ground to the scene is one engine load (290 to 440 ms measured earlier), and cooking a new setting's ground is one engine terrain write (1.7 to 4.3 s measured earlier, editor only). Cook every setting in the editor before you publish. Put the ground in the scene yourself and the load happens with the scene instead of mid-build; the Jungle adopts a Terrain that shows its ground (the showcase does this):
```luau
entity.spawn("JungleGround").component.add("Terrain", { terrain = require("jungleKit.JungleBuilder").groundAsset(JUNGLE) })
```
- **Spawn point:** `JungleBuilder.spawnPoint(settings)` reads the trailhead saved beside the cooked ground (`jungles/<key>.spawn.txt`, written by every editor build), so calling it from a scene build does not plan the whole walk in one frame.
- **Rebuilds:** the old jungle is torn down before the new one starts building (one teardown, about 120 ms, issue #2), so two jungles are never held at once.
- **Villagers:** the rope bridge's deck, the bridge landings and the temple summit are not joined on the villagers' baked nav map, so `JungleWanderers` checks the walk with a plan between each pair of route waypoints when it bakes, and joins every break with a walked navKit link (ramps over the deck and the breaks, stairs up the front of the temple). Without them every villager plan to the far bank or the summit searched the whole 42,661-node map and failed, a 1 to 2 s freeze each time (measured 1,005 to 2,139 ms in play, several a minute). With them, 44 plans in 90 s took at most 7 ms.
- **Temple stairs:** each flight's walkable ramp is a one-sided surface, and a sprinting player pushed between two flights could slip under the next flight's lower edge and wedge inside the pyramid. jungleProps 1.0.9 fills the space under every ramp with solid slices (just below the walking surface) and a slab over the landing strip. Eight climbs from the foot (four walking, 34 to 50 s, four sprinting, 13 to 15 s) all reached the summit with no stalls, and two full walks of the signed route from the trailhead in a row both reached 6 of 6 stops (169 s and 221 s; the first caught once for 3 s where the path drops off the far bridge landing and freed itself).
## What is inside
- **Jungle** (component), **JungleBuilder** (`build`, `planFor`, `spawnPoint`, `keyFor`, `:destroy`): build and tear down a jungle.
- **JungleField**, **JungleNoise**: the land as numbers (four relief types, the river with falling levels, the escarpment, plunge pool and gorge); deterministic noise and the frame budget.
- **JungleGround**: heights on the CPU, pads and path benches, the eight painted surfaces, the terrain write.
- **JungleLayout**: the walk, the pads, the bridge and temple sites, path covers, canopy gaps, firefly zones.
- **JungleKinds**: which kinds grow in each layer of each type, overrides and stand-ins. **JungleRules**: the layered placement. **JungleRender**: instanced draws with three levels of detail, lianas between trees.
- **JungleWater**: river ribbons, the plunge pool, the waterfall sheet and foam (jungleMaterials `riverWater`, `plungePool`, `waterfallSheet`, `riverFoam`).
- **JungleSite**: questions about the ground. **JungleWanderers** (component): navKit villagers on the trail.
- **JungleGoal** (component): a goal at any stop (the temple summit by default) in one line, per player. **JungleHud**: where an own message goes clear of the route guide and the time-and-weather panel, and a one-call message box.
- Tests: `tests/jungleKit.testSuite`.
## Time, weather and sound
Add one **JungleAtmosphere** next to the Jungle, and worldClockKit's shared clock if the scene has none. The weather is **Cloudburst's**: the atmosphere adds a synced `Weather` entity with a `Cloudburst` component in play when the scene has none (or put your own in, with any preset), and turns the clock's own rain, lightning and weather sound off so there is only one rain:
```luau
-- the shared clock: ONE per scene, on a synced entity, lit with the jungle sky look
entity.spawnSynced("WorldClock").component.add("WorldClock", { dayLengthMinutes = 24, startHour = 7, sky = "jungle",
precipitation = false, lightning = false, sound = false, autoWeather = false })
-- the weather (optional: added in play when missing); the kit's weathers drive it
entity.spawnSynced("Weather").component.add("Cloudburst", { preset = "", kind = "clear" })
-- light, air, weather and sound on every machine (jungleType "auto" follows the Jungle)
entity.spawn("JungleAtmosphere").component.add("jungleKit.JungleAtmosphere", { rainEveryMinutes = 9 })
```
Change it for every player from any script or the console:
```luau
local Atmos = require("jungleKit.Atmos")
Atmos.setTime("dawn") -- "dawn" | "day" | "dusk" | "night"; { hold = true } stops the clock there
Atmos.setWeather("downpour") -- "clear" | "rain" | "downpour", or any Cloudburst preset (fades over 8 s)
Atmos.shower({ duration = 60 }) -- a passing shower that clears by itself ({ heavy = true } pours)
print(Atmos.timeOfDay(), Atmos.weather(), Atmos.rainAmount())
```
What each time looks like (every jungle type reshapes it):
| | light and air | sound |
|---|---|---|
| **dawn** | low golden sun, golden ground mist drifting through the trunks, long slanting shafts | the dawn chorus, howler monkeys far off |
| **day** | green-filtered light under the canopy, bright sunlit gaps and shafts over the clearing, the river and the pool, light humid haze | birds and insects, cicadas swelling, toucans and hornbills |
| **dusk** | amber light low through the trunks, violet shade, the first fireflies | cicadas giving way to frogs |
| **night** | deep blue moonlight, hundreds of fireflies drifting over the clearing, the riverbank, the pool and the temple, groups of glowing green mushrooms and brackets on mossy logs, stumps and tree feet beside the walk (a hero log heavy with them on the clearing's edge), each lighting the bark and litter round it | tree frogs, crickets and katydids |
| **rain / downpour** | grey-green flat light, the haze closes in, no shafts; Cloudburst's rain (a 0.6 tropical shower with misty splashes, or its `tropical_downpour`) stopping on the canopy, drips falling from the leaves, splashes on the river and the pool, wet shining leaves | Cloudburst's rain, muffled under cover; the broad leaves dripping on after it |
- **Jungle types:** `lowland` as above; `cloud` thick drifting mist all day and soft light; `monsoon` heavy humid haze and rain twice as often; `templeGrove` golden shafts.
- **Moods:** JungleAtmosphere's `mood` holds one look over every hour, on top of the jungle type. `auto` (the default) is everything above, unchanged. `mist`: low heavy fog in the forest and over the water, soft shadowless light (Cloudburst's mist with a valley fog bank). `storm`: a dark sky and Cloudburst's thunderstorm, pouring rain, lightning and thunder, gusts. `golden`: warm low-sun haze and strong golden shafts (best at dawn or dusk; the mood does not move the clock). `steamy`: humid haze after rain, steam off the ground and the river, wet shining leaves. A mood holds its weather, so the timed showers stop while it is on; back on `auto` the weather clears and the showers return:
```luau
entity.find("JungleAtmosphere").component.get("jungleKit.JungleAtmosphere").mood = "storm" -- "auto" | "mist" | "storm" | "golden" | "steamy"
```
- **Everywhere:** mist rising off the river banks and the plunge pool, spray and mist thrown up where the falls land. The river bed is loud by the water and fades away from it; the waterfall roars near the falls and drowns the forest there.
- **Footsteps** for every walker (players, NPCs, the trail's villagers): squelching mud on the banks, crunchy leaf litter, soft moss, wet stone on the temple and rocks, gravel in the river bed, hollow planks on the bridge, a splash when wading. Tag any collider with the attribute `jungleSurface` (`"mud"`, `"leaves"`, `"moss"`, `"stone"`, `"gravel"`, `"wood"`, `"water"`, or `"ground"` to read the jungle there); it counts for its children too. `require("jungleKit.Footsteps").give(npc, "barefoot")` gives any other walker jungle steps.
`JungleAtmosphere` fields: `jungleType` (auto), `mood` (auto), `clock`, `startTime`, `holdTime`, `grade`, `haze`, `air`, `airQuality` (sprite and shaft counts, 0.2-2; the browser caps it at 0.6), `glow`, `volumetric` (the engine's ray-marched shafts, off by default for the web), `ambience`, `ambienceVolume`, `footsteps`, `rainEveryMinutes` (0 = only when you call it), `downpourShare`.
**Hold the clock at a time of day.** A Jungle adds a JungleAtmosphere by itself when the scene has none (its `atmosphere` field), with a shared clock starting at dusk (`Atmos.SHOWCASE_TIME`); one the scene has always wins. `clock` (default true) adds worldClockKit's shared clock in play when the scene has none; `startTime` (`auto`, `dawn`, `day`, `dusk`, `night`; `auto` leaves a scene's own clock alone and starts one the kit adds at dusk) sets the clock for everyone at play start; `holdTime` pauses it there (the weather still comes and goes). The logic is `Atmos.startClock`. With your own `WorldClock`, its `startHour` and `paused` hold it the same way; while playing, `Atmos.setTime("night", { hold = true })` jumps and holds, `{ hold = false }` runs it again.
```luau
-- dusk for everyone, held there, a shower every 5 minutes, a fifth of them downpours
entity.spawn("JungleAtmosphere").component.add("jungleKit.JungleAtmosphere", { startTime = "dusk", holdTime = true, rainEveryMinutes = 5, downpourShare = 0.2 })
```
**How often it rains:** `rainEveryMinutes` (default 9 minutes of shared time; a monsoon jungle rains twice as often; 0 = only when a script calls `Atmos.shower` or `Atmos.setWeather`) and `downpourShare` (default 0.35, 0 to 1).
How it is built: the grade is jungleKit's own `shaders/jungleGrade` (brightness, saturation and contrast like the engine's colorGrade, plus a `shadow` toe so shade keeps its detail instead of crushing to black) and two of the engine's post passes (tint, vignette); the haze goes into worldClockKit's fog through its director, so there is one fog writer; the sky is a `jungle` look defined on worldClockKit; the weather is Cloudburst's (`Atmos.WEATHERS` maps clear, rain and downpour to Cloudburst settings, and `rainAmount` / `wetness` read `cloudburst.weather.now()`). Fireflies, spray and mist puffs are each one mesh animated on the GPU by `shaders/jungleAir` (one draw a layer, no per-frame CPU); shafts and mist banks are jungleMaterials' `lightShaft` and `mistCard` cards at the site's `canopyGaps` and along its river. At quality 1 a 400 m lowland jungle draws about 400 fireflies, 360 spray drops and a few dozen shafts. The fungus glow is `jungleMaterials.JungleMaterials.setNightGlow`. Sound is soundstage beds and 3D calls, all generated for this package (`audio/`: 7 loop-clean beds, 5 calls, 15 footstep takes). Modules: **Atmos**, **JungleAir**, **Ambience**, **Footsteps**; tests: `tests/atmos.testSuite`.
## Time and weather panel, prop gallery
**JungleControls** puts a "Time & Weather" button at the bottom left of every player's screen; it, T on a keyboard or Select on a gamepad (the `toggle` control of `jungleKit.controls`) opens a panel with Dawn, Day, Dusk, Night and Clear, Rain, Downpour, styled after the route guide's HUD (navUiKit's fantasy theme). Each press goes through `Atmos.setTime` / `setWeather`, so it changes worldClockKit's shared clock and weather for everyone. In play the mouse is freed while it is open; on a pad the d-pad walks the buttons, South presses, East closes. Fields: `inputMap`, `keyLabel`, `startOpen`, `showInEditor`, `clockRunning`; `press("time:night")` and `isOpen()` from code.
```luau
entity.spawn("JungleControls").component.add("jungleKit.JungleControls", {})
```
The showcase also stands jungleProps' **PropGallery** on a stone terrace past the jungle's south edge, below the trailhead: all 90 kinds, every variant, in all five looks (1,300 props), labelled, the real look nearest the jungle. Giants are scaled to fit 4 m cells (`maxSize = 4`, labelled with the scale), props pick their level of detail by screen size, and each look band stands only while someone is within 30 m of it (`buildWithin = 30`), so nothing stands at the trailhead (about 48 m away) and standing on the terrace keeps two of the five bands up.
## Performance
Measured on 2026-11-14 in play in the native desktop dev build (Luau codegen on, drawn at 1920x1080, 60 Hz pace) on a shared Linux machine (4 cores, other engines running, about 1 to 2% of each frame spent waiting for a core). The showcase settings: 500 m lowland, normal density, seed 7, with **JungleAtmosphere on** (grade, tint, vignette, haze and air) and the four villagers walking. The camera stood where a player's third-person camera stands (1.7 m eye plus 2.2 m up, 4.5 m behind) at each spot, facing down the trail. At each spot the scene settled for 10 s, then `profiler.cost` measured 12 s (636 to 696 frames) standing still. Quality is the Jungle's draw-reach quality (`jungle:setQuality`); 0.6 is the browser cap, used here as a stand-in.
| spot | quality 1: mean / p95 / p99 (ms) | quality 0.6: mean / p95 / p99 (ms) | engine CPU mean q1 / q0.6 (ms) |
|---|---|---|---|
| trailhead | 17.5 / 28.4 / 41.3 | 17.6 / 26.3 / 68.6 | 12.6 / 11.3 |
| clearing | 17.9 / 28.1 / 65.7 | 17.3 / 26.3 / 70.3 | 12.7 / 11.2 |
| rope bridge | 18.9 / 29.7 / 73.9 | 18.1 / 27.8 / 74.7 | 13.4 / 11.5 |
| temple summit | 17.2 / 25.8 / 66.0 | 17.6 / 25.9 / 70.7 | 11.0 / 11.1 |
The p50 was 16.0 to 16.8 ms everywhere (the 60 Hz pace). The worst frame in a 20 s profiler ring window was 119 ms. Own GPU time was about 1.6 ms a frame. Before the villagers' nav links (same day, same spots), means were 17.5 to 31.3 ms with p99 up to 1,033 ms: each villager plan to the far bank or the summit froze a frame for 1 to 2 s (see *Never freezing the game*). The person's earlier reading (28 ms mean, 58 ms spikes) matches that state.
What the spikes are now (`profiler.retro`, 20 s, issue #5): about 50 frames of engine cluster registration at 27 to 36 ms (`slot_clusters`, it grows with the clusters drawn), about 21 frames of Luau collector steps at 60 to 86 ms (every script's worst update lands on the same frames; the Luau heap is about 590 MB in play), and a few engine texture-streaming frames at 68 to 82 ms.
- **Draws:** the jungle registers 1,035 instanced draws (three levels of detail for each part of each of 175 kind groups) holding 90,208 instances; that is the figure behind "about 1,000 draws". What the GPU draws a frame is far less, because empty levels are hidden and the cluster renderer batches the rest: at the trailhead (quality 1) 75 draw calls, 24 instanced draws, 3,797 clusters and 317,000 triangles, with 8,530 instances tested by the cull; at the temple summit (quality 0.6) 81 draw calls, 43 instanced draws, 3,359 clusters, 255,000 triangles. The renderer refreshes these counts only on a frame that draws a capture, so they were read right after a capture. Beyond the canopy's reach 64 far-canopy tiles (37,920 triangles) stand in for the trees, plus 7 signposts and 20 trail markers.
- **What is drawn at each level of detail, live:** `jungleComponent:status().drawn` answers `{ near, middle, far, liveDraws, byCategory, farTiles }` for wherever the camera stands right now (`byCategory` gives every category's near / middle / far copies; `nil` while the jungle is still building, so ask once `status().built` is true). Read on 2026-11-14 from the editor camera on the showcase jungle: **263 near, 991 middle, 2,399 far, through 714 live draws**. The far tiles' crowns are a core lobe and four leaf clumps each, shaded apart so they read as leafy canopy from a distance (223,500 triangles over all tiles).
- **Memory:** in play the editor process held 5.93 GB private (6.11 GB resident, 6.83 GB peak after several rebuilds); most of that is the editor itself (asset index, sources, allocator reserve). Graphics memory was 2.09 GB in all: 359 MB instance buffers, 235 MB cluster cull lists, 165 MB geometry, 168 MB textures, 872 MB the driver's own. The Luau heap was 445 MB in the editor and 590 MB in play; the jungle itself holds 67 MB of it (50 MB of that is the 90,208 instance records).
- **Build:** see *Never freezing the game*.
- **Route guide:** navUiKit's HUD measured about 0.4 ms of script a frame here (`profiler.scripts`); the route adds a check of the player's position four times a second.
- **Walking (2026-11-15):** profiler ring over 35 s of walking the signed route: p50 16.4, p99 78.9, worst 160.8 ms, 104 frames of 1,826 at 33 ms or more (66 of them Luau collector steps landing in whichever script allocated, 23 GPU waits, 13 texture streaming). Standing at the trailhead: p50 16.1, p99 33.2, worst 86.8 ms, 15 of 1,493 frames over 33 ms. The Luau heap took about 15 MB a second of new garbage standing still. What the jungle itself added and no longer does: every JungleProp (186 in the showcase) asked `camera.viewData()` and read its own position and scale on its level-of-detail test, about 48 KB a frame (3 MB a second), now one shared `viewData` a frame and a pose read every 3 s in play (0 KB a frame measured); and each 3 m walked, the level-of-detail re-sort built a joined string of every level's chunk list and a string copy of each new transform buffer, about 600 KB per re-sort, now compared in place and written straight from the buffer. The garbage left is mostly other packages' per-frame work (Cloudburst about 20 KB a frame, worldClockKit about 15 KB, soundstage about 5 KB) and the engine's own; JungleAtmosphere's blend (Atmos, Ambience) is about 10 KB a frame. A clean after-walk could not be measured: the shared machine kept rebuilding the scene in play (other sessions changing the player prototype), so no jungle stayed built long enough to walk.
- **Not measured:** a browser. No browser client can run on the machine this was measured on, so quality 0.6 on the desktop is the closest stand-in (issue #4).
## Known limits
Each limit links the open issue it is tracked in: jungleKit's own on this world's tracker (Emerald Falls, read one with `zero zeromind viewIssue 8dfefcb6-4b09-439c-9f01-e8525ed36695 <number>`), the others upstream.
- **Frame spikes in play:** standing still, about 2 to 3 frames a second run 27 to 36 ms (engine cluster registration) and about 1 a second runs 60 to 86 ms (Luau collector steps at a 590 MB heap), so p99 is 41 to 75 ms while the mean is 17 to 19 ms. Walking the route (2026-11-15) the p99 was 79 ms with about 3 frames a second over 33 ms, most of them collector steps paid for by every script's garbage together (see *Performance*, walking). Emerald Falls issue #5.
- **A few build frames run over the slice budget:** one engine call each (a temple piece up to 58 ms, the rope bridge 21 to 30 ms, a signpost 12 to 18 ms, a far-canopy tile 15 to 19 ms) cannot be cut by a yield. Emerald Falls issue #6.
- **The engine terrain load and terrain write each run in one frame** (290 to 440 ms, and 1.7 to 4.3 s for a first cook). Cook in the editor before publishing and put the ground in the scene (see *Never freezing the game*). If a setting changes while playing, the Jungle rebuilds and cooks during play. Emerald Falls issue #1.
- **A rebuild tears the old jungle down in one frame** (about 120 ms) before the sliced build starts. Emerald Falls issue #2.
- **Stepping off the gorge edge beside the rope bridge leaves the player stuck** in the gorge (the deck has guard walls; the bank beside it does not). Emerald Falls issue #3.
- **Not checked in a browser:** neither whether the browser builds the same jungle from the same seed nor how smoothly it runs there has been checked, because no browser client can run on the machine this kit was built and tested on. What is checked is the native desktop: the same settings and seed gave the same fingerprint in two separate desktop processes, and the kit's `determinism` test pins those fingerprints, so running jungleKit's tests in the browser editor answers the first question (that test fails if the browser builds a different jungle). The quality 0.6 column in *Performance* is the desktop at the browser's draw reach, not a browser measurement. Emerald Falls issue #4; an agent cannot start a browser build itself, [OrigoZero/zero#20946](https://github.com/OrigoZero/zero/issues/20946).
- **The terrain paints from above**, so the escarpment's and gorge's steep faces stretch their texture; cliff-face props stand along steep ground to cover most of it. Emerald Falls issue #7.
- **The nav map is baked on every peer when play starts** (a second or two, sliced), not saved with the ground; navKit's spread grid bake hitches. navKit issue #2 on the Pathwise world's tracker.
- **Two editors on one account count as one player**: test multiplayer (and the per-player route guide) with two accounts. [OrigoZero/zero#14448](https://github.com/OrigoZero/zero/issues/14448)
- The forest-floor techniques the kit borrows from forestKit carry its open issue #3 on the Beechwood Brook tracker.
## Built on
jungleKit and the two jungle packages it brings reuse these installed packages instead of carrying copies of them. Scores are from [reuse-review.md](../reuse-review.md), which says per package what worked, what broke and what was filed upstream (ZeroMind takes no rating from this account for them: they share its owner).
| Dependency | Version | What it gives the kit | Rating |
|---|---|---|---|
| jungleProps | 1.1.1 | every tree, plant, rock, log, temple piece and the rope bridge (own package) | not rated (ours) |
| jungleMaterials | 1.0.8 | every jungle surface and terrain layer in five looks (own package) | not rated (ours) |
| tropicalKit | 1.1.2 | the deterministic noise (`IslandNoise`) under the ground and placement; the kit's structure follows it | 3 / 5 |
| tropicalProps | 1.0.3 | (through jungleProps) the bake-time mesh kits `VegGeo` (plants) and `ShoreGeo` (rocks, logs, temple, bridge) | 4 / 5 |
| desertProps | 1.0.6 | (through jungleProps) the signed-distance sculpting kit `RockGeo` for river rocks, logs and temple carvings | 4 / 5 |
| tropicalMaterials | 1.0.3 | (through jungleMaterials) the world-wide look switch, shaders and CardBaker | 4.5 / 5 |
| materialLibraryKit | 1.4.3 | (through jungleMaterials) the material library and collection format the material collections are read through | 3.5 / 5 |
| groundMaterials, stoneMaterials, woodsMaterials, organicMaterials, animatedMaterials | 1.0.8, 1.2.1, 1.0.2, 1.0.8, 1.0.16 | (through jungleMaterials) soil, mud, moss, gravel, stone, bark, planks, bamboo, fungi and the animated river water | 4.5, 4, 4.5, 4, 4.5 / 5 |
| weatheringMaterials | 1.0.11 | installed in this world and reviewed, but not used by the kit: it offers only overlays and decals, and jungleMaterials needed base surfaces | 3.5 / 5 |
| cloudburst | 1.4.5 | the rain: drops, drips from the leaves, splashes on the water, rain sound and wet ground (the kit's own rain drawing was handed to it in 1.1.0) | not rated (ours) |
| worldClockKit | 1.6.8 | the shared clock, sky and fog director the atmosphere runs on (its own rain is turned off), and `Clock.hourForSolar` for the dawn and dusk presets | 4 / 5 |
| soundstage | 2.1.3 | ambience beds, 3D calls and footsteps per surface | 4 / 5 |
| navKit | 1.4.9 | the nav map and the villagers walking the trail | 4 / 5 |
| navUiKit | 1.3.8 | the signposted route guide | 4 / 5 |
| climbKit | 1.1.10 | `ClimbMover` on every player body (`climbing = true`): pull up onto buttress roots and temple tiers | 4.5 / 5 |
## Guides
- **How do I add a jungle with a river and waterfall to my world?** (`guides/how-do-i-add-a-jungle-with-a-river-and-waterfall-to-my-world.guide`): installing jungleKit, the one-line start and which size, type and seed for a small or big level, your own player at the trailhead, the Jungle component and every setting, the four jungle types and three temple styles, the world-wide look, single props and materials, time of day (and holding it), how often it rains, ambience and footsteps, villagers, climbing, JungleSite, a summit goal, where to put your own messages on screen, multiplayer, building in the editor before publishing, performance.
- **Make a small jungle grove level with temple ruins** (`guides/make-a-small-jungle-grove-level-with-temple-ruins.guide`): step by step from an empty world to a 200 m temple grove level with a signed trail, your own player at the trailhead, the clock held at dusk, rain every few minutes, villagers, a one-line goal at the top of the temple (and how to write it yourself), and where your own messages go on screen.
# jungleMaterials: Emerald Falls rainforest surfaces
**Every surface of a tropical rainforest behind one name, in five looks (real, painted, toon, lowpoly, pixel): 75 named surfaces: 38 shipped as the package's own generated materials (jungle leaf cards, kapok / fig / dipterocarp / tree-fern bark, temple and carved glyph stone, fungi, petals), 16 borrowed from installed collections, and 21 built at runtime (wet and tinted variants, the animated river, waterfall, foam, mist, light shafts, fireflies, glowing fungus and the far-canopy crown blob).** `JungleMaterials.get("leafMonstera", { look = "toon" })` returns a material you put straight on a `Model` or an instanced draw, `JungleMaterials.terrainLayer("leafLitter")` returns a layer record for the engine terrain, and `JungleMaterials.setNightGlow(1)` lights the glowing fungi and fireflies at night.
**Install and use:** install jungleMaterials from ZeroMind. It brings tropicalMaterials (whose look switch and shaders it shares), Terra Firma (groundMaterials), Bedrock (stoneMaterials), Heartwood (woodsMaterials), Scale and Feather (organicMaterials), Flux and Flicker (animatedMaterials) and the materialLibraryKit core. Then `require("jungleMaterials.JungleMaterials")` and ask for a surface by name and look. A `JungleLookSetting` component switches every jungle **and** tropical surface between the looks for every player at once. The package works wherever it is installed; nothing in it looks for a fixed path.
**Guides:** "How do I use jungle moss, bark, mud and temple stone materials?" (getting a surface, the five looks, one switch for all, terrain layers, night glow, UV conventions) and "Make a mossy jungle temple corner with leaf litter, mud and glowing fungi" (an empty world to a small terrain patch with a mossy temple block, leaf cards and fungi). Both ship in `guides/`.
## First example
```luau
local JM = require("jungleMaterials.JungleMaterials")
local floor = entity.spawn("Jungle Floor", { temporary = true, components = { Model = {
model = "@builtin::meshes.plane", material = JM.get("leafLitter") } } })
floor.localScale = { 6, 1, 6 }
local block = entity.spawn("Temple Block", { temporary = true, components = { Model = {
model = "@builtin::meshes.cube", material = JM.get("stoneTempleMossy") } } })
block.localPosition = { 0, 0.5, 1 }
local leaf = entity.spawn("Monstera Leaf", { temporary = true, components = { Model = {
model = "@builtin::meshes.plane", material = JM.get("leafMonstera", { look = "toon" }) } } })
leaf.localPosition = { -1.5, 0.8, 0 }
leaf.localRotation = { 0.7071, 0, 0, 0.7071 } -- stood upright, base at the bottom
print(JM.source("barkSmooth")) -- installed:woodsMaterials.materials.beechBark
print(JM.source("leafMonstera")) -- own:leafMonstera
print(JM.source("riverWater")) -- runtime:jungleMaterials:riverWater|real
print(JM.terrainLayer("mudWet").albedo) -- groundMaterials.textures.wetMud_albedo
JM.setNightGlow(1) -- fungusGlow and firefly at full night
```
To see everything: `entity.spawn("Swatches").component.add("jungleMaterials.MaterialGallery", { looks = "all", nightGlow = 0.8 })`.
## API
- `JM.get(surface, { look? }) -> material`, never nil. `look` is `real | painted | toon | lowpoly | pixel`; nil or `"auto"` follows `JungleLook.get()`, an unknown look is `real`, an unknown surface answers a neutral forest floor.
- `JM.surfaces()` (75 names in catalogue order), `JM.group(s)` (`ground | bark | moss | leaf | flower | fungus | rock | temple | wood | water | fx`), `JM.isCard(s)` (alpha-cut two-sided swaying card), `JM.isEffect(s)` (see-through effect card), `JM.palette(s)` (flat lowpoly colour, linear), `JM.source(s, opts)` (`own:`, `installed:`, `runtime:`, `fallback:`), `JM.refresh()`.
- `JM.terrainLayers()` -> `jungleSoil, leafLitter, leafLitterWet, mudRiverbank, mudWet, mossGround, gravelRiver, sandRiver, rockWetDark, templeFloorStones` (a terrain carries at most eight). `JM.terrainLayer(name, look?) -> { name, albedo, normal?, mask?, tiling, tint }`, exactly the record `terrain.write`'s `surfaces` takes; stylised looks hand out baked `terrain_<layer>_<look>_albedo` textures.
- `JM.setNightGlow(0..1)` drives the emissive brightness of `fungusGlow` (pale cap by day, green glow at night) and `firefly` (off by day) in every look, already built or built later; `JM.nightGlow()` reads it.
- `JungleLook` (module) = tropicalMaterials' `TropicalLook`: `set`, `get`, `resolve`, `valid`, `onChanged`, `LOOKS`. `JungleLookSetting` (component): a synced `look` field that calls it on every peer. `MaterialGallery` (component): every surface × look on cards and spheres.
## Every surface
Own = a material this package ships (generated textures). Installed = a collection material used as installed. Runtime = built once per machine from shipped textures. Every surface also has painted, toon, lowpoly and pixel looks.
| Surface | Looks like | Comes from |
|---|---|---|
| **Ground** (uv in metres; ★ = terrain layer) | | |
| `jungleSoil` ★ | dark forest-floor soil with litter | installed: Terra Firma `forestFloor` |
| `leafLitter` ★ | thick layer of big brown, tan and orange decaying tropical leaves | own, 512² tile + terrain mask |
| `leafLitterWet` ★ | the same, rain-dark and glossy | runtime (leafLitter, wetness + clear coat); glossy terrain mask |
| `mudRiverbank` ★ | brown riverbank mud | installed: Terra Firma `mud` |
| `mudWet` ★ | dark wet mud with puddle gloss | installed: Terra Firma `wetMud` |
| `mossGround` ★ | green moss carpet | installed: Terra Firma `moss` |
| `rootMat` | tangle of surface roots over wet soil | own, 512² tile |
| `gravelRiver` ★ | river gravel | installed: Terra Firma `gravel` |
| `sandRiver` ★ | brownish river sand | runtime (Terra Firma `wetSand`, tinted) |
| `rockWetDark` ★ | dark glossy wet rock | runtime (tropicalMaterials `rockWet`, darkened) |
| `templeFloorStones` ★ | worn sandstone paving with moss and soil in the gaps | own, 512² tile + terrain mask |
| **Bark** (u twice round, v = metres / 2) | | |
| `barkKapok` | pale silver-grey kapok bark, shallow fissures, thorn bumps | own, 512² |
| `barkFig` | strangler fig: fused interlaced root strands | own, 512² |
| `barkSmooth` | smooth grey bark | installed: Heartwood `beechBark` |
| `barkDipterocarp` | reddish-grey flaking scaly plates | own, 512² |
| `barkPalm` | ringed palm trunk | installed: tropicalMaterials `palmBark` |
| `barkTreeFern` | dark fibrous tree-fern trunk with frond scars | own, 512² |
| `barkMossy` | bark under moss | installed: Scale and Feather `barkMoss` |
| `barkDead` | silvered dead wood | installed: Heartwood `driftwood` |
| `bamboo` | green-yellow bamboo culm | installed: Heartwood `bamboo` |
| **Moss and organic** | | |
| `mossThick` | thick cushion moss | installed: Terra Firma `moss` |
| `mossHanging` | hanging old-man's-beard strands (card, attached at v = 0) | own card |
| `lichen` | pale grey-green crustose lichen | own, 256² |
| `liana` | twisted woody liana stem | own, 512² |
| `vineStem` | green young vine | runtime (liana, tinted) |
| `rootAerial` | reddish aerial root | runtime (liana, tinted) |
| **Leaves** (cards: v = 0 at the base; crown sprays attach at bottom centre) | | |
| `leafCanopy` / `leafCanopyDark` | twig spray of ~15 glossy drip-tip leaves / the same in deep shade | own card / runtime tint |
| `leafEmergent` | spray of small leathery olive leaves | own card |
| `leafStrangler` | spray of thick glossy fig leaves | own card |
| `leafPalmUnderstory` | understory palm leaflet | runtime (tropicalMaterials `palmFrond`, deeper green) |
| `leafFernFrond` / `leafTreeFern` | sword-fern frond / lacy tree-fern frond | own cards |
| `leafMonstera`, `leafElephantEar`, `leafBanana`, `leafHeliconia`, `leafPhilodendron`, `leafIvy`, `leafBromeliad`, `leafFallen` | split monstera, veined alocasia, wind-torn banana, paddle heliconia, heart philodendron, golden pothos, spiny strap, brown fallen leaf | own cards |
| `grassJungle` | broad-bladed jungle grass tuft | own card |
| **Flowers** | | |
| `petalOrchidPink`, `petalOrchidWhite`, `petalOrchidPurple` | moth-orchid petals | own cards |
| `bractHeliconia`, `petalGinger`, `petalPassion`, `bromeliadBract` | scarlet lobster-claw bract, torch-ginger bract, passion-flower petal with corona, red bromeliad bract | own cards |
| `rafflesiaPetal` | brick-red fleshy petal with cream warts | own, 256² |
| **Fungi** | | |
| `fungusBracket` | banded tan bracket fungus | own, 256² |
| `fungusCap` | tan banded cap | runtime (bracket, tinted) |
| `fungusCapRed` | red, white-spotted cap | installed: Scale and Feather `mushroomCap` |
| `fungusGlow` | bioluminescent cap, green glow driven by `setNightGlow` | runtime (`jungleGlow` shader, every look) |
| `fungusStem` | pale cream fibrous stem | own, 256² |
| **Rock and temple** (1 uv unit = 1 m; temple tiles repeat every 2 m) | | |
| `rockMossy` | moss-covered stone | installed: Bedrock `mossyStone` |
| `rockRiver` | dark wet river boulder | runtime (Bedrock `granite`, wet) |
| `stoneTemple` | weathered grey-ochre Maya limestone blocks | own, 512² |
| `stoneTempleCarved` | carved Maya hieroglyph blocks in deep relief | own, 512² |
| `stoneTempleMossy` | temple blocks with thick moss in the joints | own, 512² |
| `stoneTempleWet` | temple stone, rain-dark and glossy | runtime (stoneTemple, wet) |
| `stoneRubble` | rough stacked stones | installed: Bedrock `dryStoneWall` |
| `stuccoWeathered` | cracked lime stucco with mould and algae | own, 512² |
| **Wood and rope** | | |
| `woodPlankWet` | wet weathered planks | runtime (Heartwood `weatheredPlanks`, wet) |
| `woodPost` | weathered post wood | installed: Heartwood `weatheredPlanks` |
| `ropeJute` | tan twisted rope | installed: tropicalMaterials `rope` |
| `ropeFrayed` | worn, rougher rope | runtime (rope, tinted) |
| **Water and effects** | | |
| `riverWater` | murky green-brown jungle river flowing along +v (uv in metres), ripples and scum streaks | runtime (Flux and Flicker `animWater`, murky style; toon style for stylised looks) |
| `riverFoam` | foam streaks drifting along +v | runtime (`jungleFx`) |
| `waterfallSheet` | white water falling along +v at 4.5 m/s, ragged edges | runtime (`jungleFx`) |
| `plungePool` | deep green clear pool, depth tint, ripples | runtime (tropicalMaterials `tropicalWater`; `animWater` toon for stylised) |
| `mistCard` | drifting soft mist bank | runtime (`jungleFx`, alpha blend) |
| `lightShaft` | god-ray through a canopy gap, v = 0 at the gap, dust motes | runtime (`jungleFx`, additive) |
| `firefly` | pulsing yellow-green glow dot, driven by `setNightGlow` | runtime (`jungleFx`, additive) |
## UV conventions
- **Cards** (leaves, fronds, petals, bracts): one per 0..1 square, u across (midrib at u = 0.5), v = 0 at the stalk, v = 1 at the tip. **Crown sprays** (`leafCanopy`, `leafCanopyDark`, `leafEmergent`, `leafStrangler`): a twig of leaves attached at bottom centre (u 0.5, v 0). **Tufts** (`grassJungle`): v = 0 at the ground. **`mossHanging`**: attached at v = 0, hanging toward v = 1.
- **Vertex colour**: RGB tints. On cards ALPHA is the wind weight (0 rigid base, 1 full sway); on effect cards alpha scales opacity; on `fungusGlow` it weights the glow.
- **Tiles**: ground surfaces repeat every 2 m (temple floor 3 m) when uv is in metres; bark, temple and prop tiles assume 1 uv unit ≈ 1 m.
- **River / pool / foam / waterfall**: uv in metres, flow along +v.
## Looks
Real: tiles on tropicalMaterials' `tropicalSolid` (PBR, wetness film, clear coat), cards on `tropicalFoliage` (alpha cut 0.45, two-sided, light through the leaf, wind sway by vertex alpha). Painted, toon, lowpoly and pixel: runtime materials on `tropicalStylised` from the same textures. The water and effect surfaces and the glowing fungus carry the look in their own shaders (`animWater` style, `jungleFx` and `jungleGlow` `look`). The terrain's stylised looks are baked albedos.
## Texture memory
135 textures, about 20 MB of GPU memory (1 byte a texel, mipmaps included): sixteen 512² / 256² PBR tiles (albedo, normal, rm), 22 cards at 64–256 × 256–512, three terrain masks and 40 small baked terrain-look albedos. `JungleMaterialsBuild.textureMemory()` recounts it; the tests hold it under 32 MB.
## What's in the package
- `JungleMaterials.module` (resolver), `JungleMaterialsTable.module` (generated literal table), `JungleLook.module`, `JungleLookSetting.component`, `MaterialGallery.component`.
- `shaders/`: `jungleFx` (mist, light shaft, firefly, waterfall, foam; procedural, animated, every look), `jungleGlow` (bioluminescent fungus).
- `materials/` (38), `textures/` (135), `jungle.materialCollection` (the 38 in materialLibraryKit's picker), `guides/` (2), `tests/jungleMaterials.testSuite`.
- Authoring: `CardBaker.module` (keys a leaf picture on magenta into a fringe-free cut-out + normal map), `JungleMaterialsBuild.module` (importTile, wetMask, writeMaterials, writeTable, writeCollection, bakeTerrainLooks, textureMemory). Leaf cards were generated with image_gen on a magenta key, tiles with pbr_gen (seamless).
## Depends on
tropicalMaterials 1.0.2, materialLibraryKit 1.4.3, groundMaterials 1.0.8, stoneMaterials 1.2.1, woodsMaterials 1.0.2, organicMaterials 1.0.8, animatedMaterials 1.0.16 (versions in `package.yaml`).