# catalog The list of every style in every category (`crosshair`, `hitMarker`, `direction`, `numbers`, `nameplate`) with its id, name, theme families and a one-line purpose, plus the six themes (`realistic`, `scifi`, `fantasy`, `cartoon`, `pixel`, `minimal`) and the style each picks. `catalog(category?)`, `styles(category)`, `has`, `describe`, `family`, `themes`, `counts`, and `category(name)`, which accepts plurals such as "crosshairs". The api, the components and the gallery all read from here, so a new style appears everywhere once it is registered in its renderer module.

--- description: Loads healthKit 1.0.0 under a guard (with retries), so markersKit loads and runs when healthKit cannot. G.proxy stands in with "no healthKit targets" answers; used by hud, api, Gallery and the test suite. --- # markersKit.healthGuard Exposes `available`, `api`, `error`, `proxy`, `refresh()` and `status()`. When healthKit is missing, `proxy` answers as if no entity has health: no damage, no events, no health on plates.

# nameplates 10 overhead nameplate styles: name only, name plus health, team-coloured, boss, pixel, and sci-fi, fantasy, cartoon, minimal and realistic ones. Every health bar is a barsKit look (overhead, segmented, boss, pixel, hologram, ornate, bubbly, line, ghost), so it matches barsKit bars elsewhere in your game. `render(id, { name, frac, trail, value, max, team, teamColor, showHealth, scale, dist }, W, H)` returns the plate. `barLook(id)` names the barsKit look, `teamColor(team)` resolves a team colour.

# draw Shared drawing helpers for the renderer modules: UI node shortcuts (`box`, `row`, `label`, `svgNode`), colour maths (`rgb`, `rgba`, `mix`, `isColor`), easing, an SVG pen with outline and glow (`pen`), arc paths, a 5×7 pixel font drawn as SVG (`pixelSvg`, `pixelText`), number formatting with thousands separators (`num`) and a stable hash for per-number jitter. Internal, but safe to use for your own HUD pieces.

# hud The per-peer runtime behind `api`. It keeps the settings and the live queues of markers, numbers and directions. It listens to healthKit's `damaged`, `healed` and `killed` events, decides what this peer sees (`isMine`: the attacker gets markers and numbers, the victim gets the direction), tracks nameplates and player plates, eases the dynamic-crosshair spread and the lock-on, and draws one UI screen (`markersKit.hud`, layer 45) scaled for the screen it is on. Driven each frame by the Feedback component, or by `api.start` and `api.frame`. Most games only touch it through `api`.

