Log inGet started
World

Pathwise: Navigation and Crowd Agents Kit

README.md

SecondWind 1.3.1

Health, damage, death and respawn for any multiplayer game, in one component. Give players, enemies and breakable props health with one call, hurt them with another, and choose everything else with a setting: six health displays (a plain HP bar, a regenerating shield, armour, Zelda-style hearts, lives, or downed-then-revive), eight damage types with flames, sparks and numbers every player sees, eight death styles, teams and friendly fire, a kill feed in five looks, traps, and genre presets from shooter to party game, all labelled in a catalog you can filter by genre and visual style. Built on Lifeline (health, bars, numbers) and MatchFlow (countdowns, rounds), and multiplayer-safe.

Guides

Two guides ship inside the package, so they are in your world as soon as SecondWind is installed:

  • How to add health and damage to my game (SecondWind.package/how-to-add-health-and-damage-to-your-game): what the kit is, which health model to pick and when, how damage carries who caused it, its type and its team (and friendly fire), death and the respawn styles, the events a game can listen to, how it behaves in multiplayer, what to do first, and how barsKit, markersKit, weaponsKit, turretsKit, Trapline, pickupsKit, spawnerKit and aiKit fit with it.
  • Build a small arena game with health bars, hit markers and respawn (SecondWind.package/build-a-small-arena-game-with-health-bars-hit-markers-and-respawn): from an empty world to a multiplayer arena with SecondWind, barsKit and markersKit: players with health and a health bar, training dummies with bars over their heads, lava, spikes and a shock pad, hit markers and damage numbers for whoever lands a hit, death and respawn, and a kill feed. Every step explains why.

Open one with the guides tool (path = the name in brackets), with man in the shell, or from the Docs panel.

What's new in 1.3.1

  • No long dashes left in the package. The comment at the top of each code file used one; those are colons now. The test that checks for them now reads every file in the package, code and tests included, and names the file and line of any it finds. Only comments changed, so nothing behaves differently.
  • The showcase gallery in the Second Wind world shows the kit again. Its saved scene held every SecondWind component at its default settings: every dummy ran plain hit points and the timed respawn, nameplates and the kill feed showed entity names such as Model_hearts and Death_ragdoll, and the title sign said v1.2.0. Rebuilding did not fix it: the build set the right values, and the saved components kept their defaults. Removing the 41 entities that carry a SecondWind component and building again created them fresh with the build's settings, and the scene was saved that way. Now each model dummy runs its own model, each death dummy dies its own way, names read "Hearts" or "Ragdoll Kai", the feed reads "Nova burned Instant Kai", and the sign shows the current version. The gallery belongs to this world, not to the package, so a world that installs SecondWind gets the values its own build gives, as before.
  • If your own scene's SecondWind components show default settings after an update (for example a scene saved with healthKit 1.1.x, before the 1.2.0 rename, which is the likely cause here), do what fixed the gallery: delete the entities your build.luau gives SecondWind components to, then save build.luau or call layers.active.asset:build(). The build creates them again with your settings.

Every call, setting, event, preset and network channel works as in 1.3.0.

What's new in 1.3.0

  • Install in one call. zeromind_install guid=5da0a53c-5953-4adc-80fb-f5afb02f6568 is all a new world needs. It brings Lifeline and MatchFlow with it, and SecondWind now finds them where they land, so the second install call that 1.1.3 to 1.2.0 asked for is gone. Checked in a brand-new world: one call, then the first example below pasted as written, built and played with no errors and nothing blocking a push.
  • Two guides (see Guides).
  • A preset set on the Rules when it is created now applies in full. Before, Rules { preset = "heroShooter" } in a build gave players the preset's numbers (150 health, a 5 s respawn) but not its model, death style, kill feed look or friendly fire, because the Rules treated its starting preset as already applied; heroShooter players got a plain health bar instead of a shield. Now the Rules applies its starting preset once, on the peer that owns it, and fills only the fields you left at their defaults, so { preset = "battleRoyale", friendlyFire = false } keeps friendly fire off. Changing the preset later (HK.applyPreset, HK.setRules { preset = ... }) works as before.
  • The kill feed tells two players with the same name apart. It used to compare names to spot a self-kill, so a player knocking out another player who had the same display name read "X died". It now compares the two entities.
  • README: Known limits lists only issues that are still open, and the version history is one list.

