Log inGet started
Package

jungleMaterials.package

This package holds more than this page lists. See all of its files in its world.

README.md

jungleMaterials: Emerald Falls rainforest surfaces

Every surface of a tropical rainforest behind one name, in five looks (real, painted, toon, lowpoly, pixel): 75 named surfaces: 38 shipped as the package's own generated materials (jungle leaf cards, kapok / fig / dipterocarp / tree-fern bark, temple and carved glyph stone, fungi, petals), 16 borrowed from installed collections, and 21 built at runtime (wet and tinted variants, the animated river, waterfall, foam, mist, light shafts, fireflies, glowing fungus and the far-canopy crown blob). JungleMaterials.get("leafMonstera", { look = "toon" }) returns a material you put straight on a Model or an instanced draw, JungleMaterials.terrainLayer("leafLitter") returns a layer record for the engine terrain, and JungleMaterials.setNightGlow(1) lights the glowing fungi and fireflies at night.

Install and use: install jungleMaterials from ZeroMind. It brings tropicalMaterials (whose look switch and shaders it shares), Terra Firma (groundMaterials), Bedrock (stoneMaterials), Heartwood (woodsMaterials), Scale and Feather (organicMaterials), Flux and Flicker (animatedMaterials) and the materialLibraryKit core. Then require("jungleMaterials.JungleMaterials") and ask for a surface by name and look. A JungleLookSetting component switches every jungle and tropical surface between the looks for every player at once. The package works wherever it is installed; nothing in it looks for a fixed path.

Guides: "How do I use jungle moss, bark, mud and temple stone materials?" (getting a surface, the five looks, one switch for all, terrain layers, night glow, UV conventions) and "Make a mossy jungle temple corner with leaf litter, mud and glowing fungi" (an empty world to a small terrain patch with a mossy temple block, leaf cards and fungi). Both ship in guides/.

First example

local JM = require("jungleMaterials.JungleMaterials")
local floor = entity.spawn("Jungle Floor", { temporary = true, components = { Model = {
    model = "@builtin::meshes.plane", material = JM.get("leafLitter") } } })
floor.localScale = { 6, 1, 6 }

local block = entity.spawn("Temple Block", { temporary = true, components = { Model = {
    model = "@builtin::meshes.cube", material = JM.get("stoneTempleMossy") } } })
block.localPosition = { 0, 0.5, 1 }

local leaf = entity.spawn("Monstera Leaf", { temporary = true, components = { Model = {
    model = "@builtin::meshes.plane", material = JM.get("leafMonstera", { look = "toon" }) } } })
leaf.localPosition = { -1.5, 0.8, 0 }
leaf.localRotation = { 0.7071, 0, 0, 0.7071 }          -- stood upright, base at the bottom

print(JM.source("barkSmooth"))                         -- installed:woodsMaterials.materials.beechBark
print(JM.source("leafMonstera"))                       -- own:leafMonstera
print(JM.source("riverWater"))                         -- runtime:jungleMaterials:riverWater|real
print(JM.terrainLayer("mudWet").albedo)                -- groundMaterials.textures.wetMud_albedo
JM.setNightGlow(1)                                     -- fungusGlow and firefly at full night

To see everything: entity.spawn("Swatches").component.add("jungleMaterials.MaterialGallery", { looks = "all", nightGlow = 0.8 }).

API

  • JM.get(surface, { look? }) -> material, never nil. look is real | painted | toon | lowpoly | pixel; nil or "auto" follows JungleLook.get(), an unknown look is real, an unknown surface answers a neutral forest floor.
  • JM.surfaces() (75 names in catalogue order), JM.group(s) (ground | bark | moss | leaf | flower | fungus | rock | temple | wood | water | fx), JM.isCard(s) (alpha-cut two-sided swaying card), JM.isEffect(s) (see-through effect card), JM.palette(s) (flat lowpoly colour, linear), JM.source(s, opts) (own:, installed:, runtime:, fallback:), JM.refresh().
  • JM.terrainLayers() -> jungleSoil, leafLitter, leafLitterWet, mudRiverbank, mudWet, mossGround, gravelRiver, sandRiver, rockWetDark, templeFloorStones (a terrain carries at most eight). JM.terrainLayer(name, look?) -> { name, albedo, normal?, mask?, tiling, tint }, exactly the record terrain.write's surfaces takes; stylised looks hand out baked terrain_<layer>_<look>_albedo textures.
  • JM.setNightGlow(0..1) drives the emissive brightness of fungusGlow (pale cap by day, green glow at night) and firefly (off by day) in every look, already built or built later; JM.nightGlow() reads it.
  • JungleLook (module) = tropicalMaterials' TropicalLook: set, get, resolve, valid, onChanged, LOOKS. JungleLookSetting (component): a synced look field that calls it on every peer. MaterialGallery (component): every surface × look on cards and spheres.

