# Lifeline.api The one module scripts talk to: `damage`, `heal`, `kill`, `revive`, `fire` (projectiles), `on` (events on every peer), `get`/`all`/`isAlive`, `setDamageFilter` (owner-side validation), `setSpawnPicker`, `setStyle`. It routes requests to the owning peer over `multiplayer.send`.

# juice The juiceKit front door: `require("juiceKit.juice")`. `play(name, target, opts)` resolves a preset into its pieces, applies the global intensity, the look and reduce motion, routes each piece by scope (player pieces stay with their player, world pieces go to every peer through `net`), and returns what ran. It also holds the preset registry (`list`, `names`, `get`, `has`, `define`, `remove`), the settings (look, intensity, reduce motion), `stopAll`, `stats` and `_receive`, the handler other peers' messages arrive at. Gameplay code and the gallery call it; the package README documents every call.

# fx The hit effects, a different one per damage type: white sparks for physical, rising flames for fire, poison bubbles, ice shards, electric arcs to each chained target, an expanding explosion shell, landing dust for falls, and spikes for environment damage. Burning, poisoned and chilled entities also trail embers, bubbles or frost. Built from short-lived local entities, so every peer draws its own copy. `Fx.burst(type, pos, amount)` plays one. `Fx.enabled(false)` turns them off.

# api The one interface to SecondWind: `local HK = require("SecondWind.api")`. - **Damage:** `damage`, `heal`, `kill`, `revive`, `explode`. - **Configure:** `attach`, `configure`, `setModel`, `setDeathStyle`, `applyPreset`, `setRules`, `endRound`. - **Query:** `state`, `isAlive`, `isDowned`, `config`, `get`, `lifeline`, `all`, `rules`, `ruleValues`, `nameOf`, `isPlayer`, `catalog`, `killFeed`. - **Hooks:** `on` (events) and `setDamageFilter`. Calls on a target this peer does not own are sent to its owner, who checks them (attacker ownership, teams, the damage cap, config permission) before applying them. The package README lists every argument.

# Lifeline — health, damage & respawn kit Drop-in health for anything that can get hurt (players, enemies, breakable props), with damage zones, heal zones, projectiles, respawning, events for your own scripts, and a large wardrobe of looks: **13 health bar styles, 7 damage-number styles (4 presets) and 5 mix-and-match hit effects**, all switched by changing one field. Multiplayer-safe: only the peer that owns an entity decides what happens to its health.  ## Installing it into your world The package is called **Lifeline** — asset `Lifeline.package`, guid `7b85ce05-3903-4374-b654-2d4ffea295a5`, MIT licensed. (Its showcase world is *Lifeline — Health, Damage & Respawn Kit*.) One install, any of these ways: - **From the ZeroMind library in the editor** — search for `health` or `Lifeline` and install the **Lifeline** package. - **By guid, from the engine shell:** ``` zero zeromind installAsset 7b85ce05-3903-4374-b654-2d4ffea295a5 ``` - **From Luau:** ```lua tools.use("zeromind", "preview", "7b85ce05-3903-4374-b654-2d4ffea295a5") -- what it would write tools.use("zeromind", "installAsset", "7b85ce05-3903-4374-b654-2d4ffea295a5") -- do it ``` - **From an agent:** `zeromind.install { guid = "7b85ce05-3903-4374-b654-2d4ffea295a5" }`. It lands in your `/source` as `Lifeline.package/`, so after installing, every piece resolves by that name: `Lifeline.Health`, `Lifeline.LifelineHUD`, `Lifeline.DamageZone`, `Lifeline.HealZone`, `Lifeline.Projectile`, `Lifeline.ProjectileLauncher`, `Lifeline.SpawnPoint`, and `require("Lifeline.api")` / `require("Lifeline.bars")`. Nothing in it is world-specific — you bring the entities. Run `zeromind.update` later to pull new versions. ## Five-minute start **1. Give things health.** Add `Lifeline.Health` to the player body on your scene's PlayerPrototype, and to any enemy or prop. Put enemies and props on **synced** entities (`entity.spawnSynced`) so every player sees the same health. ```lua body.component.add("Lifeline.Health", { maxHealth = 100, regenRate = 5, maxShield = 25 }) crate.component.add("Lifeline.Health", { maxHealth = 40, onDeath = "remove" }) ``` **2. Show it.** Add `Lifeline.LifelineHUD` to one plain (non-synced) entity in the scene. Every peer runs its own copy. ```lua entity.spawn("HUD").component.add("Lifeline.LifelineHUD", { playerBar = "hearts", worldBar = "overhead" }) ``` **3. Hurt and heal.** Add a zone to any entity. It's a box of `sizeX × sizeY × sizeZ` around the entity and moves with it. ```lua lava.component.add("Lifeline.DamageZone", { sizeX = 4, sizeZ = 4, kind = "fire", amount = 5, mode = "perSecond" }) spikes.component.add("Lifeline.DamageZone", { kind = "spikes", amount = 25, mode = "onEnter" }) pad.component.add("Lifeline.HealZone", { amount = 10, interval = 0.5 }) ``` **4. From code.** ```lua local Lifeline = require("Lifeline.api") Lifeline.damage(target, 20, { kind = "fire", source = attacker, crit = false }) Lifeline.heal(target, 15) Lifeline.fire { origin = muzzlePos, direction = aim, damage = 15, source = shooter } -- projectile Lifeline.on("died", function(e) print(e.target, "died to", e.kind) end) ``` **5. Respawn.** Dead players come back after `respawnDelay` seconds at a random free `Lifeline.SpawnPoint` (or at the scene's `PlayerSpawn` if you haven't placed any), with full health and a moment of spawn protection. That's it. The `scenes.main` showcase in this world uses every piece. ## What happens on death (`onDeath`, per entity) | value | effect | |---|---| | `auto` (default) | `respawn` for players, `reset` for everything else | | `respawn` | back at a spawn point after `respawnDelay`, full health | | `reset` | back where it started after `respawnDelay`, full health | | `remove` | disappears after `removeDelay` | | `stay` | stays dead until `Lifeline.revive(target)` | ## Health fields (most useful) `maxHealth`, `health`, `maxShield`/`shield` (soaks damage first), `regenRate` + `regenDelay`, `shieldRegenRate` + `shieldRegenDelay`, `invulnerabilityTime` (i-frames after a hit; damage-over-time ticks ignore it), `invulnerable` (god mode → "IMMUNE"), `armor` (flat reduction → "BLOCKED"), `respawnDelay`, `spawnProtection`, `displayName`, `team`, `barStyle` (bar drawn over this entity, `none` hides it), `bossBar` (show the big boss bar when near), `bodyHeight`/`bodyRadius` (bar placement and hit volume), `killBelowY`. Read-only: `isDead`, `deaths`. ## Events `Lifeline.on(name, fn)` fires on **every** peer for `damaged`, `healed`, `blocked`, `died`, `respawned`, or `"*"` for all. The payload is `{ event, target, amount, shieldAmount, kind, source, crit, health, shield, maxHealth, reason, origin, pos, isPlayer, name }`. It returns a connection with `:Disconnect()`. Each Health component also exposes typed events: `entity.component.get("Lifeline.Health").events.died:connect(fn)`. ## Styles: change one field On `LifelineHUD` (or at runtime per player with `Lifeline.setStyle { bar = …, worldBar = …, number = …, feedback = … }`): - **Bars** (`playerBar`, `worldBar`, Health's `barStyle`): `classic` (lost chunk drains away), `segmented`, `ring`, `hearts` (half hearts, shield hearts, heartbeat at low HP), `boss`, `overhead`, `minimal`, `stacked` (shield on health), `scifi`, `fantasy`, `cartoon`, `pixel`, `orb`. - **Numbers** (`numberStyle`): `classic` (pop / shaky crit / green heal / IMMUNE-BLOCKED), `combo` (hits on one target add up into a running total), `comic`, `minimal`. - **Feedback** (`feedback`, any mix): `flash shake vignette heartbeat direction`, or `all` / `none`. ## Multiplayer & anti-cheat Health fields are `Sync`. Only the entity's owner mutates them, and the relay refuses writes from anyone else — so one player cannot set another player's health from their own machine. - **Hit something you own** (your avatar, or a prop your peer took) — it changes on your machine and the new value goes on the wire. Every other peer draws exactly that number: health bars, numbers and death screens all read the same synced field. - **Hit something another player owns** — `Lifeline.damage` doesn't decide anything. It sends a request to that entity's owner over `multiplayer.send`, and the owner validates it before applying. `Lifeline.setDamageFilter(function(comp, amount, info, fromPeer) ... end)` is where that validation goes: return the amount to allow (clamped if you like), or 0 to refuse. `fromPeer` is set only when the hit arrived from another peer's request. - **Zones** run on every peer but act only on entities that peer owns, so a player in a fire zone is burned exactly once, by their own machine. A player's damage events are broadcast by the owner, so remote players see the same flash, numbers and score hooks. - **Events** (`Lifeline.on`) fire on every peer — same channel the kit uses for its own visuals. **The honest limit:** the engine's model is that the owning peer is the authority for its own entities. That is what stops *other* players from touching your health, and it is what this kit is built on. It does not, by itself, stop a modified client from lying about *its own* health (a hacked client could ignore a fire zone). If your game needs damage that a cheating client can't dodge, run the damage on a peer you control and funnel it through `setDamageFilter` — the filter runs on the owner, so it's the place to require proof, rate-limit, or refuse anything that doesn't match your own simulation. ## Other hooks `Lifeline.kill`, `Lifeline.revive`, `Lifeline.get(target)`, `Lifeline.all()`, `Lifeline.isAlive`, `Lifeline.setSpawnPicker(fn(comp, points) -> entity)`, `Lifeline.kinds` (damage kinds → colour/label, add your own). ## Contents `Health`, `DamageZone`, `HealZone`, `Projectile`, `ProjectileLauncher` (player blaster on a key, or an auto turret), `SpawnPoint`, `LifelineHUD` components, plus the `api`, `bars`, `numbers`, `feedback` and `zone` modules.

