# 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.