Log inGet started
World

Open Sesame: Doors, Switches, Locks and Chests Kit

README.md

barsKit 1.2.0

Health and resource bars for any world: one kit, lots of looks. You pick a look and say what the bar shows. To change the look later you change one word, live, and nothing else gets rewritten.

  • 20 looks of its own, plus Lifeline's 13 as lifeline:<style>, in 8 theme families: sci-fi, fantasy, cartoon, pixel, minimal, realistic, horror and cozy. Each look says its shape, whether it is a screen or world bar, and its size, so you can pick one without trying them all.
  • Works with healthKit out of the box: your health, shield, armour, hearts and lives, and the health of any enemy, NPC or prop.
  • Not tied to health: it can show stamina, mana, energy, XP, a boss, or any number your game keeps. The Resource component gives you a pool that drains and refills if you don't have one yet.
  • Feels good: the value eases to its new level, the lost chunk lingers as a ghost before draining, the bar pulses when low, numbers are optional, and each kind of resource has sensible colours.
  • Fits any screen: the HUD scales with the screen and respects safe areas, so it stays readable on a phone as well as a desktop. Bars never leave the screen, and the gallery or a panel of yours and the HUD never cover each other.
  • Leaves nothing behind: BK.remove takes a bar down along with the entity it was made on, and closing or removing the gallery takes its screens with it.
  • Multiplayer: your HUD bars always show your body. Bars over other players, enemies and props read synced healthKit state, so everyone sees the same value.

It depends on healthKit (and, through it, Lifeline), which installs with it.

Install and use

Install the package into your world with zeromind_install (search ZeroMind for "barsKit"). healthKit and Lifeline come with it.

1. Give your player health first

A health bar shows the health healthKit keeps, so the player's body needs health before any health, shield, armour, hearts or lives bar can show anything. Without it, the bar finds no health to read and is hidden entirely. You get no error, just no bar. The same goes for an enemy or prop you put a bar on.

Add these lines to your scene's build.luau, inside content(), after the default player setup (body is the player body it makes):

local HK = require("healthKit.api")
HK.attach(body, { maxHealth = 100 })                       -- every joining player gets health
-- or with a regenerating shield, the way this world's own scene does it:
-- HK.attach(body, { model = "shield", maxHealth = 100, maxShield = 40 })

HK.attach(enemy, { maxHealth = 250, displayName = "Grunt" })  -- anything else that should have a health bar

HK.attach adds healthKit's Vitals and Lifeline's Health to the entity. Adding the healthKit.Vitals component yourself (body.component.add(asset.resolve("healthKit.Vitals", "component"), { ... })) does the same thing. See the healthKit README for health models (hitPoints, shield, armor, hearts, lives), death styles and teams.

To check it worked: BK.read("health", body).ok is true once the body has health, and false before.

If your game keeps its own health instead of using healthKit, skip this step and point the bar at your number (show = "value" with bar:set, or BK.bind; see Pointing a bar at something). Stamina and mana bars need a Resource instead (see No stamina or mana yet?).

2. Put bars on screen

local BK = require("barsKit.api")

-- your health in the top-left corner
local hp = BK.bar({ look = "ghost", show = "health" })

-- a little bar over an enemy's head (the enemy needs health too, step 1)
BK.bar(enemy, { look = "overhead" })

-- a boss plate across the top
BK.bar({ look = "boss", target = "The Iron Warden", anchor = "topCenter", phases = "0.66 0.33" })

-- switch the look: one word, live
BK.setLook(hp, "pixel")
BK.setLookAll("hologram")                       -- every bar at once
BK.setLookAll("ornate", { placement = "screen" }) -- just the HUD

In a scene, you can add the component directly: e.component.add(asset.resolve("barsKit.Bar", "component"), { look = "orb", show = "mana", anchor = "bottomRight" }). Every field below is also settable in the editor's inspector.

Pointing a bar at something

show says what the bar shows, and target says whose it is. With no target, a screen bar reads the local player and a world bar reads the entity it sits on.

showreads
health (default)healthKit health (works on players, enemies and props)
shield, armor, hearts, livesthe matching healthKit value
stamina, mana, xp, anything elsethe Resource of that name on the target
valuea number you set with bar:set(value, max)

You can also bind any function, or point at any component field:

BK.bind(bar, function() return myGame.energy, myGame.maxEnergy end)
BK.bind(bar, { component = "Turret", field = "heat", max = 100 })   -- or maxField = "maxHeat"
BK.bar({ look = "segmented", show = "value", kind = "ammo" }):set(12, 30)

No stamina or mana yet? Make a resource

