navUiKit 1.1.0

Wayfinding and notification HUD for any Zero world: minimaps, a full map screen, compasses, waypoint markers, objective trackers and toasts. There are 28 styles 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 the two controlsKit modules it draws button glyphs with. Then paste this into your scene's entrypoint.luau (in a new world, scenes/main.scene/entrypoint.luau) and press Play:

local Nav = require("navUiKit.nav")

function onLoad()
    Nav.start()                                   -- round minimap, compass bar, objectives, toasts
    -- mark anything: an entity, an entity id, or a point { x, y, z }
    local chest = entity.find("Chest") or { 8, 0, -12 }
    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 treasure (an entity called "Chest" if your scene has one, otherwise a spot 14 m from where you spawn): 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. onLoad runs when play starts, so nothing appears while you author.

Every play starts clean. Each time you press Play (and each time you stop), the kit forgets what the last session declared: markers, waypoints, objectives and their progress, map areas and shapes, explored fog, queued toasts and Nav.on listeners. Your onLoad then declares them again. So the example gives the same result on every play: one Treasure, one fresh objective, one toast. Settings (Nav.setTheme, Nav.setVariant, Nav.configure) are configuration and stay. Declare your game's markers and objectives in onLoad (or with PointOfInterest components), not once from the console.

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). Doing both is fine: a scene's NavHud, Nav.start() (once or many times) and extra NavHud copies all share one HUD per player.

Change the whole look with one line. Nothing else in your code changes:

Nav.setTheme("fantasy")              -- scifi, fantasy, cartoon, pixel, minimal
Nav.setVariant("compass", "arrow")   -- or Nav.use("compass.arrow")

Styles

Every style works in every look. Nav.catalogue() returns these rows as data, { id, family, variant, description, tags, themes, apply }, for a world or an agent to pick from, and Nav.use(id) applies a row. Filter by tag or family with Nav.catalogue({ tags = { "round", "phone-friendly" } }) or Nav.catalogue({ family = "compass" }); a row matches when it carries every tag you ask for.

The looks are rows too (family theme, applied with Nav.use("theme.pixel") or Nav.setTheme("pixel")):

The waypoint parts are switches that combine (Nav.configure{ waypoint = { beam = false } }); the other families pick one variant each.

Tag vocabulary. Shape: round, square, strip, ring, arrow, card, list, pill, banner, medal, icon, label, full-screen, in-world. Behaviour: north-up, heading-up, fog-of-war, radar, exploration, single-target, waypoint, notification, prompt, progress, one-at-a-time. Look: sci-fi, fantasy, cartoon, retro, minimal, realistic, animated. Fit: phone-friendly, compact, kid-friendly, default.

The four compasses. bar is a heading strip across the top. dial is a compass rose whose card turns with the camera. ring puts the compass on the minimap's own edge: round or square to match it, N/E/S/W and degree ticks on the band, a notch that swings round to your heading (on a heading-up or radar minimap the ring turns instead and the notch stays on top), tracked places as pips on the rim and the nearest waypoint's distance just inside. It frees the top of the screen. arrow has no cardinal points at all: one arrow that turns to point straight at the nearest waypoint, with its name, distance, how many others there are, an up or down cue when it is more than 3 m above or below you, and a tick when you arrive. With no waypoint it points north and says so.

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, waypoints or personal objectives. Shared objectives stay shared.

