Save Point: Profiles, Levels and Unlocks Kit
README.md
navUiKit 1.0.1
Wayfinding and notification HUD for any Zero world: minimaps, a full map screen, compasses, waypoint markers, objective trackers and toasts. There are 26 variants in five looks, every player gets their own view, and one setting changes the style.
Install and use
Install the package from ZeroMind (search "navUiKit" or use the Wayfinder Studio world). It brings controlsKit along for the button glyphs. Then, in your scene's entrypoint.luau:
local Nav = require("navUiKit.nav")
function onLoad()
Nav.start() -- round minimap, compass bar, objectives, toasts
local chest = entity.find("Chest")
Nav.mark(chest, { icon = "chest", color = "#FFB300", label = "Treasure", waypoint = true })
Nav.objective("find", "Find the treasure")
Nav.toast("Follow the beam", { title = "Quest started", icon = "quest" })
end
function onUnload()
Nav.stop()
end
That gives a round minimap at the top right, a compass bar, an objective list and a waypoint on the chest: an icon over it, an edge arrow when it is off-screen, the distance in metres, a light beam and ground rings. Toasts slide in and fade. Press M (or Select, or tap the minimap) to open the map.
Prefer no code? Add the NavHud component to any entity, and the PointOfInterest component to anything you want on the map (tick waypoint to guide players to it).
Change the whole look with one line. Nothing else in your code changes:
Nav.setTheme("fantasy") -- scifi, fantasy, cartoon, pixel, minimal
Nav.setVariant("minimap", "radar") -- or Nav.use("minimap.radar")
Styles
Every variant works in every theme: scifi, fantasy, cartoon, pixel, minimal. Nav.catalogue() returns this list as data, one row per variant with { id, family, variant, description, themes, apply }, for a world or an agent to pick from. Nav.use(id) applies a row.
| id | what it is |
|---|---|
minimap.square | Square north-up minimap with the area plan, POIs and the player arrow. |
minimap.round | Round north-up minimap (default). |
minimap.headingUp | Round minimap that turns with the camera so forward is always up; the N badge orbits the rim. |
minimap.fog | Round minimap whose plan stays hidden until this player has been near it. |
minimap.radar | Icon-only radar: no map picture, range rings and a rotating sweep that lights blips as it passes. |
minimap.pixel | Low-resolution pixel minimap sampled from a 1 m grid of the world, with chunky icons. |
map.rooms | Full map with every area outlined and named, plus a legend, scale bar and north arrow (default). |
map.fog | Full map under fog that clears where this player has explored, with a % explored readout. |
map.satellite | The real world seen from straight above (an orthographic camera), with markers on top. |
compass.bar | Strip across the top: N/E/S/W, degree ticks, and tracked POIs with distances. Its frame follows the theme (sci-fi tape, ornate fantasy scroll, cartoon pill, pixel tape, minimal line). Default. |
compass.dial | Round dial at the top centre whose card turns with the camera, with POI pips on the rim. |
objectives.list | Objective list with progress bars and shared and personal sections (default). |
objectives.line | One line under the compass: the current objective and its count. |
objectives.checklist | Boxes that tick and strike through as objectives complete. |
objectives.questCard | Quest card: title, steps, a big 3/5 counter and a bar. |
toasts.slide | Cards that slide in from the right, stack, and fade on their own (default). |
toasts.banner | Wide band across the top, one at a time; the rest queue. |
toasts.pixel | Pixel-font box with stepped motion and typewriter text. |
toasts.achievement | Medal pop with a large icon, title, burst and shine, one at a time. |
toasts.minimal | Small text pill that rises and fades at the bottom centre. |
toasts.prompt | Button prompt ("[E] Open") with the controlsKit glyph for the player's keyboard, gamepad or touch screen. |
waypoint.icon | Icon floating over the target on screen. |
waypoint.edgeArrow | Arrow pinned to the screen edge that glides around it when the target is off-screen or behind. |
waypoint.distance | Distance label in metres beside the icon or arrow. |
waypoint.beam | Beam of light rising from the target in the world. It thins away as you arrive. |
waypoint.ring | Pulse rings spreading on the ground around the target. They shrink away as you arrive. |
The waypoint parts are switches that combine (Nav.configure{ waypoint = { beam = false } }); the other families pick one variant each.
Icons for POIs and toasts (Nav.icons()): pin, star, flag, skull, chest, door, gem, home, quest, exclaim, coin, key, sword, heart, player, ally, enemy, beacon, tent, eye, trophy, check, shop, portal.
Multiplayer
The kit runs on every peer. Each peer draws one HUD for its own player, centred on their character and measured from where they stand. Nobody sees another player's minimap, fog, map, arrows or personal objectives.
- POIs are marked on every peer by the same script (or by the PointOfInterest component). Pass
playertoNav.markorNav.setWaypointfor one player only. - Objectives are shared by default: progress and completion are relayed to every peer. Pass
player = keyfor a personal one. Every peer can declare the same objectives in its ownonLoad: declaring an id that already exists keeps its progress (passcountto set it on purpose), so a second player joining never resets the group's progress. - Late joiners catch up. When a peer's HUD starts it calls
Nav.sync(), and the peers already playing answer with the shared objectives as they stand. Ones finished before the joiner arrived don't toast again. - Toasts go to the local player by default.
to = "all"sends one to everyone, andto = playersends one to a single player: their player object, their body entity (from any peer) or their key. A toast for someone on another peer is relayed to their peer and shown only there. - Per-player state for someone else is relayed too:
Nav.setWaypoint(id, on, player),Nav.clearWaypoints(player)and a personal objective's progress reach that player's peer, and each peer applies only what is addressed to its own player. - Waypoint beams and rings are local, temporary parts each peer draws for its own player. They never replicate and never land in a saved scene.
- A player key is the player's account id (
userId).require("navUiKit.core").localKey()is this peer's key, and a player object or avatar entity is accepted wherever a key is. Two tabs signed in to the same account share a key, so a toast or personal objective for that account shows in both. - Messages travel on the
navUiKitmultiplayer channel. To use your own transport, setrequire("navUiKit.core").relay = { send = function(kind, payload) ... end }and callNav._receive(kind, payload)where it arrives.
Phones and performance
- Widgets lay out inside the safe area (notches, rounded corners) and reflow in portrait and landscape. Under 560 pt of width the minimap shrinks, the compass narrows, the objective list drops rows it has no room for, and toasts stack from the top under the compass.
- The minimap and map pictures are baked once from the world's colliders (
Nav.rebake()after moving level geometry). Per frame, only the small icon layers and the compass are redrawn, and static canvases are only rebuilt when they change. - One HUD costs about 0.35 ms of script per frame (measured median). The satellite map's camera exists only while that map is open.
Nav.stop(), removing the NavHud component, orhud:destroy()removes every screen, beam, ring and camera the kit made.
Reference
All calls are on local Nav = require("navUiKit.nav"). player arguments are optional: leave them out for the local player.
Life cycle
| call | does |
|---|---|
Nav.version | "1.0.1" |
Nav.start(opts?) | Puts the HUD on screen for the local player by making (once) an entity navUiKit_hud carrying NavHud. opts is applied as Nav.configure(opts) first. Returns the entity. |
Nav.stop() | Removes every HUD on this peer (screens, beams, rings, satellite camera) and the host entity. POIs and objectives stay. |
Nav.reset() | Clears POIs, areas, objectives, fog and settings back to defaults. |
Nav.hud(player?) | The HUD object for a viewer, for split views and tests. |
Nav.on(event, fn) | Listens for poiAdded, poiRemoved, waypoint, objective, toast, mapOpened, mapClosed, styleChanged. |
Nav.sync() | Asks the other peers for the shared objectives as they stand. NavHud calls it once when this peer's HUD starts in play; call it yourself after swapping in your own relay. |
Style and settings
| call | does |
|---|---|
Nav.setTheme(name) | scifi, fantasy, cartoon, pixel, minimal, or a theme added with require("navUiKit.theme").register(name, def, base). |
Nav.setVariant(family, variant) | family is minimap, map, compass, objectives or toasts. Unknown names throw. |
Nav.use(id) | Applies a catalogue id ("toasts.achievement", "waypoint.beam") or a theme name. |
Nav.configure(opts) | Merges settings (nested tables merge). |
Nav.settings() | The live settings table (read only; change it with configure). |
Nav.styles() | { themes, minimap, map, compass, objectives, toasts, waypoint } with the variant names. |
Nav.catalogue() | Every variant as a row: { id, family, variant, description, themes, apply }. |
Nav.icons() | Icon names. |
Settings and their defaults:
{
theme = "scifi",
variants = { minimap = "round", map = "rooms", compass = "bar", objectives = "list", toasts = "slide" },
minimap = { show = true, size = 180, zoom = 1, range = 45, corner = "topRight" }, -- corner: topRight, topLeft, bottomRight, bottomLeft
map = { key = "KeyM", pad = "select", tapMinimap = true },
compass = { show = true, span = 180 },
objectives = { show = true, max = 5 },
toasts = { show = true, duration = 4, max = 4 },
waypoint = { icon = true, edgeArrow = true, distance = true, beam = true, ring = true },
fog = { cell = 4, radius = 14 },
autoToasts = true, -- a toast when an objective completes
units = "m",
}
Points of interest and waypoints
| call | does |
|---|---|
Nav.mark(target, opts?) | target is an entity, an entity id or a {x, y, z} point. opts: icon, color (#RRGGBB), label, waypoint, height (marker height above the target, m), player (only that player sees it), compass / minimap / map (false hides it there), id. Returns the POI id. |
Nav.unmark(id) | Removes it. Returns whether it existed. |
Nav.update(id, changes) | Changes any of the mark options, or hidden = true to hide it everywhere. |
Nav.get(id) | A copy of the record, or nil. |
Nav.list(player?) | POI ids; with player, only those that player can see. |
Nav.setWaypoint(id, on, player?) | Makes it a waypoint, or not, for everyone or one player. |
Nav.isWaypoint(id, player?) | Whether it is one. |
Nav.clearWaypoints(player?) | Clears all waypoints, for everyone or one player. |
Nav.distance(id, player?) | Metres from that player to the POI, or nil. |
PointOfInterest component fields: icon, color, label (empty uses the entity name), waypoint, height, onCompass, onMinimap, onMap. Its POI id is "poi_" .. entityId. Removing the component or the entity unmarks it.
Map content
| call | does |
|---|---|
Nav.addArea(name, {minX, minZ, maxX, maxZ}, opts?) | Names an area: the rooms map outlines and labels it. opts.id, opts.color. Returns its id. |
Nav.addShape({ {x, z}, ... }, opts?) | Draws an extra polygon (a road, a wall) on the minimap and map. Returns its id. |
Nav.removeShape(id) | Removes an area or shape. |
Nav.setBounds({minX, minZ, maxX, maxZ}) | Fixes the map extent instead of fitting the world. |
Nav.rebake() | Re-reads the world's colliders into the map picture. |
Nav.explored(player?) | Share of the map that player has uncovered, 0..1. |
Nav.reveal(x, z, radius?, player?) | Clears fog around a point (normally automatic). |
Objectives
| call | does |
|---|---|
Nav.objective(id, text, opts?) | Adds one, or updates it. opts: total (above 1 shows 3/5), count, shared (default true unless player), player, quest (questCard title), icon. Re-declaring an existing id keeps its progress, total, quest and icon unless you pass them. Returns the id. |
Nav.progress(id, n, add?) | Sets the count, or adds to it with add = true. It completes at the total. Returns the new count. |
Nav.complete(id) | Ticks it off; it fades from the tracker. |
Nav.removeObjective(id) | Removes it. |
Nav.objectives(player?) | What that player sees: shared plus their own. |
Toasts
| call | does |
|---|---|
Nav.toast(text, opts?) | opts: variant (default the toasts setting), title, icon, color, duration (seconds), to (nil = local player, "all", or a player / key), key + pad + action for prompts (key = "KeyE", pad = "south", action = "Open"), id (reusing an id updates that toast in place). Returns the id. Toasts queue, stack, slide and fade on their own. |
Nav.dismiss(id, player?) | Fades one out early (e.g. a prompt whose door went away). |
Map screen
| call | does |
|---|---|
Nav.openMap(player?) / Nav.closeMap(player?) / Nav.toggleMap(player?) | Opens, closes or toggles the full map. Players also use M, Select, a tap on the minimap, or the close button. |
Nav.isMapOpen(player?) | Whether it is open. |
Components
- NavHud: puts the HUD on screen for the local player. Its fields override the world settings:
theme,minimap,map,compass,objectives,toasts,corner,previewInEditor. On a player prototype it runs only for the copy this peer controls. - PointOfInterest: see above.
- NavGallery: the style gallery used by this world's startup scene. Fields:
walker,camera,path,page,theme,speed,showInEditor.
Lower level
The widget builders take a command list and a box, so a world can draw them into its own screens: navUiKit.minimap, navUiKit.compass, navUiKit.markers, navUiKit.tracker, navUiKit.mapScreen and navUiKit.toasts. Each module's README lists its calls. navUiKit.hud's Hud.new{ key, avatar, camera, box, viewBox, isLocal, world3d, theme, variants } makes an extra HUD into any rectangle, such as a split-screen view or a picture-in-picture. A HUD with isLocal = false is not ticked for you: call hud:update(dt) each frame and hud:destroy() when done.
Tests
navUiKitTests (34 tests) covers every call above, the cross-peer messages (declaring, progress, sync, waypoints and toasts for another peer's player), the HUD life cycle (nothing left behind after destroy or stop), per-viewer isolation, the toast queue and band, the waypoint 3D parts, and every builder in every theme. Run it with tools.use("tests", "run", { suite = "navUiKitTests" }).