Log inGet started
World

Save Point: Profiles, Levels and Unlocks Kit

README.md

Trapline 1.3.0

Checkpoints, traps and lives for platformers, obstacle courses and runners, in any Zero world, multiplayer-safe.

  • Touch a checkpoint and it becomes where you come back.
  • Fall off the map or get caught by a trap and you lose a life and reappear at your last checkpoint.
  • Run out of lives and it's game over for you, with a Try Again button.

Every player's progress is their own: when you die you go back to your checkpoint and lose your life, and nobody else's lives or checkpoint change. Every player sees the traps move in step.

It is built on the kits it needs, not beside them. SecondWind does all damage, death and respawn and writes the kill feed ("Kai was killed by Spinning saw"), Lifeline places respawns, juiceKit plays checkpoint, death and respawn effects, and barsKit draws the heart and pip displays.

Every part has one setting, look, that picks what it is. Change it, in the editor or with TL.setLook, and the part turns into another one. A world-wide theme switches every checkpoint and lives display left on auto.

partlooks
Trapline.Checkpoint (6)flag cartoon, campfire fantasy, beacon sci-fi, crystal fantasy, bell pixel, teleporter sci-fi
Trapline.Hazard (12)spikes cartoon, lava fantasy, saw cartoon, axe fantasy, crusher sci-fi, laser sci-fi, electric sci-fi, poison fantasy, rocks cartoon, flame pixel, pit pixel, water cartoon
Trapline.KillZone (3)invisible minimal (a boundary you can't see), abyss fantasy (a visible void you'd fall into), grid sci-fi (a glowing out-of-bounds wall)
Trapline.LivesDisplay (4)hearts cartoon, counter cartoon, tokens pixel, pips sci-fi

The world this kit comes from opens on a showcase walk with every checkpoint, hazard, kill zone and lives display labelled, which you can play with friends.

