tropicalMaterials.package
- .metadata131 B
- CardBaker.module
- README.md14.6 KB
- TropicalLook.module
- TropicalLookSetting.component
- TropicalMaterials.module
- TropicalMaterialsBuild.module
- TropicalMaterialsTable.module
- guides
- materials
- package.yaml1.3 KB
- shaders
- tests
- textures
This package holds more than this page lists. See all of its files in its world.
README.md
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:
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.lookisreal | painted | toon | lowpoly | pixel. nil or"auto"followsTropicalLook.get(), an unknown look isreal, 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 recordterrain.write'ssurfacesinput 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 syncedlookfield that callsTropicalLook.seton 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
uvis 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 ontropicalFoliage: 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 ontropicalWater(clear by depth, ripples, Fresnel sky, sun glint). - painted / toon / lowpoly / pixel: built at runtime on
tropicalStylisedfrom 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), andterrainLayer(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.modulethe resolver;TropicalMaterialsTable.moduleits generated literal table;TropicalLook.modulethe look switch;TropicalLookSetting.componentthe 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.regradegrades 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.