Every call, setting, event, preset and network channel works as in 1.2.0. Upgrading from 1.2.0 needs no change to your code. A world that followed 1.2.0's two-call install can keep its Lifeline and MatchFlow; nothing needs removing.

Install and use (five minutes)

  1. Install. One call: zeromind_install guid=5da0a53c-5953-4adc-80fb-f5afb02f6568, or search ZeroMind for "SecondWind" and install SecondWind.package from the ZeroMind panel. It brings Lifeline and MatchFlow, the two kits SecondWind is built on, under /source/deps/, and SecondWind finds them there. There is nothing else to install. If you add kits built on SecondWind (barsKit, markersKit and the others in the guides), install SecondWind first so they use it rather than bringing a copy of their own.
  2. Set it up in your scene's build.luau. A new world's main scene (or one made with the player scene template) builds its player in build.luau with a line like local body = entity.spawn("body", { parent = prototype }). Add these lines at the end of content(), after that player setup:
local HK = require("SecondWind.api")

-- World rules + on-screen HUD (kill feed, death screen, bars). Rules must be synced.
local rules = entity.spawnSynced("HealthRules")
rules.component.add(HK.RULES, { preset = "heroShooter" })   -- or leave preset empty
entity.spawn("HealthHUD").component.add(asset.resolve("SecondWind.HUD", "component"), {})

-- Players: give the PlayerPrototype's body health. Every joining player gets it.
HK.attach(body, { team = "blue" })          -- `body` from the default player setup

-- A trap: lava that burns anyone standing in it (a 3 x 1 x 3 m box on the ground).
local lava = entity.spawnSynced("Lava", { position = { 0, 0.5, 4 } })
lava.component.add(asset.resolve("SecondWind.Trap", "component"),
	{ damageType = "fire", label = "Lava", amount = 15, sizeX = 3, sizeZ = 3 })
-- An orange slab on the ground, so you can see where the lava is.
local glow = entity.spawn("LavaGlow", { position = { 0, 0.05, 4 } })
glow.component.add("Model", { model = "cube", material = asset.resolve("@builtin::materials.plastic_white", "material"),
	tintR = 1, tintG = 0.35, tintB = 0.05, tintBlend = 1 })
glow.localScale = { 3, 0.1, 3 }

-- A dummy standing in the edge of the lava: it burns, dies, and comes back where it stood.
local dummy = entity.spawnSynced("Dummy", { position = { 1, 0.5, 4 } })
dummy.component.add("Model", { model = "cube" })
HK.attach(dummy, { model = "hearts", deathStyle = "timed", displayName = "Dummy" })
  1. Press Play. The lava is the orange slab about 4 m in front of where you start, and the dummy stands in its edge. The dummy catches fire, loses its hearts, dies, and comes back where it stood 4 seconds later, then burns again. Walk onto the slab and you catch fire too: flames, damage numbers and BURNING on screen, your shield (75, from the heroShooter preset) burning away first and then your health (150). Stay in and you die and come back at the spawn point after the death screen's countdown.

Hurting something from code is one call:

HK.damage(target, 20, { by = attacker, type = "fire", team = "red" })

Switching anything is one setting, even while the game runs:

HK.setModel(target, "shield")         -- or hearts, lives, downed, armor, hitPoints
HK.setDeathStyle(target, "spectate")  -- or instant, timed, wave, ragdoll, dissolve, remove, stay
HK.applyPreset("battleRoyale")        -- the whole world at once

HK.catalog() lists everything below, with descriptions and labels.

Picking from the catalog

Every entry (model, damage type, death style, feed look, preset) carries these labels:

labelvalues
kindhealthModel, damageType, deathStyle, feedLook, preset
familyhealth models: pool, counted, secondChance. Damage types: direct, elemental, world. Death styles: respawn, deathAnimation, outOfPlay. Feed looks: killFeed. Presets: competitive, adventure, cooperative, casual
genresa list from shooter, heroShooter, battleRoyale, adventure, roguelike, rpg, coop, survival, platformer, party
hasLooktrue when the entry draws something of its own
stylefor entries with a look: minimal, scifi, fantasy, cartoon, pixel (a preset takes the style of its kill feed look)
local HK = require("SecondWind.api")