What's new in 1.3.0

  • Try Again is a clean run. The deaths count (deaths in TL.state, on the Trapline.Runner and on the body's health) goes back to 0 on every Try Again, together with lives going back to full. GAME OVER's "Lives lost" shows that count, so it reads 3 after every run with 3 lives, however many runs you play. The separate lostThisRun count 1.2.0 added next to it is gone: read deaths.
  • Every kit at its exact version. Trapline now names the exact version of each of the five kits it is built on (see Dependencies), and installing Trapline brings those versions, the same ones this world runs. 1.2.0 could bring a newer juiceKit (1.2.2) than the 1.2.1 it was built and tested with. require("Trapline.deps").check() says what a world runs of each kit.
  • More tests: 65 in the package, including deaths going back to 0 over three runs and every kit's version.

What was new in 1.2.0

  • Installing is one call, with no order to follow.
  • Try Again sends you back to the start (or the checkpoint) with full lives and health whether or not you're dead.
  • TL.runners() lists real players only, never the player template (TL.isTemplate(body)).
  • TL.view() and TL.views() report who sees whom across machines.
  • The showcase's lives display pads read in full from the start.

What was new in 1.1.0

  • The kill feed names the hazard ("Kai was killed by Spikes"), and the hazard's own effect still plays on every screen.
  • Kill zones have looks (invisible, abyss, grid).
  • The first example shows four hazards and two checkpoints.
  • Each network event is heard once, and the host can check the trap clock with TL.clockInfo().peers.
  • The showcase signs read from both sides, and no long dashes anywhere.

Install

One call:

zeromind_install guid=57c0995a-9ba8-4e5a-a7ca-341e8706c7c1 (Trapline)

That's all. Trapline brings the five kits it is built on with it, each at the exact version in Dependencies, under /source/deps/. Your scripts reach everything through Trapline.api and the Trapline.* components.

To also call a kit from your own scripts (require("SecondWind.api")), install it at the same version in a call of its own, before or after Trapline, with ref set to its build in the table below: for example zeromind_install guid=5da0a53c-5953-4adc-80fb-f5afb02f6568 ref=b4d09185914eb616f27f72be39922ca4dc37299a6cd22e4f294fd48b5c7a696f (SecondWind 1.2.0).

The copies under /source/deps/ hold a few components Trapline doesn't use (Lifeline's projectile and HUD, the MatchFlow component, older copies of SecondWind's parts), which log no root to resolve against while the world loads. Trapline doesn't touch them, and play isn't affected.

Dependencies

Trapline is built and tested on exactly these versions, and an install of Trapline brings exactly these:

kitZeroMind idversionbuildwhat Trapline uses it for
SecondWind5da0a53c-5953-4adc-80fb-f5afb02f65681.2.0b4d09185914eb616f27f72be39922ca4dc37299a6cd22e4f294fd48b5c7a696fall damage, death and respawn, and the kill feed
Lifeline7b85ce05-3903-4374-b654-2d4ffea295a51.0.1c8e3fae2509c6d43d83025965736044d08b22e7a3eceb38299b2f169648f860ahealth under SecondWind, spawn points and the respawn picker
MatchFlow31cf13b4-df7d-4888-85e2-7947a73016141.0.04c6c52e78d35aa0d72807cf1ad132ade8166e5c3b2eb33436e4b93b1f1db3578SecondWind's rounds and countdowns
juiceKiteed55f6d-afaf-4767-83c5-539ef91e0dc51.2.1afe4c446348275f6b6df1610b1541ac189eadb2fe3480247f05af71db8ddc968checkpoint, death and respawn effects
barsKitc154eb07-ce7c-48ca-8232-4ce1a87542141.2.0868543f79d202c16670ae30034a2964fce64a68a4f2f171a385ea458f759c996the hearts and pips lives displays

SecondWind, Lifeline and MatchFlow are required. juiceKit and barsKit are optional: without juiceKit there are no effects, and without barsKit the hearts and pips displays draw Trapline's own hearts and pips. A newer version of a kit may work, but these are the versions Trapline is checked on.

require("Trapline.deps") holds this table (D.kits), and D.check() says what your world runs of each kit and whether it is this exact version (matches).

First example

A scene made from the engine's player template (scene.create("course", "player")), like the one this example was checked in, builds its player in its build.luau with local body = entity.spawn("body", { parent = prototype }). Paste this at the end of content(), after the player setup:

local TL = require("Trapline.api")
local HAZARD = asset.resolve("Trapline.Hazard", "component")
local CHECKPOINT = asset.resolve("Trapline.Checkpoint", "component")

-- Lives and SecondWind health for every player who joins.
TL.attach(body)

-- Your lives in the top-left corner, and the game over screen.
entity.spawn("Lives").component.add(asset.resolve("Trapline.LivesDisplay", "component"), { look = "hearts" })

-- A short run straight ahead of the spawn: four hazards and two checkpoints.
entity.spawn("Spikes", { position = { 0, 0, 5 } }).component.add(HAZARD, { look = "spikes" })
entity.spawn("Flag", { position = { 3, 0, 8 } }).component.add(CHECKPOINT, { look = "flag", order = 1 })
entity.spawn("Saw", { position = { 0, 0, 11 } }).component.add(HAZARD, { look = "saw" })
entity.spawn("Lava", { position = { 0, 0, 16 } }).component.add(HAZARD, { look = "lava" })
entity.spawn("Campfire", { position = { 3, 0, 19 } }).component.add(CHECKPOINT, { look = "campfire", order = 2 })
entity.spawn("Laser", { position = { 0, 0, 22 } }).component.add(HAZARD, { look = "laser" })

Press Play. Three hearts sit in the top-left corner.

  1. Walk forward onto the spikes: you lose a heart, the kill feed says you were "killed by Spikes", and you come back where you started.
  2. Touch the flag: it runs up its pole, and "CHECKPOINT!" shows.
  3. Get caught by the saw, which runs back and forth across the path: you come back at the flag, not at the start.
  4. Cross the lava (go round it, or lose a heart and come back at the flag) and touch the campfire: it lights, and it is your checkpoint now.
  5. Time the laser grid: walk through while its beams are off.
  6. Lose your third heart: GAME OVER, "Lives lost: 3". Press Try Again (or R / Enter) and you start a clean run: three hearts, and the deaths count back to 0.
  7. Walk off the edge of the ground: falling below Course.fallLimitY (-25 m) costs a life too.

To turn the spikes into an electric floor, change one word: look = "electric".

With no further setup:

  • 3 lives each;
  • back 1.5 s after a death, with 1.5 s of spawn protection;
  • checkpoints count forward only;
  • Try Again starts a clean run from the start: full lives and health and a deaths count of 0, whether you are out of lives or not.

A Trapline.Course changes any of it (see Settings).

Without TL.attach, a player who touches a hazard or checkpoint is given Trapline at runtime (Course.autoSetup). TL.attach in the build is still the better way, because it puts health on the body before anyone joins.

Switching looks

TL.setLook(spikes, "lava")                -- any Hazard, Checkpoint or LivesDisplay; same as setting `look`
TL.setTheme("pixel")                      -- every part whose look is "auto": bells, 1-UP tokens
TL.find({ kind = "hazard", style = "scifi" })   -- crusher, laser, electric
TL.find({ kind = "hazard", family = { "moving", "timed" } })
TL.catalog()                              -- everything, labelled, with descriptions

Every catalog entry carries:

  • kind: checkpoint, hazard, killZone, livesDisplay;
  • family: checkpoints marker/light/pad; hazards static/moving/timed/fall; displays icons/counter/bar;
  • style: cartoon, fantasy, scifi, pixel (the kill zone is minimal);
  • a description, plus before/after for checkpoints, and damageType, size and cycle for hazards.

TL.find refuses an unknown key or kind by name, so a typo never just returns nothing.

Settings

Trapline.Hazard

fielddefaultwhat it does
lookspikesWhat the hazard is (the 12 above).
sizeX/Y/Z0Footprint in metres; 0 takes the look's own size. +Z is the front (the flamethrower blasts along +Z; the saw runs and the axe swings along X).
cycle-1Seconds per loop for moving and timed looks; -1 is the look's own, 0 is always on. Spikes pop up and down when cycle is above 0.
offset0Seconds to shift it along its loop, to stagger a row of the same trap.
damage00: touching it costs a life. Above 0: this much SecondWind damage per hit instead.
interval1Seconds between hits when damage is above 0.
grace-1Seconds you can stay in before it gets you; -1 is 3 s of breath for water, 0 for everything else.
labelnoneIts name in the kill feed and the "-1 LIFE" message; empty uses the look's name.
active, playersOnlytrue, trueSwitch it off; let it catch non-players with SecondWind health too.

Hits use the look's SecondWind damage type, so you see SecondWind's effects: fire from lava, sparks from saws, poison bubbles, electric arcs. Method: hazard:isDeadly(body, t?).

Trapline.Checkpoint

fielddefaultwhat it does
lookautoOne of the 6 looks, or auto to follow the theme.
order0Its place along the course. With forwardOnly, touching one with a lower order than yours does nothing. Leave every order at 0 and the latest one touched counts.
labelnoneIts name in "CHECKPOINT!" and "Back at … in 1.5".
radius, height1.5, 3How close counts as touching it.
restoreLivesfalseRefill lives when reached.
previewbeforeWhich state to show while editing (before or after).

You come back just in front of it (its +Z side, facing the way it faces), or on it for the teleport pad. Each machine draws checkpoints as its own player has reached them.

Trapline.LivesDisplay (one per scene, plain entity)

look (auto, hearts, counter, tokens, pips), anchor (topLeft, topCenter, topRight, bottomLeft, bottomRight), size, offsetY, showGameOver, showMessages ("-1 LIFE", the respawn countdown, "CHECKPOINT!"), showBreath (bubbles under deep water), visible.

Trapline.KillZone

A box of sizeX × sizeY × sizeZ (default 40 × 4 × 40) centred on its entity. Anyone who enters it loses a life, whatever it looks like. Pick the look with look:

lookstylewhat you see
invisible (default)minimalNothing in play; a see-through red box while editing (showInEditor = false hides that too). Put it under a level to catch falls.
abyssfantasyA black shaft at the top of the box with drifting violet mist, rising motes and a glowing brink. Put it in a gap in the floor, with its top just under floor level, so players see the drop.
gridsci-fiA glowing red holographic grid on every side, with a scan line sweeping up it: a visible out-of-bounds wall.

label names it in the kill feed; empty uses the look's own (a fall, the abyss, the out-of-bounds field). Also active and playersOnly. Falling below Course.fallLimitY costs a life with no zone at all.

local gap = entity.spawn("Gap", { position = { 0, -2.3, 30 } })
gap.component.add(asset.resolve("Trapline.KillZone", "component"), { look = "abyss", sizeX = 8, sizeY = 4, sizeZ = 4 })
TL.setLook(gap, "grid")   -- one setting turns it into a glowing wall

Trapline.Course (optional, one per scene, on a synced entity)

fielddefaultwhat it does
lives3Lives each player starts with and gets back after game over.
respawnDelay1.5Seconds between losing a life and coming back.
fallLimitY-25Falling below this costs a life.
thememixedmixed, cartoon, fantasy, scifi, pixel: the look of every auto part.
forwardOnlytrueCheckpoints only count going forward.
restartFromstartWhere Try Again (and TL.restart) puts you, dead or alive: start or checkpoint.
spawnProtection1.5Seconds you can't be hurt after coming back.
autoSetuptrueGive players Trapline at runtime when the world didn't call TL.attach.
feedbacktruePlay the juiceKit effects.
local course = entity.spawnSynced("Course")
course.component.add(asset.resolve("Trapline.Course", "component"), { lives = 5, theme = "scifi" })

Trapline.api

local TL = require("Trapline.api"). A player argument takes a body entity, a component or an entity id.

callwhat it does
TL.attach(body, opts?)SecondWind health (if missing, set to come back only when Trapline says) and a Trapline.Runner. opts: lives, health, team, displayName.
TL.state(player){ lives, maxLives, checkpoint, checkpointLabel, checkpointOrder, gameOver, deaths, respawnIn, breath, dead, alive, name }. deaths is the lives lost in this run: 0 at the start and again after every Try Again, and what GAME OVER shows.
TL.reach(player, checkpoint, opts?)Make it their checkpoint, as if touched. opts.force ignores forward-only.
TL.clearCheckpoint(player)Back to the start.
TL.hit(player, info?)A hazard hit: { label, type, damage, origin, knockback, by, force }. No damage means it costs a life.
TL.loseLife(player, cause?)Take a life now, even through spawn protection.
TL.setLives(player, n, max?), TL.addLife(player, n?)Change lives (an extra life, a 1-UP).
TL.restart(player)Try Again, a clean run: full lives and health, deaths back to 0, and back to the start (or the checkpoint, with restartFrom = "checkpoint"), whether the player is dead or still alive.
TL.returnToCheckpoint(player)Put a living player back at their checkpoint without costing a life.
TL.respawnPoint(checkpoint){ position, rotation } where players come back.
TL.hasReached(player, checkpoint)On the player's own machine.
TL.on(event, fn)checkpoint, lifeLost, respawned, gameOver, restarted, livesChanged, or "*". They fire on every machine. Returns a connection with :Disconnect().
TL.setLook(part, look), TL.setTheme(theme), TL.resolveLook(kind, look)Switch looks.
TL.catalog(), TL.find(query), TL.looks(kind)Browse what the kit offers.
TL.now(), TL.clockInfo()The shared clock traps run on, and how this machine is synced to it.
TL.view(), TL.views()What this machine sees (every real player's body: owner, lives, checkpoint, whether it is drawn here), and what each other machine last said it sees, by peer id.
TL.runner(player), TL.runners(), TL.checkpoints(), TL.course(), TL.rules(), TL.localPlayer()Lookups. TL.runners() lists real players only, never the player template.
TL.isTemplate(body)Is this the body inside a PlayerPrototype (the template each joining player is copied from), not a real player?
TL.capsuleBox, TL.capsuleSphere, TL.capsuleDiscShape tests, for your own hazard looks.

Modules: Trapline.catalog (the data), Trapline.hazards with hazardsGround and hazardsMotion (each look's build, animate and danger), Trapline.checkpoints, Trapline.killZones, Trapline.displays (D.render(look, info) for your own UI), Trapline.parts (shape helpers).

Your own hazard look

Add an entry to a hazards module: { build(root, cfg) -> h, animate(h, cfg, t, dt), danger(cfg, t, cap) -> boolean }. t is the shared clock, so make animate and danger depend only on t. Then every player sees the same thing, and the danger matches what they see. The contract is written at the top of Trapline.hazards.

Multiplayer

  • Progress is per player. Lives and checkpoint live in a Trapline.Runner on each player's own body, which only that player's machine changes. The fields are synced, so everyone can read everyone's lives.
  • Each machine tests only its own player against hazards, kill zones and checkpoints. A hit goes through SecondWind on that machine, so a death, its effects and the kill feed reach everyone through SecondWind. The hit that takes a life goes in as SecondWind's environment type with the hazard's name, because that is the type SecondWind's feed names a cause for ("Kai was killed by Lava"); every machine then draws the hazard's own effect (flames, sparks, bubbles) from the lifeLost event, whose damageType carries the hazard's real type.
  • One respawn per player. Trapline gives Lifeline a respawn picker (Lifeline.setSpawnPicker). When SecondWind brings a body back, Lifeline asks Trapline where to put it, and the answer is that player's own checkpoint. If your world sets its own picker, set it after Trapline loads and fall back to TL.respawnPoint.
  • Traps move in step. Moving and timed hazards run on TL.now(), the host's clock. Each machine asks the host for the time (trapline:ping/trapline:pong) and keeps the answer with the shortest round trip. A hazard's pose and its danger depend only on that time, so every machine shows the same blade in the same place, and the danger matches what each player sees.
  • Events go to every machine on trapline:evt. Each carries an id, and a machine hands each id to its listeners once, so an event that arrives twice (a hot reload while playing leaves an extra network listener behind) is still heard once.
  • Clock check: on the host, TL.clockInfo().peers[peerId].error says how far each other machine's trap clock is from the host's, in seconds.
  • Who sees whom: every 3 s in play, each machine sends what it sees on trapline:view: every real player's body, its owner, its lives and checkpoint as that machine reads them, and whether it is drawn there. TL.views() on any machine lists the other machines' reports by peer id, and TL.view() is this machine's own, so one machine can check that everyone sees everyone and agrees on their progress.
  • Players' lives are their own business. As with SecondWind, a modified client could lie about its own lives. Trapline doesn't try to stop that.

Tests

tools.use("tests", "run", { suite = "trapline" }) runs 65 tests. They cover:

  • every catalog label and filter;
  • that every hazard look builds, animates, is deadly where it looks deadly and safe elsewhere;
  • that timed hazards switch on and off, and that a pose depends only on the shared time;
  • that every checkpoint looks clearly different before and after;
  • that every lives display draws;
  • the shared clock's maths, and the host's per-machine clock report;
  • that every event is delivered once however many times it arrives;
  • checkpoints, forward-only and per-player checkpoints;
  • life lost, respawn, game over and Try Again (dead or alive, from the start or the checkpoint, with full lives and health), the deaths count going back to 0 on every Try Again over three runs, and that one player's death leaves another's lives alone;
  • switching looks and themes;
  • the kill feed naming the hazard, and a hurting hazard keeping its own damage type until the hit that kills;
  • TL.returnToCheckpoint (with and without a checkpoint), TL.runners (and that it leaves player templates out), TL.view and TL.views (what each machine sees, bad and stale reports dropped), TL.checkpoints (in course order) and TL.localPlayer;
  • every kill zone look, and switching kill zones with one setting;
  • the five kits: each named with its id, version and build here and in Trapline.deps, and this world running exactly those versions;
  • this README's first example (at least three hazards, every name it uses), the version, an issue number on every platform limit, and no long dashes anywhere in the package.

They drive temporary dummies by hand, far from the scene.

Two-player play was checked live for 1.2.0, with the world playing on two computers (another computer hosting, the native editor joining), using TL.view() and TL.views() to read what each machine saw:

  • each machine drew both players' bodies, and both agreed on who owned which;
  • the editor's player lost a life and touched the Flag: 2 lives, Flag, on both machines, while the other player stayed at 3 lives with no checkpoint on both;
  • the other player was then hit from the editor through SecondWind: their own machine took the life (3 to 2, back at the start, "was killed by" in the kill feed), and the editor's player stayed at 2 lives and the Flag.

Known limits

  • The pit doesn't cut a hole in your floor. It draws a deep shaft and takes a life when you step into it. To make players really fall, leave a gap in the floor under it, or use a KillZone.
  • Deep water is wading, not swimming. Trapline doesn't add swimming: under water you walk on the bottom while your breath runs out over grace seconds, with bubbles on screen.
  • Hazards don't block movement. They have no colliders: a crusher won't stop you walking under it, it just takes a life if it lands on you.