Log inGet started
World

Platform Playground: Moving, Crumbling and Bouncy Platforms Kit

README.md

platformsKit

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

Install

One call: zeromind_install guid=0c812a97-6662-4664-b81b-4e3caa64700c (or search ZeroMind for "platformsKit" and install platformsKit.package from the ZeroMind panel).

That brings the kit and what it uses with it, under /source/deps/: juiceKit (landing, crumble, bounce and respawn effects) and Trapline (its part helpers are the shapes the looks are built from), with the kits Trapline is built on (SecondWind, Lifeline, MatchFlow and barsKit). You don't need to install anything else. The kit never gives players Trapline lives or health; those only come from Trapline's own parts, which pair well with the platforms if you want checkpoints and traps. If your world already has Trapline, install it first and platformsKit adds only itself.

Your first platform: install, drop one in, press Play

  1. Install the kit (above).
  2. Drop one platform in. A new world's main scene builds everything in scenes/main.scene/build.luau. Paste these two lines at the end of its content() function, just before its closing end:
local PK = require("platformsKit.api")
PK.spawn("pingpong", "scifi", { position = { 0, 0.2, 6 }, path = { { x = 0, y = 0, z = 8 } } })

Saving the file rebuilds the scene: a sci-fi platform appears 6 m in front of where you spawn, with its path drawn as yellow dots. 3. Press Play, walk forward and step onto the platform when it is at your end. It carries you 8 m ahead, waits a second and brings you back.

That is the whole kit: PK.spawn(kind, look, options) places any platform. Change "pingpong" to "swing" or "crumble", or "scifi" to "nature", and you have another one.

First example: a little course

This works in a brand-new world with only platformsKit installed. Paste this at the end of the main scene's content() function (instead of the two lines above):

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 left, a crumbling stone to jump onto; to the right, 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 squashes, boings and launches you 7 m up, carrying 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 your left: it creaks, its pieces rock apart and it breaks under you, and it comes back three seconds later. Jump into the pixel chain on your right 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.

Guides

Two guides ship inside the package, in platformsKit.package/guides/, so they are in your world as soon as the kit is installed. Open them from the Docs panel, with the guides tool, or in the shell with zero guides read <path>:

What it does

  • 19 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, swinging platform, sinking platform and updraft fan.
  • 7 looks for every kind: cartoon, scifi, fantasy, pixel, realistic, industrial and nature. 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.
  • Alive when you stand on it: crumbling platforms creak and their pieces rock apart before they go; springs and mushrooms squash, overshoot and settle; a falling platform sags and flashes a warning frame that blinks faster until it drops; landings puff dust; lifts ding when they arrive. Every one of those moments has a sound voiced for the look (bouncy for cartoon, synth for sci-fi, chiptune for pixel, chimes and stone for fantasy, metal for realistic, heavy machinery for industrial, wood for nature), made on each machine with no sound files to install.
  • 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, swinging, sinking), 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 by a person; see Known limits).
  • 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), so a platform whose top is 0.2 m above the ground or less can be walked straight onto; anything higher needs a jump. Ladders stand on their position and go up; ropes hang down from it; a swing's deck hangs at its position with its frame above.

