Log inGet started
Package

tropicalProps.package

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

README.md

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:

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

FieldDefaultMeaning
kindpalmCoconutStraightany kind Props.kinds() lists (tables below)
lookautoauto follows TropicalLook (the world-wide switch); or real, painted, toon, lowpoly, pixel
variant1baked shape, 1..n (wraps); used when seed is 0
seed0non-zero: picks the variant and a yaw turn from the seed (scattering)
detailautoauto picks near / mid / far by screen size (one test per prop, every 6 frames); near, mid or far pins one
collidetruebuild 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)

KindWhat it is
palmCoconutStraightTall 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
palmCoconutLeaningBeach coconut palm leaning 38-52 degrees out toward +Z (the sea), curving back up toward the light
palmWindBentUpright at the root, bowing over toward +Z, every frond swept downwind
palmFanBismarck-like fan palm: stout trunk, round crown of pleated split-tipped fans on long petioles
palmYoung2-4 m young coconut palm: upright fronds from a trunk stub, often sprouting from its nut
palmCluster3-4 coconut palms of different heights leaning apart from one base, beach grass at their feet
pandanusScrewpine: stilt roots, forking arms with spiral tufts of keeled strap leaves, orange fruit

Plants, bushes and palm litter

KindCategoryWhat it is
beachGrassgrassA patch of 3-5 beach grass tufts (cards)
seaOatsgrassDune grass with tall straw stalks and nodding seed heads
seaGrapebushRounded 1-2 m coastal shrub of big round leaves (a few red), hanging grape bunches
beachMorningGlorygroundcoverRunners creeping over the sand with notched leaves and purple funnel flowers
spiderLilyflowerStrap-leaf rosette with an umbel of white spidery flowers
tropicalUndergrowthbushElephant-ear leaves on long petioles and torn banana leaves
hibiscusBushbushDense dome of glossy leaves with big red flowers
bougainvilleaBushbushMound of small leaves smothered in magenta bracts
fernTropicalfernShuttlecock of arching pinnate fronds
coconutlitterOne fallen coconut: v1 brown husk, v2 green, v3 sprouting
coconutPilelitterA heap of 6-9 husks and green nuts (sphere collider)
palmFrondFallenlitterA fallen dry frond lying on the sand

Shore (rocks, cliffs, sea, litter, pier)

KindCategoryWhat it is
rockBeachrockSmooth sea-worn grey-brown boulder with a wet foot
rockBasaltrockDark angular columnar basalt boulder
rockLimestonerockPale pitted karst limestone rock
rockMossyrockBoulder under a cap of moss
rockClusterrockA big boulder with 2-4 smaller rocks around it
rockShelfTidePoolrockFlat wet rock shelf with tide pools, algae, urchins, anemones, a red starfish (walkable)
pebbleScatterrockLoose pebbles over a small patch (no collider)
cliffWallcliff12 m wide, 11-19 m layered volcanic cliff facing +Z; tiles along X
cliffSpirecliffSea stack 8.5-14.5 m with a wave-cut notch and mossy cap
cliffBoulderPilecliffScree fan of angular blocks at a cliff foot
coralBraincoralBrain coral dome
coralStaghorncoralBranching staghorn coral
coralTablecoralBroad flat table coral on a stalk (collider)
coralFingercoralMound of stubby finger coral
coralPinkcoralPink cauliflower coral
seaFancoralFlat lattice sea fan (card, sways)
coralClustercoralMixed reef head on a rubble mound
seaGrassseagrassPatch of swaying ribbon sea-grass
kelpClumpseagrassTall brown kelp stipes with blades
driftwoodLoglitterBleached driftwood log with a root ball (collider)
driftwoodBranchlitterForked bleached branch on the sand
shellConchlitterQueen conch with a pink lip
shellCowrielitterGlossy cowrie
shellScalloplitterRibbed scallop valve
shellScatterlitterA few mixed shells strewn over the sand
starfishlitterFive-armed sea star (v1-2 orange, v3 red)
seaweedStrandlitterTangle of tide-line wrack
seaweedLinelitter2-3 m strip of wrack along X with twigs
pierDeckpier2 x 2.4 m deck section, deck top y = 0
pierDeckBrokenpierDeck section with missing and snapped planks
pierPostpier4 m pile post with rope lashing
pierRailingpier2 m railing with an X brace
pierLadderpierSwim ladder over a deck edge
pierStepspierLanding steps down to the sand (ramp collider)
pierEndpier4 x 4 m end platform with bollards
pierHutpierSmall thatched gazebo
bollardpierMooring bollard
lanternpierLantern post (point-light hook ShoreCatalog.LIGHTS.lantern)
rowboatpierSmall wooden rowboat, origin at the waterline
signpostpierWeathered signpost (label anchor ShoreCatalog.SIGN_FACE)
lookoutDeckpierRaised 4 x 4 m viewing platform open toward +Z

Coral and sea grass carry underwater = true in their entries.

Props API

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.

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)

LOD0LOD1LOD2
coconut palms (real)10.2-11.8k2.3-2.6k<= 380
fan palm / young / pandanus9.0k / 3.1k / 2.5k2.6k / 0.9k / 0.9k<= 430
palm cluster (3-4 trunks)14.0k4.7k1.0k
palms, toon / lowpoly0.4-4.3k / 0.15-1.4k
bushes1.6-2.2k<= 600<= 72
small plants, litter0.1-1.9k<= 400culled
rocks1.3-3.3k0.3-0.8k<= 400
cliffs4.6-7k1.2-2k<= 280
coral1.7-5.9k0.3-1.6k<= 620
pier pieces0.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.