Log inGet started
World

Emerald Falls: Rainforest, River and Temple Ruins

README.md

tropicalKit

Add a tropical island and beach to any world with one component. Pick a size, a shape (a cove with cliffs, a tall volcanic island, a ring atoll or a little sandbar), how dense the plants grow and a seed: tropicalKit builds white sand beaches that turn wet and glossy at the waterline, turquoise shallows over sand and coral that deepen to blue beyond the reef, leaning coconut palms and a palm grove, beach plants and flowering bushes, rocky headlands with tide pools under the cliffs, a hilltop lookout, an old wooden pier you can walk out on, coral and sea grass you see through the water, and driftwood, shells, starfish, coconuts and seaweed along the tide line. It brings a soft morning, a bright noon, a golden sunset, a moonlit night and passing tropical rain showers, surf, birds, insects and frogs, rain on the palm leaves, footsteps that sound different on dry sand, wet sand, the pier and rock, and footprints in the sand. The same seed is the same island for every player, on desktop and in the browser, so friends playing together stand on the same beach.

Version 1.1.2. Depends on tropicalProps 1.0.3 (palms, plants, rocks, coral, shore litter, the pier pieces), tropicalMaterials 1.0.3 (the surfaces), worldClockKit 1.6.8 (the shared clock and weather) and soundstage 2.1.3 (the sound); installing tropicalKit brings them all, with the ground, wood, stone and organic material collections they use. The water is the engine's own spectral ocean and the ground is the engine's own terrain. It works from wherever it is installed (a world's root or deps/).

1.1.2 releases what PR #3 merged: tropicalProps 1.0.3 (VegGeo.slice / VegGeo.tick frame slicing) and tropicalMaterials 1.0.3 (CardBaker.useFolder) were merged but never released. tropicalKit now depends on those releases and on worldClockKit 1.6.8, the clock release the rest of the stack uses, so an install no longer places an older split copy of the clock beside it (issue #4).

Changes in 1.0.3: published with the current engine library and a clearer package description (what it gives you, how to install it, the one line that adds an island); it depends on tropicalProps 1.0.2 and tropicalMaterials 1.0.2, which change the same way. The island itself is the same as 1.0.2.

Changes in 1.0.2: the footpath is cut into the hill as a level walking bench (a 4.4 m tread with soft shoulders, IslandBuilder.PATH_HALF_WIDTH and PATH_SHOULDER), so no stretch of it runs along a rock face you can be pinned against; walking off into deep water never sets you back under the pier deck or its end platform (you go back to the last wadeable spot clear of the pier, or onto the pier deck), and neither does the fall-through guard. The ground's version moved to 8, so every island cooks its ground again once.

Changes in 1.0.1: the package is called tropicalKit (it was published as tropicalIslandKit 1.0.0); footsteps now play the real surface under the foot (dry sand, soil, grass and rock each have their own sound, not just wood and wet sand); the shallows stop you at chest depth (about 1.7 m of water) and set you back where it was last wadeable; players arrive 10 m in from the pier end so the camera starts on open deck, not in the hut's thatch; cliff walls keep 12 m off the footpath and are fitted to the ground; the shower has a dark squall sky with rain curtains; the example guide's reward step works as written.

Drop an island into your world

Install tropicalKit from ZeroMind. Then, in an empty world, open scenes/main.scene/build.luau and paste this inside content(), just before its closing end (it uses the spawn entity the starter scene already makes):

local ISLAND = { size = 600, shape = "cove", density = "normal", seed = 7 }
entity.spawn("Island").component.add("tropicalKit.Island", ISLAND)

-- one shared clock, and the island's light, weather and sound on it
entity.spawnSynced("WorldClock").component.add("WorldClock", { dayLengthMinutes = 24, startHour = 10, skyMode = "engine" })
entity.spawn("IslandAtmosphere").component.add("tropicalKit.IslandAtmosphere", { showerEveryMinutes = 12 })

-- players arrive on the pier
local sp = require("tropicalKit.IslandBuilder").spawnPoint(ISLAND)
spawn.localPosition = { sp[1], sp[2], sp[3] }
spawn.localRotation = { 0, math.sin(sp[4] / 2), 0, math.cos(sp[4] / 2) }

The first build of a new setting shapes and paints the ground (about half a minute in the editor) and saves it into your world under tropicalIslands/; after that every machine loads it. Build it in the editor before you publish. Press Play: you arrive at the end of the pier. The starter scene's floor, lamps and crate end up buried in the island's hill, so delete those lines from build.luau too.

What you set

SettingValuesWhat it does
size160-1600 (m)the side of the square the island and its reef stand in; the island is about two thirds of it
shapecove, volcanic, atoll, sandbara horseshoe bay of white sand between cliffy headlands; a tall cone with a crater, steep flanks and narrow beaches; a ring of low sandy islets round a turquoise lagoon; a small low sandy islet on a reef
densitysparse, light, normal, dense, lushhow thickly palms, plants, rocks, coral and shore litter grow
seedany whole numbereach seed is a different island; the same seed is always the same one
lookauto, real, painted, toon, lowpoly, pixelhow every prop is drawn; auto follows the world look (below)
ocean, oceanPresettrue/false, an ocean presetput the engine's ocean round the island when the scene has none
pier, route, spawnOnPiertrue/falsethe pier; the signposts and lookout deck; moving the scene's player spawns onto the pier
quality0.3-1draw distance (the browser caps it at 0.6; nothing moves or stops colliding)

Switch the style with one change

Every prop and surface comes in five looks: real (photoreal), painted (hand painted), toon (cartoon, cel shaded), lowpoly and pixel. Switch the whole world at once:

require("tropicalMaterials.TropicalLook").set("toon")      -- this machine
-- or for every player: a synced setting in your scene
entity.spawnSynced("Look").component.add("tropicalMaterials.TropicalLookSetting", { look = "toon" })

or set the Island's look field. The ground keeps the paint it was saved with; to give the ground the toon paint too, set look = "toon" on the Island itself (it saves a toon ground).

Walk it

Each island plans its own walk on its own ground, signposted: arriving on the pier, the shallows to wade in beside it, the palm grove behind the beach, tide pools on the rock shelf under the nearest cliff, the headland lookout (a levelled landing with a viewing deck) and the reef view off the end of the pier, where a coral garden grows under the deck. A footpath links them, cut into the hillside as a level tread so it is walkable end to end. The shallows stop at chest depth: wander deeper and you are set back at the last wadeable spot, never under the pier. Read them from code:

local Site = require("tropicalKit.IslandSite")
local site = Site.current()                     -- the island on this machine (nil until built)
for _, poi in site.pois do print(poi.id, poi.name, poi.x, poi.y, poi.z) end
print(site:surfaceAt(x, z))                     -- drySand, wetSand, rippledSand, grass, soil, rock, wetRock, coralRubble, water
print(site:heightAt(x, z), site:shoreDistance(x, z), site:depthAt(x, z))

Time of day, weather and sound

local Atmos = require("tropicalKit.Atmos")
Atmos.setTime("sunset")                  -- morning | noon | sunset | night, for every player
Atmos.shower({ duration = 75 })          -- a passing tropical shower: it darkens, pours, then clears
Atmos.setWeather("clear")

IslandAtmosphere fields: grade, haze, shafts (off by default, for the browser), ocean, ambience, ambienceVolume, footsteps, footprints, showerEveryMinutes. Sound: surf (louder at the waterline), wind in the palms, a palm grove by day with gulls, parrots and doves, crickets, cicadas and tree frogs at night, rain on the palm leaves in a shower. Footsteps: dry sand, wet sand, wading splashes, the pier's wood, rock.

The sky: fair-weather cumulus tinted for the hour, and in a shower a dark squall with grey rain curtains and a sunlit break (SkyDome, one draw call per layer, no ray-marching, so it suits the browser).

A shell hunt

entity.spawn("ShellHunt").component.add("tropicalKit.ShellHunt", { count = 12, seed = 1 })

Shells and starfish along the pier and the tide line; walk over one to pick it up; a counter on screen; a shell a friend takes is gone for everyone. The guide Make a beach level: a cove where you collect shells along the pier builds it step by step.

Every player, the same island

The island's heights are computed on the CPU from integer-hash noise using only addition, multiplication, division and square roots, so they are bit-identical on every machine, desktop or browser, and are written into the engine terrain as they are. The walk and every placed prop are pure functions of those numbers and the seed. island.stats.fingerprint (from component:island()) is a short code of every placement: equal fingerprints on two machines mean the same island. Time and weather are worldClockKit's shared clock; footsteps are soundstage's, heard from every walker.

Checked for 1.0.1: each of { size = 400, shape = "cove", density = "normal", seed = 7 } and six one-setting changes of it (size 320, volcanic, atoll, sandbar, dense, seed 8) was built twice from scratch; every repeat gave the identical ground, walk and prop fingerprint, and each change gave a different island (density changes only what grows, the ground and the walk stay).

What is inside

  • Island (component), IslandBuilder (build, planFor, spawnPoint, keyFor): build and tear down an island.
  • IslandField, IslandNoise: the shape as plain numbers (the four shapes), deterministic noise.
  • IslandShape, IslandSurfaces: the ground written into the engine terrain and painted with eight surfaces (dry, wet and rippled sand, coral rubble, coastal grass, jungle soil, cliff rock, wet rock).
  • IslandLayout: the pier, the stops and the footpath. IslandRules: what grows and lies where. IslandRender: the props as instanced draws with three levels of detail. IslandSite: questions about the ground.
  • IslandAtmosphere (component), Atmos, Ambience, Footsteps, Footprints: light, weather, sound, footsteps and footprints. SkyDome: the cloud layers (textures/cumulus_dome, textures/squall_dome). audio/: the kit's own recordings.
  • ShellHunt (component): the shell-collecting example.
  • Guides: How do I add a tropical island and beach to my world and Make a beach level: a cove where you collect shells along the pier. Tests: tests/tropicalKit.testSuite.

Changing the ground's textures

An island's ground is cooked once per setting into tropicalIslands/<key>.terrainData, and that cook keeps its own copies of the sand, grass and rock textures. If you change the tropicalMaterials terrain textures, cook the ground again: delete the island's .terrainData folder, or raise IslandShape.VERSION, and the next build makes a fresh one.

The engine terrain hides texture repetition with hex tiling. On the island's long sand ripples its default draws a honeycomb, so the island sets softer values on its ground material (IslandBuilder.GROUND_SHADING = { hex_size = 6, hex_tiling = 0.25, hex_contrast = 0.15 }). Change that table to tune it.

Known limits

  • The first build of a new setting cooks the ground (half a minute on a desktop); it is meant to happen in the editor, and a world that ships its saved ground never cooks it in a player's browser.
  • Steep cliff faces in the ground stretch their texture (the engine terrain paints from above); the kit stands cliff-face props along cliffy coast to cover it.
  • The pier, signposts and shells are local scenery rebuilt by every machine; the shell hunt shares which shells are taken over the network.
  • Two engines signed in to one account collide as one player (#14448), so a two-player test needs two accounts.
  • Frame time on the receiving side of a multiplayer session is higher than on the sender (#20750); mesh loads are slow in the browser (#22751) and frames slow down while asset previews are generating (#22778).
  • The browser build was checked by the person who commissioned the kit, not by its author (#20946).
  • Installing brings several dependencies and can take a minute (#21420); the ZeroMind listing text can lag a release (#19258); a package folder can read as changed after every push (#22671).