platformsKit

Every platform a platformer or obstacle course needs, as one Platform component: pick what it does with kind (16 kinds) and what it looks like with look (5 styles), in multiplayer, on the normal built-in player movement.

Install

One call: zeromind_install guid=0c812a97-6662-4664-b81b-4e3caa64700c.

That brings the kit and what it uses with it: juiceKit (landing, crumble, bounce and respawn effects) and Trapline's part helpers (the shapes the looks are built from), under /source/deps/. You don't need to install anything else, and the kit never gives players Trapline lives or health. It pairs well with Trapline's own checkpoints and kill zones if you want them.

If your world already has the full Trapline installed and its log shows no root to resolve against from copies of Lifeline or SecondWind under /source/deps/, those come from Trapline's own dependencies (SecondWind's install problem, #19188 in Trapline's README), not from this kit.

First example

This works in a brand-new world with only platformsKit installed. A new world's main scene builds everything in scenes/main.scene/build.luau. Paste this at the end of its content() function:

local PK = require("platformsKit.api")

-- a spring in front of where you spawn, and a high ledge it throws you onto
PK.spawn("spring", "cartoon", { position = { 0, 0.6, 4 } })
local ledge = entity.spawn("Ledge", { position = { 0, 3.4, 6.2 } })
ledge.component.add("Model", { model = "cube" })
ledge.component.add("BoxCollider", {})
ledge.localScale = { 3, 0.4, 3 }

-- at the end of the ledge, a platform that ferries you out and back
PK.spawn("pingpong", "scifi", { position = { 0, 3.6, 9.4 }, path = { { x = 0, y = 0, z = 8 } } })

-- to the right, a crumbling stone to jump onto; to the left, a rope to swing on
PK.spawn("crumble", "fantasy", { position = { 4, 0.8, 6 } })
PK.spawn("rope", "pixel", { position = { -4, 6, 6 }, yaw = 90 })  -- turned to swing toward you

Press Play and walk forward. You run into the spring, it launches you 7 m up and carries you on onto the ledge. Walk to the end of the ledge and step onto the sci-fi platform when it's there: it takes you 8 m out and brings you back. Jump down, then jump onto the fantasy stone on the right: it shakes, breaks under you and comes back three seconds later. Jump into the pixel chain on the left to grab it, push forward and back to swing, and jump to let go.

To turn the spring into a bouncy mushroom, change one word: PK.spawn("mushroom", ...). To make it pixel art, change "cartoon" to "pixel".

The same works with no code at all: add the platformsKit.Platform component to any entity in the editor and pick kind and look.

What it does

• 16 kinds: moving along a path, ping-pong, rotating, tilting seesaw, crumbling, falling, spring pad, bouncy mushroom, conveyor, one-way (jump up through it), beat blocks, ice, sticky, elevator with call buttons, ladder, rope swing.
• 5 looks for every kind: cartoon, scifi, fantasy, pixel, realistic. Keep one look across a whole world, or mix them.
• Change a setting on a placed platform and it turns into the other kind or look straight away, in the editor or from code.
• Multiplayer: every platform is in the same place at the same moment for everyone (they move on a shared clock), crumbles, falls, runs, elevator calls and rope grabs are shared events, and everything that breaks comes back for everyone.
• Riders are carried smoothly: each machine moves its own player with whatever it stands on (moving, rising, turning, tilting), before the player's controller runs, so there is no jitter, no sliding off and no dropping through.
• Normal player movement: the kit never replaces the built-in CharacterController. It works through that controller's public settings, so the world's usual player setup is all you need.
• Light enough for a phone: primitive meshes only, no physics bodies, small parts cast no shadows, platforms past the draw distance are not drawn at all, and a lite detail level leaves the decoration out. Runs in the browser (checked in Chrome).
• Falls are caught: a SafetyNet puts a player who drops off the level back on the last solid ground they stood on (PK.safetyNet(belowY)).

Kinds

Every platform's own position is the middle of the surface you stand on (the slab fills the space below it). Ladders stand on their position and go up; ropes hang down from it.

Looks

Every kind in every look

Browse it in code with PK.list(filter) (see below). Tags are the kind, the look, what it does and what the style is made of.