Every surface

Own = a material this package ships (generated textures). Installed = a collection material used as installed. Runtime = built once per machine from shipped textures. Every surface also has painted, toon, lowpoly and pixel looks.

SurfaceLooks likeComes from
Ground (uv in metres; ★ = terrain layer)
jungleSoil ★dark forest-floor soil with litterinstalled: Terra Firma forestFloor
leafLitter ★thick layer of big brown, tan and orange decaying tropical leavesown, 512² tile + terrain mask
leafLitterWet ★the same, rain-dark and glossyruntime (leafLitter, wetness + clear coat); glossy terrain mask
mudRiverbank ★brown riverbank mudinstalled: Terra Firma mud
mudWet ★dark wet mud with puddle glossinstalled: Terra Firma wetMud
mossGround ★green moss carpetinstalled: Terra Firma moss
rootMattangle of surface roots over wet soilown, 512² tile
gravelRiver ★river gravelinstalled: Terra Firma gravel
sandRiver ★brownish river sandruntime (Terra Firma wetSand, tinted)
rockWetDark ★dark glossy wet rockruntime (tropicalMaterials rockWet, darkened)
templeFloorStones ★worn sandstone paving with moss and soil in the gapsown, 512² tile + terrain mask
Bark (u twice round, v = metres / 2)
barkKapokpale silver-grey kapok bark, shallow fissures, thorn bumpsown, 512²
barkFigstrangler fig: fused interlaced root strandsown, 512²
barkSmoothsmooth grey barkinstalled: Heartwood beechBark
barkDipterocarpreddish-grey flaking scaly platesown, 512²
barkPalmringed palm trunkinstalled: tropicalMaterials palmBark
barkTreeFerndark fibrous tree-fern trunk with frond scarsown, 512²
barkMossybark under mossinstalled: Scale and Feather barkMoss
barkDeadsilvered dead woodinstalled: Heartwood driftwood
bamboogreen-yellow bamboo culminstalled: Heartwood bamboo
Moss and organic
mossThickthick cushion mossinstalled: Terra Firma moss
mossHanginghanging old-man's-beard strands (card, attached at v = 0)own card
lichenpale grey-green crustose lichenown, 256²
lianatwisted woody liana stemown, 512²
vineStemgreen young vineruntime (liana, tinted)
rootAerialreddish aerial rootruntime (liana, tinted)
Leaves (cards: v = 0 at the base; crown sprays attach at bottom centre)
leafCanopy / leafCanopyDarktwig spray of ~15 glossy drip-tip leaves / the same in deep shadeown card / runtime tint
leafEmergentspray of small leathery olive leavesown card
leafStranglerspray of thick glossy fig leavesown card
leafPalmUnderstoryunderstory palm leafletruntime (tropicalMaterials palmFrond, deeper green)
leafFernFrond / leafTreeFernsword-fern frond / lacy tree-fern frondown cards
leafMonstera, leafElephantEar, leafBanana, leafHeliconia, leafPhilodendron, leafIvy, leafBromeliad, leafFallensplit monstera, veined alocasia, wind-torn banana, paddle heliconia, heart philodendron, golden pothos, spiny strap, brown fallen leafown cards
grassJunglebroad-bladed jungle grass tuftown card
Flowers
petalOrchidPink, petalOrchidWhite, petalOrchidPurplemoth-orchid petalsown cards
bractHeliconia, petalGinger, petalPassion, bromeliadBractscarlet lobster-claw bract, torch-ginger bract, passion-flower petal with corona, red bromeliad bractown cards
rafflesiaPetalbrick-red fleshy petal with cream wartsown, 256²
Fungi
fungusBracketbanded tan bracket fungusown, 256²
fungusCaptan banded capruntime (bracket, tinted)
fungusCapRedred, white-spotted capinstalled: Scale and Feather mushroomCap
fungusGlowbioluminescent cap, green glow driven by setNightGlowruntime (jungleGlow shader, every look)
fungusStempale cream fibrous stemown, 256²
Rock and temple (1 uv unit = 1 m; temple tiles repeat every 2 m)
rockMossymoss-covered stoneinstalled: Bedrock mossyStone
rockRiverdark wet river boulderruntime (Bedrock granite, wet)
stoneTempleweathered grey-ochre Maya limestone blocksown, 512²
stoneTempleCarvedcarved Maya hieroglyph blocks in deep reliefown, 512²
stoneTempleMossytemple blocks with thick moss in the jointsown, 512²
stoneTempleWettemple stone, rain-dark and glossyruntime (stoneTemple, wet)
stoneRubblerough stacked stonesinstalled: Bedrock dryStoneWall
stuccoWeatheredcracked lime stucco with mould and algaeown, 512²
Wood and rope
woodPlankWetwet weathered planksruntime (Heartwood weatheredPlanks, wet)
woodPostweathered post woodinstalled: Heartwood weatheredPlanks
ropeJutetan twisted ropeinstalled: tropicalMaterials rope
ropeFrayedworn, rougher roperuntime (rope, tinted)
Water and effects
riverWatermurky green-brown jungle river flowing along +v (uv in metres), ripples and scum streaksruntime (Flux and Flicker animWater, murky style; toon style for stylised looks)
riverFoamfoam streaks drifting along +vruntime (jungleFx)
waterfallSheetwhite water falling along +v at 4.5 m/s, ragged edgesruntime (jungleFx)
plungePooldeep green clear pool, depth tint, ripplesruntime (tropicalMaterials tropicalWater; animWater toon for stylised)
mistCarddrifting soft mist bankruntime (jungleFx, alpha blend)
lightShaftgod-ray through a canopy gap, v = 0 at the gap, dust motesruntime (jungleFx, additive)
fireflypulsing yellow-green glow dot, driven by setNightGlowruntime (jungleFx, additive)