kindwhat it doesdefaults
pathMoves along the points of path and back to its start, round and round, waiting wait s at every point.3 x 0.4 x 3 m, 2 m/s, waits 0.6 s, always running
pingpongGoes along path to the end and back, waiting at each end.3 x 0.4 x 3 m, 8 m along +X, 2 m/s (8 m in about 4 s), waits 1 s
rotateTurns around its centre about axis (y = flat like a turntable, x/z = rolls over). With wait, turns in steps (90 or 180 degrees) and pauses.7 x 0.4 x 1.6 m beam, 35 deg/s
seesawTips toward whoever stands on it (every player counts, by where they stand) and levels out when they leave.7 x 0.35 x 2.2 m plank, tips up to 20 deg
crumbleCreaks and shakes when someone lands on it, breaks into falling chunks wait s later (whoever stands on it falls at once), comes back respawn s after that.2.6 x 0.5 x 2.6 m, breaks 0.8 s after a landing, back after 3 s
fallSags and flashes a warning when touched, drops away (riders go down with it) wait s later, floats back respawn s after that.2.6 x 0.4 x 2.6 m, drops 0.35 s after a touch, back after 3.5 s
springLaunches you up when you land on it or walk into it, carrying you on the way you were walking. power = height in metres.1.8 x 0.6 x 1.8 m, 7 m
mushroomA springy cap that bounces you every landing (jump onto it). power = height in metres. sizeY = total height of the mushroom.2.8 x 1.1 x 2.8 m, 4.5 m
conveyorCarries whoever stands on it along its +X at speed m/s (negative runs backwards).7 x 0.45 x 2.2 m, 2.5 m/s
onewaySolid from above only: jump up through it from below and land on top.4 x 0.25 x 2.2 m
beatThere for onBeats beats, gone for offBeats, on a shared beat of beat seconds. offset makes rows take turns. It blinks and ticks before it goes.2.6 x 0.4 x 2.6 m, 0.6 s, 3 on, 3 off
iceSlippery: you speed up slowly and slide on after you let go. slide 0 (grippy) to 1 (no grip).7 x 0.45 x 3 m, 0.85
stickyGoo: you walk at slow times your speed and jump lower.7 x 0.45 x 3 m, 0.4
elevatorTravels between floors: its start plus every point of path. A call stand at each floor brings it there (step on it, or press Interact next to it). Stand on the car and it takes you to the next floor. It dings when it arrives. trigger = "always" makes it cycle on its own.3 x 0.3 x 3 m, floors +4 m and +8 m, 2.2 m/s (6.8 m in about 3 s), waits 1.5 s
ladderWalk into it to climb. Push toward it to go up, away to go down, jump to let go. At the top you hop onto whatever it leans on. Climbed from its front (+Z) side.1 m wide, 5 m high
ropeHangs from its position. Jump into it to grab on, push to swing, jump to let go and fly. It swings the way you were going when you caught it.5 m long, pump 1
swingA deck on two chains from a frame above it, swinging back and forth along its +X like a pendulum while the deck stays level, so you can ride it. power = chain length, tilt = how far it swings each way, speed = pace (1 = a real pendulum).3 x 0.35 x 2.2 m deck, 3.5 m chains, 35 deg each way (one full swing in about 3.75 s)
sinkFloats where you put it and sinks while anyone stands on it, speed m/s down to power m deep, then floats back up (at 0.8 x speed) when they step off. Keep moving.3 x 0.4 x 3 m, sinks 0.6 m/s down to 3 m
fanAn updraft: stand on it or fall into the column above it and the air lifts you, at up to speed m/s, to hover power m above it. Push to drift out of the column.2.4 x 0.4 x 2.4 m, lifts you 6 m at up to 6 m/s

Looks

lookstyle
cartoonRounded candy shapes in bright colours with a dark toon outline.
scifiDark brushed metal with glowing cyan and magenta trim.
fantasyOld stone and timber, moss and gold, with a little magic glow.
pixelChunky blocks in flat retro colours, every edge stepped.
realisticMuted steel, concrete, rubber and timber; no glow.
industrialHeavy steel, tread plate, rivets and rust, with yellow-and-black hazard stripes and amber warning lamps.
natureLogs, bark, moss and leaves, with flowers and a few fireflies.

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.