Tags by kind: path moving, loop, rideable · pingpong moving, path, back-and-forth, rideable · rotate moving, rotating, rideable, timing · seesaw tilting, physics, weight, rideable · crumble breakable, timed, respawns, hazard · fall falling, timed, respawns, hazard · spring and mushroom bounce, launch, jump · conveyor push, surface, moving-surface · oneway jump-through, one-way, surface · beat timed, rhythm, appearing, disappearing, timing · ice slippery, surface, momentum · sticky slow, surface, goo · elevator moving, vertical, buttons, floors, rideable · ladder climb, vertical, traversal · rope swing, traversal, momentum. Tags by look: cartoon bright, rounded, toon-outline · scifi metal, neon, glowing · fantasy stone, wood, gold, magic · pixel retro, blocky, voxel · realistic industrial, muted, metal, concrete.

Settings (platformsKit.Platform)

0 (or -1 where it says so) means "the kind's default", so most platforms need nothing but kind and look.

Methods on the component: settings() (every setting with defaults filled in), pose() / poseAt(t) (where the moving part is, relative to the platform), isSolid(), press(floor?), touch(), rebuild() (build its look again from its settings), parts(), handle().

A setting changed during play (in the inspector, with PK.setKind / PK.setLook, or by assigning a field) reaches every machine, including players who join later, for platforms placed in a scene and spawned ones alike. Changes made in edit mode are scene edits and are saved with the scene as usual.

Code: local PK = require("platformsKit.api")

-- a row of beat blocks that take turns
for i = 0, 3 do
    PK.spawn("beat", "pixel", { position = { 0, 2, 4 + i * 3 }, offset = i * 0.6 })
end

-- an elevator with three floors that only moves when called
PK.spawn("elevator", "realistic", { position = { 6, 0, 0 },
    path = { { x = 0, y = 5, z = 0 }, { x = 0, y = 10, z = 0 } } })

-- a ping-pong that only goes when someone steps on it
PK.spawn("pingpong", "fantasy", { position = { -6, 1, 0 }, trigger = "step" })

-- react to a crumble anywhere in the world
PK.on(myCrumble, function(ev) if ev == "touch" then print("it's going!") end end)

Catching falls (platformsKit.SafetyNet)

Put one SafetyNet in a scene (or call PK.safetyNet(belowY) from code) and nobody falls forever:

local PK = require("platformsKit.api")
PK.safetyNet(-20)                                  -- below y -20, back to the last solid ground
PK.safetyNet(-20, { respawnAt = { 0, 1, 0 } })     -- or always to one spot

Each machine watches its own player. "Solid ground" is level geometry, never a kit platform, since a crumbling tile or a moving platform may be gone or elsewhere by then. The player comes back standing still, let go of any rope or ladder. It gives no health or lives; for those, pair the kit with a lives system such as Trapline.