BK.resource(player, "stamina", { max = 100, regenRate = 25, regenDelay = 0.8, drainRate = 35, drainKey = "ShiftLeft" })
BK.resource(player, "mana", { max = 120, regenRate = 8 })

if BK.spend(player, "mana", 30) then castFireball() end   -- false (and nothing spent) when there isn't enough
BK.gain(player, "mana", 10)
BK.bar({ look = "orb", show = "mana", anchor = "bottomRight" })

A Resource regenerates after regenDelay seconds without spending, and drains while drainKey is held or draining is true. demo = true makes it drain and refill on its own, for showcases. The owner of the entity is the authority; other peers' spend/gain calls are sent to it, and the value syncs to everyone.

Note: a second Resource on one entity is a named component instance. On player avatars, add it at runtime with BK.resource(...) (for example in localPlayerReady) rather than on the PlayerPrototype, because named second instances don't carry over when the prototype is cloned.

The looks

Where is screen (HUD only), world (over an entity only) or both. Size is the HUD size in points at scale 1, and the size class is in brackets: small, medium, wide or tall.

idnameshapewheresizefamiliessuits
lineThin linelineboth240×22 (medium)minimalhealth, stamina, xp, energy
segmentedSegmentedsegmentedboth264×36 (medium)realistic, sci-fihealth, armor, energy, ammo
ringRadial ringringboth88×88 (small)sci-fi, minimalhealth, shield, energy, cooldown
heartsHeart containers (full, half and empty; blue shield hearts)heartsboth180×52 (medium)fantasy, cozy, pixelhealth, lives, hearts
bossBoss bar (name, phase marks, phase count)barscreen560×62 (wide)fantasy, horror, realisticboss
overheadOver-head barbarworld180×34 (medium)minimal, realisticoverhead, enemy, npc
ghostGhost bar (the lost chunk lingers, then drains)barboth280×30 (medium)realistic, minimalhealth, boss, shield
stackedShield on healthstackedboth272×44 (medium)sci-fi, realistichealth, shield, armor
arcCrosshair arcarcscreen76×76 (small)minimal, sci-fistamina, energy, ammo, crosshair
orbGlass orborbscreen108×126 (small)fantasy, realisticmana, health, energy
gaugeVertical gaugeverticalscreen58×176 (tall)realistic, sci-fifuel, heat, oxygen, energy
pipsPips / dotspipsboth194×32 (medium)minimal, cozy, cartoonlives, charges, ammo, combo
pixelPixel artbarboth248×34 (medium)pixel, cartoonhealth, mana, stamina, xp
hologramSci-fi hologrambarboth300×52 (medium)sci-fishield, energy, oxygen
ornateOrnate fantasy framebarboth312×50 (medium)fantasyhealth, mana, boss
bubblyBubbly cartoonbarboth272×46 (medium)cartoon, cozyhealth, xp, stamina
bloodBlood vial (drips, flickers near death)barboth270×48 (medium)horrorhealth, sanity, boss
monitorHeart monitor (ECG that flatlines at zero)tracescreen214×62 (medium)realistic, horror, sci-fihealth, stress
stitchedStitched feltbarboth262×44 (medium)cozy, cartoonhealth, hunger, warmth
megabarTick column (retro platformer meter)verticalscreen30×150 (tall)pixel, cartoonhealth, energy, weapon, boss

The eleven shapes are line, bar, segmented, stacked, ring, arc, hearts, pips, orb, vertical and trace.

Lifeline's own styles are there too, each with the same labels: lifeline:classic, segmented, ring, hearts, boss, overhead, minimal, stacked, scifi, fantasy, cartoon, pixel, orb.

Asking the kit

BK.looks()                                     -- every look: { id, name, families, suits, description,
                                               --   shape, placement, size = { w, h }, worldSize = { w, h }, sizeClass }
BK.looks({ family = "horror" })                -- blood, monitor, boss
BK.looks({ suits = "mana" })                   -- orb, pixel, ornate
BK.looks({ family = "cozy", suits = "health" })
BK.looks({ placement = "world" })              -- looks that can float over an entity ("both" counts)
BK.looks({ size = "small" })                   -- ring, arc, orb (or "medium", "wide", "tall")
BK.looks({ shape = { "ring", "arc" } })        -- one shape or several
BK.looks({ family = "pixel", shape = "bar" })  -- filters combine
BK.looks({ includeLifeline = true })
BK.families()                                  -- { { id, name, looks } } for the 8 families
BK.shapes()                                    -- { { id, name, looks } } for the 11 shapes
BK.suits()                                     -- everything looks say they suit
BK.render("orb", { frac = 0.4, kind = "mana" }) -- draw a look inside your own UI tree

