# tropicalProps
**60 kinds of tropical island props for any world, each placed with one component:** seven palms (straight, leaning and wind-bent coconut palms, a fan palm, a young palm, a palm clump and a pandanus), beach grass, sea oats and flowering bushes, palm litter, beach rocks, cliffs and sea stacks, coral and sea grass, shells and driftwood, and a modular weathered wooden pier. Every prop has near, middle and far versions, 2-3 seeded shapes, and draws in five looks (`real`, `painted`, `toon`, `lowpoly`, `pixel`) that switch world-wide with one call. Materials come from its dependency `tropicalMaterials`.
## Quick start
Install `tropicalProps` (it brings `tropicalMaterials`). In any world:
```luau
-- a leaning beach palm at the origin
local palm = entity.spawn("palm", { position = { 0, 0, 0 } })
palm.component.add("tropicalProps.TropicalProp", { kind = "palmCoconutLeaning", variant = 2 })
-- a hibiscus bush beside it, shape and turn picked from a seed (for scattering)
entity.spawn("bush", { position = { 3, 0, 1 } }).component.add("tropicalProps.TropicalProp", { kind = "hibiscusBush", seed = 41 })
-- switch every prop that follows the world look (look = "auto", the default) to cartoon:
require("tropicalMaterials.TropicalLook").set("toon")
-- or, synced to every player, put the look setting on one entity of the scene:
entity.spawn("Island Look").component.add("tropicalMaterials.TropicalLookSetting", { look = "lowpoly" })
```
Add a `tropicalProps.PropGallery` component to any entity to see every kind side by side, one band per look (`looks` and `kinds` narrow it, e.g. `{ looks = "real", kinds = "palm" }`).
The package works from wherever it is installed (the world root or `deps/<world>/`): its own files reach each other with `~.` names, its dependency with `~tropicalMaterials.`, and the bake helpers find their folder from their own location.
## Guides
Two guides ship inside the package (`guides` tool, `man`, or the Docs panel):
- **How do I add palm trees, beach plants, rocks, coral and a wooden pier to my world?** Placing a prop, every kind by family, variants and seeds, looks and switching them, colliders, detail, and building a pier with `pierLayout` or piece by piece.
- **Make a palm-fringed beach corner with a short pier.** From an empty world to a sand-and-shallows beach corner with palms, plants, rocks, shells and a pier, step by step.
## TropicalProp
Builds one child entity per part (`Model`, swapped to its cheaper versions as the prop shrinks on screen) and its static colliders, all temporary and rebuilt from the synced fields, so every peer builds the same prop and a reload rebuilds it. Changing any field rebuilds.
| Field | Default | Meaning |
|---|---|---|
| `kind` | `palmCoconutStraight` | any kind `Props.kinds()` lists (tables below) |
| `look` | `auto` | `auto` follows `TropicalLook` (the world-wide switch); or `real`, `painted`, `toon`, `lowpoly`, `pixel` |
| `variant` | `1` | baked shape, 1..n (wraps); used when `seed` is 0 |
| `seed` | `0` | non-zero: picks the variant and a yaw turn from the seed (scattering) |
| `detail` | `auto` | `auto` picks near / mid / far by screen size (one test per prop, every 6 frames); `near`, `mid` or `far` pins one |
| `collide` | `true` | build the colliders (tagged with the attribute `tropicalSurface` = the entry's footstep surface) |
Looks: `real`, `painted` and `pixel` draw the same geometry under that look's material; `toon` draws a chunkier bake (fewer, broader fronds and leaves, stacked-segment trunks, smoother rocks); `lowpoly` a faceted flat-shaded bake.
## Kinds
### Palms (category `palm`, surface `wood`)
| Kind | What it is |
|---|---|
| `palmCoconutStraight` | Tall straight coconut palm, 12-16 m: ringed tapering trunk on a flared root ball, 15-18 arching pinnate fronds with drooping tips, coconuts, dry fronds hanging under the crown |
| `palmCoconutLeaning` | Beach coconut palm leaning 38-52 degrees out toward +Z (the sea), curving back up toward the light |
| `palmWindBent` | Upright at the root, bowing over toward +Z, every frond swept downwind |
| `palmFan` | Bismarck-like fan palm: stout trunk, round crown of pleated split-tipped fans on long petioles |
| `palmYoung` | 2-4 m young coconut palm: upright fronds from a trunk stub, often sprouting from its nut |
| `palmCluster` | 3-4 coconut palms of different heights leaning apart from one base, beach grass at their feet |
| `pandanus` | Screwpine: stilt roots, forking arms with spiral tufts of keeled strap leaves, orange fruit |
### Plants, bushes and palm litter
| Kind | Category | What it is |
|---|---|---|
| `beachGrass` | grass | A patch of 3-5 beach grass tufts (cards) |
| `seaOats` | grass | Dune grass with tall straw stalks and nodding seed heads |
| `seaGrape` | bush | Rounded 1-2 m coastal shrub of big round leaves (a few red), hanging grape bunches |
| `beachMorningGlory` | groundcover | Runners creeping over the sand with notched leaves and purple funnel flowers |
| `spiderLily` | flower | Strap-leaf rosette with an umbel of white spidery flowers |
| `tropicalUndergrowth` | bush | Elephant-ear leaves on long petioles and torn banana leaves |
| `hibiscusBush` | bush | Dense dome of glossy leaves with big red flowers |
| `bougainvilleaBush` | bush | Mound of small leaves smothered in magenta bracts |
| `fernTropical` | fern | Shuttlecock of arching pinnate fronds |
| `coconut` | litter | One fallen coconut: v1 brown husk, v2 green, v3 sprouting |
| `coconutPile` | litter | A heap of 6-9 husks and green nuts (sphere collider) |
| `palmFrondFallen` | litter | A fallen dry frond lying on the sand |
### Shore (rocks, cliffs, sea, litter, pier)
| Kind | Category | What it is |
|---|---|---|
| `rockBeach` | rock | Smooth sea-worn grey-brown boulder with a wet foot |
| `rockBasalt` | rock | Dark angular columnar basalt boulder |
| `rockLimestone` | rock | Pale pitted karst limestone rock |
| `rockMossy` | rock | Boulder under a cap of moss |
| `rockCluster` | rock | A big boulder with 2-4 smaller rocks around it |
| `rockShelfTidePool` | rock | Flat wet rock shelf with tide pools, algae, urchins, anemones, a red starfish (walkable) |
| `pebbleScatter` | rock | Loose pebbles over a small patch (no collider) |
| `cliffWall` | cliff | 12 m wide, 11-19 m layered volcanic cliff facing +Z; tiles along X |
| `cliffSpire` | cliff | Sea stack 8.5-14.5 m with a wave-cut notch and mossy cap |
| `cliffBoulderPile` | cliff | Scree fan of angular blocks at a cliff foot |
| `coralBrain` | coral | Brain coral dome |
| `coralStaghorn` | coral | Branching staghorn coral |
| `coralTable` | coral | Broad flat table coral on a stalk (collider) |
| `coralFinger` | coral | Mound of stubby finger coral |
| `coralPink` | coral | Pink cauliflower coral |
| `seaFan` | coral | Flat lattice sea fan (card, sways) |
| `coralCluster` | coral | Mixed reef head on a rubble mound |
| `seaGrass` | seagrass | Patch of swaying ribbon sea-grass |
| `kelpClump` | seagrass | Tall brown kelp stipes with blades |
| `driftwoodLog` | litter | Bleached driftwood log with a root ball (collider) |
| `driftwoodBranch` | litter | Forked bleached branch on the sand |
| `shellConch` | litter | Queen conch with a pink lip |
| `shellCowrie` | litter | Glossy cowrie |
| `shellScallop` | litter | Ribbed scallop valve |
| `shellScatter` | litter | A few mixed shells strewn over the sand |
| `starfish` | litter | Five-armed sea star (v1-2 orange, v3 red) |
| `seaweedStrand` | litter | Tangle of tide-line wrack |
| `seaweedLine` | litter | 2-3 m strip of wrack along X with twigs |
| `pierDeck` | pier | 2 x 2.4 m deck section, deck top y = 0 |
| `pierDeckBroken` | pier | Deck section with missing and snapped planks |
| `pierPost` | pier | 4 m pile post with rope lashing |
| `pierRailing` | pier | 2 m railing with an X brace |
| `pierLadder` | pier | Swim ladder over a deck edge |
| `pierSteps` | pier | Landing steps down to the sand (ramp collider) |
| `pierEnd` | pier | 4 x 4 m end platform with bollards |
| `pierHut` | pier | Small thatched gazebo |
| `bollard` | pier | Mooring bollard |
| `lantern` | pier | Lantern post (point-light hook `ShoreCatalog.LIGHTS.lantern`) |
| `rowboat` | pier | Small wooden rowboat, origin at the waterline |
| `signpost` | pier | Weathered signpost (label anchor `ShoreCatalog.SIGN_FACE`) |
| `lookoutDeck` | pier | Raised 4 x 4 m viewing platform open toward +Z |
Coral and sea grass carry `underwater = true` in their entries.
## Props API
```luau
local Props = require("tropicalProps.Props") -- "~.Props" inside the package
Props.kinds() -> { string } -- every kind, registration order
Props.kindsOf(category) -> { string } -- "palm", "bush", "rock", "coral", "pier", ...
Props.info(kind) -> Entry? -- { kind, category, variants, radius, height, collider?, surface?, underwater?, description, trunks? }
Props.parts(kind, { look?, variant?, lod? }) -> { { mesh, material } } -- same parts, same order at every LOD
Props.normalize(kind, opts) -> opts
Props.register(entry, partsFn) -- how a catalog adds kinds
```
`info.collider` is the kind's one collider (`capsule` radius/height/offset, `sphere`, `box` size/offset, or `mesh` with `meshes[variant]`). Palms also carry `info.trunks[variant] = { { x0, y0, z0, x1, y1, z1, r }, ... }`: capsule segments (local metres) following that variant's baked trunk or trunks, which `TropicalProp` builds as a capsule chain.
## pierLayout
`require("tropicalProps.ShoreCatalog").pierLayout(length, opts?) -> { { kind, position = {x,y,z}, yaw, variant } }` lays a whole pier along +Z from the origin (deck top y = 0): steps, 2 m deck sections (some broken), posts, railings, lanterns, the end platform with a hut, ladder and a moored boat. Options: `railings` (`both` | `left` | `right` | `none`), `steps`, `endPlatform`, `hut`, `lanterns`, `ladder`, `boat`, `sign`, `broken` (chance per section, default 0.15), `seed`, `deckHeight`, `waterY`.
```luau
local SC = require("tropicalProps.ShoreCatalog")
local pier = entity.spawn("pier", { position = { 0, 1.2, 20 } })
for _, p in SC.pierLayout(24, { railings = "both" }) do
local e = entity.spawn(p.kind, { parent = pier, position = p.position, rotation = { 0, math.sin(p.yaw / 2), 0, math.cos(p.yaw / 2) } })
e.component.add("tropicalProps.TropicalProp", { kind = p.kind, variant = p.variant })
end
```
## Budgets (triangles, worst variant)
| | LOD0 | LOD1 | LOD2 |
|---|---|---|---|
| coconut palms (real) | 10.2-11.8k | 2.3-2.6k | <= 380 |
| fan palm / young / pandanus | 9.0k / 3.1k / 2.5k | 2.6k / 0.9k / 0.9k | <= 430 |
| palm cluster (3-4 trunks) | 14.0k | 4.7k | 1.0k |
| palms, toon / lowpoly | 0.4-4.3k / 0.15-1.4k | | |
| bushes | 1.6-2.2k | <= 600 | <= 72 |
| small plants, litter | 0.1-1.9k | <= 400 | culled |
| rocks | 1.3-3.3k | 0.3-0.8k | <= 400 |
| cliffs | 4.6-7k | 1.2-2k | <= 280 |
| coral | 1.7-5.9k | 0.3-1.6k | <= 620 |
| pier pieces | 0.25-3.7k (lookout 6.2k) | 0.1-1.4k | <= 500 |
300 palms with automatic detail cost about 0.8 ms of script time a frame (one LOD test per prop every 6 frames).
## Mesh contract
Real-world metres, +Y up, origin at the ground contact (pier pieces: deck top). Leaning and bent palms lean toward +Z. Vertex colour RGB is a tint the material multiplies its albedo by; vertex alpha is the wind-sway weight on foliage (0 at the base, 1 at the tips) and 1 on solid parts (trunks, stems, nuts, rock, wood). Front faces are counter-clockwise and agree with the normals. Every part of a prop shares one bounding box, so all parts swap LOD together.
Textures and UVs: leaves, leaflets, fan segments, petals and bracts are real geometric outlines, each carrying UV 0..1 (u across, midrib at u = 0.5; v = 0 at the base, 1 at the tip), so a tropicalMaterials leaf card (one leaf per 0..1 square, two-sided) reads on them; grass is alpha tuft cards (v = 0 at the ground); bark wraps u twice around a trunk with v = metres up it; leaf-material stalks sample the opaque midrib strip of the leaf texture. No texture is shipped here: every surface comes from `tropicalMaterials.TropicalMaterials.get(surface, { look })`.
## Regenerating
Meshes are generated once and baked into the package (`meshes/veg/<kind>/`, `meshes/shore/<kind>/`), read through generated literal indexes (`BakedVeg`, `BakedShore`), so installing costs no generation. The bakers write into the package's own folder, wherever it is installed.
- Vegetation: edit `VegPalms` / `VegPlants` (kit `VegGeo`, catalog `VegetationCatalog`), then in a task `require("tropicalProps.VegBake").run()` (all, a few minutes) or `.run({ kinds = { "palmFan" }, forms = { "toon" } })`; `.report()` answers the triangle table. Mesh names: `<kind>_<form>_v<n>_l<lod>_<part>`, forms `real`, `toon`, `low`.
- Shore: edit `ShoreRocks` / `ShoreSea` / `ShorePier` (kit `ShoreGeo`, table `ShoreGen`), then `require("tropicalProps.ShoreBake").run()` or `.run({ kinds = { "cliffWall" } })`.
- New `.mesh` folders are committed with the rest of the package (`zm add` the package folder).
Tests: `zero tests run tropicalProps` (edit mode) checks every kind x look x variant x LOD, colliders and trunk chains, `pierLayout` and `TropicalProp` rebuilds.
# TropicalProp
Puts one tropicalProps prop on its entity: `kind`, `look` (auto follows TropicalLook), `variant`, `seed`, `collide`, `detail`. Builds Model + MeshLod children and a static collider tagged `tropicalSurface`; every peer builds the same prop from the synced fields.
# ShoreCatalog
Registers the shore half of tropicalProps with `Props`: 41 kinds of rocks, cliffs, coral, sea grass, shore litter and a modular weathered wooden pier, each in 2-3 seeded variants, LOD0/1/2 and all five looks (real, painted and pixel share the default geometry; toon draws a chunkier smoother bake; lowpoly a coarse flat-shaded bake). Meshes come only from `BakedShore` (literal resolves), materials only from `tropicalMaterials.TropicalMaterials.get(surface, { look })`.
```luau
local Props = require("tropicalProps.Props")
Props.parts("cliffWall", { look = "toon", variant = 2, lod = 0 }) -- { { mesh, material }, ... }
entity.spawn("rock").component.add("tropicalProps.TropicalProp", { kind = "rockBasalt", seed = 17 })
```
| Category | Kinds |
|---|---|
| rock (mesh collider, surface `rock`) | `rockBeach`, `rockBasalt`, `rockLimestone`, `rockMossy`, `rockCluster`, `rockShelfTidePool` (surface `wetRock`, walkable, pools of `tidePoolWater` with urchins / anemones / a red starfish), `pebbleScatter` (no collider) |
| cliff (mesh collider) | `cliffWall` (12 m wide, 11-19 m tall, faces +Z out to sea, tiles along X: every variant shares the edge profile at x = +-6, runs 2 m below y = 0), `cliffSpire` (sea stack 8.5-14.5 m), `cliffBoulderPile` |
| coral / seagrass (`underwater = true`) | `coralBrain`, `coralStaghorn`, `coralTable` (mesh collider), `coralFinger`, `coralPink`, `seaFan` (card), `coralCluster`, `seaGrass` (cards), `kelpClump` (cards) |
| litter | `driftwoodLog` (mesh collider, `wood`), `driftwoodBranch`, `shellConch`, `shellCowrie`, `shellScallop`, `shellScatter`, `starfish` (v1-2 orange, v3 red), `seaweedStrand`, `seaweedLine` |
| pier (surface `wood`) | `pierDeck`, `pierDeckBroken`, `pierPost`, `pierRailing`, `pierLadder`, `pierSteps`, `pierEnd`, `pierHut`, `bollard`, `lantern`, `rowboat`, `signpost`, `lookoutDeck` |
Pier grid: pieces snap every 2 m along +Z; deck top is y = 0 at the origin; a deck section spans x -1.2..1.2, z 0..2 (posts at x = +-1.3 at each section start); the end platform x -2..2, z 0..4 (posts at x = +-2.1); a railing runs z 0..2 at its own x = 0; steps go down toward -Z from z = 0 to 1.4 m below; the ladder hangs over an edge facing +Z; the hut and the lookout deck (top at y = 0.4, open toward +Z) are centred on their origin.
## pierLayout
`ShoreCatalog.pierLayout(length, opts?) -> { { kind, position = {x,y,z}, yaw, variant } }`: a whole pier along +Z from the origin in local metres, yaw in radians about +Y, so one parent transform places it. Options: `railings` ("both" | "left" | "right" | "none"), `steps`, `endPlatform`, `hut`, `lanterns`, `ladder`, `boat` (default true), `sign` (default false), `broken` (chance per deck section, default 0.15), `seed`, `deckHeight` (added to y), `waterY` (boat waterline relative to the deck, default -1.1).
Hooks: `ShoreCatalog.LIGHTS.lantern` = `{ offset, color, range, intensity }` (a point light for the lantern glass at night); `ShoreCatalog.SIGN_FACE` = the signpost board's face centre / size / normal for a Text3D label.
## Budgets (triangles, variant 1, default form)
Rocks LOD0 1.3-3.3k, LOD1 0.3-0.8k, LOD2 <= 400; tide-pool shelf 7.2k / 1.9k / 0.3k; cliffs 4.6-7k / 1.2-2k / <= 280; coral 1.7-5.9k / 0.3-1.6k / <= 620; cards (fans, grass, kelp, wrack) <= 500; shells and starfish <= 2k / 650 / 200; pier pieces 0.25-3.7k / 0.1-1.4k / <= 500 (lookout deck 6.2k). Lowpoly bakes LOD0 only (the LOD2-class shape, flat-shaded); toon bakes LOD0/1. Exact counts per part are in `BakedShore.kinds`.
## Regenerating
Generators: `ShoreRocks`, `ShoreSea`, `ShorePier` (kit: `ShoreGeo`; table: `ShoreGen`). After a change, in a task: `require("tropicalProps.ShoreBake").run()` (all kinds, ~30 s) or `.run({ kinds = { "cliffWall" } })`. It overwrites meshes under `meshes/shore/<kind>/`, prunes stale ones and rewrites `BakedShore`. New `.mesh` folders are committed file by file: `zm add tropicalProps.package/meshes/shore/*/*.mesh`.
# Props
The tropicalProps catalog: `Props.kinds()`, `Props.info(kind)`, `Props.kindsOf(category)`, `Props.parts(kind, { look, variant, lod })`, `Props.register(entry, partsFn)`. Catalog modules listed in `Props.CATALOGS` register their kinds.
# IslandRules
What grows and lies where on an island: rule layers (palms, shrubs, ground cover, rocks, cliff faces, coral, sea grass, tide-line litter) on a jittered grid, decided by the island's own height, depth, shore distance, cliffiness, reef, slope, path and grove. Leaning palms lean out to sea; coconuts drop at the foot of coconut palms. Deterministic: `Rules.scatter(field, grid, plan, { density, kinds })`, `Rules.fingerprint(instances)`.
# IslandRender
Draws an island's scattered props as hardware-instanced draws (one per prop part per level of detail), re-sorting instances into near/mid/far levels by distance from the camera, spread over frames. `IslandRender.new(instances, { look, parent, quality })`, `:update()`, `:refresh()`, `:setQuality(q)`, `:destroy()`. Follows forestKit's ForestRender approach.
# IslandLayout
Plans the walk on an island from its own ground: the pier over the shallows from a gentle white-sand beach, the palm grove, the tide pools under the nearest cliff, the headland lookout (levelled), the wading spot, the reef view off the pier end, the spawn on the pier, and a footpath at a walking grade linking them. Deterministic: the same settings give the same walk everywhere.
# IslandShape
Turns an IslandField into ground on the engine terrain: heights and eight surface weights computed on the CPU (deterministic), written cell for cell into a terrain raster and saved by `terrain.write` as a `.terrainData`. Also `heightAt`, `slope2At`, `pad` and `gradePath` on the CPU grid, which is exactly the ground the terrain stands.
# TropicalLook
The one switch for how every tropical surface and prop is drawn: `Look.set("toon")`, `Look.get()`, `Look.resolve(name)` ("auto"/nil follow the world look, an unknown name is "real"), `Look.valid(name)` and `Look.onChanged(fn)` (returns a function that stops listening). Looks: real, painted, toon, lowpoly, pixel. The value lives in module state, so it survives a reload. It is per machine: put a `TropicalLookSetting` component on a synced entity to switch it for every player at once. TropicalMaterials and props whose `look` is `auto` follow it.
# IslandSite
Questions you can ask an island on any machine: `Site.current()`, `site:heightAt`, `surfaceAt` (drySand, wetSand, rippledSand, grass, soil, rock, wetRock, coralRubble, water), `shoreDistance`, `depthAt`, `cliffiness`, `layerAt`, `site.pois`, `site.plan`, `site.ocean`. Answers from the same CPU heights the terrain stands, so every machine answers alike.
# IslandNoise
Deterministic noise and random streams for the island builder: integer hashing and plain arithmetic only (no math.random, sin, cos or exp), so a seed gives bit-identical islands on desktop and in the browser. `hash01`, `value2`, `fbm2`, `ridge2`, `smooth`, `rng(seed)`, `dirIndex`.
# IslandField
The shape of an island as plain numbers, computed on the CPU from a size, a shape (cove, volcanic, atoll, sandbar) and a seed: `Field.new(opts)`, `f:sample(x, z)` -> height, metres inland of the shore, cliffiness, reef weight. Deterministic on every machine (IslandNoise), so the same seed is the same ground for everyone.
# tropicalKit
**Add a tropical island and beach to any world with one component.** Pick a size, a shape (a cove with cliffs, a tall volcanic island, a ring atoll or a little sandbar), how dense the plants grow and a seed: tropicalKit builds white sand beaches that turn wet and glossy at the waterline, turquoise shallows over sand and coral that deepen to blue beyond the reef, leaning coconut palms and a palm grove, beach plants and flowering bushes, rocky headlands with tide pools under the cliffs, a hilltop lookout, an old wooden pier you can walk out on, coral and sea grass you see through the water, and driftwood, shells, starfish, coconuts and seaweed along the tide line. It brings a soft morning, a bright noon, a golden sunset, a moonlit night and passing tropical rain showers, surf, birds, insects and frogs, rain on the palm leaves, footsteps that sound different on dry sand, wet sand, the pier and rock, and footprints in the sand. **The same seed is the same island for every player, on desktop and in the browser**, so friends playing together stand on the same beach.
Version 1.2.3. Depends on **tropicalProps 1.0.3** (palms, plants, rocks, coral, shore litter, the pier pieces), **tropicalMaterials 1.0.3** (the surfaces), **worldClockKit 1.7.5** (the shared clock and weather) and **soundstage 2.1.3** (the sound); installing tropicalKit brings them all, with the ground, wood, stone and organic material collections they use. The water is the engine's own spectral ocean and the ground is the engine's own terrain. It works from wherever it is installed (a world's root or `deps/`).
1.2.3 is built against worldClockKit 1.7.5 (was 1.6.8), so a world that installs tropicalKit holds one worldClockKit copy at the current release instead of a 1.6.8 copy beside a pinned 1.7.x one. No tropicalKit behaviour changed.
1.2.2 lays the signpost labels flat on their boards: they were Text3D labels that turned to face the camera (the default), so from anywhere but straight on the name cut through the board and the post and was half hidden. Each label now lies on the board face tropicalProps publishes (`ShoreCatalog.SIGN_FACE`), 1 cm in front of it, and reads out of the board.
1.2.1 adds `oceanQuality` to the Island (`auto`, `low`, `medium`, `high`, `ultra`; `auto` is medium in the browser and high on desktop). The engine ocean fixes its surface mesh when it is made, and at `high` that mesh (about 277k vertices on calmClear) is re-sent to the renderer every frame, about 10 ms of CPU a frame; `medium` (about 9k) looks the same on a calm sea. The island's ground also no longer height-blends its surfaces: the terrain's default height blend cut the sand, rock and grass edges on the hills into saw teeth.
1.2.0 adds `keepClear` to the Island (and to `IslandBuilder.build` / `planFor` options): a list of circles and boxes where no palm, plant, rock, coral, sea grass, cliff face, shore litter or coconut is placed, so your own buildings, decks and yards stand on clear ground instead of having palms growing through the floor. Changing it re-places the props; the ground keeps its saved cook (`IslandBuilder.keyFor` is unchanged; `IslandBuilder.placementKeyFor` adds the areas). The shell hunt keeps out of the areas too.
1.1.2 releases what PR #3 merged: tropicalProps 1.0.3 (`VegGeo.slice` / `VegGeo.tick` frame slicing) and tropicalMaterials 1.0.3 (`CardBaker.useFolder`) were merged but never released. tropicalKit now depends on those releases and on worldClockKit 1.6.8, the clock release the rest of the stack uses, so an install no longer places an older split copy of the clock beside it (issue #4).
Changes in 1.0.3: published with the current engine library and a clearer package description (what it gives you, how to install it, the one line that adds an island); it depends on tropicalProps 1.0.2 and tropicalMaterials 1.0.2, which change the same way. The island itself is the same as 1.0.2.
Changes in 1.0.2: the footpath is cut into the hill as a level walking bench (a 4.4 m tread with soft shoulders, `IslandBuilder.PATH_HALF_WIDTH` and `PATH_SHOULDER`), so no stretch of it runs along a rock face you can be pinned against; walking off into deep water never sets you back under the pier deck or its end platform (you go back to the last wadeable spot clear of the pier, or onto the pier deck), and neither does the fall-through guard. The ground's version moved to 8, so every island cooks its ground again once.
Changes in 1.0.1: the package is called **tropicalKit** (it was published as tropicalIslandKit 1.0.0); footsteps now play the real surface under the foot (dry sand, soil, grass and rock each have their own sound, not just wood and wet sand); the shallows stop you at chest depth (about 1.7 m of water) and set you back where it was last wadeable; players arrive 10 m in from the pier end so the camera starts on open deck, not in the hut's thatch; cliff walls keep 12 m off the footpath and are fitted to the ground; the shower has a dark squall sky with rain curtains; the example guide's reward step works as written.
## Drop an island into your world
Install **tropicalKit** from ZeroMind. Then, in an empty world, open `scenes/main.scene/build.luau` and paste this inside `content()`, just before its closing `end` (it uses the `spawn` entity the starter scene already makes):
```luau
local ISLAND = { size = 600, shape = "cove", density = "normal", seed = 7 }
entity.spawn("Island").component.add("tropicalKit.Island", ISLAND)
-- one shared clock, and the island's light, weather and sound on it
entity.spawnSynced("WorldClock").component.add("WorldClock", { dayLengthMinutes = 24, startHour = 10, skyMode = "engine" })
entity.spawn("IslandAtmosphere").component.add("tropicalKit.IslandAtmosphere", { showerEveryMinutes = 12 })
-- players arrive on the pier
local sp = require("tropicalKit.IslandBuilder").spawnPoint(ISLAND)
spawn.localPosition = { sp[1], sp[2], sp[3] }
spawn.localRotation = { 0, math.sin(sp[4] / 2), 0, math.cos(sp[4] / 2) }
```
The first build of a new setting shapes and paints the ground (about half a minute in the editor) and saves it into your world under `tropicalIslands/`; after that every machine loads it. Build it in the editor before you publish. Press **Play**: you arrive at the end of the pier. The starter scene's floor, lamps and crate end up buried in the island's hill, so delete those lines from `build.luau` too.
## What you set
| Setting | Values | What it does |
|---|---|---|
| `size` | 160-1600 (m) | the side of the square the island and its reef stand in; the island is about two thirds of it |
| `shape` | `cove`, `volcanic`, `atoll`, `sandbar` | a horseshoe bay of white sand between cliffy headlands; a tall cone with a crater, steep flanks and narrow beaches; a ring of low sandy islets round a turquoise lagoon; a small low sandy islet on a reef |
| `density` | `sparse`, `light`, `normal`, `dense`, `lush` | how thickly palms, plants, rocks, coral and shore litter grow |
| `seed` | any whole number | each seed is a different island; the same seed is always the same one |
| `look` | `auto`, `real`, `painted`, `toon`, `lowpoly`, `pixel` | how every prop is drawn; `auto` follows the world look (below) |
| `ocean`, `oceanPreset` | true/false, an ocean preset | put the engine's ocean round the island when the scene has none |
| `oceanQuality` | `auto`, `low`, `medium`, `high`, `ultra` | detail of that ocean; `auto` is medium in the browser and high on desktop. Use `medium` when the frame is tight: `high` costs about 10 ms of CPU a frame |
| `pier`, `route`, `spawnOnPier` | true/false | the pier; the signposts and lookout deck; moving the scene's player spawns onto the pier |
| `quality` | 0.3-1 | draw distance (the browser caps it at 0.6; nothing moves or stops colliding) |
| `keepClear` | a list of `{ x, z, r }` circles and `{ x, z, w, d, yaw }` boxes (world metres, yaw in degrees) | areas where nothing is scattered: no palm, bush, ground cover, rock, cliff face, coral, sea grass, litter or shell. Use it for your own buildings, decks and yards. Default empty |
Keep a dock yard and a lookout hut clear (a box turns by its `yaw` about +Y the way an entity's yaw turns it, `w` along its own X and `d` along its own Z; a palm's crown leans a few metres past its trunk, so give areas a couple of metres of margin):
```luau
entity.spawn("Island").component.add("tropicalKit.Island", {
size = 600, shape = "cove", seed = 7,
keepClear = {
{ x = 42, z = -18, w = 36, d = 22, yaw = 30 }, -- the warehouse on its stilted yard by the pier
{ x = -60, z = 75, r = 9 }, -- a hut on the hill
},
})
-- or from code: require("tropicalKit.IslandBuilder").build({ seed = 7, keepClear = { ... } })
```
Setting `keepClear` while the island stands (in edit or in play) re-places the props on the saved ground.
## Switch the style with one change
Every prop and surface comes in five looks: **real** (photoreal), **painted** (hand painted), **toon** (cartoon, cel shaded), **lowpoly** and **pixel**. Switch the whole world at once:
```luau
require("tropicalMaterials.TropicalLook").set("toon") -- this machine
-- or for every player: a synced setting in your scene
entity.spawnSynced("Look").component.add("tropicalMaterials.TropicalLookSetting", { look = "toon" })
```
or set the Island's `look` field. The ground keeps the paint it was saved with; to give the ground the toon paint too, set `look = "toon"` on the Island itself (it saves a toon ground).
## Walk it
Each island plans its own walk on its own ground, signposted: **arriving on the pier**, **the shallows** to wade in beside it, the **palm grove** behind the beach, **tide pools** on the rock shelf under the nearest cliff, the **headland lookout** (a levelled landing with a viewing deck) and the **reef view** off the end of the pier, where a coral garden grows under the deck. A footpath links them, cut into the hillside as a level tread so it is walkable end to end. The shallows stop at chest depth: wander deeper and you are set back at the last wadeable spot, never under the pier. Read them from code:
```luau
local Site = require("tropicalKit.IslandSite")
local site = Site.current() -- the island on this machine (nil until built)
for _, poi in site.pois do print(poi.id, poi.name, poi.x, poi.y, poi.z) end
print(site:surfaceAt(x, z)) -- drySand, wetSand, rippledSand, grass, soil, rock, wetRock, coralRubble, water
print(site:heightAt(x, z), site:shoreDistance(x, z), site:depthAt(x, z))
```
## Time of day, weather and sound
```luau
local Atmos = require("tropicalKit.Atmos")
Atmos.setTime("sunset") -- morning | noon | sunset | night, for every player
Atmos.shower({ duration = 75 }) -- a passing tropical shower: it darkens, pours, then clears
Atmos.setWeather("clear")
```
`IslandAtmosphere` fields: `grade`, `haze`, `shafts` (off by default, for the browser), `ocean`, `ambience`, `ambienceVolume`, `footsteps`, `footprints`, `showerEveryMinutes`. Sound: surf (louder at the waterline), wind in the palms, a palm grove by day with gulls, parrots and doves, crickets, cicadas and tree frogs at night, rain on the palm leaves in a shower. Footsteps: dry sand, wet sand, wading splashes, the pier's wood, rock.
The sky: fair-weather cumulus tinted for the hour, and in a shower a dark squall with grey rain curtains and a sunlit break (`SkyDome`, one draw call per layer, no ray-marching, so it suits the browser).
## A shell hunt
```luau
entity.spawn("ShellHunt").component.add("tropicalKit.ShellHunt", { count = 12, seed = 1 })
```
Shells and starfish along the pier and the tide line; walk over one to pick it up; a counter on screen; a shell a friend takes is gone for everyone. The guide **Make a beach level: a cove where you collect shells along the pier** builds it step by step.
## Every player, the same island
The island's heights are computed on the CPU from integer-hash noise using only addition, multiplication, division and square roots, so they are bit-identical on every machine, desktop or browser, and are written into the engine terrain as they are. The walk and every placed prop are pure functions of those numbers and the seed. `island.stats.fingerprint` (from `component:island()`) is a short code of every placement: equal fingerprints on two machines mean the same island. Time and weather are worldClockKit's shared clock; footsteps are soundstage's, heard from every walker.
Checked for 1.0.1: each of `{ size = 400, shape = "cove", density = "normal", seed = 7 }` and six one-setting changes of it (size 320, volcanic, atoll, sandbar, dense, seed 8) was built twice from scratch; every repeat gave the identical ground, walk and prop fingerprint, and each change gave a different island (density changes only what grows, the ground and the walk stay).
## What is inside
- **Island** (component), **IslandBuilder** (`build`, `planFor`, `spawnPoint`, `keyFor`, `placementKeyFor`): build and tear down an island.
- **IslandField**, **IslandNoise**: the shape as plain numbers (the four shapes), deterministic noise.
- **IslandShape**, **IslandSurfaces**: the ground written into the engine terrain and painted with eight surfaces (dry, wet and rippled sand, coral rubble, coastal grass, jungle soil, cliff rock, wet rock).
- **IslandLayout**: the pier, the stops and the footpath. **IslandRules**: what grows and lies where. **IslandRender**: the props as instanced draws with three levels of detail. **IslandSite**: questions about the ground.
- **IslandAtmosphere** (component), **Atmos**, **Ambience**, **Footsteps**, **Footprints**: light, weather, sound, footsteps and footprints. **SkyDome**: the cloud layers (`textures/cumulus_dome`, `textures/squall_dome`). `audio/`: the kit's own recordings.
- **ShellHunt** (component): the shell-collecting example.
- Guides: **How do I add a tropical island and beach to my world** and **Make a beach level: a cove where you collect shells along the pier**. Tests: `tests/tropicalKit.testSuite`.
## Changing the ground's textures
An island's ground is cooked once per setting into `tropicalIslands/<key>.terrainData`, and that cook keeps its own copies of the sand, grass and rock textures. If you change the `tropicalMaterials` terrain textures, cook the ground again: delete the island's `.terrainData` folder, or raise `IslandShape.VERSION`, and the next build makes a fresh one.
The engine terrain hides texture repetition with hex tiling. On the island's long sand ripples its default draws a honeycomb, so the island sets softer values on its ground material (`IslandBuilder.GROUND_SHADING = { hex_size = 6, hex_tiling = 0.25, hex_contrast = 0.15 }`). Change that table to tune it.
## Known limits
- The first build of a new setting cooks the ground (half a minute on a desktop); it is meant to happen in the editor, and a world that ships its saved ground never cooks it in a player's browser.
- Steep cliff faces in the ground stretch their texture (the engine terrain paints from above); the kit stands cliff-face props along cliffy coast to cover it.
- The pier, signposts and shells are local scenery rebuilt by every machine; the shell hunt shares which shells are taken over the network.
- Two engines signed in to one account collide as one player (#14448), so a two-player test needs two accounts.
- Frame time on the receiving side of a multiplayer session is higher than on the sender (#20750); mesh loads are slow in the browser (#22751) and frames slow down while asset previews are generating (#22778).
- The browser build was checked by the person who commissioned the kit, not by its author (#20946).
- Installing brings several dependencies and can take a minute (#21420); the ZeroMind listing text can lag a release (#19258); a package folder can read as changed after every push (#22671).
# tropicalMaterials: Turquoise Cay tropical surfaces
**Every surface of a Caribbean-style tropical island behind one name, in five looks (real, painted, toon, lowpoly, pixel): 50 named surfaces, 39 of them shipped as the package's own generated materials, the rest borrowed from installed collections.** Three kinds of beach sand are among them: powder-white coral sand, pink coral sand (Bermuda, Harbour Island) and glossy black volcanic sand (Punalu'u). `TropicalMaterials.get("palmFrond", { look = "toon" })` returns a material you put straight on a `Model` or an instanced draw, and `TropicalMaterials.terrainLayer("sandPink")` returns a layer record for the engine terrain.
**Install and use:** install tropicalMaterials from ZeroMind. It brings Terra Firma, Bedrock, Heartwood, Scale and Feather and the materialLibraryKit core with it. Then `require("tropicalMaterials.TropicalMaterials")` and ask for a surface by name and look, as in the first example. A `TropicalLookSetting` component switches every surface between the looks for every player at once. The package works wherever it is installed (a world's own folder, a dependency of tropicalKit or tropicalProps, a library): nothing in it, its tests and its authoring tools included, looks for a fixed path.
**Guides:** "How do I use tropical sand, coral and palm materials?" (getting a surface, the five looks, switching every look with one change, terrain layers, the full surface list) and "Make a beach terrain with dry, wet, pink and black sand" (an empty world to a baked four-sand beach with swatches). Both ship in `guides/`; `man` or the Docs panel opens them.
## First example
Runs as written in an empty world that installed only tropicalMaterials:
```luau
local TM = require("tropicalMaterials.TropicalMaterials")
local sand = entity.spawn("sandPatch", { temporary = true, components = { Model = {
model = "@builtin::meshes.plane",
material = TM.get("sandDry"), -- powder-white coral sand (real look)
} } })
sand.localScale = { 4, 1, 4 }
local pink = entity.spawn("pinkSandPatch", { temporary = true, components = { Model = {
model = "@builtin::meshes.plane",
material = TM.get("sandPink"), -- pink coral sand with red flecks
} } })
pink.localPosition = { 4, 0, 0 }
pink.localScale = { 4, 1, 4 }
local black = entity.spawn("blackSandBall", { temporary = true, components = { Model = {
model = "@builtin::meshes.sphere",
material = TM.get("sandBlack", { look = "painted" }), -- black volcanic sand, hand painted
} } })
black.localPosition = { 8, 0.5, 0 }
local leaf = entity.spawn("palmLeaflet", { temporary = true, components = { Model = {
model = "@builtin::meshes.plane",
material = TM.get("palmFrond", { look = "toon" }), -- the same leaflet, cel shaded
} } })
leaf.localPosition = { 0, 0.6, 0 }
leaf.localRotation = { 90, 0, 0 }
leaf.localScale = { 0.15, 1, 0.6 }
print(TM.source("sandDry")) -- own:sandDry
print(TM.source("driftwood")) -- installed:woodsMaterials.materials.driftwood
print(TM.source("hibiscus", { look = "pixel" })) -- runtime:tropicalMaterials:hibiscus|pixel
print(TM.terrainLayer("sandWet").albedo) -- tropicalMaterials.textures.sandWet_albedo
print(TM.terrainLayer("sandBlack", "toon").albedo) -- tropicalMaterials.textures.terrain_sandBlack_toon_albedo
```
## API
- `TM.get(surface, { look? }) -> material`, never nil. `look` is `real | painted | toon | lowpoly | pixel`. nil or `"auto"` follows `TropicalLook.get()`, an unknown look is `real`, and an unknown surface returns a neutral driftwood.
- `TM.surfaces() -> { string }`: the 50 names in catalogue order. `TM.group(surface)` -> `ground | rock | leaf | flower | bark | fruit | shore | shell | sea | coral | water | pier`. `TM.isCard(surface)` -> whether it is an alpha-cut two-sided card. `TM.palette(surface)` -> its flat lowpoly colour (linear).
- `TM.source(surface, opts)` says where the answer came from (`own:`, `installed:`, `runtime:`, `fallback:`). `TM.refresh()` drops the cache.
- `TM.terrainLayers()` -> `sandDry, sandWet, sandRippled, sandPink, sandBlack, grassCoastal, soilJungle, rockCliff, rockWet, coralRubble` (a terrain carries at most eight of them). `TM.terrainLayer(name, look?) -> { name, albedo, normal?, mask?, tiling, tint }`: texture identities and metres per repeat, exactly the record `terrain.write`'s `surfaces` input takes (see the terrain guide, "Surfaces: the layer table"). The mask uses the terrain layout (R metallic, G AO, B height, A smoothness). Wet sand's and wet rock's masks are glossy (high smoothness); black sand's is semi-glossy with glinting grains.
- `TropicalLook` (module): `set`, `get`, `resolve`, `valid`, `onChanged`, `LOOKS`. `TropicalLookSetting` (component): a synced `look` field that calls `TropicalLook.set` on every peer.
Every asset TM returns or builds from is resolved from a string literal in the generated `TropicalMaterialsTable`, so the props and scenes that call it stay publishable.
## Every surface
Own = a material this package ships, made from generated textures (`materials/`, `textures/`). Installed = a collection material used as installed. Runtime = built once per machine from shipped textures, adding no texture memory. Every surface also has painted, toon, lowpoly and pixel looks, built at runtime from the same textures.
| Surface | Looks like | Comes from |
|---|---|---|
| **Ground** (2.5 m tiles; all ten are terrain layers) | | |
| `sandDry` | powder-white coral sand with visible grain, fine dark grit and shell specks (no channel above 238) | own, 1024² tile + terrain mask |
| `sandWet` | swash-wet beige-grey sand, glossy film | own, 1024² tile + glossy terrain mask |
| `sandRippled` | pale sand in soft wave ripples | own, 1024² tile + terrain mask |
| `sandPink` | pink coral sand as on Bermuda and Harbour Island: pale pink-white grains, red foraminifera flecks, a few white shell bits, dry and matte | own, 512² albedo, 256² normal and rm, 128² terrain mask |
| `sandBlack` | black volcanic sand as at Punalu'u: glossy black-grey basalt grains, glassy specks that glint (low-roughness grains, light clear coat) | own, 512² albedo, normal and rm, 128² semi-glossy terrain mask |
| `grassCoastal` | short salt-tolerant grass over sand | own, 1024² tile + terrain mask |
| `soilJungle` | dark leaf-litter jungle floor | installed: Terra Firma `forestFloor` |
| `rockCliff` | warm grey-brown cliff rock | installed: Bedrock `cliffRock` |
| `rockWet` | dark glossy wet tidal basalt, pitted and cracked, white barnacle clusters, emerald algae in the hollows | own, 512² tile + glossy terrain mask (smoothness about 0.75) |
| `coralRubble` | bleached broken coral fragments | own, 1024² tile + terrain mask |
| **Rock props** | | |
| `rockBasalt` | dark grey volcanic basalt | installed: Bedrock `basalt` |
| `rockLimestone` | pale porous limestone | installed: Bedrock `limestone` |
| `rockMossy` | stone with green moss | installed: Bedrock `mossyStone` |
| `pebbles` | rounded mixed pebbles | installed: Bedrock `riverPebbles` |
| **Leaves and flowers** (cards) | | |
| `palmFrond` | deep emerald coconut-palm leaflet, yellow-green toward the tip, darker underside | own card |
| `palmFrondDry` | dead straw-brown leaflet | own card |
| `fanPalmLeaf` | deep green fan-palm segment | own card |
| `beachGrass` | fresh green dune-grass tuft, a little straw only at the blade tips | own card |
| `seaGrapeLeaf` | round leathery sea-grape leaf, mid green | own card |
| `tropicalLeaf` | broad banana-style leaf, deep green | own card |
| `hibiscus` | red hibiscus petal | own card |
| `bougainvillea` | magenta bougainvillea bract | own card |
| `morningGlory` | violet morning-glory petal | own card |
| `spiderLily` | white spider-lily petal | own card |
| **Palm wood and fruit** | | |
| `palmBark` | ringed grey-brown coconut palm trunk | own tile |
| `palmBarkYoung` | greener, smoother young trunk | own tile |
| `coconutHusk` | brown fibrous ripe husk | own tile |
| `coconutGreen` | smooth, slightly glossy lime-green young coconut rind with fine streaks | own, 256² tile |
| **Shore and shells** | | |
| `driftwood` | sun-bleached silver driftwood | installed: Heartwood `driftwood` |
| `shellConch` | cream and blush-pink conch, spiral ridges, glossy porcelain lip | own, 256² tile, clear-coated |
| `shellCowrie` | porcelain-glossy tiger cowrie, cream-tan with dark brown spots | own, 256² tile, clear-coated |
| `shellScallop` | ribbed scallop shell | installed: Scale and Feather `shell` |
| `starfish` | orange cushion starfish | own tile |
| `starfishRed` | the starfish in red | runtime (starfish textures, tinted) |
| `seaweed` | olive tide-line wrack | own card |
| `kelpBrown` | brown kelp blade | own card |
| **Reef** | | |
| `coralBrain` | tan brain coral with meandering grooves | own tile |
| `coralStaghorn` | cream-tan staghorn branches | own tile |
| `coralTable` | sage and tan table coral, dense polyp cups | own, 512² tile |
| `coralPink` | coral-pink porous coral with paler polyp cups | own, 512² tile |
| `seaFan` | purple sea fan | own card |
| `seaGrass` | green sea-grass blades | own card |
| `urchin` | black long-spined urchin, glossy dark-purple spines | own, 256² tile |
| `anemone` | mauve sea anemone with pink-magenta tentacle tips | own, 256² tile, sheen |
| `tidePoolWater` | clear tide-pool water: depth tint, ripples, Fresnel sky, sun glint | runtime (`tropicalWater`) |
| **Pier** | | |
| `pierPlank` | weathered grey deck planks | installed: Heartwood `weatheredPlanks` |
| `pierPost` | weathered silver-grey post wood; green algae and dense barnacles from the foot up to about 2 m, dry above | own, 256×1024 strip (u around, v up) |
| `rope` | tan twisted rope | own tile |
| `ironRusty` | rusty iron fittings | own tile |
| `thatch` | dry palm thatch | own tile |
## UV conventions the materials are made for
- **Leaves, leaflets and petals** (palmFrond, palmFrondDry, fanPalmLeaf, seaGrapeLeaf, tropicalLeaf, hibiscus, bougainvillea, morningGlory, spiderLily, kelpBrown): ONE leaf or petal fills the 0..1 square, u across its width (midrib at u = 0.5), v = 0 at the base / stalk and v = 1 at the tip. **Tufts** (beachGrass, seaGrass, seaweed, seaFan): one clump card, v = 0 at the ground.
- **Bark** (palmBark, palmBarkYoung): u once round the trunk, v in metres up it. Rings run along u.
- **Pier post** (pierPost): u once round the post, v in metres up from its foot. The strip spans 4 m: barnacles and algae up to about 2 m, a ragged algae line, then dry grey wood. It clamps past the top, so a taller post stays dry wood.
- **Vertex colour**: RGB tints the albedo. On cards, ALPHA is the wind weight (0 rigid base, 1 full sway). Solid surfaces ignore vertex alpha.
- **Tiles**: ground surfaces repeat every 2-2.5 m of uv when `uv` is in metres. Props use 1 uv unit ≈ 1 m, and the small-prop tiles repeat faster: conch 4×, cowrie and coconut 1.5×, urchin and anemone 2×, table coral 1×, pink coral 1.5×.
## Looks
- **real**: tiles on `tropicalSolid` (opaque PBR, wetness film, clear coat, sheen, optional bottom-up tint band in world height). Cards on `tropicalFoliage`: alpha cut 0.45, two-sided, darker underside, light through the leaf from the sun or a lamp behind it, and sky light only through the face turned away from the sky. Engine wind sways them by vertex alpha, plus flutter. Tide-pool water on `tropicalWater` (clear by depth, ripples, Fresnel sky, sun glint).
- **painted / toon / lowpoly / pixel**: built at runtime on `tropicalStylised` from the same textures, for every surface.
- Painted: soft brush patches in stepped tones, wrapped light, cool shadows.
- Toon: hard tones, two light bands, pale rim, hard gloss spot on wet things.
- Lowpoly: per-face normals (from derivatives), one palette colour per surface with a slight facet jitter.
- Pixel: about 24 texels a metre (12 across a leaf), mip-averaged blocks, brightness posterised with hue kept, hard light bands.
- Leaves keep their natural saturation in toon and painted.
- **terrain**: the engine terrain shades its layers itself, so each terrain layer has a baked albedo per stylised look (`terrain_<layer>_<look>_albedo`: painted 256², toon 128² flat pale tones, lowpoly 64² palette, pixel 256² of 4x4 blocks), and `terrainLayer(name, look)` hands those out.
## Texture memory
151 textures, **47.8 MB** of GPU memory (UASTC/BC7, 1 byte a texel, mipmaps included), inside the 48 MB web budget the tests hold it to.
- The five 1024² ground tiles (albedo, normal, rm and terrain mask) are 28 MB of that.
- The two newer sands are kept small to stay in budget: pink sand 512² albedo with 256² normal and rm, black sand 512² albedo, normal and rm (its glints need the resolution), both with 128² terrain masks (about 1.6 MB together).
- Prop tiles are 512² (rockWet, corals, bark, coconut husk, rope, iron, thatch, starfish), 256² for small props (shells, green coconut, urchin, anemone), and 256×1024 for the pier-post strip.
- Cards are 64-512 px, and the baked terrain looks are 2.4 MB.
`TropicalMaterialsBuild.textureMemory()` recounts it.
## What's in the package
- `TropicalMaterials.module` the resolver; `TropicalMaterialsTable.module` its generated literal table; `TropicalLook.module` the look switch; `TropicalLookSetting.component` the synced switch.
- `shaders/`: `tropicalSolid`, `tropicalFoliage`, `tropicalStylised`, `tropicalWater`.
- `materials/` (39), `textures/` (151), `tropical.materialCollection` (the 39 in materialLibraryKit's picker).
- `guides/`: the how-to (surfaces, looks, terrain layers, the full list) and the four-sand beach walkthrough.
- Authoring:
- `CardBaker.module`: keys a leaf painted on a flat key colour into a fitted, halo-free cut-out with a normal map, base flipped to v = 0. `regrade` grades a card to a target colour.
- `TropicalMaterialsBuild.module`: `importTile` (with roughness remap, glint, height and per-map shrink options), `regradeTile`, `writeMaterials`, `writeTable`, `writeCollection`, `bakeTerrainLooks`, `swatches`, `textureMemory`. Build order: textures, then materials, then the table. Both modules find the package's folder from their own location, so they run wherever the package is installed.
- `tests/tropicalMaterials.testSuite`.
## Depends on
Installed packages, at the versions `package.yaml` states: materialLibraryKit 1.4.3, Terra Firma (groundMaterials) 1.0.8, Heartwood (woodsMaterials) 1.0.1, Bedrock (stoneMaterials) 1.2.1, Scale and Feather (organicMaterials) 1.0.7.