kindcartoonscififantasypixelrealisticindustrialnature
pathBubblegum CruiserHover ShuttleFloating IslePixel LiftSteel Cargo PlatformGantry PalletDrifting Leaf
pingpongToybox GliderMag-Rail SledWizard's Raft8-Bit ShuttleIndustrial CarriageRail Shuttle CartRiver Raft
rotatePinwheel SpinnerRotor BridgeWindmill BeamPixel PropellerTurntable GirderCrane Jib SpinnerLog Spinner
seesawCandy SeesawBalance Beam MK-IITroll ScalePixel TeeterTimber SeesawGirder TeeterBranch Teeter
crumbleCookie CrumbleUnstable HexplateAncient Ruin SlabBrittle BrickCracked ConcreteRusted GrateRotten Stump
fallJelly DropperGrav-Fail PanelCursed FlagstoneFalling BlockRusty Drop SlabTrapdoor PlateLoose Rock Ledge
springBoing SpringGravity LauncherRune Leap StonePixel SpringCoil Spring PadPiston LauncherBounce Bloom
mushroomBouncy ToadstoolBio-Gel MushroomFairy Ring CapPixel ShroomBracket FungusRubber Buffer DomeForest Puffball
conveyorSushi BeltPlasma ConveyorMillstone WalkArrow BeltRubber BeltFactory LineLeaf Stream
onewayCloud LedgeHardlight LedgeVine BridgePass-Through BrickScaffold PlankCatwalk GrilleLeafy Branch
beatDisco TilePhase BlockSpirit Stepping StoneBlink BlockStrobe GrateHazard ShutterFirefly Stones
iceFrosty SlabCryo PlateGlacier ShelfIce BlockSheet IceOil SlickFrozen Pond
stickyBubblegum PadGluon FieldSwamp MossSlime BlockTar PatchWet CementMud Bog
elevatorGumball LiftGrav ElevatorDwarven LiftPixel ElevatorFreight ElevatorCargo HoistTreetop Lift
ladderCandy LadderMaintenance LadderVine LadderPixel LadderAluminium LadderCage LadderBranch Ladder
ropeLicorice RopeEnergy TetherJungle VinePixel ChainHemp RopeCrane ChainLiana Vine
swingCandy SwingboatPendulum PodDungeon Swing SlabPixel PendulumChain Swing DeckCrane Hook PalletVine Swing Log
sinkMarshmallow FloatFailing Hover PadSinking Lily StoneSinking BlockPontoon FloatHydraulic Sag PlateFloating Log
fanBubble BlowerGrav-Lift VentWind Rune CirclePixel FanFloor Fan GrateTurbine VentDandelion Updraft

Tags by kind: path moving, path, 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 bounce, launch, jump · mushroom bounce, launch, jump, organic · 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 · swing moving, swinging, pendulum, rideable, timing · sink sinking, floating, weight, rideable, timing · fan lift, updraft, air, vertical, traversal. Tags by look: cartoon cartoon, bright, rounded, toon-outline · scifi scifi, metal, neon, glowing · fantasy fantasy, stone, wood, gold, magic · pixel pixel, retro, blocky, voxel · realistic realistic, industrial, muted, metal, concrete · industrial industrial, factory, steel, rust, hazard-stripes · nature nature, wood, leaves, moss, organic.

Settings (platformsKit.Platform)

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

fielddefaultused bywhat it does
kindpathallWhat the platform does (the 19 above).
lookcartoonallWhat it looks like (the 7 above).
sizeX, sizeY, sizeZ0allWidth, thickness (ladder/rope: height or length; mushroom: total height) and depth in metres. Use these rather than scaling the entity.
pathemptypath, pingpong, elevatorThe points it travels to after its start, relative to the platform and turned with it. In the editor they show as yellow dots and lines.
speed0path, pingpong, elevator, conveyor, rotate, seesaw, swing, sink, fanm/s; degrees/s for rotate; how fast a seesaw responds; pace for swing (1 = a real pendulum); sinking speed for sink; rising speed for fan.
wait-1path, pingpong, elevator, rotate, crumble, fallSeconds it waits at each stop / each end / between turns, or how long it holds after a touch before it breaks or falls.
offset0all timed kindsSeconds to shift it along its cycle, so several of the same kind take turns.
triggerautopath, pingpong, rotate, elevatoralways (runs on its own), step (one run when someone steps on it), button (one run when someone presses its button stand). auto is the kind's default: elevators use buttons, everything else runs always.
axisautorotatey, x or z.
beat, onBeats, offBeats0, 0, -1beatSeconds per beat, beats there, beats gone.
power0spring, mushroom, rope, swing, sink, fanLaunch height in metres (spring, mushroom); how hard pushing pumps a rope (1 = normal); chain length (swing); how deep it sinks (sink); how high the air takes you (fan).
respawn0crumble, fallSeconds before it comes back.
slide-1ice0 (grippy) to 1 (no grip).
slow-1stickyYour speed as a fraction of normal.
tilt0seesaw, swingThe most a seesaw tips, or how far a swing swings each way, in degrees.
buttonOffsetunsetelevator, button triggerWhere the call / trigger button stands, relative to the platform (and to each floor). Unset = 1.5 m past the elevator's +X side, or beside a triggered platform.
activetrueallOff: it rests at its start and does nothing to players.