Bar fields

fielddefaultwhat it does
lookghostWhich look. Change it any time.
showhealthWhat it shows (see above).
target—Whose value: an entity name or id. Empty means the local player (screen) or this entity (world).
placementscreenscreen = HUD; world = floats over the target.
anchortopLeftScreen corner or edge: topLeft, topCenter, topRight, left, center, right, bottomLeft, bottomCenter, bottomRight, crosshair. Bars on one anchor stack by order.
label—Caption. Defaults to the resource's name (or the boss's name).
kind / colorautoColour by resource kind (health, shield, armor, stamina, mana, energy, xp, boss, rage, oxygen, heat, ammo, lives, hunger, generic), or a hex override.
numbersautovalue (75 / 100), percent, none or auto.
lowWarning0.25Below this fraction the bar pulses. 0 turns it off.
size1Scale on top of the screen-size scale.
phases—Boss phase marks as fractions, e.g. "0.66 0.33".
segmentsautoCell, pip or heart count, where the look uses one.
worldHeight, range2.2, 30World bars: height above the target, and how far from the camera they still show.
hideWhenFull, hideOwnfalse, trueHide while full; don't draw a world bar over your own body.
offsetX, offsetY, visibleFine placement and on/off.

Methods on a Bar (call them with a colon): bar:setLook(id), bar:cycleLook(dir), bar:bind(fn | spec), bar:set(value, max), bar:sample(). On a Resource: res:spend(n), res:gain(n), res:set(v), res:fraction(). The API mirrors them: BK.setLook, BK.bind, BK.sample, BK.read(show, target), BK.bars(), BK.barOf(entity), BK.localPlayer().

Multiplayer

  • Bar settings are local (not synced). Each peer runs its own HUD, so your screen bars always read your avatar.
  • World bars and boss bars read healthKit's synced state, so every player sees the same value over the same enemy.
  • Resource values are owned by the entity's owner and synced. BK.spend/BK.gain from another peer are sent to the owner.
  • Damage and healing go through healthKit (HK.damage, HK.heal), which already routes them to the authority.

The gallery (barsKit.Showcase)

Add the Showcase component to any entity to get the gallery:

  • Every look side by side, all following one value that drains and refills. Each card is labelled with the look's name, its id and families, and a gold line giving its shape, where it goes and its size.
  • Filter chips for families, recolour chips for resource kinds, a numbers toggle, and Lifeline's looks.
  • A switcher that flips your own health bar through every look. Use [ / ] or the ◀ ▶ buttons; G hides or shows the gallery.

The gallery and the HUD never cover each other, at any screen size:

  • The panel takes the largest part of the screen the HUD leaves free (BK.freeRect), clear of every screen bar and the touch buttons.
  • While the gallery is open the switcher sits inside it. When it is closed, the switcher stands alone and screen bars step clear of it.
  • Bars that would land under the panel (the crosshair arc, world bars) are hidden until it closes.
  • Cards are dealt into even rows. Rows differ by at most one card, and every row is stretched to fill the width, so there are no empty spots.

On a desktop-sized window, every look and its label is on screen at once, with no scrolling. The gallery tries every column count from 3 to 8, splits the panel's height evenly between the rows, and picks the grid that draws the looks largest without shrinking any one of them too far (BK.layout.fitGrid). A 1080p window comes out as 6 columns by 4 rows, and a shorter 1280×682 window as 7 by 3. The cards get compact there: the family line shortens or drops families ("+2") instead of being cut off. A panel too small to fit every card at a readable size scrolls instead, with the larger cards. That covers a phone in either orientation, where the touch buttons and the boss plate leave the gallery a small panel. On a phone the cards reflow to two columns, and a card's labels shorten rather than get cut off.

local g = entity.find("BarsGallery").component.get(asset.resolve("barsKit.Showcase", "component"))
g:gridInfo()                    -- the grid it drew last: { fits, scrolls, cols, rows, cellH, gridH, minScale, cards, panel }
g:layoutFor(1920, 1080)         -- lay it out for another screen size without drawing: info, widget tree

G toggles the gallery, as does setting the component's open field. Removing the component or despawning its entity takes down both of its screens.

Phones and touch screens

  • Bars scale with the screen but never drop below 0.85 on a phone, so text stays legible.
  • Corner bars are laid out first. A centred bar (a boss bar) that meets one first slides sideways, and only then steps a row down (or up, for a bottom bar), so nothing overlaps on a narrow screen.
  • A bar never leaves the screen. On a tiny screen with no clear row left, it shrinks into the widest gap of a row it tried.
  • While the player is on touch, screen bars step clear of the on-screen buttons (Jump, Sprint, …). Top stacks move down past them and bottom stacks move up.
  • World bars (over heads) draw under screen bars, with the nearest on top.

