Skyhook
- ..
- .metadata138 B
- Checkpoint.component
- Course.component
- Hazard.component
- KillZone.component
- LivesDisplay.component
- README.md34.8 KB
- Runner.component
- api.module
- catalog.module
- checkpoints.module
- deps.module
- displays.module
- guides
- hazards.module
- hazardsGround.module
- hazardsMotion.module
- killZones.module
- package.yaml1.2 KB
- parts.module
- trapline.testSuite
README.md
Trapline 1.5.8
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. A cartoon, fantasy, sci-fi or pixel game each has at least two kill zones and two lives displays of its own style to pick from.
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 (9) | 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), sea cartoon (cartoon water with a shark fin), clouds cartoon (a drop to the clouds far below), thorns fantasy (a bramble wall), plasma sci-fi (a crackling plasma pool), pixelvoid pixel (a black pit with a blocky rim), pixelfence pixel (a red and white warning fence) |
Trapline.LivesDisplay (12) | hearts cartoon, counter cartoon, balloons cartoon, potions fantasy, shields fantasy, candles fantasy, pips sci-fi, battery sci-fi, holo sci-fi, tokens pixel, pixelhearts pixel, arcade pixel |
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.
Guides
Two guides ship inside this package, in Trapline.package/guides/, and install with it. Open them in the editor's Docs panel (search "Trapline"), with the guides tool by the path in the link, or ask your agent for them by name:
- How to add checkpoints, traps and lives to my game: the how-to, for someone who just found the kit. What it is and what to do first, checkpoints and coming back at your last one, traps and falling off the map, lives and the game over screen with Try Again, restarting a run, how it behaves with several players, and switching any part to another look with its one setting.
- Make an obstacle course game with checkpoints, traps, lives and a game over screen: the example. An empty world becomes a short obstacle run with three checkpoints, spikes and other traps, a fall-off edge, a lives counter and game over, plus coins from pickupsKit, a finish time from scoreKit, a title, pause and game over flow from menusKit, and the reached checkpoint and best time saved with saveKit, so Continue on the title screen takes you back to your last checkpoint. Every step of it was followed in a new world before release.
What's new in 1.5.8
- One health stack. Trapline reaches Lifeline (spawn points, the respawn picker) through SecondWind's new
HK.base()instead of requiring it beside SecondWind, so health has one line of ownership: Trapline, then SecondWind, then Lifeline (which comes with SecondWind). Needs SecondWind 1.4.8. - barsKit loads only when it draws. The
heartsandpipslives displays load barsKit the first time one is drawn; a course with another display (or none) never loads it.displays.hasBarsKit()is now a call.
What's new in 1.5.7
- A Course with
lives = 0gives unlimited lives: a death sends you back to your checkpoint and never ends in game over (the lives display stays at 0 lives left).
What's new in 1.5.6
- On the current kits. Trapline is now built and tested on SecondWind 1.4.5, Lifeline 1.0.4, MatchFlow 1.3.2, juiceKit 1.2.10 and barsKit 1.4.5, so installing it no longer brings the older releases of those kits alongside the current ones. Nothing else changed.
What was new in 1.5.5
- Tests run wherever Trapline is installed. Its tests find the package's own files wherever it is installed (at /source, or under /source/deps when another package installs it). In a world where platformer3dKit installed it, 10 of its tests failed because they read README.md, package.yaml and source files from a fixed /source/Trapline.package path. The check that this world runs exactly the dependency builds named below now asks for that exact build only in Trapline's own world; elsewhere the world decides the build (an @builtin upgrade repins it, another package pins its own), so it asks for the same version.
What's new in 1.5.4
- A checkpoint that draws nothing:
look = "none"builds no checkpoint model and animates nothing per frame, while touching it, its order, coming back at it and its events work as with any other look. For games that draw their own checkpoint (a 2D sprite, say); it costs next to nothing. It is not one of the catalogue looks, so counts and look cycling are unchanged. Trapline.depsreports the copies Trapline runs.D.check()reads each kit through Trapline's own pinned reference instead of looking the kit up by name, so a world that also holds another copy of a kit (another install's, or an older one an earlier install left behind) no longer reads as running the wrong version.- One version everywhere: package.yaml,
TL.VERSION, the catalogue and this README all say 1.5.4.
What was new in 1.5.2
- A clearer description on ZeroMind: what the kit gives you, its four styles, and that one install brings the kits it is built on. The kit itself is the same as 1.5.1.
What was new in 1.5.1
1.5.0 was out for a few minutes with the example guide's course turned round the wrong way; 1.5.1 is the release, with the guide as it was played through in a new world.
- Six more kill zones and eight more lives displays, so every style has a few of its own. Kill zones: a cartoon
seawith a circling shark fin, a cartooncloudssky drop, a fantasythornsbramble wall, a sci-fiplasmapool, a pixelpixelvoidpit and a pixelpixelfence. Lives displays: cartoonballoonsthat pop, fantasypotions,shieldsandcandles, sci-fibatteryandholo, and pixelpixelheartsand anarcade"1UP REST x 03" counter. Each is the same component with a differentlook, so a world swaps between them with that one setting. - On the current kits. Trapline is now built and tested on SecondWind 1.4.4, MatchFlow 1.3.1, juiceKit 1.2.8 and barsKit 1.4.3 (Lifeline 1.0.1 as before), so the how-to now links those kits' own guides, SecondWind's arena example included, and they open in the Docs panel.
- The first example starts in view. In a scene made from the player template the camera looks down -Z when you press Play, so the first example now runs that way, with each checkpoint turned round so you come back facing the run. Before, it was built behind you. (A new world's own main scene faces +Z, which is where the example guide's course runs.)
- Lighter to edit. While you edit, the previews of checkpoints, hazards and kill zones move at 15 frames a second instead of every frame, spread over frames; a level full of Trapline parts no longer slows the editor down.
- A kill zone over the spawn is named. If a kill zone covers a player spawn (easy to do with the default 40 m box at the origin), Trapline warns once, by name, instead of players losing lives as they appear.
- Clearer docs. The README and the how-to say that R and Enter for Try Again only work once you have clicked into the game view, and the example guide says why it picks each setting and kit.
- The showcase: the four pads at the start are one per style (cartoon, fantasy, sci-fi, pixel); step on one for its look and again for the next. A new stretch of the walk crosses a bridge between the six new kill zones, and the finish gate now celebrates with confetti and a card with your time and lives.
What was new in 1.4.2
- Every link in the how-to guide opens. Its links to SecondWind's, juiceKit's and barsKit's guides pointed at guides that only those kits' newer releases have, so with the versions Trapline comes with (SecondWind 1.2.0, juiceKit 1.2.1, barsKit 1.2.0) they opened nothing. They now open those kits' READMEs, for exactly the versions Trapline installs.
- SecondWind's arena guide is pointed to. Build a small arena game with health bars, hit markers and respawn ships with SecondWind 1.3.0 and later, not the 1.2.0 Trapline comes with, so the how-to links SecondWind's page on ZeroMind, where it can be read, and says which version it is written for.
- The example guide links each kit's own example game: pickupsKit's coin and gem collecting game, scoreKit's arcade game, menusKit's pause menu game and saveKit's save slots, level unlocks and Continue game, next to their how-to guides. They open once the example's Step 2 has installed those kits.
- A test opens every link in both guides: Trapline's own guides, the READMEs of the kits Trapline ships with, a web page, or (in the example only) a guide of one of the four kits the example installs.
What was new in 1.4.1
1.4.0 was published for a short time during this release's checks, with an earlier draft of the example guide. 1.4.1 is the release: the same kit, with the example guide as it was played through in a new world.
- Two guides inside the package (see Guides above): a how-to and a step-by-step example game.
- Checked again on the current engine. The four bugs fixed in 1.2.0 and 1.3.0 were played again, twice each: the lives display pads read in full from the start, GAME OVER says "Lives lost: 3" after every Try Again, the player template is never in the runner list (with a second player's body present), and Try Again sends a living player back to the start.
- Installing is quick and exact again. Checked today, an install of 1.3.0 into a new world timed out on ZeroMind (it couldn't work out what to bring). This world now keeps each of the five kits as one install pinned to the commit its version came from, and an install of 1.4.0 into a new world took under 3 seconds and brought exactly the versions in Dependencies.
- A test that no longer depends on child order. One test compared a hazard's parts in the order the engine lists an entity's children, which the current engine does not keep the same between two identical builds. It now compares them sorted. The kit itself didn't change for it.
What was new in 1.3.0
- Try Again is a clean run. The deaths count (
deathsinTL.state, on theTrapline.Runnerand 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 separatelostThisRuncount 1.2.0 added next to it is gone: readdeaths. - 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()andTL.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=0438275b43fd883e671f167f8b438f696e97c5be57badbda526881ed12a6d244 (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.4.8 | caf5bbdf206dd5813040a7728f7a4bcd2afd76fbe2b352fecc810c2c6a45c868 | all damage, death and respawn, and the kill feed |
| Lifeline | 7b85ce05-3903-4374-b654-2d4ffea295a5 | 1.0.4 | 602a98c6e5202bd52ed60e275e11d06ca336dbdc9ce41507a4edc76c5acc8edf | health under SecondWind, spawn points and the respawn picker; comes with SecondWind, and Trapline reaches it through SecondWind (HK.base()) |
| MatchFlow | 31cf13b4-df7d-4888-85e2-7947a7301614 | 1.3.2 | d2122b6ce481e3f483d17139b400f01d8a5e48e382d4c740c63bfad8554dc352 | SecondWind's rounds and countdowns |
| juiceKit | eed55f6d-afaf-4767-83c5-539ef91e0dc5 | 1.2.10 | 98b784aedeb338392db0d7112c2d2896d1b927737d8c461059f063bfd47d52bd | checkpoint, death and respawn effects |
| barsKit | c154eb07-ce7c-48ca-8232-4ce1a8754214 | 1.4.5 | 09133dec0da4eebdac79ebaa403a1dcff1cd84ae9df0dd5730b59a37708d50a2 | 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:
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.
-- Ahead is -Z, the way the player template's camera looks when you press Play,
-- and each checkpoint is turned round so you come back facing the run.
local TURN = { 0, 1, 0, 0 }
entity.spawn("Spikes", { position = { 0, 0, -5 } }).component.add(HAZARD, { look = "spikes" })
entity.spawn("Flag", { position = { 3, 0, -8 }, rotation = TURN }).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 }, rotation = TURN }).component.add(CHECKPOINT, { look = "campfire", order = 2 })
entity.spawn("Laser", { position = { 0, 0, -22 } }).component.add(HAZARD, { look = "laser" })
Pasting it into a new world's own scenes/main.scene instead? That scene's camera looks down +Z, so drop the minus signs from the z positions and leave out rotation = TURN.
Press Play. Three hearts sit in the top-left corner.
- 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.
- Touch the flag: it runs up its pole, and "CHECKPOINT!" shows.
- Get caught by the saw, which runs back and forth across the path: you come back at the flag, not at the start.
- 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.
- Time the laser grid: walk through while its beams are off.
- 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. R and Enter only work once you have clicked into the game view; right after Play the keyboard still belongs to the editor, so click the game once or use the button.
- 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: checkpointsmarker/light/pad; hazardsstatic/moving/timed/fall; displaysicons/counter/bar;style:cartoon,fantasy,scifi,pixel(the kill zone isminimal);- a
description, plusbefore/afterfor checkpoints, anddamageType,sizeandcyclefor 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, or any of the twelve: hearts, counter, balloons, potions, shields, candles, pips, battery, holo, tokens, pixelhearts, arcade), 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.
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. |
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.Runneron 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
environmenttype 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 thelifeLostevent, whosedamageTypecarries 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 toTL.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].errorsays 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, andTL.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 69 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 at every count from full to none and right after a life is lost, and that each of the cartoon, fantasy, sci-fi and pixel styles has at least two kill zones and two lives displays;
- 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.viewandTL.views(what each machine sees, bad and stale reports dropped),TL.checkpoints(in course order) andTL.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;
- the two guides: each is there with a description, each links the other, this README links both, and every link in them opens something with the kits Trapline ships with (or, in the example, the kits it installs).
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
graceseconds, 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.
- Two engines signed in to one account are one player (#14448). To try two players yourself, sign the second engine or browser tab in with another account; with the same account, both bodies count as the same player and share one set of lives.
- The web build runs at a lower frame rate (#20750). Moving traps animate every frame; Trapline skips animating any part more than 45 m from the camera, which keeps a long course cheap, but a scene with many traps close together costs more in a browser tab than in the editor.
- The browser check is done by hand (#20946). An agent can't start a browser engine itself, so the web build of this release is checked by a person opening the world in a browser tab; everything here was played in the native editor.
- ZeroMind's search text lags a release (#19258). For a while after a new version, the description ZeroMind shows in search results is the one from the previous README.