Log inGet started
World

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.

idwhat it is
minimap.squareSquare north-up minimap with the area plan, POIs and the player arrow.
minimap.roundRound north-up minimap (default).
minimap.headingUpRound minimap that turns with the camera so forward is always up; the N badge orbits the rim.
minimap.fogRound minimap whose plan stays hidden until this player has been near it.
minimap.radarIcon-only radar: no map picture, range rings and a rotating sweep that lights blips as it passes.
minimap.pixelLow-resolution pixel minimap sampled from a 1 m grid of the world, with chunky icons.
map.roomsFull map with every area outlined and named, plus a legend, scale bar and north arrow (default).
map.fogFull map under fog that clears where this player has explored, with a % explored readout.
map.satelliteThe real world seen from straight above (an orthographic camera), with markers on top.
compass.barStrip 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.dialRound dial at the top centre whose card turns with the camera, with POI pips on the rim.
objectives.listObjective list with progress bars and shared and personal sections (default).
objectives.lineOne line under the compass: the current objective and its count.
objectives.checklistBoxes that tick and strike through as objectives complete.
objectives.questCardQuest card: title, steps, a big 3/5 counter and a bar.
toasts.slideCards that slide in from the right, stack, and fade on their own (default).
toasts.bannerWide band across the top, one at a time; the rest queue.
toasts.pixelPixel-font box with stepped motion and typewriter text.
toasts.achievementMedal pop with a large icon, title, burst and shine, one at a time.
toasts.minimalSmall text pill that rises and fades at the bottom centre.
toasts.promptButton prompt ("[E] Open") with the controlsKit glyph for the player's keyboard, gamepad or touch screen.
waypoint.iconIcon floating over the target on screen.
waypoint.edgeArrowArrow pinned to the screen edge that glides around it when the target is off-screen or behind.
waypoint.distanceDistance label in metres beside the icon or arrow.
waypoint.beamBeam of light rising from the target in the world. It thins away as you arrive.
waypoint.ringPulse 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 player to Nav.mark or Nav.setWaypoint for one player only.
  • Objectives are shared by default: progress and completion are relayed to every peer. Pass player = key for a personal one. Every peer can declare the same objectives in its own onLoad: declaring an id that already exists keeps its progress (pass count to 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, and to = player sends 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 navUiKit multiplayer channel. To use your own transport, set require("navUiKit.core").relay = { send = function(kind, payload) ... end } and call Nav._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, or hud: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

calldoes
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

calldoes
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

calldoes
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

calldoes
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

calldoes
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

calldoes
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

calldoes
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" }).