• One HUD per player. However the HUD is started (a NavHud in the scene, on the player prototype, Nav.start(), any mix, any number of times), each peer has exactly one HUD for its player. The first holder draws it and the others stand by. It goes when the last holder goes, or with Nav.stop().
• Players are sessions. A player key is "<userId>#<peerId>" while connected ("<userId>" offline). The relay gives every connection its own peer id, so two machines signed in to the same account are two players to the kit. require("navUiKit.core").localKey() is this peer's key. A player object or avatar entity is accepted wherever a key is, and names that one session.
• Addressing. A full key, a player object or a body reaches one session. A bare userId reaches every session of that account. "all" reaches everyone.
• 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 = ... 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. A toast for someone on another peer is relayed to their peer and shown only there. When every peer runs the same script (a trigger that fires everywhere), the target would get the toast twice, from its own call and from the relay. The same toast arriving both ways within 2.5 s shows once.
• 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. Neither does the Nav.start() host entity.
• 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.
• What one HUD costs. Measured in the playground scene on the native desktop editor (one player, five POIs, four objectives, toasts, round minimap, compass bar): hud:update takes a median 0.83 ms per frame (p90 1.5 ms, p99 4.0 ms, over 300 frames), and the profiler's average for NavHud was 0.78 to 1.2 ms. Drawing the HUD's screens adds about 2.4 ms to the engine's UI render pass (2.44 ms with the HUD, 0.04 ms with it stopped, averaged over 15 frames). Together, about 3.5 ms of CPU a frame. Starting the HUD several times costs no more: four holders measured 0.88 ms of script.
• The satellite map's camera exists only while that map is open.
• Nav.stop(), removing the last NavHud, or hud:destroy() removes every screen, beam, ring and camera the kit made.

Known limits

These come from open issues on the engine's GitHub tracker. Each one says what you would see.

• Two machines on one account (#14448). Two sessions of one account in the same play room collide, and the engine can refuse one player's spawn. The kit tells the two sessions apart (each connection has its own peer id), so a toast, waypoint or personal objective meant for one machine reaches only that one. But on the machine whose spawn was refused there is no body to centre on: its minimap, compass and distances are measured from its camera instead, and other players see no avatar for it. What was checked: on one machine, connected, the kit gave this session its own key (userId#9), and a toast for another session of the same account was sent and not shown here. Nobody has run it on two real machines yet.
• No picture-based round or heading-up minimap (#19181, #19182). A viewport widget draws nothing inside a fully rounded panel, and rotating one is ignored. So the minimaps are vector drawings baked from the world's colliders rather than a live camera picture, and the map.satellite view, the one real picture of the world, is a north-up rectangle on the full map screen only. If you put the satellite view from the lower-level builders into your own rounded panel, it comes out blank.
• Simulated notches only work in edit mode (#19179). In the editor, ui.simulateSafeArea does nothing while playing, so the HUD won't move away from a simulated notch in play. Check notch layouts in edit mode with NavHud's previewInEditor on. Real phones report their safe area normally.
• {PlayerName} over the gallery walker (#19201). The NavGallery component's walker is an avatar nobody owns, and such an avatar shows a literal {PlayerName} label. This world's gallery scene removes it in its entrypoint (it despawns the walker's NameLabel child). If you use NavGallery in your own scene with an avatar as the walker, do the same.

Reference

All calls are on local Nav = require("navUiKit.nav"). player arguments are optional: leave them out for the local player.

Life cycle

Style and settings

Settings and their defaults:

{
    theme = "scifi",
    variants = { minimap = "round", map = "rooms", compass = "bar", objectives = "list", toasts = "slide" },   -- compass: bar, dial, ring, arrow
    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",
}

With compass = "ring" and minimap.show = false, the ring draws on its own in the minimap's corner, round a dark face.

Points of interest and waypoints

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

Objectives

Toasts

Map screen

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. Any number of NavHuds share one HUD.
• 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. Hud.acquire(owner, opts) / Hud.release(hud, owner) share one HUD between several holders, which is how NavHud does it.

Tests

navUiKitTests (47 tests) covers every call above. That includes every play starting clean (the README example run over three plays), one HUD however it is started, session keys and toasts for one machine on a shared account, echo suppression, the ring and arrow compasses and their layout, the catalogue tags and filters, the cross-peer messages, the HUD life cycle (nothing left behind after destroy or stop), per-viewer isolation, the toast queue and band, the waypoint 3D parts, every builder in every theme, opaque 8-digit colours, and one version number everywhere. Run it in edit mode with tools.use("tests", "run", { suite = "navUiKitTests" }).