Log inGet started
Package

tropicalMaterials.package

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

SurfaceLooks likeComes from
Ground (2.5 m tiles; all ten are terrain layers)
sandDrypowder-white coral sand with visible grain, fine dark grit and shell specks (no channel above 238)own, 1024² tile + terrain mask
sandWetswash-wet beige-grey sand, glossy filmown, 1024² tile + glossy terrain mask
sandRippledpale sand in soft wave ripplesown, 1024² tile + terrain mask
sandPinkpink coral sand as on Bermuda and Harbour Island: pale pink-white grains, red foraminifera flecks, a few white shell bits, dry and matteown, 512² albedo, 256² normal and rm, 128² terrain mask
sandBlackblack 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
grassCoastalshort salt-tolerant grass over sandown, 1024² tile + terrain mask
soilJungledark leaf-litter jungle floorinstalled: Terra Firma forestFloor
rockCliffwarm grey-brown cliff rockinstalled: Bedrock cliffRock
rockWetdark glossy wet tidal basalt, pitted and cracked, white barnacle clusters, emerald algae in the hollowsown, 512² tile + glossy terrain mask (smoothness about 0.75)
coralRubblebleached broken coral fragmentsown, 1024² tile + terrain mask
Rock props
rockBasaltdark grey volcanic basaltinstalled: Bedrock basalt
rockLimestonepale porous limestoneinstalled: Bedrock limestone
rockMossystone with green mossinstalled: Bedrock mossyStone
pebblesrounded mixed pebblesinstalled: Bedrock riverPebbles
Leaves and flowers (cards)
palmFronddeep emerald coconut-palm leaflet, yellow-green toward the tip, darker undersideown card
palmFrondDrydead straw-brown leafletown card
fanPalmLeafdeep green fan-palm segmentown card
beachGrassfresh green dune-grass tuft, a little straw only at the blade tipsown card
seaGrapeLeafround leathery sea-grape leaf, mid greenown card
tropicalLeafbroad banana-style leaf, deep greenown card
hibiscusred hibiscus petalown card
bougainvilleamagenta bougainvillea bractown card
morningGloryviolet morning-glory petalown card
spiderLilywhite spider-lily petalown card
Palm wood and fruit
palmBarkringed grey-brown coconut palm trunkown tile
palmBarkYounggreener, smoother young trunkown tile
coconutHuskbrown fibrous ripe huskown tile
coconutGreensmooth, slightly glossy lime-green young coconut rind with fine streaksown, 256² tile
Shore and shells
driftwoodsun-bleached silver driftwoodinstalled: Heartwood driftwood
shellConchcream and blush-pink conch, spiral ridges, glossy porcelain lipown, 256² tile, clear-coated
shellCowrieporcelain-glossy tiger cowrie, cream-tan with dark brown spotsown, 256² tile, clear-coated
shellScallopribbed scallop shellinstalled: Scale and Feather shell
starfishorange cushion starfishown tile
starfishRedthe starfish in redruntime (starfish textures, tinted)
seaweedolive tide-line wrackown card
kelpBrownbrown kelp bladeown card
Reef
coralBraintan brain coral with meandering groovesown tile
coralStaghorncream-tan staghorn branchesown tile
coralTablesage and tan table coral, dense polyp cupsown, 512² tile
coralPinkcoral-pink porous coral with paler polyp cupsown, 512² tile
seaFanpurple sea fanown card
seaGrassgreen sea-grass bladesown card
urchinblack long-spined urchin, glossy dark-purple spinesown, 256² tile
anemonemauve sea anemone with pink-magenta tentacle tipsown, 256² tile, sheen
tidePoolWaterclear tide-pool water: depth tint, ripples, Fresnel sky, sun glintruntime (tropicalWater)
Pier
pierPlankweathered grey deck planksinstalled: Heartwood weatheredPlanks
pierPostweathered silver-grey post wood; green algae and dense barnacles from the foot up to about 2 m, dry aboveown, 256×1024 strip (u around, v up)
ropetan twisted ropeown tile
ironRustyrusty iron fittingsown tile
thatchdry palm thatchown 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.