# JungleMaterials
The resolver of the jungleMaterials package: `JM.get(surface, { look })` answers a material for any of the 74 Emerald Falls rainforest surfaces (jungle floor, leaf litter dry and wet, riverbank and wet mud, moss, root mat, river gravel and sand, dark wet rock, temple floor; kapok, fig, dipterocarp, palm, tree-fern, mossy and dead bark and bamboo; moss, hanging moss, lichen, liana, vine stem, aerial root; canopy, emergent and strangler-fig leaf sprays, monstera, elephant ear, banana, heliconia, philodendron, ivy, bromeliad, fern and tree-fern fronds, fallen leaf, jungle grass; orchid, heliconia, ginger, passion-flower and bromeliad petals, rafflesia; bracket, cap, red cap, glowing fungus and stem; mossy, river, temple, carved glyph, mossy and wet temple stone, rubble, stucco; wet planks, posts, jute and frayed rope; animated river, river foam, waterfall sheet, plunge pool, mist card, light shaft, firefly) in five looks (real, painted, toon, lowpoly, pixel), never nil.
Also `JM.surfaces()`, `JM.group()`, `JM.isCard()`, `JM.isEffect()`, `JM.palette()`, `JM.source()` (where an answer came from: own / installed / runtime), `JM.terrainLayers()` and `JM.terrainLayer(name, look)` (the record the engine terrain's `surfaces` input takes), `JM.setNightGlow(0..1)` / `JM.nightGlow()` (drives the emission of glowing fungi and fireflies) and `JM.refresh()`. jungleProps, jungleKit and terrain painting call it; `look` nil or "auto" follows JungleLook (= tropicalMaterials' TropicalLook).
# 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`).