Methods: rescues() (how many times this machine's player was caught), safePoint(), setSafePoint(p).

Phones and the browser

The kit runs in the browser and on phones as it is. To draw less on a small screen, add two lines at the top of your scene's content() (or call them from a settings menu at any time; platforms already placed rebuild at once):

local PK = require("platformsKit.api")
PK.setDetail("lite")      -- leave the decoration out; every kind still reads as itself
PK.setDrawDistance(60)    -- don't draw platforms more than 60 m away (default 130)

Both are per machine, so each player can choose. The engine doesn't tell a world whether it runs on a phone, so the kit never switches on its own: offer it as a setting, or use it in levels made for phones.

How it works

• Same place, same moment. Every machine computes a platform's pose from the shared clock (platformsKit.clock, the host's real-time clock read on each machine), so nothing about a platform's motion is sent over the network at all. A seesaw is the exception: each machine tilts it by where every player's body stands.
• Shared events. A crumble or fall being touched, a step/button run, an elevator call and a rope grab are small messages stamped with the shared clock. Every machine keeps the same set and folds it the same way (a touch during a break is ignored, calls are served in time order), so two players stepping on the same tile at once still agree, and a broken platform comes back at the same moment for everyone. A player who joins late asks the host for the events they missed.
• Carrying. Platforms run before the player's controller each frame. The kit finds what the local player stands on (from where everything was at the end of the last frame), moves the player by exactly the platform's motion (turning included), and only then lets the controller walk, jump and snap to the ground. Then RiderGlue (a hidden helper the kit spawns, which runs after the controller) puts the feet back exactly on the drawn surface: a collider moved from script reaches the physics world a frame late, so without it a rider on a lift would sit a frame of motion above or below the floor. Measured: a rider stays 1.0 cm (the controller's skin) above path movers, spinners, seesaws, elevators and falling slabs, with frame-to-frame steps under 1 mm. Remote players are carried by their own machines.
• Never through a floor. A carry downward (a falling slab, a descending lift) stops on any other solid ground under the rider, and the glue never pulls a rider down through it: the platform goes on, the rider lands. Feet that sink into a platform are always lifted back on, even in the frames where a lift speeding up makes the controller say the player is in the air.
• Still standing on it. Whether the rider stands on a platform is judged against the platform's own vertical speed (a lift pushing its rider up is not a jump; a car speeding away downward is not the rider jumping off), with room for the frame its physics surface trails behind, and a rider stays on the platform they rode last frame while their feet are over it and it is still solid: the moment a platform breaks, falls away or blinks out, its riders drop. A body falling past a platform's edge only counts once its feet are within 25 cm of the surface.
• Settings changed during play are shared events too (set), so a platform placed in a scene changes on every machine; the latest change wins.
• Using the built-in controller. Conveyors move the player; ice and sticky rewrite the controller's movement intent (inputX / inputZ); springs, ladders and ropes set the upward speed through the controller's own jump (a jump whose jumpForce is the speed wanted) and switch gravity off while climbing or swinging. Every change lasts exactly one frame unless the platform asks again, so stepping off puts everything back.
• Colliders are plain BoxColliders on local child entities. One-way, beat, crumble and fall platforms switch theirs per machine by moving them out of the way (never by adding or removing the component, which the engine would broadcast), so a one-way can be solid for a player above it and open for one below.
• Looks are temporary child entities made of primitive meshes, rebuilt on each machine and never saved into the scene. Platforms far from the camera keep their state but skip drawing work.

Tests

zero tests run platformsKit (or tools.use("tests", "run", "platformsKit")) in edit mode: 93 tests in 18 groups covering the catalog (including exact kind and look filters and tags never listed twice), the motion maths, shared events and their merge, the clock, every kind in every look building with the right colliders, switching kind and look on a placed platform, the component's methods, the rider's controller changes, the rider glue (put back on the drawn surface, and left alone off the edge, when jumping, in the air, too far off or on a stale pose), the host's per-peer clock report, settings that replicate, colliders that switch by moving, PK.spawn with temporary, yaw and vector paths, a destroyed platform forgetting its events, the version matching in the README, package.yaml and PK.VERSION, the lite detail level (every kind in every look still builds, with fewer parts and the same colliders, and its cues stay), no shadows from small parts, the draw distance hiding and redrawing a platform, switching detail on hidden platforms, PK.all(), rebuild(), the catalog calls, cartoon outlines on and off, the safety net, a falling carry stopping on other ground (and the glue refusing to pull a rider through it), sunk riders lifted back on even while the controller reports them in the air, shared setting changes (the newest wins, late joiners get them, edit-mode changes are not sent), riders on lifts (a rising lift is not a jump, a rider is kept while the lift's collider lags, and still lets go when jumping, walking off or far below; a body falling past an edge only lands near the surface), a rider let go the moment a crumble breaks under them, a new player body (a new play session, a respawn) starting clean without touching the old one, the api and the first example. One test reads this README and fails if any call it lists has no test. They leave nothing behind.

The first example was also played start to finish with real input in a stand-in for a brand-new world (the starter scene a new world gets, with only this kit added): the spring lands you on the ledge whether you hold forward 1.3 s or 2 s, the ferry carries you 8 m out and back, the stone breaks under you and comes back, and the rope swings and lets go.

Known limits

Caused by the engine

Each is the engine's to fix, and each has a public engine issue you can follow; the kit works around what it can.