UV conventions

  • Cards (leaves, fronds, petals, bracts): one per 0..1 square, u across (midrib at u = 0.5), v = 0 at the stalk, v = 1 at the tip. Crown sprays (leafCanopy, leafCanopyDark, leafEmergent, leafStrangler): a twig of leaves attached at bottom centre (u 0.5, v 0). Tufts (grassJungle): v = 0 at the ground. mossHanging: attached at v = 0, hanging toward v = 1.
  • Vertex colour: RGB tints. On cards ALPHA is the wind weight (0 rigid base, 1 full sway); on effect cards alpha scales opacity; on fungusGlow it weights the glow.
  • Tiles: ground surfaces repeat every 2 m (temple floor 3 m) when uv is in metres; bark, temple and prop tiles assume 1 uv unit ≈ 1 m.
  • River / pool / foam / waterfall: uv in metres, flow along +v.

Looks

Real: tiles on tropicalMaterials' tropicalSolid (PBR, wetness film, clear coat), cards on tropicalFoliage (alpha cut 0.45, two-sided, light through the leaf, wind sway by vertex alpha). Painted, toon, lowpoly and pixel: runtime materials on tropicalStylised from the same textures. The water and effect surfaces and the glowing fungus carry the look in their own shaders (animWater style, jungleFx and jungleGlow look). The terrain's stylised looks are baked albedos.

Texture memory

135 textures, about 20 MB of GPU memory (1 byte a texel, mipmaps included): sixteen 512² / 256² PBR tiles (albedo, normal, rm), 22 cards at 64–256 × 256–512, three terrain masks and 40 small baked terrain-look albedos. JungleMaterialsBuild.textureMemory() recounts it; the tests hold it under 32 MB.

What's in the package

  • JungleMaterials.module (resolver), JungleMaterialsTable.module (generated literal table), JungleLook.module, JungleLookSetting.component, MaterialGallery.component.
  • shaders/: jungleFx (mist, light shaft, firefly, waterfall, foam; procedural, animated, every look), jungleGlow (bioluminescent fungus).
  • materials/ (38), textures/ (135), jungle.materialCollection (the 38 in materialLibraryKit's picker), guides/ (2), tests/jungleMaterials.testSuite.
  • Authoring: CardBaker.module (keys a leaf picture on magenta into a fringe-free cut-out + normal map), JungleMaterialsBuild.module (importTile, wetMask, writeMaterials, writeTable, writeCollection, bakeTerrainLooks, textureMemory). Leaf cards were generated with image_gen on a magenta key, tiles with pbr_gen (seamless).

Depends on

tropicalMaterials 1.0.2, materialLibraryKit 1.4.3, groundMaterials 1.0.8, stoneMaterials 1.2.1, woodsMaterials 1.0.2, organicMaterials 1.0.8, animatedMaterials 1.0.16 (versions in package.yaml).