HK.find({ kind = "preset", genre = "coop" })                 -- { coopRevive entry }
HK.find({ kind = "feedLook", style = { "pixel", "cartoon" } }) -- any of the listed values
HK.find({ kind = "healthModel", family = "counted" })        -- hearts, lives
HK.find({ genre = "roguelike" })                             -- everything that suits a roguelike

for _, p in HK.find({ kind = "preset", genre = "battleRoyale" }) do
	print(p.id, p.family, p.style, table.concat(p.genres, ", "))
end

HK.vocabulary()  -- { kinds, families, genres, styles }, each word with a label and description

Every key is optional and takes one value or a list (any of them matches). An unknown key or kind is an error that names the valid ones, so a typo never just returns nothing. SecondWind.catalog also offers C.filter(kind, query) for one kind (a kind id like "preset" or a list name like "presets").

What it offers

Health models (model)

idwhat it does
hitPointsOne health bar.
shieldA shield soaks damage first and recharges after shieldRegenDelay seconds without a hit. Electric damage does double to shields.
armorAn armour pool absorbs armorAbsorb of each physical, fire, ice, electric or explosion hit and wears down. Poison, fall and environment damage go around it.
heartsZelda-style hearts with half hearts (one half heart = 10 HP). Every hit costs at least half a heart and rounds up to whole half hearts.
liveslives lives, each with a pool of lifeHealth. Emptying a pool spends a life and refills it. Losing the last life is death.
downedA lethal hit knocks you down instead. You crawl at reduced speed and bleed out over bleedOutTime. A living teammate who stands within reviveRadius for reviveTime picks you up.

Damage types (type)

idbehaviourlooks like
physicalA plain hit.white sparks
fireKeeps burning for a few seconds after the hit. Ice puts it out.rising flames; burning targets trail embers
poisonStacks up to 5. Each stack ticks every second, and a new hit refreshes them. Goes around armour.poison bubbles; poisoned targets trail bubbles
iceSlows the target to half speed for a few seconds. Puts out fire.ice shards; chilled targets trail frost
electricChains to up to 3 nearby targets at 60% damage. Double damage to shields.electric sparks and arcs to each chained target
explosionFalls off with distance and knocks targets back (HK.explode).an expanding explosion shell
fallTaken automatically when landing faster than Rules.fallSafeSpeed. Goes around armour.landing dust
environmentLava, spikes, acid: the world itself (SecondWind.Trap). Goes around armour.red spikes

Death styles (deathStyle)

idwhat happens
instantBack at a spawn point straight away.
timedBack at a spawn point after respawnDelay seconds, with a MatchFlow countdown on screen.
waveEveryone who died comes back together on the next wave, every Rules.waveInterval seconds.
ragdollThe body is flung and tumbles limp, then respawns after respawnDelay.
dissolveThe body sinks and dissolves into sparks, then respawns after respawnDelay.
spectateStays dead and watches a living player until the round ends (HK.endRound(), a MatchFlow round ending, or Rules.autoEndRound).
removeGone for good: for breakable props and one-shot enemies.
stayStays dead until a script calls HK.revive.

Presets (preset)

idmodeldeath stylefeedfriendly fire
arcadeShooterhitPointsinstantpixeloff
heroShootershield (150 HP + 75 shield)timed (5 s)scifioff
adventureHeartshearts (5)dissolvefantasyoff
roguelikeLiveslives (3 × 40 HP)ragdollpixeloff
coopRevivedowned (20 s bleed-out)waveminimaloff
battleRoyalearmorspectateminimalon
partyBrawlhitPoints, huge knockbackragdollcartoonon

Kill feed looks (feedLook)

minimal, scifi, fantasy, cartoon, pixel. Rows read like "Nova burned Kai" or "Kai was killed by Lava".

Reference

How settings resolve