# juiceKit **One call makes hits, explosions, pickups and level-ups feel great: `Juice.play("explosionLarge", someEntity)` shakes the camera, flashes the screen, freezes the action for a beat, squashes the target and plays an effect at the spot, all together and correctly for every player.** Version **1.2.2** (`Juice.VERSION`). The version, this README and `package.yaml` move together. ## First example 1. Install juiceKit into your world. 2. Create a component named `juiceDemo` (a `juiceDemo.component` folder with this `init.luau`). 3. Add `juiceDemo` to any entity in your scene, press Play and press **E** (Interact). Each press plays the next of the three effects. ```lua local Juice = require("juiceKit.juice") declare {} public = { inputMap = Field.assetRef("inputMap", "@builtin::inputMaps.default", NoSync, "The controls the Interact press comes from."), } local controls = nil local presses = 0 function start() controls = public.inputMap:activate("juiceDemo") controls.interact:onPressed(function() presses += 1 local here = public.entity if presses % 3 == 1 then -- an explosion at this entity: everyone sees it, and each player -- feels the shake as strongly as their distance to it warrants Juice.play("explosionLarge", here) elseif presses % 3 == 2 then -- a coin pickup at a point in the world Juice.play("coinPickup", { 4, 1, 2 }) else -- the local player got hurt by an attacker standing at this entity: -- red vignette, a short freeze, a kick away from it (only this player) Juice.play("hurt", nil, { from = here }) end end) end function onDestroy() if controls then public.inputMap:deactivate(controls) end end ``` Nothing else is needed. Only the player who pressed E calls `play`, so the default routing is right: the explosion and the coin reach every player, and the hurt stays with this one. Requiring `juiceKit.juice` starts listening for other peers' effects, and the first shake attaches the shake components to the camera on screen. To make sure a peer whose own scripts never call `play` still receives world effects, put the **JuiceNet** component on any scene entity. Its `look` field also sets the starting look. ## Swapping things Everything goes through the same call, so a different preset, look or strength is a one-word change: ```lua Juice.play("hitLight", enemy) -- -> "hitHeavy", "hitCritical" Juice.play("vfxFire", pos, { look = "pixel" }) -- one effect in another look Juice.setLook("realistic") -- every effect from now on Juice.play("shakeExplosion", pos, { intensity = 0.5 }) -- half strength, this call only ``` ## Presets (51) Kinds: `combo`, `shake`, `hitstop`, `flash`, `squash` and `vfx`. Strengths: `light`, `medium` and `heavy`. Scope is `player` (it happens only for the player it is about) or `world` (every peer sees it). `hurt`, `heal`, `death`, `levelUp` and `landingHard` also carry `personal = "player"`: their screen parts play only for a player who is the target, never for whoever called `play`. See the multiplayer rules below. | name | kind | strength | scope | pieces | what it is | |---|---|---|---|---|---| | `coinPickup` | combo | light | world | squash + vfx | A coin sparkle and pulse. | | `death` | combo | heavy | world | shake + hitstop + flash + squash + vfx | A death: crushed flat, smoke, a slow-motion freeze, and a dark fade for the player who died. | | `explosionLarge` | combo | heavy | world | shake + hitstop + flash + squash + vfx | A big blast: fireball, debris, a dust ring, a flash and a shake everyone feels by distance. | | `explosionSmall` | combo | medium | world | shake + squash + vfx | A small blast: fireball, smoke and a distance-scaled shake. | | `heal` | combo | light | world | flash + squash + vfx | Healing: rising green motes and a soft green pulse for the healed player. | | `hitCritical` | combo | heavy | world | shake + hitstop + flash + squash + vfx | A critical: a long freeze into slow motion, a hot flash, a kick away from the attacker and zap sparks. | | `hitHeavy` | combo | medium | world | shake + hitstop + flash + squash + vfx | A heavy hit: bigger sparks, a freeze, a strong shake and a flash. | | `hitLight` | combo | light | world | shake + hitstop + squash + vfx | A light hit: sparks, a tiny freeze, a small shake and a wobble. | | `hurt` | combo | medium | player | shake + hitstop + flash | Taking damage: a red vignette, a kick away from the attacker and a tiny freeze. | | `landingHard` | combo | medium | world | shake + squash + vfx | A hard landing: a dust ring, a landing squash and a short heavy shake. | | `levelUp` | combo | heavy | world | shake + flash + squash + vfx | Level up: a golden column, a ring, confetti, a golden glow and a stretch. | | `spawn` | combo | light | world | squash + vfx | Something appears: a pop-in with a magic burst. | | `shakeEarthquake` | shake | heavy | world | shake | A rolling earthquake that swells, peaks and fades over four seconds for everyone nearby. | | `shakeExplosion` | shake | heavy | world | shake | A blast shake that every player feels, weaker the farther they are from it. | | `shakeHeavy` | shake | heavy | player | shake | A strong jolt for big hits and slams. | | `shakeKick` | shake | medium | player | shake | A directional kick that pushes the view away from where the hit came from (pass `from` or `direction`). | | `shakeLight` | shake | light | player | shake | A quick, small jitter for light hits and footfalls. | | `shakeRecoil` | shake | light | player | shake | A weapon recoil: the view snaps back and up, then settles. | | `shakeRumble` | shake | medium | player | shake | A long, low rumble for engines, collapsing rock or a boss approaching. | | `hitstopCritical` | hitstop | heavy | player | hitstop | A 180 ms freeze that eases out through slow motion, for critical hits and finishers. | | `hitstopHeavy` | hitstop | medium | player | hitstop | A 120 ms freeze for heavy blows. | | `hitstopLight` | hitstop | light | player | hitstop | A 50 ms freeze that lands a light hit. | | `hitstopSlowmo` | hitstop | medium | player | hitstop | Half a second of 25% slow motion with no freeze, for near misses and dramatic moments. | | `flashBlackout` | flash | heavy | player | flash | A fade to black and back, for death, respawn or a scene cut. | | `flashCritical` | flash | heavy | player | flash | A blinding white-orange burst with hot edges. | | `flashDamage` | flash | medium | player | flash | A red vignette that closes in from the screen edges when you take damage. | | `flashExplosion` | flash | medium | world | flash | A bright blast flash every player near the explosion sees. | | `flashFreeze` | flash | light | player | flash | An icy blue vignette for frozen, chilled or shielded. | | `flashHeal` | flash | light | player | flash | A soft green pulse from the edges. | | `flashHit` | flash | light | player | flash | A sharp white flash across the screen. | | `flashLevelUp` | flash | medium | player | flash | A warm golden glow that blooms and fades. | | `flashPoison` | flash | light | player | flash | A sickly purple-green vignette for poison and curses. | | `flatten` | squash | heavy | world | squash | Crushed flat, held, then springs back up, for deaths and stomps. | | `jellyWobble` | squash | light | world | squash | A jelly wobble when something is hit. | | `popIn` | squash | medium | world | squash | Grows from nothing with an overshoot, for spawns and pickups appearing. | | `pulse` | squash | light | world | squash | A quick uniform bump for collect, select or a heartbeat. | | `punch` | squash | heavy | world | squash | A hard punch inward that rings out, for heavy impacts. | | `squashLand` | squash | medium | world | squash | Flattens on landing and springs back. | | `stretchJump` | squash | medium | world | squash | Stretches tall on take-off and settles. | | `vfxCoin` | vfx | light | world | vfx | A coin sparkle. | | `vfxConfetti` | vfx | medium | world | vfx | A confetti burst. | | `vfxDust` | vfx | light | world | vfx | A dust puff. | | `vfxExplosionLarge` | vfx | heavy | world | vfx | A large explosion: fireball, debris and a smoke ring. | | `vfxExplosionSmall` | vfx | medium | world | vfx | A small explosion. | | `vfxFire` | vfx | medium | world | vfx | A burst of fire. | | `vfxHeal` | vfx | medium | world | vfx | Rising healing motes. | | `vfxLevelUp` | vfx | medium | world | vfx | A level-up column and ring. | | `vfxMagic` | vfx | medium | world | vfx | A magic burst. | | `vfxSmoke` | vfx | medium | world | vfx | A smoke cloud. | | `vfxSparks` | vfx | light | world | vfx | Impact sparks. | | `vfxZap` | vfx | medium | world | vfx | An electric zap. | Every `vfx` preset and every combo's effect is drawn in the current look: **cartoon** (solid toon shapes, the default), **realistic** (soft additive glow, smoke and dark debris), **pixel** (chunky cubes snapped to a grid) or **scifi** (cyan and magenta energy). Effect kinds: `sparks`, `dust`, `explosionSmall`, `explosionLarge`, `magic`, `heal`, `levelUp`, `coin`, `smoke`, `fire`, `zap` and `confetti`. ## Interface (`require("juiceKit.juice")`) ### Playing `Juice.play(name, target?, opts?) -> result` plays a preset. It raises on an unknown preset, look or target, and otherwise returns a table saying what ran on this peer: `{ shake = strength, hitstop = true, flash = alpha, squash = true, vfx = particleCount, sent = true, id = playId }`. Every play gets an `id`, even one that intensity 0 turned into nothing, so the result can always be handed to `Juice.stop`. - `target`: an entity, an entity id, an entity name, a position (`{x,y,z}`, `{x=,y=,z=}` or a vector), or nil for the local player. - `opts`: | option | meaning | |---|---| | `intensity` | Multiplier for this call (multiplied by the global intensity). | | `look` | Draws this call's effect in a look other than the current one. | | `from` | The attacker: an entity or a position. Kicks push away from it, and when the target is a thing (not a player) and `from` is another player's avatar, the personal parts land on that attacking player's screen. | | `direction` | World direction the hit travels, used instead of `from`. | | `scale` | Effect size multiplier. | | `axis` | Squash axis: `"y"` (default), `"x"` or `"z"`. | | `scope` | `"auto"` (default): world parts go to every peer, personal parts to the one player they belong to. `"local"`: play here only what belongs on this peer and send nothing, for code that already runs on every peer. `"world"`: also send a player preset's world parts to every peer. | | `seed` | Seed for a repeatable effect. | `Juice.stop(what) -> boolean` stops one play early and leaves everything else running. `what` is the table `play` returned, its `id`, or a preset name; a name stops every play of that preset on this peer, its own and ones received from other peers. ```lua local charge = Juice.play("shakeRumble") -- the charge was cancelled: Juice.stop(charge) ``` - The shake comes off the camera with no drift; other shakes keep going. - The hitstop lets go: normal speed comes back at once unless another hitstop still holds. - The flash disappears, the squash lands on the exact base scale, and the effect's particles and light vanish. - Stopping a play this peer sent to others stops it on their screens too. - It returns false for a play that has already finished or was stopped, and for nil. An unknown preset name raises. `Juice.isPlaying(what) -> boolean` says whether any part of a play (same `what` as `stop`) is still running here. `Juice.stopAll()` stops every shake, hitstop, flash, squash and effect at once, puts squashed things back at their exact base scale, and releases the time scale. It acts on this peer only and forgets every play id. ### Finding presets - `Juice.list(filter?) -> rows` returns every preset as `{ name, kind, strength, scope, personal, looks, pieces, effects, tags, custom, description }`, sorted by kind and then name. - A **kind name** string (`"shake"`, `"combo"`, …) keeps that kind. - Any other string matches a tag or a name (`"heavy"`, `"world"`, `"explosion"`, `"custom"`). - A table `{ kind?, strength?, scope?, look?, piece?, tag?, custom? }` requires all of its fields. - `Juice.names(filter?) -> { string }` returns the same rows as `list`, names only. - `Juice.get(name) -> row?` returns one row plus `spec`, the resolved pieces. Both are copies: changing them never changes the preset. - `Juice.has(name) -> boolean` says whether a preset by that name exists. - Constants: `Juice.KINDS`, `Juice.STRENGTHS`, `Juice.SCOPES` and `Juice.PIECES`. ### Making your own `Juice.define(name, spec) -> row` adds a preset, or replaces one you defined earlier. Each piece in `spec` is either the name of an existing preset of that kind or a table of its own: ```lua Juice.define("bossSlam", { shake = "shakeEarthquake", hitstop = "hitstopHeavy", flash = "flashExplosion", squash = "punch", vfx = { kind = "explosionLarge", scale = 1.6 }, strength = "heavy", scope = "world", tags = { "boss" }, description = "The boss hits the floor.", }) Juice.play("bossSlam", boss) ``` Besides the pieces, `spec` takes `kind`, `strength`, `scope` (`"player"` or `"world"`, worked out from the pieces when left out), `personal` (`"target"`, the default, or `"player"` for moments that only make sense for a player; see the multiplayer rules), `tags` and `description`. Your presets can be built on each other (`Juice.define("bossSlamBig", { shake = "bossSlam", vfx = { "bossSlam", "confetti" } })`), and changing one never breaks another: - `Juice.remove(name) -> boolean` removes a preset you defined (false when there was none). Presets built on it keep working exactly as before: each keeps its own copy of the pieces it took from it. - Redefining a preset changes what the presets built on it play, except for a piece the new version no longer has: those keep the piece they had. - `define` and `remove` refuse a change that would leave another preset broken, such as two presets naming each other in a loop. They raise `juiceKit.define: 'a' would break 'b': …` (or `'a': …` when `a` itself would break), and every preset stays as it was. ### Settings | call | what it does | |---|---| | `Juice.setLook(name)` / `getLook()` / `looks()` / `hasLook(name)` / `vfxKinds()` | The one look switch every effect follows. | | `Juice.setIntensity(x)` / `getIntensity()` | Global intensity, clamped to 0–2. It scales shake, flash, hitstop and squash strength and effect density; 0 turns the kit off. | | `Juice.setReduceMotion(on)` / `getReduceMotion()` | Motion-sickness comfort: no camera shake at all, and gentler, shorter flashes. Hitstop, squash and effects still play. | | `Juice.stats()` | Counters and live counts from every piece, plus `recent`, the last 12 plays and receives with who got the personal parts, for HUDs, tests and debugging. | Settings are per peer, so each player chooses their own look, intensity and comfort. ## Multiplayer The world is always multiplayer, and `play` routes each piece for you. Every preset is made of two kinds of parts: - **World parts** happen at a spot: the visual effect, the squash, a blast shake (one with distance falloff), a blast flash (one with a radius) and a blast's hitstop. For a `world`-scope preset they run here and on every other peer. Each peer works out **its own** shake, flash and freeze from **its own** distance to the spot. A far player sees the blast without being shaken. Only players within roughly the inner third of the shake's range freeze. - **Personal parts** belong to one player's screen: a fixed camera shake, a screen flash and a hitstop. They play for **exactly one player**, never for everyone: | target | who gets the personal parts | |---|---| | nil, or your own avatar | you | | another player's avatar | only that player (it is sent to them) | | a thing (an NPC, a prop) or a point | you, or the attacking player when `opts.from` is another player's avatar | | a thing or a point, for a preset with `personal = "player"` | nobody: these moments only make sense for a player | The presets with `personal = "player"` are `hurt`, `heal`, `death`, `levelUp` and `landingHard`. A healer never sees the healed player's green pulse, and a killer never gets the victim's blackout. A hit (`hitLight`, `hitHeavy`, `hitCritical`) on an NPC lands on the attacker's screen; on another player it lands on theirs. - **Squash on a shared object**: a synced entity owned by another peer is squashed by its owner, who receives the same play, and its scale reaches everyone from there. Peers never write to an entity they don't own. - `scope = "local"` plays here only what belongs on this peer and sends nothing. Use it from code that already runs on every peer (for example, reacting to a synced health field): each peer then gets exactly its own share. - `Juice.stats().recent` shows, for the last few plays and receives, who got the personal parts (`"here"`, `"nobody"` or the recipient avatar's id) and what ran. - **Stopping travels like playing:** `Juice.stop` on a play this peer sent also sends a small stop message, and each peer that received the play stops exactly that one (matched by sender and play id). Stopping by name stops received plays of that name on your own screen only. A peer on a version before 1.1.2 ignores the stop and lets its share finish. ## Guarantees - **No camera drift:** the shake is added after every camera controller has run and removed before they run again. Measured on all nine builtin controllers (orbital follow, third person follow, first person, orbit, chase, side scroller, bird's eye, isometric and RTS): the camera returns to exactly where it would have been (0.000000 m of drift). - **Hitstop never sticks:** it is one owned time-scale hold. The slowest live request wins, and every span is capped (no freeze longer than 0.6 s). It always releases on end, on `stopAll`, on interruption and on reload. - **Cheap and self-cleaning:** particles are pooled instanced draws, capped at 700 live, with the oldest stolen first. Lights come from a pool of 4. Nothing is spawned per particle, and everything drains to zero and idles when quiet. - **Flashes are part of the picture:** they are drawn by one post-process pass over the lit scene, before the UI, so your HUD stays on top and untinted. The pass is switched off whenever no flash is playing. A copy of the module left behind by a hot reload can never switch it back on. - **Never touches the editor:** the shake only moves the gameplay camera in play mode, never the editor's fly-camera. A peer drops plays sent by other peers until its own scene has arrived. ## Pieces (for advanced use) The `juice` module is the front door. The modules under it can be used directly: | module | what it holds | |---|---| | `juiceKit.shake` | Additive camera shake layers (noise, kick, rumble, quake) with distance falloff. | | `juiceKit.hitstop` | Owned, capped time-scale holds. | | `juiceKit.flash` | Full-screen flashes, vignettes and glows, drawn into the rendered picture by one post-process pass under the UI. | | `juiceKit.squash` | Squash-and-stretch springs that always return to the base scale. | | `juiceKit.vfx` | Pooled particle effects: 12 kinds in 4 looks. | | `juiceKit.net` | The `juiceKit.play` message channel. | | `juiceKit.presets` | The data: presets, looks, palettes and effect recipes. | | `juiceKit.util` | Small vector, quaternion and targeting helpers. | Components: **JuiceNet** (optional; listens from scene load and sets the starting look), **JuiceShakeApply** and **JuiceShakeRestore** (attached to the camera automatically). Assets: `juiceParticle.shader`, `juiceFlash.shader` and the `juiceSolid`, `juiceGlow` and `juiceSmoke` materials. ## Tests Run them the standard way, in edit mode: `tools.use("tests", "run", "juiceKit")` (the shell form is `zero tests run juiceKit`). The suite is named `juiceKit`, not `juiceKit.testSuite`. You can also run it directly with `asset.resolve("juiceKit.juiceKit", "testSuite"):run()`. 104 tests cover every public call. They pass on repeated runs, either way, with or without a player or a scene camera: - **Playing:** every target form, and exactly what a play reports. - **Listing:** every filter, the sort order, and the copies `list` and `get` hand out. - **Defining your own presets:** broken specs are refused, defaults are worked out, redefining replaces, and presets build on presets. - **Presets built on presets:** removing or redefining a base keeps its dependents playing the same thing, a chain survives losing its root and then its middle, and loops are refused with the old preset intact. - **Looks:** each look's material and shape, and a look given to one play. - **Intensity:** flash alpha, shake strength, particle count and hitstop length. - **Reduce motion:** no shake, gentler flashes. - **Stopping early:** `stopAll` mid-shake, mid-hitstop, mid-squash, mid-flash and mid-effect. - **Stopping one play:** `Juice.stop` and `Juice.isPlaying` by result, id and name. Tested per piece (one shake, hitstop, flash, squash or effect stopped while another keeps going) and on whole combos, and a stop sent to and received from another peer reaches only that play. - **Multiplayer routing:** another player's flash and hitstop never land on the caller, blasts are scaled by distance, and squash is left to the owner. ## Watch out for - **Play from code every peer runs, or from one peer with the default scope.** By default (`scope = "auto"`) `play` sends the world parts to everyone. If the same call already runs on every peer (for example, a reaction to a synced health value), pass `scope = "local"`, or each peer receives it once per sender. - **Shakes only move the camera in play mode.** In edit mode `Juice.play` still runs the effects, flashes and squashes, but it never touches the editor's fly-camera. - **The flash is a post-process pass.** It tints the scene camera's picture, under your UI. If you want a flash *over* the UI (a menu fade), use a UI screen instead. The pass also tints offscreen captures and render-to-texture cameras taken while a flash plays, and clamps highlights brighter than white for that moment. - **Heavy scenes slow down joiners.** Every entity a scene bakes in is replicated in play, and a joining peer receives them all as one snapshot before its gameplay starts. Keep static scenery light, or spawn it from code each peer runs, so new players get in quickly. - **Reduce motion is per peer.** It is a comfort setting for the player at this screen. Set it from that player's own options, not from shared state. - **Give every joiner a start view of your own.** A player prototype's camera rig is `OwnerOnly`, so a joiner whose player was spawned on another peer receives the body and no camera. The showroom's Gallery shows one way to handle it: it gives that player a local follow camera, and works out the starting heading from the spawn and the stage rather than from the body. - **Testing with the standard runner.** `tests.run` runs a suite in edit mode with no avatar, an empty scene and fallback lighting, and in edit mode the camera on screen is the editor's. The kit's "where am I" (`U.herePos`) falls back from the avatar to the gameplay camera, then to the camera on screen, then to the world origin, so the suite passes either way. The runner takes the suite's asset name: `juiceKit`, not `juiceKit.testSuite`. - **A second player needs a second client.** Two agent sessions in one engine (`play as <name>`) are one peer, so a real two-player check needs another desktop session or the web, ideally signed in to another account (see #14448). - **Small API traps.** `entity.exists` raises when given a live entity's name, so pass an id. `_G` is sealed. A local named after an engine namespace (`live`, `av`) hides that namespace. ## Known issues These are engine problems met while building the kit or the showroom, each with its engine issue number. The kit or the showroom works around each one where it can; they are listed so a creator who meets one knows what it is. - **No character is drawn on a joining player's screen** (#16913, #14448). In a two-session test, the player who joined saw neither their own character nor the other player's. Another player's avatar arrives with no visible body (#16913), and two sessions signed in to the same account are mishandled when the second one joins (#14448). The showroom still gives the joiner a working view and HUD, and every effect still plays for them. - **A joining player in a session with no window gets no view** (#19169). Run two-player checks with two windowed sessions. - **A one-shot particle burst `.effect` fails to build** (#19206). The kit draws its effects with its own pooled particles instead, so nothing in the kit depends on it. - **A test clean-up hook registered outside a group is dropped** (#12497). A top-level `Test.afterEach` never runs, so each `describe` in the kit's suite installs its own clean-up. - **A follow camera binding to a body whose look has not loaded starts in front of it** (#19313). The orbital follow camera takes its heading from the body's facing when it binds. A body that has not loaded yet reports the default facing, so the camera lands in front of the player looking away. The showroom sets the heading itself for the first moments after a player appears. - **Harmless `asset-unresolved` warnings** (#12937). The code checker reports them for `~.JuiceShakeApply`, `~.JuiceShakeRestore`, `~.juiceSolid`, `~.juiceGlow`, `~.juiceSmoke` and `~.juiceFlash`; they all resolve when running.

