# motion The pure maths of every platform: vectors and quaternions, path and ping-pong poses with waits and easing, triggered runs, stepped rotation, beat on/off state, crumble and fall phases, the elevator's call queue (deterministic, whatever order calls arrive in), seesaw and rope-swing steps, and launch speed for a jump height. Every function takes settings and a time and returns a pose, so every machine asking for the same time gets the same answer. Used by the Platform component and the tests.

# clock The shared clock every platform moves on: the host's real-time clock, read on every machine (the other machines ping the host and keep the offset of the fastest answer). `Clock.now()` is seconds on it, `Clock.tick()` keeps it in step (platforms call it each frame), `Clock.info()` reports the offset and round trip. Real time, so a local slow-motion effect never puts one machine's platforms behind.

# rider What platforms do to the LOCAL player, through the normal built-in `CharacterController` only: it finds what the player stands on each frame, carries them with a moving/turning platform, pushes (conveyor), rewrites movement intent (ice, sticky), sets upward speed through the controller's own jump (springs, ladders, ropes), switches gravity off while climbing or swinging, and puts every changed controller field back the frame no platform asks for it. Also holds the Interact control while button platforms exist.

# net Shared platform events: a crumble or fall being touched (`touch`), a step/button run starting (`go`), an elevator call (`call`), a rope grab and release, and the cosmetic `bounce`. Each is stamped with the shared clock and sent to every machine; every machine keeps the same sorted set per platform, so they fold to the same result. A late joiner asks the host for a snapshot. `Net.send`, `Net.state(key)`, `Net.on(key, fn)`, `Net.reset(key?)`, `Net.stats()`.

# looks Builds what a platform looks like for every kind in every look (cartoon, scifi, fantasy, pixel, realistic) out of the engine's primitive meshes, using Trapline's part helpers. Parts are temporary local child entities, never saved into the scene. `L.build(kind, look, base, mover, cfg)` returns the handles the Platform component animates (coil, cap, stripes, chunks, glows, call stands). Also the edit-mode path markers and button stands.

# catalog Every platform kind and look the kit offers, as data: the 16 kinds with their default sizes, speeds and tags (`C.KIND`), the 5 looks (`C.STYLE`), and the 80 named kind x look rows. `C.list(filter)` browses them by kind, look, tag, a word of the name or a table `{ kind, look, tag }`; `C.get(kind, look)` returns one row; `C.markdown()` prints the whole list. Used by the Platform component for defaults and by `platformsKit.api` (`PK.list`).