Methods on the component: settings() (every setting with defaults filled in: a table { sx, sy, sz, speed, wait, power, tilt, trigger, stops, ... }), pose() / poseAt(t) (where the moving part is, relative to the platform: { pos, rot, scale }), isSolid() (true or false), press(floor?), touch(), rebuild() (build its look again from its settings), parts() ({ mover, root, colliders, handles }, for tests), handle().

local p = PK.get(lift)                -- the component on a platform entity
print(p:settings().speed)             --> 2.2
print(p:isSolid())                    --> true
print(p:poseAt(PK.now() + 1).pos.y)   --> where the car will be in a second (metres above its start)

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")

Every call, what you get back, and a tiny example. A platform can be passed as its entity, its entity id or its component.

  • PK.spawn(kind, look?, opts?) returns the new platform's entity (named after the catalog, e.g. "Cargo Hoist"). opts: position, rotation (quaternion), yaw (degrees about the up axis, the easy way to turn a platform), name, parent, synced (spawn it on every machine at runtime; its settings replicate), temporary, plus any setting above (path = { {x=,y=,z=}, ... }, speed, trigger, ...). look defaults to "cartoon".
    local lift = PK.spawn("elevator", "industrial", { position = { 6, 0.2, 0 } })
    print(lift.name)   --> Cargo Hoist
    
  • PK.setKind(platform, kind), PK.setLook(platform, look) return nothing; the platform rebuilds at once as the other kind or look, keeping every other setting. Setting the kind / look field does the same on the next frame.
    PK.setLook(lift, "nature")      -- the Cargo Hoist becomes the Treetop Lift
    
  • PK.get(platform) returns the Platform component, or nil when there is none.
    print(PK.get(lift).kind)   --> elevator
    
  • PK.list(filter?) returns a list of rows { key, kind, look, name, kindLabel, lookLabel, tags, description }, one per kind x look. filter: a kind ("rope"), a look ("pixel"), any other word (a tag like "bounce" or part of a name), or a table { kind?, look?, tag? }.
    print(#PK.list("pixel"))                    --> 19 (every kind in pixel)
    print(PK.list({ kind = "rope" })[1].name)   --> Licorice Rope
    
  • PK.catalog.get(kind, look) returns one row (or nil); PK.catalog.markdown() returns the whole list as a markdown table (a string).
    print(PK.catalog.get("swing", "fantasy").name)   --> Dungeon Swing Slab
    
  • PK.press(platform, floor?) returns nothing: it presses the platform's button from code (starts a step/button run, or calls an elevator to floor; floors count from 1, the ground floor).
    PK.press(lift, 2)    -- the car comes to floor 2
    
  • PK.on(platform, fn) returns a connection (call :Disconnect() to stop). fn(event, data) runs on every machine for the platform's shared events: touch, go, call (data.floor), grab / release (data.avatar), bounce.
    local c = PK.on(myCrumble, function(ev, data) if ev == "touch" then print("it's going!") end end)
    c:Disconnect()
    
  • PK.standingOn() returns two values: the entity id of the platform the local player stands on and its kind, or nil when they stand on no platform.
    local id, kind = PK.standingOn()
    if kind == "ice" then print("careful!") end
    
  • PK.now() returns a number: seconds on the shared clock platforms move on. PK.clockInfo() returns a table { offset, rtt, synced, isHost, pings, peers }: how this machine keeps time with the host. On the host, peers[peerId].error is how far each other machine's clock is from it, in seconds (a platform moving at v m/s is |error| x v metres apart on the two screens).
    print(PK.now(), PK.clockInfo().synced)   --> 812.4  true
    
  • PK.netStats() returns a table { sent, received, platforms, greeted } (message counters).
    print(PK.netStats().sent)
    
  • PK.setDetail("full" / "lite") returns nothing (placed platforms rebuild at once); PK.detail() returns "full" or "lite". See Phones and the browser.
    PK.setDetail("lite"); print(PK.detail())   --> lite
    
  • PK.setDrawDistance(metres) returns nothing; PK.drawDistance() returns a number (default 130). Past this a platform is not drawn at all.
    PK.setDrawDistance(60); print(PK.drawDistance())   --> 60
    
  • PK.all() returns a list of every Platform component in the world.
    print(#PK.all())
    
  • PK.setOutlines(on) returns nothing; PK.outlines() returns true or false (default true): whether cartoon platforms draw their toon outline. The engine draws that rim through floors and walls, so switch it off when cartoon platforms sit under or behind other geometry.
    PK.setOutlines(false)
    
  • PK.setVolume(v) returns nothing; PK.volume() returns a number from 0 to 1 (default 0.6): how loud the kit's sounds are on this machine. 0 turns them off. Each player can choose their own.
    PK.setVolume(0.3); print(PK.volume())   --> 0.3
    
  • PK.safetyNet(belowY?, opts?) returns the SafetyNet entity (it spawns one, or updates the one already there). Below world height belowY (default -30) a player is put back on the last solid ground they stood on, or on opts.respawnAt ({ x, y, z }).
    local net = PK.safetyNet(-20)
    
  • PK.KINDS, PK.LOOKS are lists of names; PK.VERSION is a string ("1.6.4"); PK.motion is the pure motion maths (platformsKit.motion).
    print(#PK.KINDS, #PK.LOOKS, PK.VERSION)   -->  19  7  1.6.4
    
-- 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.2, 0 },
    path = { { x = 0, y = 5, z = 0 }, { x = 0, y = 10, z = 0 } } })