• juiceKit logs red errors while a world starts (engine issue #19309). In a fresh world with only this kit installed, juiceKit's own JuiceNet component logs module '@builtin::modules.frameDriver' not found a few times as the world opens, because the engine compiles world content before that engine module is registered. It is harmless: the effects work once the world is up, and the kit loads juiceKit only on the first effect, so it adds no errors of its own.
• Other players look sunk or floating on moving lifts (engine issue #18595). Each player is carried exactly by their own machine (1.0 cm above the floor), but you see other players where replication puts them, about 50 ms late. Measured in a two-window test: at rest the other player stood at exactly the same height on both screens; on a lift moving about 1.5 m/s they were drawn up to 12 cm sunk into the floor going up and 8 cm above it going down. It is only how they are drawn on your screen; on their own screen they stand on the floor.
• Cartoon outlines show through floors and walls (engine issue #19385). The engine draws the toon rim without a depth test. Use PK.setOutlines(false), or another look, for cartoon platforms under or behind other geometry.
• A scene can fail its first rebuild after you update the kit (engine issue #19350). The engine's scene builder can take a kit component it saved under an older name (or with settings of an older shape) for a different one, remove it and add it again in the same step, and then refuses the add: component.add('platformsKit.Platform') (or 'platformsKit.SafetyNet'): entity ... already has a ... component. The fix takes four steps and is under Version history, "If a scene fails to rebuild after updating".
• No automatic phone mode (engine issue #18744). The engine gives a world no way to tell it is running on a phone (a phone's browser reports itself as a browser like any other), so lite and the draw distance are yours to switch on.
• Ladders and ropes play the normal air pose (engine issue #19387). The built-in player has no climb or hang animation, so climbing and swinging use the falling pose.
• Rope release has to move the player by hand to keep the swing going (engine issue #19386). The built-in controller has no way to set sideways speed, so for about a second after you let go the kit moves the player itself. A wall in the way stops it.

In the kit

• One-way platforms can't be dropped through from above.
• Seesaws disagree slightly between machines while players move on them (each tilts from the bodies it sees); they settle to the same angle.
• If the host leaves, the next host's clock takes over and moving platforms can jump once while the others resync.
• Scale with the size settings, not the entity's scale. Rotation of the entity is fully supported.
• A SafetyNet gives no lives or health. It only puts a fallen player back. For lives, checkpoints and kill zones, pair the kit with a lives system (Trapline has them, but needs its own full install).
• Ropes swing along their local X axis. Turn a rope with yaw so it swings toward the way players approach it.
• Springs taller than a step can't be walked onto, so they launch you on side contact instead. A spring set into a floor (its top level with the floor) behaves like one you land on.
• Path points must be plain {x=, y=, z=} tables when passed to component.add directly (PK.spawn converts vectors for you).

Showcase

The world this kit comes from opens on a gallery with every kind in every look, labelled, laid out as one walk: eight rows of challenges you ride, climb, swing and jump through, with a catch floor and lifts underneath. Play it with friends.

Version history

Version 1.4.1 (require("platformsKit.api").VERSION, and version in package.yaml).

If a scene fails to rebuild after updating

A scene whose build.luau places platforms or a SafetyNet can fail its first rebuild after an update, with component.add('platformsKit.Platform') (or 'platformsKit.SafetyNet'): entity ... already has a ... component (engine issue #19350). It happened after 1.0.0 to 1.1.0 (the settings changed shape) and to this world's gallery after updating to 1.4.1 (a SafetyNet saved by 1.3.0 under its short name). Fix it once per scene: in edit mode, with that scene loaded, run scene.save, then scene.clean, then scene.reload, then scene.save again. The build places everything fresh, and from then on the scene rebuilds normally. Platforms placed by hand in the editor, or spawned from code in play, are not affected.

What's new in 1.4.1

• A crumbling platform drops you the moment it breaks. Before, the rider was held on the vanished stone for up to a few seconds, standing in mid-air, because the hold that keeps riders on fast lifts while their collider lags did not check that the platform was still solid. It now holds a rider only on a platform that is still there; lifts ride exactly as before (0 sunk frames on a 6 m/s test lift). The same goes for falling slabs, beat blocks and one-way platforms switching off.
• Pressing Play again after leaving play while on a rope or ladder starts clean. The kit used to put the jump and gravity settings back onto the previous session's character, which no longer exists, and logged an error for each. A new body now starts with nothing carried over, and its jump and gravity are normal.
• README: opens with what the kit does, then Install and the first example; version history moved here.
• Every engine-caused known limit names its public engine issue (#19309, #18595, #19385, #19350, #18744, #19387, #19386).
• The rebuild fix after updating (engine issue #19350) is under "If a scene fails to rebuild after updating" and now ends with a second scene.save, which makes it stick.
• 93 tests.

Upgrading to 1.3.0

Nothing to change. Platforms placed in a scene now share setting changes made during play, and riders are no longer carried through floors. If your world relied on a falling platform taking players far below, put a SafetyNet (or a floor) there instead.

What's new in 1.4.0

• Elevators hold you the whole ride. On a fast lift (or at a low frame rate, as in a browser) the kit sometimes stopped counting a rider as standing on the car for a few frames, so they sank 10-40 cm and popped back. Three causes, all fixed: the lift pushing its rider up read as a jump; on a car going down, the car speeding away read as the rider jumping; and the car's physics surface trails it by a frame, so the downward check could miss it. Standing is now judged against the platform's own vertical speed, allows for that lag, starts above feet that sank in, and keeps a rider on the platform they rode last frame while they are over it. Measured: the gallery's Freight Elevator to floor 3 and back, the Grav Elevator and the undercroft lift, plus test lifts at 3, 6 and 9 m/s, with 0 sunk frames.
• A body falling past a platform's edge is not taken for landing on it.
• Known limits name the engine issue behind each engine-caused limit (#19309, #18595).
• 91 tests.

What's new in 1.3.0

• Falling platforms no longer drag you through floors. A carry downward stops on any other solid ground; you land and the slab falls on.
• Elevators keep you exactly on top. Feet that sink into a lift are always lifted back on (riders on the gallery's lifts: 0 sunk frames, was up to 10.6 cm).
• SafetyNet / PK.safetyNet(belowY) catch players who fall off the level and put them back on solid ground.
• Setting changes made during play reach every machine, for platforms placed in a scene too (before, only spawned synced ones did), and late joiners get them.
• PK.setOutlines(on) / PK.outlines(), because the cartoon outline shows through floors.
• No startup errors from the kit: juiceKit is loaded on the first effect, not while the world is still starting.
• 87 tests, including one that checks every call this README lists has a test.

What's new in 1.2.0

Everything from 1.1.0 works as before, and looks the same by default. New:

• Lighter to draw. Parts smaller than 45 cm no longer cast shadows (the gallery went from 1,232 shadow casters to 1,077 with no visible change). A platform past the draw distance (130 m by default) is not drawn at all; it keeps time while hidden and is right the moment it comes back.
• A lite detail level for phones: PK.setDetail("lite") leaves out purely decorative parts (studs, trims, chips, spare stripes, leaves, extra chevrons) and keeps everything that says what a platform does. In the showcase gallery that is 1,846 parts down to 1,284, and shadow casters down to 754.
• PK.setDrawDistance(metres) to draw less on small screens. In the gallery, lite plus a 60 m draw distance took a frame from 35.5 ms to 27 ms on the machine it was measured on.
• Checked in the browser: the gallery loads, a moving platform carries the player (all frames on it, 1.0 cm above the surface) and a crumbling one breaks and comes back for both machines.
• PK.all(), PK.detail() and PK.drawDistance(); 78 tests.

What's new in 1.1.0

Everything from 1.0.0 works as before. New and fixed:

• Feet stay on the floor of lifts. A hidden helper (RiderGlue) runs after the player's movement and puts a rider back on the drawn surface. Before, a rider on anything moving up or down sank or floated 1-3 cm a frame (up to 17 cm on a fast lift). Now riders stay 1.0 cm above path movers, spinners, seesaws, elevators and falling slabs, moving less than 1 mm a frame.
• Shared platforms are the same everywhere. Every setting replicates, so a platform spawned with synced = true during play is the same platform on every machine.
• No stray network traffic. One-way, beat, crumble and fall platforms switch their collider by moving it out of the way instead of adding and removing it, which the engine used to broadcast to every machine.
• Springs launch you when you walk into them, not only when you land on top, and a launch carries you on the way you were walking. Mushrooms do the same when you jump into the cap's side, and the mushroom is lower by default (1.1 m).
• Ropes let go properly. Letting go near the bottom of a rope no longer grabs it straight back; the same rope waits until you touch the ground.
• PK.spawn takes yaw (degrees about the up axis), temporary, and path points as vectors.
• Fixes: PK.list("path") returns only path platforms (a kind or look name is an exact match); tags are never listed twice; a destroyed platform forgets its events; elevator calls from code are never dropped.
• The host can check the clock: PK.clockInfo().peers says how far each other machine is from the host.
• A tested first example that works in a brand-new world, and more tests (see Tests).