# markersKit **Version 2.0.5** On-screen combat feedback for shooters and brawlers: **crosshairs, hit markers, damage-direction indicators, floating damage numbers and nameplates**. There are 72 styles in six theme families (realistic, sci-fi, fantasy, cartoon, pixel, minimal), and they all work the same way: - **One setting switches a style**: `kit.setCrosshair("shotgun")`, or the `crosshair` field on the Feedback component. - **One call themes the whole kit**: `kit.setTheme("pixel")`. - **The catalog lists every style and what it is for**: `kit.catalog()`. Every style carries `tags` (`"spread"`, `"scope"`, `"heal"`, `"boss"`, …) so you can filter by what you need. - **healthKit damage drives it**: markers and numbers appear when healthKit reports damage. There is nothing to wire, in an empty world too. - **Every health-bar nameplate shows a bar** that follows healthKit health: a real barsKit `Bar` under the plate, on a fresh engine and after a restart. If barsKit's `Bar` ever fails to load, the plate draws the same look itself (see [what you see on a fresh engine](#what-you-see-on-a-fresh-engine)). - **Multiplayer-correct**: only the attacker sees their hit markers and numbers, only the victim sees where a hit came from, and everyone sees nameplates with each player's real name. - **Off means off**: disable the Feedback component (or call `kit.stop()`) and everything goes; delete it and nothing is left behind. - **Phone and web ready**: the HUD and gallery scale for portrait and landscape phones and keep out of safe-area cutouts. ## Quick start Run this in a world that has nothing in it except this package (from an agent's `execute`, a script, or a component's `awake`): ```lua local kit = require("markersKit.api") -- 1. The HUD: one Feedback component anywhere in the scene. Every player draws their own. local hud = entity.spawn("CombatFeedback") hud.component.add(asset.resolve("markersKit.Feedback", "component"), { theme = "scifi" }) -- 2. Some feedback right now, so you can see it working. kit.start({ theme = "scifi" }) kit.showHit("headshot") -- headshot marker round the crosshair kit.showNumber({ 0, 1.6, 6 }, 128, "crit") -- a crit number floating at a world point kit.showDirection(90, 0.8) -- "hurt from the right" print(kit.stats().markers, kit.stats().numbers, kit.stats().directions) --> 1 1 1 ``` To keep it in your world, put the two Feedback lines in your scene's `content()`. That is the whole setup: from then on every hit healthKit reports gives the attacker a marker and a number, and the victim a direction indicator. Give anything a nameplate with the Nameplate component (or `kit.nameplate(entity, { style = "boss" })`): ```lua local NAMEPLATE = asset.resolve("markersKit.Nameplate", "component") dummy.component.add(NAMEPLATE, { style = "health", name = "Training Dummy" }) boss.component.add(NAMEPLATE, { style = "boss", name = "The Iron Warden", height = 4 }) ``` Players get one automatically, showing the player's name (`playerNameplates = true`). Your own plate is hidden from you (`hideOwnNameplate = true`). While the kit draws player plates it hides the engine's own floating name label over players on your screen, so a name is never shown twice (`hideEngineNameLabels = true`; set it to `false` to keep the engine's label). The name on a plate is, in order: the Nameplate's own `name`, else the player's `PlayerAvatar.displayName` (for a player avatar or anything parented under one; it is synced, so every peer shows the same name), else a `displayName` set on the target's healthKit health, else healthKit's name for it, else the entity's name. `kit.nameOf(entityOrId)` returns the same name for your own UI. ## Installing into an empty world Install markersKit from ZeroMind and run the quick start: there is no extra step. This was checked by installing markersKit into a brand-new, empty world and following this README word for word. **What lands in `/source/deps`:** `barsKit.package` (1.2.0), `Lifeline.package` (1.0.1), `MatchFlow.package` (1.0.0) and healthKit 1.0.0. healthKit was renamed SecondWind after its 1.1.4 release, so its folder is `deps/7a497fbf-1b4e-4655-8abf-e588fa7caa5c/SecondWind.package` and its `package.yaml` says "SecondWind 1.2.0", but the code inside is healthKit 1.0.0 (its catalog reports `VERSION = "1.0.0"`). The `versions/` folders beside them hold copies of a few parts that barsKit and MatchFlow were built against; leave them alone. **What you get straight away:** - The quick start prints `1 1 1`. - healthKit loads: `attach`, `damage` and `heal` work, and healthKit damage drives hit markers, damage numbers and direction indicators. - Health-bar nameplates sit on real barsKit Bars that follow health (a plate read 1 → 0.7 after a 30-point hit and 0.8 after a 10-point heal), in edit mode, in play and after a world reload. - Crosshairs, themes, the catalog and the Gallery all work. **In the log:** for a few seconds right after installing, a burst of `needs version … which is being fetched`, `not found` and `component 'PlayerAvatar' is recorded as asset …` errors while the content lands. They stop once it has landed. After that you see `module 'Lifeline.api' not found` from `deps/7a497fbf-…/versions/…/SecondWind.Vitals`, which is healthKit 1.1.4's copy that barsKit brings along (issue #19260, see [Known limits](#known-limits)). markersKit and healthKit 1.0.0 do not use it, and nothing stops working. Two things here are still open platform issues, listed under [Known limits](#known-limits): healthKit arrives under the name "SecondWind 1.2.0" (#19270), and the copied SecondWind `Vitals` cannot find Lifeline (#19260). `require("markersKit.healthGuard").available` and `require("markersKit.barsFallback").mode` say what loaded (`true` and `"barsKit"` in a fresh install today). ## What is in the box | asset | what it is | |---|---| | `markersKit.api` | **Start here.** The one module a game needs: themes, styles, settings, feedback calls, nameplates, the catalog. | | `markersKit.Feedback` (component) | The HUD. One per scene. Its fields are the kit's settings, so you can style everything from the inspector or the scene. | | `markersKit.Nameplate` (component) | A nameplate over the entity it sits on: style, name, team, height. | | `markersKit.Gallery` (component) | The firing-range style browser this world opens with. Add it to your own range to compare styles in place. | | `markersKit.catalog` | Every style with its name, families and purpose. Also the theme table. | | `crosshairs`, `hitmarkers`, `directions`, `numbers`, `nameplates` | One renderer per category: `render(id, view)` returns a UI node tree. Use them to draw a style anywhere, such as a settings menu preview. | | `hud` | The per-peer runtime behind the api (queues, healthKit hookup, screen). | | `draw` | Shared drawing helpers (pens, SVG arcs, pixel font). | ## Choosing a style ```lua local kit = require("markersKit.api") for _, s in kit.catalog("crosshair") do print(s.id, s.name, s.purpose) end kit.describe("crosshair", "dynamic") --> { id, name, families, purpose, ... } kit.family("pixel") --> every pixel style in every category kit.styles("numbers") --> { "pop", "arc", "combo", ... } kit.themes() --> the six themes and the style each picks -- every style has tags: pick by what it does for _, s in kit.catalog() do if table.find(s.tags, "heal") then print(s.category, s.id) end end ``` Each entry is `{ id, category, name, families, tags, purpose }`. Switch with one call each. Each call returns `ok, err`, and an unknown id is refused with a message naming the catalog call to use: ```lua kit.setTheme("fantasy") -- every category at once kit.setCrosshair("dynamic", { color = "#7cf7ff", size = 1.2, thickness = 1.5 }) kit.setHitMarker("scifi") kit.setDirection("edge") -- "none" turns it off kit.setNumbers("combo") -- or "heal", "lifeline:pop", … kit.setNameplate("team") kit.set("showNumbers", false) -- any setting by name ``` On the component, set the same thing as a field: `theme = "pixel"`, `crosshair = "scope"`, and so on. `auto` means "the theme's choice". ## Themes Setting a theme picks one style per category plus the crosshair colour. Any single style can still be overridden afterwards. | theme | crosshair | hitMarker | direction | numbers | nameplate | colour | |---|---|---|---|---|---|---| | `realistic` | `dynamic` | `tactical` | `edge` | `realistic` | `realistic` | `#ffffff` | | `scifi` | `holo` | `scifi` | `chevrons` | `scifi` | `scifi` | `#7cf0ff` | | `fantasy` | `rune` | `fantasy` | `lifeline` | `fantasy` | `fantasy` | `#ffe6a8` | | `cartoon` | `bubble` | `cartoon` | `arrow` | `cartoon` | `cartoon` | `#ffffff` | | `pixel` | `pixelCross` | `pixel` | `pixel` | `pixel` | `pixel` | `#ffffff` | | `minimal` | `dot` | `minimal` | `ring` | `minimal` | `minimal` | `#ffffff` | ## Styles Generated from `kit.catalog()`, so the purposes here are the same words the catalog returns. ### Crosshairs (`crosshair`, 26) | id | name | families | tags | what it is for | |---|---|---|---|---| | `dot` | Dot | minimal | `basic` | A single small dot. Least screen clutter; good for third-person and casual shooters. | | `cross` | Classic cross | realistic, minimal | `basic` | Four arms with a centre gap: the default FPS crosshair that reads on any background. | | `crossDot` | Cross + dot | realistic | `basic` | Classic cross with a centre dot for precise aim at range. | | `tCross` | T cross | realistic, minimal | `basic` | Cross without the top arm so the target's head stays visible. | | `circle` | Circle | minimal | `basic` | An open ring: forgiving, readable aim for casual and arcade games. | | `circleDot` | Circle + dot | realistic, minimal | `basic` | Ring around a dot; the ring frames the target, the dot gives the exact point. | | `dynamic` | Dynamic spread | realistic, scifi | `dynamic` `spread` | Cross whose arms spread open while you move or shoot and tighten when you stop, showing your accuracy. | | `bloom` | Bloom ring | scifi, minimal | `dynamic` `spread` | Ring that grows with spread (bloom) and settles back: accuracy feedback without arms. | | `shotgun` | Shotgun ring | realistic | `dynamic` `spread` `shotgun` | Wide ring showing the pellet cone, with pellet dots and ticks; widens with spread. | | `scope` | Sniper scope | realistic | `overlay` `sniper` `fullscreen` | Full-screen scope overlay: black surround, fine reticle with mil-dots and a red centre. Use while aiming down a sniper. | | `chevron` | Chevron | realistic, minimal | `basic` | An upward chevron (ACOG style) with the tip as the aim point; precise but unobtrusive. | | `lockOn` | Lock-on reticle | scifi | `lock` `target` | Brackets that slide onto the target nearest your aim and lock with a LOCKED tag; for homing weapons and aim assist. | | `brackets` | Brackets | scifi | `themed` | Two angled brackets around a dot: a clean sci-fi HUD reticle. | | `diamond` | Diamond | minimal, scifi | `themed` | A small rotated square with a dot; tidy and modern. | | `triangle` | Triangle | scifi | `themed` | Triangle outline with a dot; a sci-fi interface look. | | `hex` | Hex | scifi | `themed` | Glowing hexagon with inner ticks: sci-fi energy weapons. | | `arcs` | Split arcs | scifi | `themed` | Three glowing arcs around a dot: futuristic plasma and laser guns. | | `pixelCross` | Pixel cross | pixel | `themed` | Chunky 8-bit plus made of square pixels: retro and voxel games. | | `pixelDot` | Pixel dot | pixel | `themed` | A pixel dot with four corner pixels; retro and low-res styles. | | `star` | Star | cartoon | `themed` | Bold-outlined cartoon star: playful party and kids' games. | | `bubble` | Bubble | cartoon | `themed` | Thick inked ring with a shine highlight: cartoon and toy shooters. | | `gap` | Four dots | minimal | `themed` | Four tiny dots around an empty centre: the lightest possible reticle. | | `rune` | Rune circle | fantasy | `themed` | Thin gold circle with diamond runes at the cardinals: bows, spells and fantasy RPGs. | | `compass` | Compass rose | fantasy | `themed` | A four-point compass star: magic and crossbow aiming. | | `holo` | Holo red dot | realistic | `themed` `sight` | Holographic sight: faint glass ring and a glowing dot. Modern military shooters. | | `milDot` | Mil-dot | realistic | `themed` `sniper` | Long thin cross with range dots along the arms: tactical and marksman rifles. | ### Hit markers (`hitMarker`, 8) | id | name | families | tags | what it is for | |---|---|---|---|---| | `classic` | Classic X | realistic, minimal | `basic` `default` `x` `fps` | Four diagonal ticks around the crosshair. Crit turns gold and grows, headshot adds a ring and tag, kill flashes red with a skull. | | `tactical` | Tactical | realistic | `subtle` `fast` `mil-sim` `x` | Thin, fast, quiet X for mil-sim shooters; kills add an ELIMINATED tag. | | `minimal` | Minimal dots | minimal | `subtle` `dots` `competitive` | Four tiny dots that blink: the least intrusive confirmation. | | `scifi` | Sci-fi chevrons | scifi | `glow` `chevron` `animated` | Glowing chevrons that snap inward; kills burst into a hexagon with TERMINATED. | | `pixel` | Pixel | pixel | `retro` `8-bit` `blocky` | Blocky 8-bit X with pixel sparkles; kills show a pixel skull and KO. | | `cartoon` | Cartoon POW | cartoon | `comic` `words` `bold` | Inked comic bursts with words: POW!, CRIT!, BONK! and K.O.! | | `fantasy` | Fantasy sparkle | fantasy | `sparkle` `star` `rpg` | Four-point star sparkles: silver hits, gold crits, crimson headshots, SLAIN on a kill. | | `burst` | Speed burst | cartoon, scifi | `animated` `speed-lines` `flashy` | Radial speed lines that fly outward; more lines and colour the bigger the hit. | ### Damage direction (`direction`, 9) | id | name | families | tags | what it is for | |---|---|---|---|---| | `ring` | Crosshair ring | realistic, minimal | `crosshair` `default` `subtle` | A red arc on a ring around the crosshair, centred on the attacker's side. The modern shooter default. | | `edge` | Screen edge glow | realistic, minimal | `screen-edge` `peripheral` `subtle` | The screen edge nearest the attacker glows red. Readable from the corner of your eye, never covers the crosshair. | | `arrow` | Cartoon arrow | cartoon | `arrow` `bouncy` `crosshair` | A fat outlined arrow orbiting the centre and pointing at the attacker, with a bounce. | | `compass` | Compass bar | scifi, realistic | `compass` `top-of-screen` `bearing` | A heading strip at the top of the screen with a red tick at the attacker's bearing; behind you shows at the ends. | | `vignette` | Side vignette | realistic | `screen-edge` `vignette` `immersive` | A blood-red vignette that leans toward the side the hit came from. | | `pixel` | Pixel arrows | pixel | `retro` `arrow` `screen-edge` | Blocky 8-bit arrows at the screen edge pointing at the attacker. | | `lifeline` | Lifeline arc | fantasy, realistic | `lifeline` `arc` `crosshair` | Lifeline's red arc-and-pointer around the centre, reused as is for worlds already using Lifeline. | | `chevrons` | Sci-fi chevrons | scifi | `glow` `radar` `animated` | Three glowing chevrons stacked toward the attacker that pulse outward like a radar warning. | | `none` | Off | minimal | `off` `none` | No damage-direction indicator. | ### Damage numbers (`numbers`, 19) | id | name | families | tags | what it is for | |---|---|---|---|---| | `pop` | Pop | realistic, minimal | `default` `punchy` `rise` `lifeline` | Numbers punch in over the target, settle and rise away. Crits use Lifeline's gold burst. The all-round default. | | `arc` | Arc fly-out | cartoon, realistic | `arc` `fly-out` `fan` | Each number is flung out sideways and falls in an arc, so rapid hits fan out instead of stacking. | | `combo` | Running total | realistic, scifi | `total` `stacking` `counter` `lifeline` | Hits on one target add into one growing total with an xN hit counter; it bumps on every hit and fades once you stop. | | `dramatic` | Dramatic crits | fantasy, cartoon | `crit` `big` `shake` | Normal hits stay small; crits, headshots and kills slam in huge with a starburst and a shake. Big moments feel big. | | `scroll` | Scrolling combat text | fantasy, realistic | `mmo` `column` `readable` | MMO-style text that scrolls steadily up beside the target in a tidy column, easy to read during long fights. | | `pixel` | Pixel | pixel | `retro` `8-bit` `blocky` | Chunky 3x5 pixel digits with a hard shadow that hop up in steps. Retro and arcade games. | | `scifi` | Sci-fi readout | scifi | `monospace` `glow` `readout` | Monospace digits in brackets with a scan-in flicker and a glow, like a targeting computer's readout. | | `fantasy` | Fantasy gilded | fantasy | `serif` `gold` `rpg` | Serif numbers in parchment white and gilded gold for crits, drifting up like embers. | | `cartoon` | Cartoon | cartoon | `comic` `bouncy` `lifeline` | Lifeline's tilted, inked comic-book numbers with a bouncy pop. | | `minimal` | Minimal | minimal | `small` `subtle` `competitive` `lifeline` | Small plain digits that rise and fade fast. Stays out of the way in competitive play. | | `realistic` | Tactical | realistic | `small` `translucent` `subtle` | Small, crisp, slightly translucent numbers that drift and fade without bounce, for grounded shooters. | | `heal` | Healer green | minimal, fantasy | `heal` `green` `support` `soft` | Built for support and healer classes: heals bloom as big soft green +N with a cross and rise gently, while damage stays small and plain so the healing reads first. | | `lifeline:pop` | Lifeline pop | realistic, minimal | `lifeline` `punchy` `rise` | Lifeline's own pop numbers, every hit drawn with Lifeline's pop look (heals use Lifeline's heal look). For worlds already using Lifeline's numbers. | | `lifeline:crit` | Lifeline crit burst | fantasy, cartoon | `lifeline` `crit` `burst` `gold` | Lifeline's gold crit burst on every hit: loud and celebratory, for arcade games where every hit should feel big. | | `lifeline:heal` | Lifeline heal | fantasy, minimal | `lifeline` `heal` `green` `soft` | Lifeline's soft green heal number for everything, so a support-only HUD stays calm. | | `lifeline:combo` | Lifeline combo | realistic, scifi | `lifeline` `total` `stacking` `counter` | Lifeline's running combo total with its xN counter; hits on one target add into one number. | | `lifeline:immune` | Lifeline blocked | realistic, scifi | `lifeline` `shield` `blocked` `immune` | Lifeline's shield-glyph IMMUNE/BLOCKED look, for tanks, shields and invulnerable phases. | | `lifeline:minimal` | Lifeline minimal | minimal | `lifeline` `small` `subtle` `competitive` | Lifeline's small plain digits, unchanged. | | `lifeline:comic` | Lifeline comic | cartoon | `lifeline` `comic` `bouncy` | Lifeline's tilted, inked comic numbers on every hit (crits keep the gold burst). | ### Nameplates (`nameplate`, 10) | id | name | families | tags | what it is for | |---|---|---|---|---| | `name` | Name only | minimal, realistic | `name-only` `social` `no-bar` | Just the name, with a small marker on players. For social spaces, or when health should stay hidden. | | `health` | Name + health | realistic, minimal | `default` `health-bar` `enemy` | The standard overhead plate: name over a health bar (barsKit 'overhead'). Good default for enemies and dummies. | | `team` | Team coloured | realistic, scifi | `team` `health-bar` `pvp` | Name, team chip and a segmented bar all in the team's colour, so friend and foe read at a glance. | | `boss` | Boss | fantasy, realistic | `boss` `wide` `health-bar` | A wide boss bar (barsKit 'boss') under a big title with a skull crest. For bosses and elites. | | `pixel` | Pixel | pixel | `retro` `8-bit` `health-bar` | Pixel-font name over barsKit's chunky 8-bit bar. | | `scifi` | Sci-fi hologram | scifi | `hologram` `monospace` `health-bar` | Monospace bracketed name over barsKit's flickering hologram bar. | | `fantasy` | Fantasy ornate | fantasy | `ornate` `serif` `health-bar` | Serif name with flourishes over barsKit's gilded ornate bar. | | `cartoon` | Cartoon bubbly | cartoon | `bubbly` `bold` `health-bar` | Bold rounded name over barsKit's bubbly, glossy bar. | | `minimal` | Minimal line | minimal | `hairline` `small` `health-bar` | Small name over a hairline bar (barsKit 'line'). Lowest clutter. | | `realistic` | Realistic ghost | realistic | `ghost-trail` `plain` `health-bar` | Plain name over barsKit's ghost bar, whose trail shows how much a hit just took. | Every crosshair takes `color`, `size` (0.5–3) and `thickness` (0.5–4). Every hit marker has four variants (`hit`, `crit`, `headshot`, `kill`); `markerColor` tints the normal one. Every numbers style has `hit`, `crit`, `headshot`, `kill` and green `heal` looks, and `numberScale` sizes them. Special behaviour: - **`dynamic`, `bloom`, `shotgun` and `brackets`** spread open as you move or fire and tighten when you stop. Spread comes from your avatar's speed (`spreadFromMovement`) plus `kit.kick(amount)`, which you call when your weapon fires. Every hit also kicks a little. - **`lockOn`** grabs the healthKit target nearest the crosshair within `lockRange` metres and fills its lock over `lockTime` seconds. Read the lock with `kit.lockTarget()` (`id, locked`), and pin a target yourself with `kit.lockOn(entity)` (`nil` releases it). - **`combo`** and **`lifeline:combo`** (numbers) merge your hits on one target into one running total while you keep hitting. Heals never merge. - **`heal`** (numbers) is the green healing look as a style of its own (`kit.setNumbers("heal")`): heals bloom as big soft green `+N` with a cross, while damage stays small and plain so the healing reads first. For medics, support classes and regen showcases. Every other style turns heals green too, just less loudly. - **`lifeline:*`** (numbers) are Lifeline's own number styles, drawn by Lifeline's renderer: `lifeline:pop`, `lifeline:crit`, `lifeline:heal`, `lifeline:combo`, `lifeline:immune`, `lifeline:minimal`, `lifeline:comic`. - **Nameplate bars** sit on real barsKit `Bar` components (`show = "health"`, `placement = "world"`, target = the plate's entity) on a fresh engine, after a restart and for every player, so they follow healthKit health and look exactly as they do anywhere else barsKit is used. Each style picks the barsKit look (`overhead`, `pixel`, `hologram`, `ornate`, `bubbly`, `line`, `ghost`, `segmented`); `boss` uses a large `ghost` bar in the world because barsKit's `boss` look is screen-only (the gallery preview shows the `boss` look). The bar goes when the plate goes. If barsKit's `Bar` ever fails to load, the plate draws the same look itself instead, so it still shows a bar that follows health (see [what you see on a fresh engine](#what-you-see-on-a-fresh-engine)). - **`scope`** draws a full-screen sniper overlay. Switch to it while aiming down sights and back afterwards. ## Settings | setting | default | meaning | |---|---|---| | `theme` | `""` | One theme for the whole kit (empty = the defaults below). | | `crosshair` / `hitMarker` / `direction` / `numbers` / `nameplate` | `cross` / `classic` / `ring` / `pop` / `health` | The style in each category. | | `color` | `#ffffff` | Crosshair colour. | | `size`, `thickness` | `1`, `1` | Crosshair size and line thickness multipliers. | | `markerColor` | `""` | Normal hit-marker tint (empty = the style's own). | | `numberScale`, `nameplateScale` | `1`, `1` | Size multipliers. | | `showCrosshair`, `showMarkers`, `showNumbers`, `showDirection`, `showNameplates` | `true` | Turn a whole category on or off. | | `playerNameplates` | `true` | Give every player a nameplate with their name. | | `hideOwnNameplate` | `true` | Do not draw your own plate. | | `hideEngineNameLabels` | `true` | While player nameplates are drawn, hide the engine's own name label over players on this peer (no double names). | | `nameplateRange` | `45` | Metres beyond which plates are hidden. | | `spreadFromMovement` | `true` | Moving opens the dynamic crosshairs. | | `lockOn`, `lockRange`, `lockTime` | `auto`, `60`, `0.6` | Lock-on reticle behaviour. | `kit.settings()` returns a copy of the current settings. `kit.reset()` puts the defaults back. ## Multiplayer Every peer runs its own HUD, and it decides what to show by asking "is this mine?": | event (from healthKit) | who sees what | |---|---| | `damaged` | **The attacker** (`by` is my avatar, a child of it such as a weapon, or a synced thing I own) sees the hit marker and the number over the target. **The victim** (`target` is my avatar) sees the direction indicator, pointing at `origin` (or at the attacker). Nobody else sees anything. | | `healed` | The healer sees the green number. A self-heal shows on yourself. | | `killed` | The killer sees exactly one kill marker (the damage that caused the kill does not add a second one). | | nameplates | Everyone. Plates read health from healthKit, which is already synced. | **Synced and unsynced targets.** A synced target (a player, or anything with `setSynced(true)`) takes damage on its owner's peer, and healthKit sends the event to everyone, so every player sees the same health and the rules above decide who sees what. An unsynced target exists separately on every peer: hits on it are simulated only on the peer that made them, so its bar can differ between players. Make shared targets synced. The gallery's dummies are synced scene entities, so everyone sees the same health drop. The dummies' owner (the first player in, the host) applies the range's scripted strikes as real healthKit damage, credited to the `RangeGallery` entity rather than to a player, and every player's Gallery shows the markers and numbers for them. Your own shots at a dummy still follow the rules above: only you see your markers. In edit mode nobody owns the dummies yet, so the Gallery previews the strikes without changing health. "Me" is the scene's local player avatar (from the PlayerPrototype), so the scene needs nothing extra. Worlds with their own player system can say who "me" is with `kit.setLocalPlayer(entityOrId)`, or replace the test entirely with `kit.setMineFilter(function(byId) return ... end)`. `kit.isMine(id)` answers the question for your own code. The `kit.show*` calls are pure local display. They draw on the peer that calls them and deal no damage. Call them from your own client-side code when you are not using healthKit. ## One set of numbers: healthKit and Lifeline alongside markersKit markersKit draws its own hit markers, damage numbers and damage direction. Lifeline draws its own as well, and healthKit's `HUD` component adds Lifeline's HUD by itself. Turn theirs off so each hit shows one number and one direction cue: - **Lifeline's `LifelineHUD`:** set `showNumbers = false`, and take `direction` out of `feedback` (e.g. `"flash shake vignette heartbeat"`). Its health bars, flash and death screen keep working. - **healthKit's `HUD`:** set `addLifelineHUD = false` if you don't want Lifeline's HUD added at all. Otherwise apply the line above to the `LifelineHUD` it adds. ```lua for _, e in entity.findAll("*") do local ll = e.component.get("LifelineHUD") if ll then ll.showNumbers = false; ll.feedback = "flash shake vignette heartbeat" end end ``` To keep Lifeline's look instead, use its styles through markersKit: `kit.setNumbers("lifeline:pop")` (or `lifeline:crit`, `lifeline:combo`, …) with Lifeline's own numbers off. The engine's name labels over players are handled separately by `hideEngineNameLabels`. ## What you see on a fresh engine **Today, on a freshly started engine and after every restart:** barsKit loads in full, so every nameplate with a health bar (`health`, `team`, `boss`, `pixel`, `scifi`, `fantasy`, `cartoon`, `minimal`, `realistic`) sits on a real barsKit `Bar` component (`show = "health"`) from the first frame, with the plate's name and dressing on top. The bar reads the same synced healthKit health as everything else, so it drops as the target takes damage, refills when it heals and fades out when it dies, and every player sees the same bar on a synced target. `name` stays bar-less. Nothing about barsKit shows up in the log. **If barsKit's `Bar` ever fails to load** (an older engine, a broken install), every health-bar plate still shows a bar that follows health: the plate draws it itself, picking the best it can get, and markersKit logs one warning saying which: | `barsFallback.mode` | when | the plate shows | |---|---|---| | `"barsKit"` | barsKit's `api` and `hud` load (**today**) | a real barsKit `Bar` component over the target | | `"looks"` | only barsKit's `looks` loads | the same barsKit look (overhead, segmented, boss, pixel, hologram, ornate, bubbly, line, ghost), drawn inside the plate | | `"lifeline"` | barsKit does not load at all | Lifeline's matching bar style, drawn inside the plate | | `"plain"` | neither loads | a plain green bar | markersKit keeps retrying what is missing (after 2 s, doubling up to once a minute). If barsKit's `Bar` starts loading later in the session, the plates switch to real barsKit Bars on the next frame, with nothing for you to do. ```lua local BF = require("markersKit.barsFallback") print(BF.mode, BF.available) --> "barsKit" true (a fresh engine today) print(BF.status().tries) -- load attempts so far kit.plateView(dummy.id) --> { frac = 0.6, bar = "barsKit", realBar = true, style = "health", ... } ``` ## Switching off and cleaning up Everything the kit draws lives only while it is switched on, and goes when it is switched off. | you do | what happens | |---|---| | disable the last enabled Feedback component | the HUD screen is unregistered; crosshair, markers, numbers, directions, every nameplate and every barsKit bar it put up go | | enable a Feedback again | the HUD comes back (and lifts a `kit.stop()`) | | delete the Feedback (or its entity) | the same as disabling, and nothing is left behind | | `kit.stop()` | switches the HUD off on this peer even while Feedbacks are enabled, until `kit.start()` or a Feedback is enabled again | | disable or delete a Nameplate | its plate and its bar go; enabling it puts them back | | disable or delete the Gallery | its panel screen is unregistered; enabling it brings the panel back | Nameplates are drawn only while the HUD is on (an enabled Feedback, or `kit.start()`). ```lua kit.active() --> is the HUD running on this peer? kit.stopped() --> did kit.stop() switch it off? kit.stats() --> { markers, numbers, directions, plates, drawn, bars, feedbacks, registered, active, stopped, engineLabelsHidden } ``` `plates` counts registered plates, `drawn` the plates on screen this frame and `bars` the real barsKit Bars the kit has up (0 while the plates draw their own bars, see the fresh-engine section). `kit.plateView(entity)` says what one plate showed last frame. The Gallery component has `refresh()` (draw the panel now) and `shown()` (is the panel on screen?). ## Without healthKit ```lua kit.hit(target, 35, { kind = "crit" }) -- healthKit target: deals real damage (and feedback follows); -- anything else: just shows the marker + number kit.heal(target, 20) kit.showHit("kill") kit.showNumber(entityOrIdOrPosition, 42, "headshot") -- kinds: hit, crit, headshot, kill, heal kit.showDirection(fromPositionOrEntity, 0.7) -- or an angle in degrees (0 = ahead, 90 = right) kit.clear() ``` ## Dependencies markersKit 2.0.5 depends on these published packages. They are declared in `package.yaml` (`dependencies:`) and install with the kit. | package | version | guid | world | what markersKit uses it for | |---|---|---|---|---| | **healthKit** | 1.0.0 | `5da0a53c-5953-4adc-80fb-f5afb02f6568` | `7a497fbf-1b4e-4655-8abf-e588fa7caa5c` | Health, damage, death and respawn. Its `damaged`, `healed` and `killed` events drive markers, numbers and directions; nameplates read its health and names. | | **barsKit** (Gaugeworks) | 1.2.0 | `c154eb07-ce7c-48ca-8232-4ce1a8754214` | `d9f6c7f4-b6e3-4865-958f-8b9ed971056d` | Nameplate bar looks: each health-bar plate sits on a real barsKit `Bar` showing healthKit health (and draws its looks itself if the `Bar` ever fails to load). | | **Lifeline** | 1.0.1 | `7b85ce05-3903-4374-b654-2d4ffea295a5` | `45f92606-2e79-4b2b-8e03-b1fa2649e5c2` | The `lifeline` direction indicator, the `lifeline:*` number styles and the crit burst are Lifeline's own renderers, reused rather than copied. Its bar styles are what plates draw if barsKit does not load at all. | | **MatchFlow** | 1.0.0 | `31cf13b4-df7d-4888-85e2-7947a7301614` | `40bc9b7f-d32c-427f-b0ac-22d25071e2fa` | Comes in with healthKit (rounds and teams); markersKit does not call it directly. | ## The gallery `markersKit.Gallery` turns a scene into a style browser: a panel listing every style of every category with a live preview and its purpose, while dummies whose names start with `Dummy` take scripted hits. The role is read from the dummy's name: `normal`, `crit`, `headshot`, `kill`, `heal`, `combo`, `boss`, `team`, `plate`. | control | default key | |---|---| | show / hide the panel | `G` (or the Styles button) | | previous / next style | `[` / `]` (or the arrow buttons) | | next category | `\` (or the tabs) | Every key can be changed with the component's `toggleKey`, `prevKey`, `nextKey` and `categoryKey` fields. On a portrait phone the panel docks to the bottom with three cards a page. On landscape it docks to the side. ## Phones and the web The HUD measures the screen every frame. Landscape screens scale against 1280×720, and portrait screens lay out as a ~430-point-wide phone, so crosshairs, numbers and plates stay legible from a desktop monitor down to a phone. Everything is UI-tree drawing (SVG and labels), with no textures or shaders to load, so it runs the same in the web build. ## Tests `markersKit` (testSuite) covers every public call of `api`, `catalog` and `hud`, every renderer for every style and hit kind, tags on every style, the `heal` and `lifeline:*` number styles, multiplayer filtering, player names from `PlayerAvatar`, healthKit integration, real barsKit bars under plates, the barsKit-not-available case (every fallback tier drawing every bar style, bars following healthKit damage and heals, switching to real Bars when barsKit loads later, two players seeing the same bars and never their own plate), the healthKit-not-available case (the quick start, `kit.hit`/`kit.heal`, nameplates and the Gallery without healthKit, and hooking up when healthKit loads later), switching off and cleaning up (Feedback, Nameplate and Gallery disabled, re-enabled and deleted; `stop()`/`start()`), phone layouts, and the version and dependencies agreeing across the catalog, `package.yaml` and this README. Run it in edit mode (it is refused in play). `tests` is a toolbox, not a Luau global, so call it through `tools.use`. From Luau (an agent's `execute`, or a script): ```lua local r = tools.use("tests", "run", { suite = "markersKit" }) print(r.passed, r.stats.passed, r.stats.failed, r.stats.skipped) --> true 66 0 0 ``` Or from the engine shell: ```bash zero tests run markersKit ``` Both write the full report to `/source/tmp/test_results.md` and `/source/tmp/test_results.json`. ## Known limits Two platform issues are open. Both show up only after installing into an empty world, and neither stops markersKit from working: - **#19270: healthKit arrives as "SecondWind 1.2.0".** The healthKit dependency is installed in a folder named `SecondWind.package`, and its `package.yaml` and README say "SecondWind 1.2.0". The code inside is healthKit 1.0.0, which markersKit pins: its catalog reports `VERSION = "1.0.0"`, and attach, damage and heal work. - **#19260: the copied SecondWind `Vitals` cannot find Lifeline.** healthKit 1.1.4's `Vitals`, copied into `deps/7a497fbf-…/versions/` because barsKit was built against it, logs `module 'Lifeline.api' not found` whenever it loads. markersKit and healthKit 1.0.0 do not use that copy, and nothing stops working. Fixed since earlier versions: barsKit's `Bar` not loading on a fresh engine (#19188), and healthKit not loading at all after an install into an empty world (see the 2.0.4 changelog). ## Changelog ### 2.0.5 - README: "Known limits" lists the two platform issues still open after installing into an empty world, healthKit arriving as "SecondWind 1.2.0" (#19270) and the copied SecondWind `Vitals` not finding Lifeline (#19260). "Installing into an empty world" points to them. - README: the Tests section shows commands that really run the suite (`tools.use("tests", "run", { suite = "markersKit" })` from Luau, `zero tests run markersKit` from the shell). The old `tests.run(...)` line failed because `tests` is not a Luau global. - No change to styles, settings or the api. ### 2.0.4 - Checked again on today's platform: barsKit's real `Bar` loads on a fresh engine and after a restart (#19188 is fixed), so every health-bar nameplate sits on a real barsKit `Bar` that follows health, for every player. The plate-drawn bar stays as a safety net. - Installed into a brand-new, empty world, healthKit 1.0.0 now loads with no extra step, so the README's workaround (deleting the healthKit 1.1.4 copies) is gone. The quick start was followed word for word in a fresh install. - README: "Installing into an empty world", "What you see on a fresh engine" and the nameplate-bar notes describe what you see today; new "Known limits" section. No change to styles, settings or the api. ### 2.0.3 - healthKit is loaded behind a guard (new `markersKit.healthGuard`), so markersKit loads and runs even when healthKit cannot. That is the case today right after installing into an empty world (see "Installing into an empty world"). Without healthKit, crosshairs, markers, numbers, directions, themes, nameplate names and the gallery preview all work. `kit.hit`/`kit.heal` show the marker and number without dealing damage. markersKit hooks up to healthKit as soon as it loads. - Six new tests cover the healthKit-not-available case. Tests that need healthKit stand down, reported as skipped with the reason, where it cannot load. ### 2.0.2 - Fix: health-bar nameplates showed no bar at all on a fresh engine and after a restart. With barsKit's `Bar` missing (#19188), plates still reserved room for a barsKit Bar that never came. Now a plate leaves that room only when a real Bar is up. Otherwise it draws its own bar in its style's barsKit look, or Lifeline's matching bar style if barsKit's looks are missing too, or a plain bar as a last resort. The bar follows healthKit health and is the same for every player. - `barsFallback` decides live and keeps retrying (2 s doubling to 60 s), so plates switch to real barsKit Bars if barsKit's `Bar` loads later in the session. New `barsFallback.mode`, `status()` and `refresh()`, plus `kit.plateView(entity)`. - README: the fresh-engine section says exactly what you see. Six new tests cover the barsKit-not-available case. ### 2.0.1 - barsKit is loaded with a guard: if it fails (#19188), the kit still runs and nameplates draw a plain bar. New `markersKit.barsFallback` module. - README: how to keep a single set of numbers with healthKit and Lifeline installed, and the barsKit known issue. - Gallery world: opens looking at the range, six spawns along the firing line, no "{PlayerName}" placeholder. - **2.0.0** (breaking): Renamed from combatFeedbackKit to **markersKit**; require `markersKit.api` (and `markersKit.*` assets). Every style carries `tags`. 8 new number styles: a green `heal` style and Lifeline's `lifeline:pop`, `lifeline:crit`, `lifeline:heal`, `lifeline:combo`, `lifeline:immune`, `lifeline:minimal` and `lifeline:comic` (19 in all, 72 styles). Nameplate bars are now real barsKit `Bar` components hooked to healthKit health. Player plates show the player's own `PlayerAvatar.displayName`. The gallery dummies are synced, so every player sees the same health. Switching off works: disabling a Feedback, Nameplate or Gallery hides what it drew, re-enabling brings it back, deleting leaves nothing behind, and `kit.stop()` is a real off switch (new `kit.active()`, `kit.stopped()`, `stats().drawn/bars/active/stopped`, Gallery `refresh()`/`shown()`). Dependencies are declared in `package.yaml`. - **1.0.0**: First release (as combatFeedbackKit). 26 crosshairs, 8 hit markers, 9 direction indicators, 11 number styles, 10 nameplates, 6 themes, a catalog, the Feedback, Nameplate and Gallery components, and a test suite.

