# Trapline.api The kit's public interface: TL.attach for players, per-player state (lives, checkpoint, game over), checkpoints and respawn (through Lifeline's spawn picker and SecondWind's revive), hazard hits through SecondWind, events (TL.on), the shared clock hazards run on (TL.now), switching looks and themes, and the labelled catalog (TL.catalog, TL.find). Required by every Trapline component and by game code. Full reference in the package README.

# 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`. | part | looks | |---|---| | `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: | kit | ZeroMind id | version | build | what Trapline uses it for | |---|---|---|---|---| | SecondWind | `5da0a53c-5953-4adc-80fb-f5afb02f6568` | 1.2.0 | `b4d09185914eb616f27f72be39922ca4dc37299a6cd22e4f294fd48b5c7a696f` | all damage, death and respawn, and the kill feed | | Lifeline | `7b85ce05-3903-4374-b654-2d4ffea295a5` | 1.0.1 | `c8e3fae2509c6d43d83025965736044d08b22e7a3eceb38299b2f169648f860a` | health under SecondWind, spawn points and the respawn picker | | MatchFlow | `31cf13b4-df7d-4888-85e2-7947a7301614` | 1.0.0 | `4c6c52e78d35aa0d72807cf1ad132ade8166e5c3b2eb33436e4b93b1f1db3578` | SecondWind's rounds and countdowns | | juiceKit | `eed55f6d-afaf-4767-83c5-539ef91e0dc5` | 1.2.1 | `afe4c446348275f6b6df1610b1541ac189eadb2fe3480247f05af71db8ddc968` | checkpoint, death and respawn effects | | barsKit | `c154eb07-ce7c-48ca-8232-4ce1a8754214` | 1.2.0 | `868543f79d202c16670ae30034a2964fce64a68a4f2f171a385ea458f759c996` | the 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: ```lua 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 ```lua 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` | field | default | what it does | |---|---|---| | `look` | `spikes` | What the hazard is (the 12 above). | | `sizeX/Y/Z` | 0 | Footprint 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` | -1 | Seconds 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. | | `offset` | 0 | Seconds to shift it along its loop, to stagger a row of the same trap. | | `damage` | 0 | 0: touching it costs a life. Above 0: this much SecondWind damage per hit instead. | | `interval` | 1 | Seconds between hits when `damage` is above 0. | | `grace` | -1 | Seconds you can stay in before it gets you; -1 is 3 s of breath for `water`, 0 for everything else. | | `label` | none | Its name in the kill feed and the "-1 LIFE" message; empty uses the look's name. | | `active`, `playersOnly` | true, true | Switch 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` | field | default | what it does | |---|---|---| | `look` | `auto` | One of the 6 looks, or `auto` to follow the theme. | | `order` | 0 | Its 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. | | `label` | none | Its name in "CHECKPOINT!" and "Back at … in 1.5". | | `radius`, `height` | 1.5, 3 | How close counts as touching it. | | `restoreLives` | false | Refill lives when reached. | | `preview` | `before` | Which 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`: | look | style | what you see | |---|---|---| | `invisible` (default) | minimal | Nothing in play; a see-through red box while editing (`showInEditor = false` hides that too). Put it under a level to catch falls. | | `abyss` | fantasy | A 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. | | `grid` | sci-fi | A 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. ```lua 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) | field | default | what it does | |---|---|---| | `lives` | 3 | Lives each player starts with and gets back after game over. | | `respawnDelay` | 1.5 | Seconds between losing a life and coming back. | | `fallLimitY` | -25 | Falling below this costs a life. | | `theme` | `mixed` | `mixed`, `cartoon`, `fantasy`, `scifi`, `pixel`: the look of every `auto` part. | | `forwardOnly` | true | Checkpoints only count going forward. | | `restartFrom` | `start` | Where Try Again (and `TL.restart`) puts you, dead or alive: `start` or `checkpoint`. | | `spawnProtection` | 1.5 | Seconds you can't be hurt after coming back. | | `autoSetup` | true | Give players Trapline at runtime when the world didn't call `TL.attach`. | | `feedback` | true | Play the juiceKit effects. | ```lua 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. | call | what 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.capsuleDisc` | Shape 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.