Your own panels and the HUD

All of these use UI points, the same space as ui.screenSize(). Pass nil as the rect to clear a key.

-- keep screen bars out of a rect (a minimap, a chat box): the bars move
BK.keepOut("minimap", { x = 1100, y = 10, w = 170, h = 170 })

-- a panel of yours covers a rect (an inventory): bars that would land under it are hidden until you clear it
BK.cover("inventory", rect)

-- or let the HUD tell you where there is room: the largest rect clear of every bar, touch button and keepOut
local sz = ui.screenSize()
local rect = BK.freeRect(sz.width, sz.height, { pad = 8, margin = 6, minW = 300, minH = 200 })

BK.screenRects()   -- where the HUD drew its screen bars last frame: { { x, y, w, h, anchor, look, hidden } }
BK.layout          -- the pure helpers the gallery uses: largestFree, evenRows, rowWidths, packLines, fitGrid, overlaps

Removing bars

local hp = BK.bar({ look = "ghost", show = "health" })   -- makes an entity for the bar
BK.remove(hp)          -- removes the bar and despawns that entity; true, or false when there was no bar
BK.remove(hp)          -- calling it again is harmless

local tag = BK.bar(enemy, { look = "overhead" })
BK.remove(tag)         -- removes only the Bar component; the enemy stays

BK.unbind(bar)         -- undo BK.bind: the bar goes back to its `show` field
BK.isBound(bar)        -- is a function or field spec bound right now?

Removing a Bar component by hand, despawning its entity or removing a Resource cleans up the same way. No HUD entries, bindings, covers, keepOuts or screens stay behind; the tests check this.

Known limits

  • An installed copy loses the bars and showcases placed in a scene once the world reloads, and it does not load at all in the web browser version. Bars you make from code at runtime (BK.bar in a component or in localPlayerReady) are made again each run, but Bar and Showcase components saved into a scene are dropped when they fail to load.
  • The likely cause, found in this world: installing healthKit also brings in older, single-file copies of Lifeline modules, under deps/45f92606-2e79-4b2b-8e03-b1fa2649e5c2/versions/ (Lifeline's guid). Your world then has two candidates for Lifeline.api and Lifeline.Health, and the engine can pick the partial copy. When it does, require("healthKit.api") fails, barsKit's modules fail with it, and their components can't compile. A scene that holds them then loads without them.
  • Workaround: delete the versions/ folder inside deps/45f92606-2e79-4b2b-8e03-b1fa2649e5c2/, keeping the full Lifeline.package beside it, then reload. In this world that brought every barsKit, healthKit and Lifeline component back. It is not yet verified in a fresh install or in the web version. The partial copies come from Lifeline's install and have been reported upstream. If they come back after a reinstall, delete them again.
  • A health bar is hidden while its target has no health (see Give your player health first). That is by design, but it looks like a broken bar.

Version

1.2.0. require("barsKit.api").VERSION. Tests: barsKit.testSuite, 56 tests (run with the tests toolbox).

  • 1.2.0: every look is on screen at once on desktop-sized windows, labelled and without scrolling: the gallery picks its column count and card size to fit the panel (BK.layout.fitGrid, BK.layout.packLines), and adds gridInfo() and layoutFor(). Phones scroll as before. The shared value, boss bar, overhead dummy, ghost bar and look switcher are unchanged. The README now says to give your player health first, and how, and lists the known limits.

  • 1.1.0: every look says its shape, where it goes (screen, world or both) and its size, and BK.looks filters on all three (BK.shapes() lists the shapes). The gallery places itself in the room the HUD leaves free and hides bars under it, keeps the switcher inside it while open, and deals cards into even rows. A centred bar slides sideways before stepping down and never leaves the screen, and world bars draw under screen bars. New: BK.remove, BK.unbind, BK.isBound, BK.cover, BK.screenRects, BK.freeRect and BK.layout. Removing a bar, unbinding or closing the gallery leaves nothing behind.

  • 1.0.2: lighter gallery: virtual scrolling (only the rows in view are laid out and painted), the look switcher is redrawn only when it changes, and the gallery rebuilds 20 times a second on phones (30 on desktop). On a phone the open gallery now costs about 3ms a frame instead of about 9.5ms.

  • 1.0.1: phone layout: a legible minimum scale, no overlap between corner and centre bars, bars and the gallery keep clear of touch buttons, and BK.keepOut.

  • 1.0.0: first release.