# 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: ```lua 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. | kind | what it does | defaults | |---|---|---| | `path` | Moves 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 | | `pingpong` | Goes 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, waits 1 s | | `rotate` | Turns 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 | | `seesaw` | Tips 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 | | `crumble` | 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, 0.8 s, back after 3 s | | `fall` | Drops away (riders go down with it) `wait` s after someone touches it, floats back `respawn` s later. | 2.6 x 0.4 x 2.6 m, 0.35 s, back after 3.5 s | | `spring` | Launches 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 | | `mushroom` | A 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 | | `conveyor` | Carries 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 | | `oneway` | Solid from above only: jump up through it from below and land on top. | 4 x 0.25 x 2.2 m | | `beat` | There for `onBeats` beats, gone for `offBeats`, on a shared beat of `beat` seconds. `offset` makes rows take turns. It blinks before it goes. | 2.6 x 0.4 x 2.6 m, 0.6 s, 3 on, 3 off | | `ice` | Slippery: 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 | | `sticky` | Goo: you walk at `slow` times your speed and jump lower. | 7 x 0.45 x 3 m, 0.4 | | `elevator` | Travels 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. `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, waits 1.5 s | | `ladder` | Walk 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 | | `rope` | Hangs from its position. Jump into it to grab on, push to swing, jump to let go and fly. It swings along its local X axis: give it `yaw = 90` (or a rotation) so it swings toward the way players run at it. | 5 m long | ## Looks | look | style | |---|---| | `cartoon` | Rounded candy shapes in bright colours with a dark toon outline. | | `scifi` | Dark brushed metal with glowing cyan and magenta trim. | | `fantasy` | Old stone and timber, moss and gold, with a little magic glow. | | `pixel` | Chunky blocks in flat retro colours, every edge stepped. | | `realistic` | Muted steel, concrete, rubber and timber; no glow. | ## 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. | kind | cartoon | scifi | fantasy | pixel | realistic | |---|---|---|---|---|---| | `path` | Bubblegum Cruiser | Hover Shuttle | Floating Isle | Pixel Lift | Steel Cargo Platform | | `pingpong` | Toybox Glider | Mag-Rail Sled | Wizard's Raft | 8-Bit Shuttle | Industrial Carriage | | `rotate` | Pinwheel Spinner | Rotor Bridge | Windmill Beam | Pixel Propeller | Turntable Girder | | `seesaw` | Candy Seesaw | Balance Beam MK-II | Troll Scale | Pixel Teeter | Timber Seesaw | | `crumble` | Cookie Crumble | Unstable Hexplate | Ancient Ruin Slab | Brittle Brick | Cracked Concrete | | `fall` | Jelly Dropper | Grav-Fail Panel | Cursed Flagstone | Falling Block | Rusty Drop Slab | | `spring` | Boing Spring | Gravity Launcher | Rune Leap Stone | Pixel Spring | Coil Spring Pad | | `mushroom` | Bouncy Toadstool | Bio-Gel Mushroom | Fairy Ring Cap | Pixel Shroom | Bracket Fungus | | `conveyor` | Sushi Belt | Plasma Conveyor | Millstone Walk | Arrow Belt | Rubber Belt | | `oneway` | Cloud Ledge | Hardlight Ledge | Vine Bridge | Pass-Through Brick | Scaffold Plank | | `beat` | Disco Tile | Phase Block | Spirit Stepping Stone | Blink Block | Strobe Grate | | `ice` | Frosty Slab | Cryo Plate | Glacier Shelf | Ice Block | Sheet Ice | | `sticky` | Bubblegum Pad | Gluon Field | Swamp Moss | Slime Block | Tar Patch | | `elevator` | Gumball Lift | Grav Elevator | Dwarven Lift | Pixel Elevator | Freight Elevator | | `ladder` | Candy Ladder | Maintenance Ladder | Vine Ladder | Pixel Ladder | Aluminium Ladder | | `rope` | Licorice Rope | Energy Tether | Jungle Vine | Pixel Chain | Hemp Rope | 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`. | field | default | used by | what it does | |---|---|---|---| | `kind` | `path` | all | What the platform does (the 16 above). | | `look` | `cartoon` | all | What it looks like (the 5 above). | | `sizeX`, `sizeY`, `sizeZ` | 0 | all | Width, thickness (ladder/rope: height or length; mushroom: total height) and depth in metres. Use these rather than scaling the entity. | | `path` | empty | path, pingpong, elevator | The 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. | | `speed` | 0 | path, pingpong, elevator, conveyor, rotate, seesaw | m/s; degrees/s for rotate; how fast a seesaw responds. | | `wait` | -1 | path, pingpong, elevator, rotate, crumble, fall | Seconds it waits at each stop / each end / between turns, or how long it holds after a touch before it breaks or falls. | | `offset` | 0 | all timed kinds | Seconds to shift it along its cycle, so several of the same kind take turns. | | `trigger` | `auto` | path, pingpong, rotate, elevator | `always` (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. | | `axis` | `auto` | rotate | `y`, `x` or `z`. | | `beat`, `onBeats`, `offBeats` | 0, 0, -1 | beat | Seconds per beat, beats there, beats gone. | | `power` | 0 | spring, mushroom, rope | Launch height in metres; for a rope, how hard pushing pumps the swing (1 = normal). | | `respawn` | 0 | crumble, fall | Seconds before it comes back. | | `slide` | -1 | ice | 0 (grippy) to 1 (no grip). | | `slow` | -1 | sticky | Your speed as a fraction of normal. | | `tilt` | 0 | seesaw | The most it tips, in degrees. | | `buttonOffset` | unset | elevator, button trigger | Where the call / trigger button stands, relative to the platform (and to each floor). Unset = beside it. | | `active` | true | all | Off: it rests at its start and does nothing to players. | 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")` | call | what it does | |---|---| | `PK.spawn(kind, look?, opts?)` | Spawn a platform. `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, so it is the same platform everywhere), `temporary`, plus any setting above (`path = { {x=,y=,z=}, ... }`, `speed`, `trigger`, ...). Returns the entity. | | `PK.setKind(platform, kind)`, `PK.setLook(platform, look)` | Turn a placed platform into another kind or look, at once. Setting the `kind` / `look` field does the same on the next frame. | | `PK.get(platform)` | The Platform component on an entity (entity, id or component). | | `PK.list(filter?)` | Every kind x look row: `{ key, kind, look, name, kindLabel, lookLabel, tags, description }`. `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? }`. | | `PK.catalog.get(kind, look)`, `PK.catalog.markdown()` | One row; the whole list as a markdown table. | | `PK.press(platform, floor?)` | Press a platform's button from code (start a step/button run, or call an elevator to a floor). | | `PK.on(platform, fn)` | Hear its shared events on every machine: `touch`, `go`, `call` (data.floor), `grab` / `release` (data.avatar), `bounce`. Returns a connection with `:Disconnect()`. | | `PK.standingOn()` | The platform the local player stands on (entity id and kind), or nil. | | `PK.now()`, `PK.clockInfo()` | The shared clock platforms move on, and how this machine keeps time with the host. On the host, `clockInfo().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. | | `PK.netStats()` | `{ sent, received, platforms, greeted }`. | | `PK.setDetail("full" / "lite")`, `PK.detail()` | How much every platform draws; placed platforms rebuild at once. See Phones and the browser. | | `PK.setDrawDistance(metres)`, `PK.drawDistance()` | Past this a platform is not drawn at all (default 130). | | `PK.all()` | Every Platform component in the world. | | `PK.setOutlines(on)`, `PK.outlines()` | Whether cartoon platforms draw their toon outline (default on; placed platforms rebuild at once). The engine draws that rim through floors and walls, so switch it off when cartoon platforms sit under or behind other geometry. | | `PK.safetyNet(belowY?, opts?)` | Catch players who fall off the level: spawns a `SafetyNet` (or updates the one 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 }` or `{ x, y, z }` list). Returns the entity. | | `PK.KINDS`, `PK.LOOKS`, `PK.VERSION`, `PK.motion` | Constants and the pure motion maths. | ```lua -- 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: ```lua 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 ``` | field | default | what it does | |---|---|---| | `belowY` | -30 | World height below which a falling player is put back. | | `respawnAt` | unset | Where to put them. Unset = the last solid ground they stood on (or where they first appeared). | | `active` | true | Switch 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()` (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): ```lua 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 `BoxCollider`s 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).