# SecondWind 1.2.0 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. ## What's new in 1.2.0 The package is now called **SecondWind**, like this world, and it sits beside Lifeline and MatchFlow. It used to be called healthKit. It is still the same package with the same guid (`5da0a53c-5953-4adc-80fb-f5afb02f6568`), and every call, setting, event, preset and network channel works exactly as in 1.1.4. - **New require line:** `local HK = require("SecondWind.api")`, in place of `require("healthKit.api")`. - **New asset names:** the components are `SecondWind.Vitals`, `SecondWind.Rules`, `SecondWind.HUD` and `SecondWind.Trap`, the modules are `SecondWind.catalog`, `SecondWind.logic`, `SecondWind.feed` and `SecondWind.fx`, and the test suite is `secondwind`. - **Upgrading from 1.1.x:** after you update, change `healthKit.` to `SecondWind.` in your `require` and `asset.resolve` lines. An installed copy stays at the version it was installed at, so a world on 1.1.4 keeps working until it updates. - **Kept on purpose:** the network channels keep their names (`healthKit:evts`, `healthKit:state` and the rest), and the HUD's screen id stays `healthkit_hud`, so nothing a game sends, listens for or looks up changes. - **A store listing:** the package description now says what the kit gives a creator, its six health displays and eight death styles, and how to install it with Lifeline and MatchFlow. ## What's new in 1.1.4 Every call, setting, event and preset works exactly as in 1.1.1. This version fixes the first example and the descriptions. - **The first example works as pasted.** Its dummy stood outside the lava and above it, and nothing in the kit moves a dummy, so it couldn't be pushed in and never burned. It now stands in the edge of the lava, on the ground, and an orange slab shows where the lava is. Checked in a new world holding only the two-call install: the dummy went from 60 to 40 to 20 to dead in about 4 s, came back with full hearts where it stood 4 s later, and did it again; a player standing in the lava burned from 150 to 95 in 3 s. - **Second Wind opens in the gallery again.** 1.1.3 saved a small test scene as the world's main scene by mistake, so the editor opened in it. - **Known limits names the public engine issue #19188** for the install problem, instead of two internal ticket ids. - **The package description says eight death styles**, as the catalog and this README do. It said six and left out `remove` and `stay`, and it called the component `Health` instead of `Vitals`. ## What's new in 1.1.3 Every call, setting, event and preset works exactly as in 1.1.1. This version corrects step 1 again. - **Install in two calls.** The one-call install that 1.1.2 gave doesn't work. When SecondWind, Lifeline and MatchFlow go in one call, the last two only update the copies SecondWind brought under `/source/deps/` and nothing is installed in `/source`, so SecondWind still can't reach them. Step 1 now installs SecondWind first, then Lifeline and MatchFlow in a second call with `at=/source`. Checked with the published kit in a new world: after the one call, `module 'Lifeline.api' not found` and five publish errors remained. After the second call, the scene built, the player got 150 HP, the lava burned, the hearts dummy died and came back, and `zm push` published the world. If you followed 1.1.2's step 1, run the second call now; it fixes the world in place. ## What's new in 1.1.2 Every call, setting, event and preset works exactly as in 1.1.1. This version fixes the install instructions. - **The first example works in a brand-new world.** Step 1 used to say Lifeline and MatchFlow come along with SecondWind. In a new world they do arrive, but SecondWind can't reach them: its components fail with `module 'Lifeline.api' not found` and the world can't be published (see Known limits). Step 1 now installs Lifeline and MatchFlow as well. Checked in a new world holding only those three installs: the scene builds, the player gets 150 HP from the `heroShooter` preset, the lava burns, the hearts dummy dies and comes back, the health bar shows, and `zm push` publishes the world. Earlier versions were only checked in the world that authors the kit, which has both installed. ## What's new in 1.1.1 Every 1.0.0 and 1.1.0 call, setting, event and preset works as before. New in this version: - **Fewer messages per hit.** Events for other peers wait up to 0.05 s and leave together as one `healthKit:evts` message, in order, so a burst (a chain, a blast, a kill and its death) is one message instead of one per event. Listeners on the peer that raised them (`HK.on`) still hear each event at once, and a health snapshot never overtakes the events queued before it. 1.1.1 still receives the one-per-event `healthKit:evt` messages that 1.1.0 peers send, so mixed sessions work. - **`HK.syncReport().totals`** also counts `evtSent` (event batches sent) and `evtBatched` (the events inside them). - **A lighter showcase gallery.** Its dummies and damage stations only work while a player is within 18 m (`wakeRadius` on the Gallery component). The dummies drain just as fast with half as many hits, the kill-feed boards rebuild only when the feed changes, signs and pads refresh a few times a second instead of every frame, and name labels are looked up by name instead of by scanning every entity. With a player inside, the gallery's host now sends about 12 to 14 messages a second instead of about 46, a damage request through a browser host comes back in 0.2 to 0.4 s instead of 25 s or more, and on a peer that doesn't host it the Gallery script costs 0.07 ms a frame. - **Gallery labels stay hidden after a scene rebuild.** Right after a rebuild the engine can briefly refuse to switch a `{PlayerName}` label off; the gallery now retries until it holds. ## What's new in 1.1.0 Every 1.0.0 call, setting, event and preset works as before. New in this version: - **A labelled catalog.** Every health model, damage type, death style, kill feed look and preset now says its `kind`, its `family`, the `genres` it suits, whether it has a look of its own (`hasLook`) and, if so, its `style`. `HK.find({ kind = "preset", genre = "coop" })` picks by label, and `HK.vocabulary()` lists the words. See [Picking from the catalog](#picking-from-the-catalog). - **Hit effects for everyone.** Flames, sparks, bubbles and frost now show on every player's screen, not just for the player who landed the hit. Each hit is also written into the target's synced `hitSeq`, `hitType` and `hitAmount`, so a peer that misses the hit message still draws the effect. - **One health on every screen.** On every death, respawn, revive, life lost and knock-down, the owner sends a full state snapshot (`healthKit:state`) at once, again after 0.5 s and again after 2 s. It also sends one after any change and every 5 s regardless. A peer whose view stays off for more than half a second asks for a fresh one (`healthKit:resync`). `HK.state` gives the latest agreed snapshot, and `HK.syncReport()` shows how sync is doing. - **Fall damage fixed around death and respawn.** Fall tracking now starts fresh on death, on respawn and on any teleport, with one second of grace after a respawn. A player who died from a fall no longer takes a second fall hit when they reappear, and their own screen and everyone else's agree. - **A clean gallery and a new cover.** The gallery dummies no longer show a `{PlayerName}` placeholder, in play or in the editor. ## Install and use (five minutes) 1. **Install.** Install three packages from ZeroMind, in two calls: - first **SecondWind**: `zeromind_install guid=5da0a53c-5953-4adc-80fb-f5afb02f6568` - then the two it is built on, **Lifeline** (`7b85ce05-3903-4374-b654-2d4ffea295a5`) and **MatchFlow** (`31cf13b4-df7d-4888-85e2-7947a7301614`), into `/source`: `zeromind_install guid=7b85ce05-3903-4374-b654-2d4ffea295a5,31cf13b4-df7d-4888-85e2-7947a7301614 at=/source` Don't skip the second call, don't merge the two, and keep `at=/source`. SecondWind brings its own copies of Lifeline and MatchFlow but the engine doesn't connect it to them yet, and in one call, or without `at`, the second install only updates those copies (see Known limits). While Lifeline installs, the log may say `'~Lifeline.api' is ambiguous` for a moment; that clears when the install finishes. 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: ```lua 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" }) ``` 3. **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, BURNING on screen and your bar dropping from 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: ```lua HK.damage(target, 20, { by = attacker, type = "fire", team = "red" }) ``` Switching anything is one setting, even while the game runs: ```lua 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: | label | values | |---|---| | `kind` | `healthModel`, `damageType`, `deathStyle`, `feedLook`, `preset` | | `family` | health models: `pool`, `counted`, `secondChance`. Damage types: `direct`, `elemental`, `world`. Death styles: `respawn`, `deathAnimation`, `outOfPlay`. Feed looks: `killFeed`. Presets: `competitive`, `adventure`, `cooperative`, `casual` | | `genres` | a list from `shooter`, `heroShooter`, `battleRoyale`, `adventure`, `roguelike`, `rpg`, `coop`, `survival`, `platformer`, `party` | | `hasLook` | `true` when the entry draws something of its own | | `style` | for entries with a look: `minimal`, `scifi`, `fantasy`, `cartoon`, `pixel` (a preset takes the style of its kill feed look) | ```lua 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`) | id | what it does | |---|---| | `hitPoints` | One health bar. | | `shield` | A shield soaks damage first and recharges after `shieldRegenDelay` seconds without a hit. Electric damage does double to shields. | | `armor` | An armour pool absorbs `armorAbsorb` of each physical, fire, ice, electric or explosion hit and wears down. Poison, fall and environment damage go around it. | | `hearts` | Zelda-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. | | `lives` | `lives` lives, each with a pool of `lifeHealth`. Emptying a pool spends a life and refills it. Losing the last life is death. | | `downed` | A 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`) | id | behaviour | looks like | |---|---|---| | `physical` | A plain hit. | white sparks | | `fire` | Keeps burning for a few seconds after the hit. Ice puts it out. | rising flames; burning targets trail embers | | `poison` | Stacks up to 5. Each stack ticks every second, and a new hit refreshes them. Goes around armour. | poison bubbles; poisoned targets trail bubbles | | `ice` | Slows the target to half speed for a few seconds. Puts out fire. | ice shards; chilled targets trail frost | | `electric` | Chains to up to 3 nearby targets at 60% damage. Double damage to shields. | electric sparks and arcs to each chained target | | `explosion` | Falls off with distance and knocks targets back (`HK.explode`). | an expanding explosion shell | | `fall` | Taken automatically when landing faster than `Rules.fallSafeSpeed`. Goes around armour. | landing dust | | `environment` | Lava, spikes, acid: the world itself (`SecondWind.Trap`). Goes around armour. | red spikes | ### Death styles (`deathStyle`) | id | what happens | |---|---| | `instant` | Back at a spawn point straight away. | | `timed` | Back at a spawn point after `respawnDelay` seconds, with a MatchFlow countdown on screen. | | `wave` | Everyone who died comes back together on the next wave, every `Rules.waveInterval` seconds. | | `ragdoll` | The body is flung and tumbles limp, then respawns after `respawnDelay`. | | `dissolve` | The body sinks and dissolves into sparks, then respawns after `respawnDelay`. | | `spectate` | Stays dead and watches a living player until the round ends (`HK.endRound()`, a MatchFlow round ending, or `Rules.autoEndRound`). | | `remove` | Gone for good: for breakable props and one-shot enemies. | | `stay` | Stays dead until a script calls `HK.revive`. | ### Presets (`preset`) | id | model | death style | feed | friendly fire | |---|---|---|---|---| | `arcadeShooter` | hitPoints | instant | pixel | off | | `heroShooter` | shield (150 HP + 75 shield) | timed (5 s) | scifi | off | | `adventureHearts` | hearts (5) | dissolve | fantasy | off | | `roguelikeLives` | lives (3 × 40 HP) | ragdoll | pixel | off | | `coopRevive` | downed (20 s bleed-out) | wave | minimal | off | | `battleRoyale` | armor | spectate | minimal | on | | `partyBrawl` | hitPoints, huge knockback | ragdoll | cartoon | on | ### 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. | call | what it does | |---|---| | `HK.damage(target, amount, opts?) -> ok, reason` | Hurt 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, reason` | Restore health. Hearts round up to half hearts. opts: `by`. | | `HK.kill(target, opts?) -> ok, reason` | Kill outright, skipping lives and downed. opts: `by`, `type`. | | `HK.revive(target, opts?) -> ok, reason` | Pick a downed target up, or respawn a dead one now. | | `HK.explode(pos, opts?) -> count` | Explosion with falloff and knockback. opts: `radius` (5), `damage` (60), `by`, `team`, `knockback` (10), `minFalloff` (0.2). | | `HK.attach(entity, settings?) -> Vitals` | Add Lifeline.Health and SecondWind.Vitals with these settings. Use it in a build or on a freshly spawned entity. | | `HK.configure(target, settings) -> ok, reason` | Change 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, reason` | Change 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) -> conn` | Listen 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.logic` | The 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`, `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 87 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, and the 1.2.0 rename (new names, same guid, no old requires left, channels kept). Run it with `tools.use("tests", "run", { suite = "secondwind" })`. ## Known limits - **#2612: a package cannot list Lifeline as a dependency.** `package.yaml` names no dependencies, so installing SecondWind doesn't install Lifeline and MatchFlow as packages of your world. Install them yourself, as step 1 says. - **#19188: installing SecondWind doesn't connect it to Lifeline and MatchFlow.** The install logs errors saying a component type was not found and a version is still being fetched. It writes Lifeline and MatchFlow under `/source/deps/`, but SecondWind's `require("Lifeline.api")` doesn't find them there: its components fail with `module 'Lifeline.api' not found`, and `zm push` refuses with `could not resolve require("Lifeline.api")`. Installing Lifeline and MatchFlow in a call of their own with `at=/source`, as step 1 says, fixes both. In the same call as SecondWind, or without `at`, that install answers `updated` with a path under `/source/deps/` and puts nothing in `/source`. The copies under `/source/deps/` stay behind; the MatchFlow one logs `module ~.rules … has no root to resolve against` on each scene rebuild, which the first example plays through. - **#19168: effects spawned from a message another player sent.** Worked around: the kit queues hit effects and draws them on the next frame instead of inside the message handler, and also draws them from the synced `hitSeq`/`hitType`/`hitAmount` fields when no message arrives. - **#19201: the `{PlayerName}` label.** The engine's humanoid avatar shows a `{PlayerName}` placeholder on any body no player owns, and has no setting to turn it off. This only matters if you give dummies or enemies the humanoid avatar. The showcase gallery hides those labels in play and in the editor: it disables `PlayerNameLabel` on bodies with no `PlayerAvatar` above them. - **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 (see 1.1.1). Keep the number of bodies taking damage at the same moment modest, or only run them near players, as the showcase gallery does. - **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, and it may have come from the browser's controls. Nothing in the kit was found to cause it: the kit only moves a player's body when it respawns. - **Two-player checks.** Checked live with two players, one on the native engine and one in a web browser. In 1.1.0, hit effects, fall deaths and respawns matched on both screens. In 1.1.1, with the browser hosting the gallery, batched events arrived in order and damage requests came back in 0.2 to 0.4 s. The test suite also plays the remote peer's side (receiving, drifting, asking for a resync, catching up). - **Web browser.** The kit uses only cross-platform engine APIs (no file, OS or native calls outside its tests). In 1.1.1 a browser tab hosted the showcase gallery for the checks above and ran at about 15 frames a second with the gallery awake around a player, against 80 to 200 ms a frame before. Big scenes run slower in a browser than on the native engine, which is why the message rate above matters most there. The first example works in a browser: in a brand-new world with SecondWind installed by the two-call step 1 (on 1.1.2's code, which 1.1.3 and 1.1.4 don't change), the player started with 150 health, the lava set them on fire with flames, damage numbers and BURNING on screen, the bar dropped to about 20 of 150, and the dummy took damage. It plays choppily in a browser tab, even in that small scene. On the native engine the same scene runs at about 19 ms a frame, and the kit's components take about 0.5 ms of it; most of the rest is UI drawing, the built-in character controller and rendering, so the kit is not the likely cause. The browser frame itself has not been profiled. 1.1.4's example only moves the dummy and adds a plain coloured cube, and 1.2.0 only renames the package; both were checked on the native engine.