For each entity, each value is taken from the first of these that sets it:

  1. The entity's own Vitals fields. A model or deathStyle of auto means "not set".
  2. The entity's own preset.
  3. For player bodies only: the world Rules (playerModel, playerDeathStyle, and the preset's tuning).
  4. For everything else: hitPoints and Rules.otherDeathStyle.

HK.config(target) returns the resolved result. A model switch keeps the current health fraction.

SecondWind.api (local HK = require("SecondWind.api"))

Every target argument accepts an entity, a component or an entity id.

callwhat it does
HK.damage(target, amount, opts?) -> ok, reasonHurt a target. opts: by, type, team, origin {x,y,z}, knockback (m/s), crit, dot, label ("Lava"), ignoreInvulnerability, status (false = no burn/poison/chill).
HK.heal(target, amount, opts?) -> ok, reasonRestore health. Hearts round up to half hearts. opts: by.
HK.kill(target, opts?) -> ok, reasonKill outright, skipping lives and downed. opts: by, type.
HK.revive(target, opts?) -> ok, reasonPick a downed target up, or respawn a dead one now.
HK.explode(pos, opts?) -> countExplosion with falloff and knockback. opts: radius (5), damage (60), by, team, knockback (10), minFalloff (0.2).
HK.attach(entity, settings?) -> VitalsAdd Lifeline.Health and SecondWind.Vitals with these settings. Use it in a build or on a freshly spawned entity.
HK.configure(target, settings) -> ok, reasonChange any Vitals settings at runtime.
HK.setModel(target, model) / HK.setDeathStyle(target, style)Switch one setting. Pass "auto" to follow the preset or the rules again.
HK.applyPreset(name, target?)With no target, sets the world preset. With a target, sets that entity's own preset.
HK.setRules(t) -> ok, reasonChange world rules, e.g. { friendlyFire = true }.
HK.endRound()End the round: spectators come back.
HK.state(target)Snapshot in the terms of its model: health, maxHealth, fraction, shield, maxShield, armor, maxArmor, hearts, heartsLeft, lives, livesLeft, downed, bleedLeft, reviveProgress, dead, deaths, respawnIn, dyingStyle, burning, poisonStacks, chilled, model, deathStyle, preset, team, name.
HK.isAlive(target) / HK.isDowned(target)Booleans. A downed target counts as alive.
HK.config(target)The resolved settings (model, deathStyle, preset, all tuning).
HK.get(target) / HK.lifeline(target) / HK.all()The Vitals, the Lifeline.Health underneath, and every Vitals keyed by id.
HK.rules() / HK.ruleValues()The Rules component, and its values as a table (defaults when there is no Rules entity).
HK.nameOf(target) / HK.isPlayer(id) / HK.idOf(x)Display name, player-body test, and id normaliser.
HK.on(event, fn) -> connListen to an event on this peer ("*" = all). conn:Disconnect() stops it.
HK.killFeed()Recent kill feed entries on this peer.
HK.setDamageFilter(fn?)fn(vitals, amount, info) -> amount, run on the owner after team checks. Return 0 to cancel.
HK.catalog()Every model, damage type, death style, preset, feed look and event, plus version and vocabulary. Every entry carries its labels.
HK.find(query?) -> { entry }Catalog entries matching labels: kind, family, genre, style, hasLook, id. Each takes one value or a list.
HK.vocabulary()The words the labels use: kinds, families per kind, genres and styles.
HK.syncReport()How health sync is doing on this peer: totals (sent, asked, served, resyncs, snapshots, evtSent, evtBatched), the entities this peer owned and the ones it watched (in sync, seconds off, latest snapshot).
HK.VERSION, HK.HEALTH, HK.RULES, HK.logicThe version string, the Vitals and Rules component assets, and the pure rules maths.

Events (HK.on)

damaged, healed, blocked (reason: immune, friendly, self, armor, dead), lifeLost, downed, revived, died, killed (a kill feed entry: killer, killerName, victim, victimName, type, text), respawned, statusApplied, chained, exploded, wave, roundEnded. They fire on every peer.

SecondWind.Vitals component

Settings: model, deathStyle, preset, team, displayName, barStyle, startFull, invulnerable, fallDamage, canRevive. Tuning: maxHealth 100, regenRate 0, maxShield 50, shieldRegenRate 20, shieldRegenDelay 3, maxArmor 50, armorAbsorb 0.66, hearts 3, lives 3, lifeHealth 30, bleedOutTime 15, reviveTime 3, reviveRadius 2, reviveHealth 0.3, respawnDelay 4, invulnerability 0.5 (i-frames after a hit), knockbackScale 1. Read-only synced state: armor, livesLeft, downed, bleedLeft, reviveProgress, reviver, respawnIn, dyingStyle, burning, poisonStacks, chilled, activeModel, activeStyle, activePreset, hitSeq, hitType, hitAmount (the last hit, for its effect), changeSeq (bumped on every health change). Methods: damage(amount, opts), heal(amount, opts), kill(opts), revive(opts). It needs Lifeline.Health on the same entity; awake adds it when missing.

SecondWind.Rules component (one per scene, on a synced entity)

preset (applied when the Rules starts, to the fields still at their defaults, and again whenever it changes), friendlyFire (off), selfDamage (on), playerModel (hitPoints), playerDeathStyle (timed), otherDeathStyle (timed), feedLook (minimal), waveInterval 10, autoEndRound (on), matchEntity ("Match", a MatchFlow entity whose round end ends the SecondWind round), maxRemoteDamage 1000, fallSafeSpeed 10, fallDamagePerSpeed 7, allowClientConfig (off). Read-only: waveIn, waveSeq, roundSeq.

SecondWind.HUD component (per peer, local)

feedLook (rules follows Rules.feedLook), showFeed, maxFeed 5, feedTime 6, showDeathScreen, showStatus, showDownedMarkers, countdownStyle (any MatchFlow countdown style; default bold), spectateSwitch 8, addLifelineHUD, autoBarStyle. Method: nextTarget() switches the spectated player.

SecondWind.Trap component

A box volume that hurts what enters it: damageType, label, amount, mode (perSecond | onEnter), interval, sizeX/Y/Z, knockback, team, by, playersOnly, active. It runs on the authority of each victim, so put it on any entity, synced or not.

Other modules

  • SecondWind.catalog: the data behind HK.catalog().
  • SecondWind.logic: pure maths (pools, armour and shield split, falloff, fall damage, team rule, feed text).
  • SecondWind.feed: render(look, entries, opts) for your own UI.
  • SecondWind.fx: burst(type, pos, amount) hit effects.

Multiplayer

  • Authority: each health is owned by the peer that owns its entity. A player's body belongs to that player, and synced world entities belong to the host. Only the owner changes health. All state is synced fields, so every peer sees the same health, deaths and respawns.
  • Remote calls: HK.damage on a target you don't own sends a request to its owner. The owner checks that you own the attacker you named, applies team and friendly-fire rules, and caps the amount at maxRemoteDamage.
  • Admin calls: configure, kill, revive and endRound from another peer are refused unless that peer owns the Rules entity or allowClientConfig is on.
  • Events: effects and events run on every peer. Events for other peers leave in batches on healthKit:evts, at most one message every 0.05 s, in the order they were raised; healthKit:evt messages from 1.1.0 peers are still received. Hit effects are drawn on the next frame from a queue, and each hit is drawn once per peer however it arrives (event or synced hitSeq).
  • State snapshots: the owner sends the full health state on the healthKit:state channel. It sends right away on every death, respawn, revive, life lost and knock-down, then again after 0.5 s and 2 s. It also sends after changes (at most once a second for players, every 3 s for others) and every 5 s regardless. Snapshots are batched, about 2 to 3 messages a second for a busy scene. A peer whose fields disagree with the last snapshot for over 0.5 s asks for a fresh one on healthKit:resync. All the kit's channels are registered when the kit loads; you do not call them yourself.

Tests

The SecondWind.secondwind test suite has 97 tests covering every public call: catalog labels and filtering, hit effects reaching peers, fall damage around death and respawn, health sync, event batching, the README's install step and first example, the package description, the 1.2.0 rename (new names, same guid, no old requires left, channels kept), and 1.3.0's starting preset, kill feed and guides (both guides ship in the package, the arena guide's settings exist on the components it sets them on, and no long dash in any file of the package, code included). Run it with tools.use("tests", "run", { suite = "secondwind" }).

Known limits

These are the open issues that still touch SecondWind:

  • #2612: a package cannot list its dependencies. package.yaml has no field for them. Installing SecondWind still brings Lifeline and MatchFlow, because SecondWind's code refers to them, and they land under /source/deps/, where SecondWind finds them.
  • #22181 and ZeroMind#3099: guides inside a published package don't show up in ZeroMind search yet. Once SecondWind is installed, its two guides open with the guides tool, man and the Docs panel (see Guides); a ZeroMind search for them finds nothing until this is fixed.
  • #19258: ZeroMind's description of SecondWind can lag one release behind for a while after a release is pushed. The package itself, this README and package.yaml are current.
  • Message rate. Lifeline, which the kit builds on and does not change, sends one lifeline:evt message for every hit, so the owner of many bodies taking damage at once still sends at least one message per hit. A peer with a low frame rate, such as a browser tab at 10 to 15 fps, drains those messages slowly, and everything sent after them waits behind them. The kit's own events are batched. Keep the number of bodies taking damage at the same moment modest, or only run them near players, as the showcase gallery does.
  • #20750: frame rate in a web browser. The kit uses only cross-platform engine APIs. The first example works in a browser tab (checked with a person on 1.1.2's code: the lava set the player on fire, the bar dropped and the dummy took damage), but plays choppily there, even in that small scene. On the native engine the same scene runs at about 19 ms a frame, of which the kit's components take about 0.5 ms; most of the rest is UI drawing, the built-in character controller and rendering.
  • #20946: the web build can't be checked from an agent's engine. 1.3.0 was checked on the native engine only. The earlier browser checks (1.1.0 to 1.1.2) were done live with a person in a browser tab.
  • #14448: two engines signed in to one account collide as one player. Test two players with two accounts. 1.3.0's two-player check ran in one engine, with a second player body beside the real one: one player knocked the other out, the kill feed credited the right player, the respawn came 3 s later at a spawn point with full health and shield, and in 23 samples the owner's health and shield matched the synced values every other peer reads.
  • Tower freeze, seen once in a browser. During a two-player test, a player in a web browser walked off the gallery's JUMP OFF platform and stayed hanging in the air, unable to move, until knocked out. It was not reproduced on the native engine, where the same walk falls and takes fall damage. Nothing in the kit was found to cause it: the kit only moves a player's body when it respawns.

Version history

  • 1.3.1: No long dashes in any file of the package, and the test for them reads the code too; the showcase gallery in the Second Wind world rebuilt so every dummy shows its own model, death style and name, and the sign the current version. No change to how the kit behaves. See What's new in 1.3.1.
  • 1.3.0: One-call install; two guides in the package; a preset set on the Rules when it is created applies its model, death style, feed look and friendly fire; the kill feed tells two players with the same name apart; Known limits lists only open issues. See What's new in 1.3.0.
  • 1.2.0: healthKit became SecondWind, with the same guid (5da0a53c-5953-4adc-80fb-f5afb02f6568). The require line is local HK = require("SecondWind.api"); the components are SecondWind.Vitals, SecondWind.Rules, SecondWind.HUD and SecondWind.Trap, the modules SecondWind.catalog, SecondWind.logic, SecondWind.feed and SecondWind.fx, and the test suite secondwind. Upgrading from 1.1.x: change healthKit. to SecondWind. in your require and asset.resolve lines. The network channels (healthKit:evts, healthKit:state and the rest) and the HUD's screen id healthkit_hud kept their names, so nothing on the wire changed. The package description became a store listing.
  • 1.1.4: The first example works as pasted: its dummy stands in the edge of the lava, on the ground, and an orange slab shows where the lava is. The world opens in the gallery again. The package description counts eight death styles and names Vitals.
  • 1.1.3: Step 1 became two install calls, as a workaround for an engine install problem that has since been fixed; 1.3.0 goes back to one call.
  • 1.1.2: Step 1 named Lifeline and MatchFlow as installs of their own (also a workaround, also gone in 1.3.0). Tests for the install instructions.
  • 1.1.1: Events for other peers leave in batches (one healthKit:evts message per 0.05 s, in order); HK.syncReport().totals counts evtSent and evtBatched. A lighter showcase gallery: dummies and damage stations only run near a player, and the host sends about 12 to 14 messages a second instead of about 46.
  • 1.1.0: A labelled catalog (HK.find, HK.vocabulary); hit effects drawn on every player's screen, also from the synced hitSeq, hitType and hitAmount; full health snapshots on every death, respawn, revive, life lost and knock-down, with resyncs; fall tracking reset on death and respawn, so a fall death no longer charges a second fall hit; gallery dummies without a {PlayerName} placeholder.
  • 1.0.0: First release: six health models, eight damage types, eight death styles, teams and friendly fire, a kill feed in five looks, traps and genre presets.