# navUiKit 1.3.15
Wayfinding and notification HUD for any Zero world: minimaps, a full map screen, compasses, waypoint markers, objective trackers and toasts, and a room map for games made of rooms. There are 30 styles in six looks (sci-fi, fantasy, cartoon, pixel, minimal, gothic), and one setting changes the look. Every player gets exactly one HUD of their own in multiplayer, every style carries tags you can filter by, and every play starts clean.
It suits any game where players need to know where to go and what to do next: open worlds, quests, races, scavenger hunts, co-op objectives, and room-based games such as metroidvanias and dungeon crawlers, top-down or side view. It works on desktop and phones (keyboard, gamepad and touch).
## What's new in 1.3.15
- **The compass bar makes room for touch buttons in the top band.** On a phone held upright the engine's Menu button (and a game's corner Pause button) sat on the compass bar. While touch controls show, the bar now narrows between any buttons in its band, and drops below them when that would leave it under 240 points wide; the objective list and messages follow it down. And the objective list is redrawn when its spot moves, not only when an objective changes: it used to stay where it was first drawn, on top of a compass that had moved. Checked in stealthKit's Two Lanterns at 390x844, 844x390, 1024x768 and 1280x720 with touch controls: compass, objectives and buttons clear of each other.
## Earlier changes
- **Touch messages stay out of the middle of the view.** On a touch screen the message stack now takes a side column (left or right) whenever one holds as many cards as the centre would; the centre is used only when the sides are full. In Skyhook a stack of four went down the middle of the screen over the player. A test checks it with Skyhook's arrangement (a panel top-left, buttons down the right).
- `Nav.configure({ toasts = { top = 150 } })` keeps top-anchored messages below a HUD of your own, such as a match timer.
## Earlier: top-HUD setting
- **Keep messages below your own top HUD.** `Nav.configure({ toasts = { top = 150 } })` sets the highest a top-anchored message may sit (points from the top of the HUD). A game that draws its own top-centre HUD the kit cannot see, such as a match timer, sets it once and messages that stack from the top (on a touch screen, a narrow screen, or the banner) start below it. Found in Skyhook, where a message covered MatchFlow's race timer on a touch screen. A test checks it.
## Also recent: toasts keep clear of touch controls
- **Toasts keep clear of on-screen touch controls.** On a touch screen the lower corners belong to the thumbs (the stick bottom-left, controlsKit's button diamond bottom-right) and the engine's Menu button sits top-right, but at tablet and desktop sizes (1280x720 and up) `slide` cards still stacked up from the bottom right, right under the thumb buttons, and the `minimal` pill sat at the bottom centre. While touch controls are showing (the engine draws its touch layout, the surface is `touch`, or controlsKit draws its own buttons), every toast now keeps clear of every control: `slide` and `pixel` cards stack from the top, below the compass and any banner, in whichever column (right, left or centre) has room clear of the buttons, the Menu button, the minimap and the objectives; `minimal` and `prompt` lift above the lowest control; a `banner` or `achievement` drops below a control in its band. The controls are read from `zinput.touchControls.layout()` (controlsKit's buttons included) and the corner a stick rests in; `Toasts.touchControls()` returns them. Waypoint pins avoid the moved stack. Keyboard and gamepad layouts are unchanged. A test checks it with a stubbed touch layout.
- The kit's own version test and reference table now name the current version (the first release of the touch fix shipped them naming the release before it).
## From the last release
- **Built against the controlsKit release menusKit, saveKit and inventoryKit ship with today**, so a world that installs navUiKit beside them (questKit, economyKit, arpgKit) holds one controlsKit. Nothing else changed.
## From the release before it
- **Waypoint markers never take a tap.** The marker layer covers the whole view so a pin can sit anywhere on screen, but it was wrapped in a plain `panel`, which takes every tap that lands on it, painted or not. While any waypoint was set, every click and touch over the game (a settings panel, a phone button, a tap on the world) landed on the empty marker layer instead. The layer is now a pass-through canvas (`pointerEvents = "none"`, the same path the toast layer uses), so taps reach whatever is under it. Markers look exactly as before. A test checks hit testing across the view with a waypoint set, full-screen and boxed.
## From earlier releases
- **Built against the controlsKit release economyKit and towerDefenseKit ship with**, so a world that installs navUiKit beside them holds one controlsKit instead of a second, older copy. Nothing else changed.
## From earlier releases
- **Messages never take a tap, in any HUD.** The toast layer covers the whole HUD area but is painted only where a card is, so it must let every tap through to the game under it. The previous release did that for a full-screen HUD (the layer is one canvas with `pointerEvents = "none"`) but kept a positioning frame that took taps for a HUD drawn into a box (`Hud.new{ box = ... }`), saying a canvas was the only widget that lets taps pass. That was wrong: as the UI guide says, the engine reads `pointerEvents = "none"` on a canvas and on the layout containers (`vertical`, `horizontal`, `grid`, `spacer`); only a plain `panel` takes every tap that lands on it. The boxed HUD's frame is now built from `vertical` containers with `pointerEvents = "none"`, so messages let taps through in both layouts. Messages look exactly as before.
From the last feature release:
- **A room map.** Declare rooms on a grid with `Nav.addRoom` (their cells, the world rectangle each covers, their doors and icons) and pick the `roomGrid` minimap and map screen. Rooms appear once a player has visited them; the room they are in is lit and their position pulses in it; every door is a gap in the outline, and a door they have not tried yet carries a pulsing arrow; icons such as a home (save room), a skull (boss) or a star sit in the room. The map screen names the rooms, counts how many the player has seen and builds its legend from the icons on the map.
- **Each player's own map, fed from your game.** The HUD marks the room a player walks into as visited (`rooms.autoVisit`), or a game that saves its own record turns that off and hands it over with `Nav.setVisitedRooms`, `Nav.useDoor` / `Nav.setUsedDoors` and `Nav.setRoomIcons` (a boss room's skull becomes a check for the player who won). Calls for a player on another peer travel there, like waypoints do.
- **Side view for 2D games.** `Nav.configure{ plane = "xy" }` draws every map with world up as up on the map (x across, y up) instead of top-down (x, z). The baked level picture, fog, distances and the room map all follow it.
- **A sixth look, `gothic`**: dark stone plates, silver borders, crimson spikes and serif capitals. Each look now also carries room-map colours (`roomFill`, `roomHere`, `roomEdge`, `roomNew`, `roomText`, `roomIcons`), and a theme registered without them falls back to its map colours.
- **`map.input = false`** lets a game open and close the map with its own controls (`Nav.toggleMap`) while the hint still shows `map.key`; Escape still closes it.
- Nothing that worked before changes: the defaults, every existing style and every existing call behave as they did in the last release.
## 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 the example below into your scene's `entrypoint.luau` (in a new world, `scenes/main.scene/entrypoint.luau`) and press Play.
```lua
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). Change a NavHud's fields at any time, also while the HUD is showing: the HUD restyles at once. 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:
```lua
Nav.setTheme("fantasy") -- scifi, fantasy, cartoon, pixel, minimal
Nav.setVariant("compass", "arrow") -- or Nav.use("compass.arrow")
```
## Guides
Two guides ship inside the package (`navUiKit.package/guides/`). Once navUiKit is installed, the engine's guide search finds them and they open in the Docs panel.
- **How to add a minimap and compass to my game**: what the kit is and what to do first, the four compasses and when to pick each, the minimaps and the map screen, marking places and turning them into waypoints, shared and personal objectives, toasts and button prompts, changing a style or the whole look with one setting and finding styles by their tags, and who sees what in multiplayer.
- **Show a waypoint to the next objective: build a small exploration game**: a step-by-step example from an empty world to a game two players can play together. Places to discover, a compass and a minimap, a waypoint that moves on to the next place when you reach it, a toast when you pick up a relic (pickupsKit), a title screen and pause menu (menusKit) and nameplates over the other explorers (markersKit), all installed from ZeroMind.
## 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.
| id | what it is | tags |
|---|---|---|
| `minimap.square` | Square north-up minimap with the area plan, POIs and the player arrow. | square, north-up, map-plan, classic, phone-friendly |
| `minimap.round` | Round north-up minimap; the default. | round, north-up, map-plan, classic, phone-friendly, default |
| `minimap.headingUp` | Round minimap that turns with the camera so forward is always up; the N badge orbits the rim. | round, heading-up, map-plan, open-world, driving |
| `minimap.fog` | Round minimap whose plan is hidden until the player has been near it (per-player fog of war). | round, north-up, fog-of-war, exploration, per-player |
| `minimap.radar` | Icon-only radar: no map picture, range rings and a rotating sweep that lights blips as it passes. | round, heading-up, radar, sci-fi, icons-only, animated, combat |
| `minimap.pixel` | Low-resolution pixel minimap sampled from a 1 m grid of the world, chunky icons. | square, north-up, retro, low-res, map-plan |
| `map.rooms` | Full map screen with every area outlined and named, a legend, scale bar and north arrow. | full-screen, north-up, areas, labelled, indoor, default |
| `map.fog` | Full map screen hidden under fog that clears where this player has explored; shows % explored. | full-screen, fog-of-war, exploration, per-player |
| `map.satellite` | Full map screen showing the real world from straight above (an orthographic camera) with markers on top. | full-screen, realistic, top-down, open-world |
| `minimap.roomGrid` | Square room map centred on the player: the rooms they have visited (Nav.addRoom), the one they are in lit, doors, room icons and arrows on untried doors. | square, rooms, grid, doors, exploration, per-player, side-view, metroidvania, dungeon, phone-friendly |
| `map.roomGrid` | Full map screen of the visited rooms on a grid, named, with doors, room icons, untried-door arrows, rooms seen and a legend. Side view (plane xy) or top-down. | full-screen, rooms, grid, doors, exploration, per-player, side-view, labelled, metroidvania, dungeon |
| `compass.bar` | Compass strip across the top: N/E/S/W, degree ticks, tracked POIs with distances. Its frame follows the theme (sci-fi tape, ornate fantasy scroll, minimal line, cartoon pill, pixel tape). | strip, heading, bearings, distance, open-world, phone-friendly, default |
| `compass.dial` | Round compass dial at the top centre, card turning with the camera, POI pips on the rim. | round, heading, bearings, classic, nautical |
| `compass.ring` | Compass bezel round the minimap's own edge (round or square): N/E/S/W and degree ticks, a notch that swings to your heading (or a ring that turns with a heading-up map), tracked places on the rim. Frees the top of the screen. | ring, round, square, heading, bearings, minimap, compact, phone-friendly |
| `compass.arrow` | No cardinal points at all: one arrow at the top that turns to point straight at the nearest waypoint, with its name, distance and an up/down cue when it is above or below you. | arrow, single-target, waypoint, distance, height, minimal, compact, phone-friendly, kid-friendly |
| `objectives.list` | Objective list with progress bars, shared and personal sections. | list, progress, shared, personal, default |
| `objectives.line` | One-line tracker under the compass showing the current objective and its count. | strip, compact, minimal, phone-friendly |
| `objectives.checklist` | Checklist whose boxes tick and strike through as objectives complete. | list, checkbox, progress, cozy |
| `objectives.questCard` | Quest card: title, the steps, a big 3/5 progress counter and bar. | card, quest, progress, rpg |
| `toasts.slide` | Cards sliding in from the right edge, stacking upward, fading out on their own. | card, stack, notification, animated, default |
| `toasts.banner` | Wide banner across the top centre, one at a time, the rest wait in a queue. | banner, wide, announcement, one-at-a-time |
| `toasts.pixel` | Pixel-font toast box with a stepped slide, in any theme. | card, retro, typewriter, notification |
| `toasts.achievement` | Achievement pop: large icon medallion, title and text, a shine sweep, one at a time. | medal, reward, animated, one-at-a-time |
| `toasts.minimal` | Small text-only pill near the bottom centre. | pill, minimal, subtle, phone-friendly |
| `toasts.prompt` | Button prompt ("[E] Open") using controlsKit glyphs for the player's device; stays until dismissed or it times out. | prompt, button-glyph, keyboard, gamepad, touch, phone-friendly |
| `waypoint.icon` | Icon floating over the target on screen. | icon, on-screen, waypoint |
| `waypoint.edgeArrow` | Arrow pinned to the screen edge that glides round it when the target is off-screen or behind. | arrow, on-screen, off-screen, waypoint |
| `waypoint.distance` | Distance label in metres beside the icon or arrow. | label, distance, waypoint |
| `waypoint.beam` | A beam of light rising from the target in the world. | in-world, 3d, light, waypoint, visible-from-afar |
| `waypoint.ring` | Pulsing rings on the ground around the target. | in-world, 3d, ground, waypoint, animated |
The looks are rows too (family `theme`, applied with `Nav.use("theme.pixel")` or `Nav.setTheme("pixel")`):
| id | look | tags |
|---|---|---|
| `theme.scifi` | Sci-fi: dark glass panels, cyan neon edges, condensed display type. | look, sci-fi, neon, dark, futuristic, default |
| `theme.fantasy` | Fantasy: leather and brass, serif type, diamond ornaments. | look, fantasy, medieval, ornate, rpg |
| `theme.cartoon` | Cartoon: white cards, thick black outlines, drop shadows, bold rounded type. | look, cartoon, bright, playful, kid-friendly, chunky |
| `theme.pixel` | Pixel: chunky pixel boxes and a built-in 3x5 bitmap font, stepped motion. | look, retro, pixel-art, 8-bit, chunky |
| `theme.minimal` | Minimal: soft translucent panels, hairlines, plain sans-serif type. | look, minimal, clean, subtle, realistic |
| `theme.gothic` | Gothic: dark stone plates, silver borders, crimson spikes, serif capitals. | look, gothic, dark, ornate, horror, castle |
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 are open issues on the engine's 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. Test multiplayer with two accounts.
- **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.
- **The gallery's frame rate in the web player (#20750).** The gallery scene draws every style in every look at once, and in a web browser it runs at a lower frame rate than on desktop. A game's own HUD draws one of each and is not affected the same way.
- **Installs with several dependencies are slow (#21420).** navUiKit brings only two controlsKit modules and installs in seconds. The example guide also installs pickupsKit and markersKit, which bring several kits each and can take a while; wait for each install to finish.
- **The ZeroMind page can lag a release (#19258).** For a while after a new version is published, ZeroMind can show the previous release's description. The README inside the installed package is always the current one.
- **Guides inside a package don't show up in library search yet (#22181, ZeroMind#3099).** The two guides arrive with the package and the engine's guide search finds them once navUiKit is installed, but a ZeroMind library search does not list them. Search for "navUiKit" and read the guides in the Docs panel or under `navUiKit.package/guides/`.
## 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.3.15"` |
| `Nav.start(opts?)` | Puts the HUD on screen for the local player. Makes (once) a runtime-only entity `navUiKit_hud` carrying NavHud; it is never saved or replicated. If a NavHud is already in the scene they share the one HUD. `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. NavHud components already in the scene stand down until `Nav.start()` or a new NavHud. POIs and objectives stay until the session ends (the next press of Play or Stop), so you can hide the HUD and bring it back mid-game. |
| `Nav.reset()` | Clears POIs, areas, objectives, fog and settings back to defaults, now. (Pressing Play or Stop does the same for everything except settings by itself.) |
| `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`, `hudStarted`, `hudStopped`. Listeners last for one session: register them in `onLoad`. |
| `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 (`"compass.ring"`, `"toasts.achievement"`, `"waypoint.beam"`, `"theme.pixel"`) 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(filter?)` | Every style and look as a row: `{ id, family, variant, description, tags, themes, apply }`. `filter`: `{ tags = { ... } }` (rows with all of them), `{ tag = "..." }`, `{ family = "..." }`. |
| `Nav.icons()` | Icon names. |
Settings and their defaults:
```lua
{
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 }, -- input = false: the game opens the map itself
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 },
rooms = { autoVisit = true, showAll = false, cell = 0, legend = {} }, -- cell 0: the minimap picks its own cell size
plane = "xz", -- "xy" for a side view: world up is up on every map
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
| 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). |
### Room map
For games made of rooms (metroidvanias, dungeon crawlers, station maps). Pick it with `Nav.setVariant("minimap", "roomGrid")` and `Nav.setVariant("map", "roomGrid")`; for a 2D side-scroller add `Nav.configure{ plane = "xy" }`.
```lua
Nav.configure({ plane = "xy", variants = { minimap = "roomGrid", map = "roomGrid" },
rooms = { legend = { home = "Save room", skull = "Boss", check = "Boss beaten", star = "Shrine" } } })
Nav.addRoom("hall", { name = "Great Hall", cell = { 0, 0, 2, 1 }, area = { 0, 0, 48, 14 }, icons = { "home" },
doors = { { id = "hall>crypt", side = "right", at = { 0.1, 0.3 } } } })
Nav.addRoom("crypt", { name = "Crypt", cell = { 2, 0, 1, 1 }, area = { 48, 0, 72, 14 }, icons = { "skull" },
doors = { { id = "crypt>hall", side = "left", at = { 0.1, 0.3 } } } })
```
| call | does |
|---|---|
| `Nav.addRoom(id, def)` | Declares a room (or replaces it). `def`: `name`; `cell = {gx, gy, w, h}` in grid cells (gx to the right, gy UP the map; or `gx`, `gy`, `cw`, `ch`); `area = {a0, b0, a1, b1}`, the world rectangle the room covers on the plane's axes (x and z top-down, x and y side view), which places the player and POIs in it and marks it visited when they walk in; `icons` (icon names, or `{ name, color, label }`); `doors = { { id, side = "left" \| "right" \| "up" \| "down", at = {f0, f1} (0..1 along the side, from its bottom or left), to = roomId?, cell = {gx, gy}? } }` (left out, a door leads into the cell just across it); `color`; `hidden`. |
| `Nav.updateRoom(id, changes)` / `Nav.removeRoom(id)` / `Nav.clearRooms()` | Changes, removes one, removes all (with every player's visits and doors). |
| `Nav.room(id)` / `Nav.rooms()` / `Nav.roomAt(target)` | A copy of a room, the ids in order, the room whose area holds a point. |
| `Nav.visitRoom(id, player?, on?)` / `Nav.setVisitedRooms(ids, player?)` | Marks one room visited (or not), or replaces the whole list (a saved map coming back). |
| `Nav.roomVisited(id, player?)` / `Nav.roomsExplored(player?)` | Whether a room is visited; rooms visited and rooms in all. |
| `Nav.useDoor(id, player?, on?)` / `Nav.setUsedDoors(ids, player?)` / `Nav.doorUsed(id, player?)` | Doors a player has gone through. A door is untried until it is used or the room behind it is visited. |
| `Nav.untriedDoors(player?)` | `{ { room, door } }` for the untried doors of the rooms a player has visited. |
| `Nav.setRoomIcons(id, icons?, player?)` | Other icons on a room for one player (nil goes back to the room's own). |
Settings: `rooms.autoVisit` (default true: the room a player stands in becomes visited; turn it off when your game keeps the record and feeds it), `rooms.showAll` (draw rooms not visited yet too), `rooms.cell` (minimap points per cell, 0 = fit), `rooms.legend` (labels for the legend by icon name, plus `you` and `new`). Event: `roomVisited(roomId, key)`. Room state for a player on another peer is relayed to that peer, the same way per-player waypoints are.
### 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`. Each is applied when the NavHud starts and again whenever you change it, also while the HUD is showing (in play, or in the editor with `previewInEditor` on), so changing `compass` from `dial` to `ring` swaps the compass at once, exactly like `Nav.setVariant`. A field left empty keeps the world setting, a field you have not changed never overrides a later `Nav.setTheme`, `Nav.setVariant` or `Nav.use`, and an unknown name logs a warning and changes nothing. 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`. The walker can be any avatar; one nobody owns shows no name label over it.
### 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` (57 tests) covers every call above. That includes the room map (rooms, per-player visits, used and untried doors, icon overrides, the HUD marking the room a player walks into, the roomGrid minimap and map screen in every theme, top-down and side view, phone-sized, the relay and the session reset), the xy plane, map input left to the game, NavHud fields restyling a running HUD, the two guides shipping inside the package, 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" })`.
## Version history
- **1.3.15**: the compass bar narrows (or drops below) to clear touch buttons in the top band; the objective list redraws when its spot moves.
- **1.3.14**: the minimap keeps clear of on-screen touch controls too: on a phone, a bottom-corner minimap slides along its edge (or up its side, whichever is shorter) until no thumb button covers it, and goes back to its corner when the touch controls hide.
- **1.3.13**: touch messages prefer a side column over the centre of the view.
- **1.3.12**: `toasts.top` keeps top-anchored messages below a game's own top HUD.
- **1.3.11**: the version test and reference table name the current version; no behaviour change.
- **1.3.10**: toasts keep clear of on-screen touch controls (stack from the top in a clear column, bottom pills lift above the controls).
- **1.3.9**: built against controlsKit 1.3.2 (was 1.3.1), so it shares one controlsKit with menusKit 1.3.19, saveKit 1.3.13 and inventoryKit 1.0.27.
- **1.3.8**: waypoint markers never take a tap.
- **1.3.7**: the README keeps only the current version number above this history, as the version test asks.
- **1.3.6**: built against controlsKit 1.3.1 (was 1.2.8), so it shares one controlsKit with economyKit and towerDefenseKit.
- **1.3.5**: a HUD drawn in a box (`Hud.new{ box = ... }`) lets taps through its message layer too: the layer is positioned by `vertical` containers with `pointerEvents = "none"`, which the engine reads on canvases and on the layout containers (vertical, horizontal, grid, spacer), as the UI guide says; only a plain `panel` takes every tap. Corrects 1.3.4's note that only a canvas could let taps through.
- **1.3.4**: on a full-screen HUD the toast layer lets every tap through while messages show (it took every tap on the screen before, so a phone game's own buttons and taps on the world went dead under it); a HUD in a box keeps its frame; 109 tests.
- **1.3.3**: built against controlsKit 1.2.8 (one controlsKit release beside menusKit, saveKit, twoDKit and sideScrollerKit); no kit code changed.
- **1.3.2**: the test suite reads the package from wherever it is installed (its own world, a top-level install or a dependency copy), so `version` and `guides ship with the package` pass as a dependency too; 109 tests.
- **1.3.1**: text only, the gallery README writes key ranges with a plain hyphen.
- **1.3.0**: the room map (`Nav.addRoom`, the `roomGrid` minimap and map screen, per-player visited rooms, used doors and room icons fed from the game or by walking in); the `xy` side-view plane for 2D games; the `gothic` look and room-map colours in every look; `map.input = false`; 55 tests.
- **1.2.1**: changing a NavHud field while the HUD is showing (in play or in the editor preview) restyles it at once, and an unchanged field never overrides a later call; this world on the engine's current built-in library; Known limits names ZeroMind#3099 beside #22181; 49 tests.
- **1.2.0**: two guides ship inside the package (how to use the kit, and an example exploration game with pickupsKit, menusKit and markersKit); checked on the November engine with no changes to the kit's code; Known limits lists only open issues; #19201 fixed in the engine, so the gallery walker shows no `{PlayerName}`; 48 tests.
- **1.1.0**: one shared HUD per player however it is started; per-session player keys, so two machines on one account are told apart; the ring and arrow compasses; tags on every style and the looks as catalogue rows; every play starts clean; opaque 8-digit colours accepted everywhere; 47 tests.
- **1.0.1**: multiplayer fixes: a toast to a player's body reaches them, joining no longer resets the group's progress, per-player waypoints and objectives for another player are relayed, late joiners catch up on shared objectives, and waypoint beams stay local.
- **1.0.0**: first release: minimaps, map screen, compass, waypoints, objective trackers and toasts in five looks, a gallery scene and a two-player playground, phone layouts and a test suite.