-- a swinging deck over a gap, two sinking logs and a fan up to a high ledge
PK.spawn("swing", "industrial", { position = { -6, 2, 8 }, yaw = 90 })
PK.spawn("sink", "nature", { position = { 0, 1, 12 } })
PK.spawn("sink", "nature", { position = { 0, 1, 16 } })
PK.spawn("fan", "scifi", { position = { 4, 0, 20 }, power = 8 })

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
fielddefaultwhat it does
belowY-30World height below which a falling player is put back.
respawnAtunsetWhere to put them. Unset = the last solid ground they stood on (or where they first appeared).
activetrueSwitch the net on or off.

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() (a number: how many times this machine's player was caught), safePoint() ({ x, y, z } where a fall would put them now, or nil), setSafePoint(p).

Sounds and effects

Every platform plays its moments on every machine that can see them: a crumble's creak and crack, a falling slab's alarm and drop, the pop when something comes back, a spring's boing and a mushroom's bloop, a rope's grab and the whoosh as you let go, a fan's rush of air, a sinking float's gloop, the tick before a beat block switches, and a lift's ding when it arrives. Each sound is synthesised on the machine from a short recipe voiced by the platform's look, so the kit carries no sound files. Sounds play in play mode only, get quieter with distance from the camera and fade out past 30 m. PK.setVolume(0) turns them off on that machine.

The visual effects (dust, smoke, sparkle on respawn, a landing puff) come from juiceKit, drawn in the closest of its looks.

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. That covers swings too. Seesaws and sinking platforms are the exceptions: each machine tilts or sinks them 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, swings, 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, a sinking float) 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, ropes and fans set the upward speed through the controller's own jump (a jump whose jumpForce is the speed wanted) and switch gravity off while climbing, swinging or riding the air. 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. Industrial is built on the realistic shapes and nature on the fantasy ones, each with its own palette, materials and signature parts (hazard stripes, bolts and beacons; logs, moss, leaves and fireflies). Platforms far from the camera keep their state but skip drawing work.
  • Sounds (platformsKit.sounds) are rendered once per machine the first time they are needed and mixed into one audio stream; nothing about them is sent over the network.

Tests

