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).
• 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):

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" })):

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). 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: 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

Choosing a style

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:

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.

Styles

Generated from kit.catalog(), so the purposes here are the same words the catalog returns.

Crosshairs (crosshair, 26)

Hit markers (hitMarker, 8)

Damage direction (direction, 9)

Damage numbers (numbers, 19)

Nameplates (nameplate, 10)

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).
• scope draws a full-screen sniper overlay. Switch to it while aiming down sights and back afterwards.

Settings

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?":

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.

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:

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.

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.

Nameplates are drawn only while the HUD is on (an enabled Feedback, or kit.start()).

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

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.

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.

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):

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:

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.