# hitmarkers 8 hit-marker looks (classic, tactical, minimal, scifi, pixel, cartoon, fantasy, burst), each with distinct `hit`, `crit`, `headshot` and `kill` variants and an animated life (`LIFE[kind]`). `render(id, { kind, age, cx, cy, color, size })` returns a UI tree. Used by `hud` when this peer's hit lands.

# directions 8 damage-direction indicators that show the hurt player where a hit came from: around the crosshair (ring, chevrons, arrow, Lifeline's own arc), at the screen edges (edge, vignette), on a compass strip at the top, or in pixel art. `render(id, { angle, age, intensity, W, H, cx, cy })`, where `angle` is relative to the camera (0 = ahead, positive = right). The `lifeline` style is Lifeline's feedback renderer, reused.

# numbers 11 floating damage and heal number styles: pop, arc fly-out, running combo total (`merges`), dramatic crits, scroll, pixel, sci-fi, fantasy, cartoon, minimal and realistic. Each has hit, crit, headshot, kill and green heal looks. `render(id, entry, age, W, H)` draws one number entry (`amount`, `kind`, screen `x`, `y`, `hits`, `seed`). Crit bursts and the cartoon and fantasy faces come from Lifeline's numbers module.

# crosshairs 26 crosshair styles and their renderer: `render(id, view)` returns a UI node tree centred on `view.cx, view.cy`. The view fields are `color`, `size`, `thickness`, `spread` (0–1, used by the dynamic styles), `t`, `lock` (for `lockOn`) and `opacity`. Includes dot, cross, circle, dynamic spread, shotgun ring, sniper scope, chevron, lock-on and themed sci-fi, fantasy, cartoon, pixel and minimal reticles. `ids`, `has` and `get` list them. Called by `hud`; call it yourself to preview a crosshair in a menu.