zero tests run platformsKit (or tools.use("tests", "run", "platformsKit")) in edit mode: 107 tests in 21 groups covering the catalog (19 kinds x 7 looks) (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, a call stand flush with the deck around it still found as the stand, the 1.6.0 additions (the industrial and nature looks' palettes and shapes, swing, sink and fan building in every look with the parts they animate, every falling platform's warning frame hidden until touched, the swing's pendulum and level deck, the sink and updraft maths, the spring curve, a fresh swing, sink and fan getting the documented defaults, every sound rendering in every look and differing between looks, sounds only in play and at the volume each machine picks, and the README's tables of kinds and defaults matching the catalog), the two guides (in the package, opening by their paths, their own links and juiceKit's opening with only this kit installed, no long dashes), 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 with real input in a brand-new world with only this kit installed (1.5.0, and again for 1.5.4), pasted exactly as printed: holding forward 2 s, the spring threw the player 7.5 m up and they landed on the ledge. For 1.6.0 the new kinds were played in the showcase gallery with the real player: on a swing the rider stayed on the deck every frame for 4 s, 1.0 cm above it, carried 4 m back and forth; a sinking float went 1.2 m down in 2 s and rose back once they stepped off; a fan carried them to hover 6.0 m above it; a rope with no yaw, run into along +Z, swung along +Z and let go on a jump; a platform 0.2 m high was walked onto and one 0.25 m high stopped the player at its edge. In an earlier stand-in for a new world, the spring landed you on the ledge whether you held forward 1.3 s or 2 s, the ferry carried you 8 m out and back, the stone broke under you and came back, and the rope swung and let 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.
  • 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.
  • 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.
  • Two engines signed in to one account are one player (engine issue #14448). To try two players, sign the second engine or browser tab in to another account. It is also why another player riding a moving lift has not yet been measured on a second screen: two sessions of one account collide as one player. Each player is carried by their own machine, and platforms and shared events agree on every machine (measured with two machines up to 1.2.0).
  • Lower frame rate in a web browser (engine issue #20750). The gallery, with about 140 platforms, ran at 21 to 28 fps in a Chrome tab. Platforms keep their place on the shared clock and riders stay on lifts at any frame rate, but a level with many platforms in view costs more in a tab than in the desktop editor: PK.setDetail("lite") and PK.setDrawDistance help.
  • The browser check is done by a person (engine issue #20946). An agent's engine can't start a browser engine of its own, so the browser results (the gallery loads, a moving platform carries the browser's player, a crumbling one breaks and comes back on both machines) come from a person playing in Chrome on 1.2.0. Releases since were checked in the desktop editor; the kit uses no desktop-only calls.
  • Installing takes a while (engine issue #21420). One install brings the kit with juiceKit, Trapline and the four kits Trapline is built on (about 550 files), and installs with several dependencies are slow. Let it finish before pressing Play.
  • ZeroMind's search text can lag a release (engine issue #19258). For a while after a new version, the description in search results can be the previous version's. This README and package.yaml are current.
  • A change to a kit that came with this one can't be sent to that kit's own world (engine issue #23047). juiceKit, Trapline and the kits Trapline is built on arrive in your world with the platformsKit install. If you change one of those copies, zm pr create opens the pull request on this kit's world instead, and aiming it at the kit's own world answers "nothing ahead of this origin". If you mean to change Trapline, install Trapline on its own first: platformsKit then adds only itself, and a change to Trapline goes to Trapline's world.

In the kit

  • One-way platforms can't be dropped through from above.
  • Seesaws and sinking platforms disagree slightly between machines while players move on them (each machine tilts or sinks them from the bodies it sees, which arrive a moment late); they settle to the same angle and depth.
  • Sounds don't pan. They get quieter with distance from the camera but play from the middle, not from the left or right.
  • 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, and comes with this kit; the example guide shows it).
  • Only platforms up to 0.2 m above the ground can be walked onto (0.25 m already stops the built-in player at the edge); place higher ones where players jump. Springs taller than that 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: ten rows of challenges you ride, climb, swing, float and jump through (225 platforms), with a catch floor and lifts underneath. Play it with friends.

Version history

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

What's new in 1.6.4

  • Same kit as 1.6.3, with its version stated the same everywhere: PK.VERSION, package.yaml and this README all say 1.6.4 (1.6.3 was published straight from the merge of pull request #6, whose PK.VERSION and README still said 1.6.2). Use 1.6.4 rather than 1.6.3.

What's new in 1.6.3

  • Effects keep working in a world that installs juiceKit itself as well as this kit. The Platform component now reaches juiceKit by its name (~juiceKit.juice) instead of by the folder this kit's install puts it in, so it finds juiceKit wherever it is installed: crumbling, falling and spring platforms no longer lose their effects with [platformsKit] effects are off, and zm push of such a world is no longer refused with dep.unresolved on that line. Contributed from the Skyhook world (pull request #6, issue #5).

What's new in 1.6.2

  • A platform whose look or mover was despawned under it (a scene rebuild in the editor, another script clearing entities) builds its look again on the next frame instead of writing to entities that no longer exist every frame.

What's new in 1.6.1

Docs only: the kit behaves exactly as in 1.6.0. The READMEs of the Platform component, the catalog, the looks, the api and the test suite (what ZeroMind search shows for each) still described 16 kinds, 5 looks and 80 platforms; they now say 19 kinds, 7 looks and 133 platforms, and the api README lists every call, PK.setVolume included.

What's new in 1.6.0

Everything from 1.5.8 works as before; nothing you placed needs changing.

  • Three new kinds: swing (a deck on chains that swings like a pendulum and stays level, so you can ride it), sink (floats, sinks while anyone stands on it, floats back) and fan (an updraft that lifts you to hover above it). 19 kinds.
  • Two new looks: industrial (steel, tread plate, rust, hazard stripes, amber lamps) and nature (logs, moss, leaves, flowers, fireflies), for every kind. 7 looks, 133 named platforms, still one component: change look and a world swaps style.
  • Alive when you stand on it: crumbling platforms creak and their pieces rock apart before they break; springs and mushrooms squash, overshoot into a stretch and settle; falling platforms sag and flash a warning frame that blinks faster until they drop; landings puff dust; lifts ding on arrival.
  • Sounds for every moment, voiced per look (creak, crack, alarm, drop, pop back, boing, bloop, ding, grab, whoosh, gloop, tick), synthesised on each machine, so there are no sound files to install. PK.setVolume(v) / PK.volume().
  • Ropes swing the way you jump into them. No more turning a rope with yaw so it swings toward players (it still works if you do).
  • Docs: every call in the README lists what it returns with a tiny example; "Your first platform" is three steps; the Kinds table states measured timings (a ping-pong covers 8 m in about 4 s, a lift 6.8 m in about 3 s). The how-to's first platform was 0.4 m high, which the built-in player cannot walk onto (it stops at the edge from 0.25 m up); it is 0.2 m now, and the "up to 0.3 m" rule is corrected to 0.2 m.
  • 107 tests in 21 groups, all passing.

What's new in 1.5.8

Docs only: the kit, its settings and its tests behave exactly as in 1.5.5.

  • The README's call table says the same as the how-to guide: PK.standingOn() returns two values, the platform's entity id and its kind (local id, kind = PK.standingOn()), or nil. Checked in play: standing on the gallery's Cryo Plate (ice) and riding the Bubblegum Cruiser (path), it returned that platform's entity id and its kind on every frame sampled.
  • 1.5.6 is withdrawn (see below); if you installed it, update.
  • 97 tests in 20 groups, the same as 1.5.5.

What's new in 1.5.7

Docs only: the kit, its settings and its tests behave exactly as in 1.5.5.

  • The how-to guide describes PK.standingOn() as it is: it returns two values, the platform's id and its kind (it said { id, kind }).
  • 97 tests in 20 groups, the same as 1.5.5.

1.5.6 (withdrawn)

Published from the first revision of a contributed pull request. Besides the PK.standingOn() fix that 1.5.7 kept, it changed the example guide's install order to Trapline, platformsKit, scoreKit, pickupsKit, saying pickupsKit is refused in the original order. That was a mistake, withdrawn by its author: the refusal came from a world whose dependency folders had been deleted by hand, and in a new world the original order (Trapline, platformsKit, pickupsKit, scoreKit) installs all four. 1.5.7 and later have the original order. Update from 1.5.6.

What's new in 1.5.5

Docs only: the kit, its settings and its tests behave exactly as in 1.5.4.

  • Known limits name engine issue #23047: a change to juiceKit, Trapline or a kit Trapline is built on, in the copies that came with platformsKit, can't be sent as a pull request to that kit's own world. The limit says where it goes instead, and how to install Trapline so its changes reach Trapline's world.
  • The showcase gallery's saved scene now holds the sun its sky sets, so opening this world no longer shows an unsaved edit on the gallery.
  • 97 tests in 20 groups, the same as 1.5.4.

What's new in 1.5.4

Docs only: the kit, its settings and its tests behave exactly as in 1.5.3.

  • First example: left and right were swapped. Facing the way you spawn (+Z), +X is on your left, so the crumbling stone (x = 4) is on your left and the rope (x = -4) on your right. The code is unchanged; its comment and the walkthrough now say so.
  • Example guide: the flag, the campfire and the elevator's call stands are at the left edge of the decks as you walk (x = 1.4); the guide said right. The drop is described as it is built, its top 4 m below the ground.
  • How-to guide: the note that another player can look sunk or floating on a fast lift is gone; that was engine issue #18595, fixed in the engine (see 1.5.0).
  • Known limits now name every open engine issue that affects the kit: #14448 (one account, one player), #20750 (browser frame rate), #20946 (browser check by a person), #21420 (slow installs) and #19258 (search text lags a release) are new there.
  • 97 tests in 20 groups, the same as 1.5.3.

What's new in 1.5.3

Update from 1.5.2: its test suite does not load, and its example level's end wall can be jumped onto.

  • The test suite loads again. In 1.5.2 every module and component name in platformsKit.testSuite had been cut down to platformsKit, so zero tests run platformsKit ran nothing and reported one load failure. The names are back: 97 tests in 20 groups, passing.
  • The example guide's end wall is 2 m above the deck. In 1.5.2 it rose 1.25 m, about what the built-in player can jump: a running jump at it reached its top, so a player could land on the wall and drop off the far side into the drop. Three running jumps at the 2 m wall all stop at the wall. The guide now says what the wall is for under "What each part does".
  • README: the Tests section counts 97 tests in 20 groups and names the call-stand test.
  • The rider, the elevator call stands and everything else are the same as 1.5.2.

What's new in 1.5.2

  • A call stand level with a deck now calls the elevator. A stand's top is level with its floor's stop, so on a floor where the car stops level with a deck (the usual build, and the example guide's) the stand is flush with the deck, and the rider's ground probe could report the deck instead of the stand: stepping on it did nothing. The probe now prefers a registered call button level with whatever it found first. Played: a player on the example level's upper deck stepped on the top stand and the car came up from the ground in 3 seconds; before, it stayed down.
  • The example guide's top call stand is on the deck now: buttonOffset = { x = 1.4, y = 0, z = 2.2 } on the elevator. Left at its default, the top stand floated in the air beside the shaft, out of reach of anyone on the 4 m deck.
  • The example guide's goal deck ends in a low wall, so running through the star no longer carries you off the end of the deck and costs a heart right after you win (made higher in 1.5.3).
  • One new test checks that a hit on a deck flush with a stand is traded for the stand, and a deck clearly above it is kept (the suite did not load in this version; fixed in 1.5.3).

What's new in 1.5.1

  • The example guide, fixed by following it word for word in a new world: the spikes on the upper deck use cycle = 3, so they stay down long enough to cross at walking speed, and the guide says to wait a step back from them; step 2 says to walk off the elevator straight away, because a rider who stays on the car at the top is taken back down. With both, the level was played through with real input: coins, elevator, flag, spikes, both falling platforms, campfire, moving platform, saw and star (score 50 to 160, three hearts left).
  • Install says what one call brings now: juiceKit and the whole Trapline 1.5.2 (whose part helpers build the looks) with the kits Trapline is built on. If your world already has Trapline, install it first and platformsKit adds only itself.
  • 96 tests, the same as 1.5.0.

What's new in 1.5.0

  • Two guides in the package (see Guides): a how-to, "How to add moving platforms, elevators and falling platforms to my game", and an example, "Make a platformer level with elevators, moving platforms and falling platforms", which builds a short level with Trapline, pickupsKit and scoreKit. The example was followed word for word in a new world, played with real input.
  • Built on the current kits: Trapline 1.5.2 and juiceKit 1.2.8.
  • Engine issue #19350 is fixed in the engine: a scene saved by an older version of the kit now rebuilds cleanly after an update. Replayed on this world's gallery as it was saved before the 1.4.1 repair (the exact scene that failed then): it rebuilt with all 143 platforms and its SafetyNet. The four-step fix that stood here is no longer needed and is gone, and so is the limit.
  • Engine issue #18595 is fixed in the engine (other players drawn sunk or floating on moving lifts), so it is no longer a known limit. Each player is carried by their own machine as before; a fresh two-player measurement on a lift is still to be done.
  • Install: the note about no root to resolve against from Trapline's own dependencies (#19188 in Trapline's README) is gone; Trapline 1.5.2 installs without those errors.
  • 96 tests.

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).
  • A rebuild fix after updating (engine issue #19350, since fixed in the engine; see 1.5.0) ended with a second scene.save, which made 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).