Press Start Studio: Title, Pause, Settings and Credits Menus
README.md
menusKit
Every menu a game needs, as one styled screen stack: title, pause, settings, game over, victory, loading and credits. One call puts a finished screen up, and the game listens for what the player picked. There are 8 looks (sci-fi, fantasy parchment, cartoon, pixel retro, minimal, military, horror, cozy) and 4 layouts (centred list, side rail, card carousel, radial). One setTheme or setLayout call restyles every screen at once. It works with keyboard, gamepad and touch, and ships in English, Brazilian Portuguese and Spanish.
One-step install: install menusKit from ZeroMind and you are done. It brings controlsKit (button prompts, input reading and rebinding) along by itself and spawns its own menu host, so there is nothing to place in a scene. See Install and use.
It is built for multiplayer worlds:
- Pause is per player. Escape, Start or the on-screen pause button pauses only that player's game and stands their character down, while the world and everyone else carry on.
- Settings are per player. They apply immediately and are saved with the player, so they are back when the player rejoins.
- It works with keyboard, gamepad and touch, down to phone-sized screens. Each screen is a fixed screen-space area at the window's corner, so its backdrop covers the whole display, under the notch and the home bar, while its text and buttons stay inside the safe area (plus any
insetsthe game asks for). This was checked with simulated safe areas in the editor, not on a real phone; see Known limits. - Every word on screen comes from a string table. English, Brazilian Portuguese and Spanish ship with it, the language follows the player, and settings has a picker.
Version 1.3.20, built against controlsKit 1.3.2.
Guides: two guides ship inside the package. Main menu, pause menu and settings screen for my game explains how the pieces fit together and what to do first; How to add a pause menu to my game walks from an empty world to a playable game with menusKit and controlsKit. Once the kit is installed, open them from menusKit.package/guides/ in the Docs panel or with the guides tool (for example the path menusKit.package/guides/how-to-add-a-pause-menu-to-my-game).
Install and use
Install menusKit and you are done. It is one install:
tools.use("zeromind", "installAsset", "61aaf7c0-6b6e-4451-9141-a5ef7a087272") -- menusKit
menusKit uses controlsKit (from Thumbstick Studio, guid 889ac3ad-87d6-427a-8bc4-3e955943fa6c) for the button-prompt glyphs, keyboard and pad reading, and the button-rebinding screen. You don't install it yourself:
- It comes in by itself. controlsKit is a declared dependency, so the install brings it along, at
/source/deps/<id>/controlsKit.package. If your world already has controlsKit, that copy is used. - Any folder works. Install menusKit wherever you like (
/source,/source/games/myGame, ...). The two kits find each other by asset name (menusKit.menus,controlsKit.controls), not by path, so nothing has to sit in a particular place.
You can also search ZeroMind for "menusKit" (home world: Press Start Studio, guid 37a0d1f9-9896-4626-b140-43fea7fbedeb) and install it from there.
Then paste this at the end of your main scene's entrypoint (/source/scenes/main.scene/entrypoint.luau in a new world; the rest of that file is comments, so it can stay). It runs as written, in edit and in play, with no other code:
local Menus = require("menusKit.menus")
-- Your game's own actions. Replace the prints with your code.
local function startRun()
print("Start the run")
end
local function restartLevel()
print("Restart the level")
end
local function leaveGame()
print("Leave the game")
end
-- onLoad runs when the scene starts in play.
function onLoad()
Menus.on("play", startRun) -- the menu closes by itself
Menus.on("retry", restartLevel)
Menus.on("quit", leaveGame)
Menus.showTitle({ title = "My Game", theme = "pixel" })
end
Pressing Play prints "Start the run" and closes the menu. The same calls work from any script or component. A handler added while play is running lasts until play stops, so registering in onLoad each time play starts never doubles up; one added in edit mode (a module's top level) stays. Later, from your game:
local Menus = require("menusKit.menus")
Menus.showGameOver({ score = 12040, best = 15500 }) -- Retry calls restartLevel
Menus.showVictory({ score = 48210, time = 271, stars = 2 })
Menus.setTheme("horror") -- every screen restyles at once
Menus.setLayout("radial") -- every screen re-arranges at once
That is all a game needs. Pause, settings, the touch pause button, sounds, transitions, saving and translation all work without further code. The kit spawns its own local host (MenusHost) the first time it is used in play, so there is nothing to place in a scene.
Menus.show(name, opts) opens any screen by name ("title", "pause", "settings", "gameover", "victory", "loading", "credits") with the same options as its own call. For settings, opts.tab picks the tab.
Add it in the editor
With no code at all, add the menusKit.MenusScreen component to any entity in a scene, or to the player prototype. Its inspector fields are:
| Field | What it picks | Default |
|---|---|---|
theme | the look, from a dropdown of all 8 | scifi |
layout | the layout, from a dropdown of all 4 | list |
startScreen | the screen it opens when play starts: title, loading, settings, credits, gameover, victory, pause or none | title |
title | the game name on the title screen (blank shows "menusKit") | blank |
When play starts it styles every screen and opens the start screen for the local player. Changing theme or layout while playing restyles every open screen at once. On a player prototype only the local player's copy runs. Your game still listens for choices in code, with Menus.on("play", fn).
Looks
Menus.themes() lists them (it returns the same list as Menus.looks(); each entry's name is what setTheme takes), and Menus.describe(name) returns one. Every look styles all 7 screens with its own fonts, colours, frames, focus treatment, enter/exit transitions, ambient motion and four synthesised UI sounds (move, confirm, back, open).
| Name | Look | What it is like | Fonts (title / body) | Mood | Fits | Best input |
|---|---|---|---|---|---|---|
scifi | Sci-Fi | Holographic HUD panels, chamfered glass, cyan glow and a scanning line. | Archivo Black / JetBrains Mono | sleek, tense, high-tech | shooter, space, strategy, racing | gamepad, keyboard |
fantasy | Fantasy Parchment | An illuminated scroll on dark oak: serif ink, gilt rules, a wax-red ribbon for the chosen line. | EB Garamond / Gelasio | epic, storybook, warm | rpg, adventure, strategy, card | mouse, keyboard, touch |
cartoon | Cartoon | Thick ink outlines, candy colours, chunky drop shadows and everything bounces. | Archivo Black / Comic Neue | playful, bright, silly | party, platformer, kids, casual | touch, gamepad |
pixel | Pixel Retro | 8-bit arcade: stepped frames, chunky shadows, a blinking cursor and CRT scanlines. | Cousine / Cousine | nostalgic, arcade, upbeat | platformer, arcade, roguelike, puzzle | gamepad, keyboard |
minimal | Minimal | Quiet editorial white: one typeface, hairlines, generous space and a single red accent. | Arimo / Arimo | calm, elegant, focused | puzzle, narrative, indie, sports | mouse, touch, keyboard |
military | Military | Tactical briefing: olive drab, stencil caps, hazard stripes, numbered orders and an amber cursor. | Anton / Cousine | gritty, serious, tactical | shooter, strategy, survival, simulation | gamepad, keyboard |
horror | Horror | Candle-dark and wrong: blood-red serif, a vignette that breathes, drifting fog and lights that flicker. | PT Serif / Tinos | dread, dark, unsettling | horror, survival, thriller, mystery | keyboard, gamepad |
cozy | Cozy | Warm cottage afternoon: soft rounded cards, peach and sage, floating petals and a gentle bob. | Bricolage Grotesque / Arimo | warm, gentle, relaxing | farming, life-sim, puzzle, crafting | touch, mouse, gamepad |
Aliases work everywhere a name does: sci-fi, parchment, toon, retro, 8bit, pixel retro, clean, army, spooky and warm.
Layouts
Menus.layouts() lists them. A layout arranges the choice screens (title, pause, game over, victory) on top of any look. Settings, loading and credits keep their own arrangement, which adapts to the screen shape.
| Name | Layout | What it is like | Mood | Fits | Best input |
|---|---|---|---|---|---|
list | Centred List | Title on top, a framed column of choices in the middle. The classic; reads instantly on any device. | classic, clear | any | any |
rail | Side Rail | A tall panel down the left edge holds the title and choices; the rest of the screen stays open for the game behind it. | cinematic, modern | action, shooter, racing, open-world | mouse, keyboard |
carousel | Card Carousel | Big illustrated cards slide sideways with the focused one centred and its neighbours peeking in. Made for thumbs and shoulder buttons. | playful, showcase | party, casual, mobile, fighting, kart | touch, gamepad |
radial | Radial Menu | Choices ring a central hub; point the stick at one to pick it, the hub names it. Fast and satisfying on a gamepad. | dynamic, tactile | action, shooter, adventure, console | gamepad |
Aliases: centered, centred, column, side, sidebar, cards, card, wheel, ring, pie.
Picking one by tags
local best = Menus.match({ mood = "dark", genre = "survival", input = "gamepad", kind = "look" })
Menus.setTheme(best[1].name) -- "horror"
local all = Menus.catalogue() -- { version, looks, layouts, screens, events, languages, settings }
Screens
| Screen | Call | Default choices | Notes |
|---|---|---|---|
| Title | showTitle{ title, subtitle, version, canContinue, items, theme, layout, credits } | play, continue, settings, credits, quit | Continue is greyed out unless canContinue = true. Replaces whatever was open. |
| Pause | showPause{ items, restart } | resume, settings, mainMenu, quit | Opens by itself on Escape / P / Start / the touch button. restart = true adds Restart. |
| Settings | showSettings(tab) | tabs: audio, controls, graphics, language | Opened from the Settings choice of title or pause. Back returns there. |
| Game over | showGameOver{ score, best, time, title, subtitle, items } | retry, mainMenu | time is in seconds and shown as mm:ss. |
| Victory | showVictory{ score, best, time, stars, maxStars, stats, title, subtitle, items } | next, retry, mainMenu | stats = {{ label, value }} adds lines. Stars are out of 3 by default. |
| Loading | showLoading{ title, tips, progress, tipSeconds } | none | Tips rotate every tipSeconds (4.5). progress = nil shows a looping bar. Drive it with setProgress(p). |
| Credits | showCredits{ title, sections, speed, thanks, loop } | none | sections = {{ title = "Design", names = { "Ada Park" } }}. It scrolls at speed pt/s (46) and ends by itself. |
items replaces a screen's choices. Each one is an id string, or { id, text, desc, icon, disabled }. text is a string key or plain text, and choosing it emits an event named after its id.
Menus.showPause({ items = { "resume", { id = "shop", text = "Shop", icon = "storefront" }, "settings", "quit" } })
Menus.on("shop", openShop)
Events
Menus.on(event, fn) returns a handle for Menus.off(handle). fn(info) receives info = { id, screen, opts, ... }.
Menus.on("settingsChanged", function(info)
print(info.key, info.value) -- e.g. "music", 4
end)
| Event | When |
|---|---|
play, continue, settings, credits, quit | The title's choices. |
resume, restart, mainMenu | The pause menu's choices. resume also fires whenever pause closes. |
retry, next | Game over and victory. |
pause | This player paused (any way). |
back | The player went back one screen (info.screen is the one that closed). |
select | Any choice was picked (info.id, info.screen = the screen it was picked on). It fires last: after the choice's own event and after any screen change the choice causes. Picking Settings fires show, settings, select; Main Menu fires mainMenu, show, select; Play fires play, hide, select. |
show / hide | A screen was pushed or shown (info.screen) / every menu closed. |
settingsChanged | A setting really changed (info.key, info.value = the new value). It fires for every way a setting changes: keyboard, gamepad or touch on the settings screen, Reset to defaults (once per setting it changed), the game calling setSetting / setLanguage, and a saved copy that arrives late. Setting a value it already has (or one that clamps to it) fires nothing. Rebound buttons fire it with info.key = "bindings" and the bindings now in use ({ scheme, bindings }), when the rebinding screen closes and when the controls tab is reset. |
creditsEnd | The credits finished (info.skipped = false) or the player backed out (true). It fires exactly once. |
loadingDone | setProgress reached 1. It fires once per loading screen. |
theme / layout | The look or layout changed (info.name). |
Event names are checked. Menus.on raises at once on a name that doesn't exist, so a typo can't leave a game that never reacts. The error lists every event name that exists and suggests the closest one:
menusKit.on: unknown event 'settingChanged'. Did you mean 'settingsChanged'? Events: play, continue, ... For a custom menu choice, show it on a screen first or declare it with Menus.addEvents("settingChanged").
Custom choices are events named after their id. on accepts one once a screen has shown it (as in the Shop example under Screens), or once the game has declared it with Menus.addEvents("shop"). Declare it first when you subscribe before opening the screen:
Menus.addEvents("shop")
Menus.on("shop", openShop)
-- later
Menus.showPause({ items = { "resume", { id = "shop", text = "Shop" }, "settings", "quit" } })
Old name. setting was the 1.2.0 name of settingsChanged. It still works in 1.x as an alias (Menus.EVENT_ALIASES): Menus.on("setting", fn) gets the same events and prints a warning once telling you to switch to settingsChanged. It will be removed in 2.0.
With the default autoClose = true, picking play, continue, retry, next or restart closes the menus. mainMenu, and quit from anywhere but the title, returns to the last title screen. Settings and credits open their screens. Your game only has to react.
Settings
Each player has their own settings. A change applies the moment it is made and is saved to that player's own data (runtime_data.player), so it is restored when they come back, whichever session of the world they land in.
How the saved copy behaves:
- One leaf per setting under
menusKit/settings/(menusKit/settings/music, …). Only what the player changed is written; a setting they never touched is never saved, so a later default change reaches them. - A saved copy that reaches the machine after the menus opened (the player's data can arrive a moment after they join) is taken up when it arrives and applied. It is never overwritten by the defaults that stood in for it.
- A player identity that arrives late is picked up too: what was changed before it is saved once it exists.
- Rebound buttons are saved as
menusKit/settings/bindings, together with the scheme they belong to. They are imported when that controlsKit scheme is active, or as soon as it becomes active; menusKit never switches the game's scheme to apply them. - The single table menusKit 1.0.0 saved at
menusKit/settingsis still read. A leaf wins over it. MenusHostdrives all of this by callingSettings.tick(dt)every frame. A game that only usesmenusKit.settingswithout the host callsSettings.load()once andSettings.tick(dt)from its own update.
| Key | Values (default) | What it changes |
|---|---|---|
master | 0 to 10 (8) | Master volume. |
music | 0 to 10 (7) | The music channel. |
effects | 0 to 10 (8) | The sfx and ui channels. |
voice | 0 to 10 (8) | The voice and dialogue channels. |
sensitivity | 1 to 10 (5) | Camera look speed. Menus.lookScale() gives the multiplier (1.0 at 5, 2.0 at 10) for games with their own camera. |
invertY | true / false (false) | Inverts the camera's vertical look. |
prompts | auto, keyboard, xbox, playstation, switch, generic (auto) | Which controlsKit glyph set the prompts show. |
quality | auto, low, medium, high (auto) | The renderer's quality tier. |
language | auto, en, pt-BR, es, … (auto) | The menus' language. auto follows the player's own. |
The controls tab also has Rebind buttons, which opens controlsKit's rebinding screen for the scheme the game uses. It is greyed out when the game has no controlsKit scheme active. Each tab has Reset to defaults.
Menus.setSetting("music", 3)
print(Menus.getSetting("quality"), Menus.settings().language)
Input
| Keyboard | Gamepad | Touch / mouse | |
|---|---|---|---|
| Pause / back out | Escape, P | Start | the pause button (top right, touch only) |
| Move focus | arrows, WASD | left stick, d-pad | tap / hover; swipe the cards sideways (carousel) |
| Choose | Enter, Space | A (south) | tap / click |
| Back | Backspace | B (east) | the on-screen back button |
| Settings tab | Q / E | LB / RB | tap the tab |
| Radial layout | arrows | point the stick at a choice | tap |
On the card carousel a sideways drag on the cards moves one card per step (with a finger or a held mouse button), and lifting the finger at the end of a swipe never counts as a tap. A tap without a drag picks the card drawn under the finger. While the cards slide to a new focus (0.34 s), a tap goes to the card whose resting place is under the finger, which can be the neighbour of the card drawn there mid-slide.
Prompts along the bottom show the right glyphs for the device in use (from controlsKit) and hide on touch. While any menu is open, Menus.inputBlocked() is true. The kit's input map stands gameplay input down for that player, and the player's controlsKit controller is released, so a controlsKit-driven character stops. A game reading devices itself should check Menus.inputBlocked().
The pause option of setup turns Escape/Start pausing off, and pauseButton = "auto" | true | false controls the touch pause button.
With controlsKit
menusKit uses controlsKit for prompt glyphs, pause/back/confirm and the rebinding screen. It arrives with menusKit as a dependency and is found by name wherever it lands. One thing to know when your game also drives its character with a controlsKit scheme:
-
One pause button on touch. Every controlsKit scheme draws its own touch-corner pause button, and menusKit doesn't listen to it. Register a copy of your scheme without it, so a phone shows menusKit's button only:
local Schemes = require("controlsKit.schemes") local s = Schemes.get("platformer") -- a fresh copy, safe to change s.touch.corner = {} Schemes.register("myGame", s) require("controlsKit.controls").use("myGame")Or keep controlsKit's button and call
Menus.setup({ pauseButton = false }).
Languages
All text comes from string tables in menusKit.strings: English (en), Brazilian Portuguese (pt-BR) and Spanish (es). Open screens re-translate the moment the language changes.
Menus.setLanguage("es") -- or "auto" to follow the player
Menus.addLanguage("fr", "Français", { ["menu.play"] = "Jouer", ["menu.quit"] = "Quitter" })
Menus.text("result.best", { best = "15,500" }) -- "Best: 15,500"
Menus.showTitle({ title = { en = "Star Forge", es = "Forja Estelar" } }) -- inline translations
Missing keys fall back to English. require("menusKit.strings").keys() lists every key a translation should cover.
API
menusKit.menus: what games use
Constants
VERSION("1.3.20"),SCREENS,EVENTS,DEFAULT_ITEMS.EVENT_ALIASES: old event names that still work, and the name each stands for ({ setting = "settingsChanged" }).SCREEN/PAUSE_SCREEN: the ui screen idsmenusKit_menuandmenusKit_pauseBtn.LAYER(950): the ui layer the menu screen registers at. Its root is a screen-spacearea, so a game's own screens at layer 1000 or above draw over the menus, and anything below 950 draws under them. The touch pause button sits atLAYER - 10.
Screens
showTitle(opts),showPause(opts),resume(),showSettings(tab?),showGameOver(opts),showVictory(opts).showLoading(opts),setProgress(p),showCredits(opts).show(name, opts?): any of the above by name;opts.tabpicks the settings tab. Raises on an unknown name, listing the screens.hide(): closes everything.back() -> boolean: false on a screen with nothing behind it.
State
current() -> string?,stack() -> {string}.isOpen(),isPaused(),inputBlocked().
Events
on(event, fn) -> handle,off(handle) -> boolean.onraises on an event name that doesn't exist.events() -> {string}: every nameonaccepts right now (EVENTS, then the custom choice ids shown or declared).addEvents(...): declare custom choice ids (strings or lists of strings) soonaccepts them before a screen shows them.
Style
setTheme(name, quiet?),setLayout(name, quiet?),theme(),layout().setup(cfg)(aliasconfigure) with{ theme = "scifi", layout = "list", pause = true, pauseButton = "auto", sounds = true, soundLevel = 1, autoClose = true, credits = nil, transitions = true, insets = nil }.insets = { top, left, right, bottom }keeps that many extra points clear on every screen and around the touch pause button, for a game HUD that must stay visible.config(): a copy of the current options.
Catalogue
looks(),themes()(the same list aslooks()),layouts(),describe(name).match{ mood, genre, input, kind }: sorted best first, each entry with ascore.catalogue().
Settings and text
settings(),getSetting(key),setSetting(key, value),lookScale().getSetting("bindings")returns a copy of the controlsKit bindings in use ({ scheme, bindings }), or nil with no scheme active.text(key|table, vars?),addLanguage(tag, name, strings),setLanguage(tag),language().
Navigation (what the host calls; handy for tests and custom input)
navigate("up"|"down"|"left"|"right") -> boolean.focus(i) -> boolean,focused() -> (index, id),items(),select().tab(dir|name),togglePause().handle(uiId) -> boolean: the screens' click ids,mk:item:<i>,mk:back,mk:set:<key>:incand so on.
Rendering (what the host draws)
build(w, h, safe?, { prompt, touch }) -> tree?.buildPauseButton(w, h, safe?) -> tree?.
Functions starting with _ are internal.
Supporting modules
These are mostly internal, but stable enough to extend:
menusKit.themes: the 8 looks.list(),get(name),canonical(name),describe(name).fitTitle(look, ctx, text, size),helpers.ICONS: the icon each default choice uses.icon(ref, size, color)draws an icon node (the same asIcons.node).fonts(name) -> {string}: the font families a look uses. MenusHost checks they are registered and re-registers the builtin fonts if a web build's font loading raced the first frame, so every look shows its own font.
menusKit.icons: the kit's own 32 SVG icons, drawn in the text colour. They need no icon font, so they show the same in the editor, a native build and the web player.names(),aliases()(for examplestorefrontdrawsshop),has(ref).svg(ref, opts?) -> string?,node(ref, size, color?, opts?) -> tree?.- An item's
iconcan be any of these names, an alias, or an inline<svg>document.
menusKit.layouts: the 4 layouts.list(),get(name),canonical(name),describe(name).- Each layout has
compose,navandstepKeys. The carousel also hasmetrics(ctx, n, reserve?); the radial hasangle,pickandmetrics(ctx, n, hasTitle, subH?). The optional height is the room the screen keeps for its title, score block and prompts, so the cards or the ring shrink to fit.
menusKit.screens: builds each screen's widget tree.NAMES,TABS,context(w, h, safe?, extra?),build(name, state).contextreturnsw/h(the space content may use),fullW/fullH(the whole screen),compact,portrait,safe,extraandinset(safe + extra on each side). A screen's root is a fixedareaat the window's origin (screen space, not moved by the safe area); inside it a full-screen stage draws the backdrop to the screen edges, and the content sits atinset.- One builder per screen, plus
promptStrip,tipText,pauseButton. - Credits:
defaultCredits(),creditsHeight(sections).
menusKit.settings: per-player settings.KEY,DEFAULTS,PROMPTS,QUALITY,TABS.get,all,set,step,reset(tab?),choices,onChange/offChange.save()(false when the player has no identity to save under),load()(true when a saved copy was found),isLoaded,tick(dt)(takes up a late saved copy or identity; MenusHost calls it).applyAll,applyCamera,sensitivityScale.rows(tab),valueText.- Test hooks:
_useStore(fn)saves and loads throughfn()instead of the player's data (_useStore(nil)puts the live session back);_forget()starts over as a player who has just joined.
menusKit.strings: string tables.BUILTIN,t(key, vars),has,keys.register(tag, name, strings),languages(),language(),setLanguage,resolve.number(n, decimals): locale digit grouping.
menusKit.sounds: UI sounds.KINDS,clip(look, kind),play(look, kind),setEnabled(on, level),isEnabled().synth,bake,clipName. The 32 clips are pre-baked undersounds/.
menusKit.MenusHost(component): spawned automatically. It draws the screens, reads keys, pads and swipes, and routes clicks.menusKit.MenusScreen(component): the editor set-up described in Add it in the editor.menusKit.menuInputBlock(inputMap): the map that stands gameplay input down while a menu is open.
Tests
menusKitTests covers every public call: the screen stack, events, looks and layouts, settings, languages, navigation, drawing every screen × look × layout on desktop and phone shapes, and each module. Run it in edit mode with tools.use("tests", "run", { suite = "menusKitTests", onWorker = true }) (121 tests). onWorker runs it on a fresh module graph; without it, it runs on the engine thread against the modules already loaded. The suite saves and loads through a stand-in store and pins its own language, so it passes the same on any engine whatever the player running it has saved, and never touches their real settings.
Changelog
- 1.3.20: the API list names the real
VERSION(it said "1.3.5");VERSION,package.yamland the test agree on 1.3.20. Behaviour is unchanged. - 1.3.19: MenusHost, themes and settings are published again so their controlsKit references record controlsKit 1.3.2. A file records the releases it names only when a commit takes that file, and in 1.3.18 MenusHost still named controlsKit 1.3.1 and themes 1.3.0, so an install still landed three controlsKit releases. Every controlsKit name menusKit uses now records one release. No behaviour changed.
- 1.3.18: menusKit now really runs one controlsKit release. This world held an empty leftover
controlsKit.package/controls.modulefolder from an old local copy, so MenusHost, menus and settings recordedcontrolsKit.controlsat that empty folder whilecontrolsKit.rebindScreencame from the installed controlsKit, and an install landed controlsKit 1.3.2 plus the 1.3.1 and 1.3.0 copies. The leftover is gone and controlsKit 1.3.2 is installed fresh, so every controlsKit name menusKit uses records the same release. No behaviour changed. - 1.3.17: built against controlsKit 1.3.2, the first controlsKit release that installs as one copy (1.3.1 still pointed some of its own files at 1.3.0), and menusKit now names its own input map relatively (
asset.resolve("~.menuInputBlock", "inputMap")), so a menusKit release never points at an older menusKit. Installing menusKit lands one menusKit and one controlsKit. The world moved to the current engine library. No behaviour changed. - 1.3.16: every menu screen holds the pointer (
holdsPointeron its root), so in a game whose camera captures the mouse the cursor comes free while a menu is up and clicks reach its buttons. Before, a victory or game over screen opened mid-game could not be clicked at all (Castaway Isle's dawn screen). - 1.3.15: a finger's tap works the choice under it on the title, pause, game over and victory menus. In some engine builds a tap does not reach a
buttonwidget as a click at all (it does not even hover it), so a touch-only player could not pick "Keep surviving" or "Main menu" on a victory screen. MenusHost now reads short taps frominput.events()itself, finds the choice under the finger (Menus._itemAt(x, y), from each row's layout rect) and focuses and selects it, unless the engine delivered the tap as a click already. Checked in play (Castaway Isle): a real dawn shows the victory screen, a simulated tap on "Keep surviving" closes it; Enter and pad A still do. - 1.3.13: built against controlsKit 1.3.1 (was 1.2.8), the release economyKit and towerDefenseKit ship with, so a world that installs menusKit beside them holds one controlsKit. No code change.
- 1.3.12: the camera settings no longer cost a frame with a crowd.
Settings.applyCamera(run every 2 s) read two camera components on every entity in the scene each time, about 19 ms a frame in a tower defense with 150 enemies and their shots. Now each entity is checked once for a camera controller, entities that are gone are forgotten, and a camera is written only when look sensitivity or invert Y changed. Same behaviour for players. Fixes #4. - 1.3.11: built against controlsKit 1.2.8, the release every package that ships with sideScrollerKit moves to together. A package's dependency on controlsKit resolves to the release controlsKit's world ships, so a menusKit built against an older one still landed two controlsKit copies in a fresh world; built against the newest, it lands one. No change to menusKit itself.
- 1.3.10: one controlsKit release throughout. menusKit is built against the published controlsKit 1.2.4, the release twoDKit, sideScrollerKit, abilitiesKit and saveKit are built against, so a world that installs them together holds one copy of controlsKit and every file reads that same copy. The controls module change 1.3.7 carried (later published as controlsKit 1.2.6) only reworded a comment, so controlsKit needed none of it. No change to menusKit itself.
- 1.3.9: installs again. 1.3.8 recorded controlsKit's controls module as an empty file; 1.3.9 holds it exactly as controlsKit 1.2.6 publishes it.
- 1.3.8: installs again. 1.3.7 was published against a copy of controlsKit's controls module that only this world held, so every install of menusKit (and of saveKit, which brings it) failed reading it. That build is now published as controlsKit 1.2.6, and 1.3.8 is built against it. No change to menusKit itself.
- 1.3.7: the number drawn beside each choice ([01], [02], ...) picks it. Keys 1 to 9, on the top row or the number pad, choose that choice on the title, pause, game over and victory menus, exactly as moving the focus there and pressing select would (the choice's own event, then
select). A disabled choice ignores its number. Before, the numbers were only labels.Menus.numberKey()answers which number was pressed this frame.Menus.VERSIONand the version line at the top of this README read the package version again (they had stayed at 1.3.4 and 1.3.5). - 1.3.5: a game's own look.
require("menusKit.themes").define(name, spec)adds a look built on a builtin one (spec.base, default fantasy): every field the spec leaves out comes from the base, the spec's ownbackdrop,title,item,paland so on replace it, and the base's ornament fonts are loaded for it.Menus.setTheme(name)then uses it like any other look. - 1.3.4: the
selectevent documented as it really fires, and no long dashes left.selectorder. The events table saidselectfires before the choice's own event. It fires last, after the choice's own event and after any screen change the choice causes (for example Settings firesshow,settings,select, and Main Menu firesmainMenu,show,select). The table now says so. The behaviour is unchanged; a new test pins the order (121 tests).- No long dashes. The comments at the top of the kit's scripts and the names of the test groups used long dashes; they now use ordinary punctuation, as do the gallery and the scenes. No behaviour changed.
- 1.3.3: docs only.
- With controlsKit. The note about the builtin touch controls coming back over controlsKit's on a second editor Play is gone. controlsKit 1.1.0, which a menusKit install brings, keeps its takeover across Play, Stop and Play (checked over three rounds in a fresh world). The code is the same as 1.3.2 apart from the version number.
- 1.3.2: two guides, and a check on today's engine.
- Guides. Two guides now ship inside the package, so they arrive with every install: Main menu, pause menu and settings screen for my game (how the screen stack, per player pause, saved settings, rebinding, looks and languages fit together, what to do first and where to read on) and How to add a pause menu to my game (a worked example, Coin Dash, from an empty world to a playable game with a title, pause, settings and game over with Retry, installing menusKit and controlsKit from ZeroMind). The example was followed step by step in a brand new world.
- Checked on today's engine, nothing broken. In a fresh world with menusKit installed on its own, the first example above ran as pasted (the title showed and Play fired). Pause stopped only the player who pressed it while the world carried on,
setThemerestyled the open screen and the title behind it, the menus answered touch and a gamepad, and the tests passed 120 of 120 twice in a row. The world's built-in library was already current. A fresh install now brings controlsKit 1.1.0, and every check above ran against it. - Docs. Known limits now name only problems that are still open, with their issue numbers. No code changed apart from the version number.
- 1.3.1: the first README example works when pasted.
- Self-contained example. The first example used
startRun,restartLevelandleaveGamewithout defining them, so the strict checker flagged three unknown names and the world refused to enter play or publish. It now defines all three, says where to paste it (the main scene's entrypoint), shows the title fromonLoad, and keeps the Game Over, Victory, theme and layout calls in a second snippet. It was checked in play, with the strict checker on. - Handlers no longer pile up between play runs. A handler added with
Menus.onwhile play is running now ends when play stops. Before, registering inonLoadadded another copy every time play started, so Play fired twice on the second run, three times on the third, and so on. Handlers added in edit mode are kept as before. - Tests. 4 new: play-session handlers, no pile-up across runs, and the README's first example both passing the strict checker and running as written (Play, Retry and Quit reach the game's own functions).
- Self-contained example. The first example used
- 1.3.0:
settingsChanged, and event names are checked.settingsChanged. The settings event now has the name it was asked for. It fires on every real change, whether by keyboard, gamepad or touch on the settings screen, by Reset to defaults, or from code, withinfo.keyand the newinfo.value. Rebound buttons now fire it too (key = "bindings"); before, a rebind or a controls reset was saved without any event.getSetting("bindings")reads the bindings in use.- Old name kept.
settingstill works as a documented alias that warns once (EVENT_ALIASES). It will be removed in 2.0. - Unknown event names raise.
Menus.on("settingChanged", fn)used to be accepted and never fire. It now raises at once, listing the event names and suggesting the closest one. A non-string name or a non-functionfnraises too. - Custom choices. Their ids are still events.
onaccepts one once a screen has shown it, or afterMenus.addEvents(id). Upgrading: a game that calledMenus.on("shop", fn)before any screen showed a Shop choice now gets an error; addMenus.addEvents("shop")first.Menus.events()lists every accepted name. - Gallery. The gallery's settings toast listens to
settingsChanged. - Tests. 116 tests (9 new: each way a setting changes, the alias, unknown names, custom ids,
addEvents, rebinds).
- 1.2.0: the themes list, the title keeps its theme, and two 1.1.0 promises made true.
- Themes list. Adds
Menus.themes(), the same catalogue entries aslooks()under the namesetThemeuses.looks()is unchanged. - Main Menu keeps the current look. A
themeorlayoutpassed toshowTitleis applied once and no longer stored with the title. Before, Main Menu (or Quit from pause) brought the title back in the look it was first opened with, undoing anysetThemesince. - Full-bleed backdrop, for real. 1.1.0 said the backdrop covered the area under the notch and home bar, but on a phone-shaped screen it stopped at the safe area: the stage reached out under the top bar, but the band under the home bar was never painted. Each screen's root is now a fixed
areaat the window's origin, and the backdrop covers the whole screen. Because of this,LAYERmoves from 1100 to 950, so a game's overlays at 1000+ stay above the menus. - Carousel taps. 1.1.0 said taps worked as before, but a tap on a card picked its neighbour: the card row was moved with a transform, which touches don't follow. The row is now placed by layout and only the slide animation uses a transform, so a tap picks the card under the finger.
- Room for the score. The radial ring and the carousel cards now leave room for the game over and victory score block and the prompt strip. Before, the radial's lower choice and its caption ran off the bottom on most screen heights. Screens also go compact below 520 pt of height (was 480).
- Gallery. The gallery title shows the kit's current version.
- Tests. 107 tests.
- Themes list. Adds
- 1.1.0: phones, touch, fonts and the editor.
- Safe area. The backdrop now covers the whole screen, under the notch and home bar, and content stays inside the safe area plus the game's
insets. Before, a strip at the bottom was bare, and with a large safe area the radial's lower button and the foot of the credits panel were cut off. - Radial hub. The centre is now a disc capped at 220 pt and kept clear of the ring in any window shape. Before, a tall window turned it into a large rounded square running into the choices. The focused choice is named once: by the hub, or by a caption when the hub is too small.
- Carousel swipe. Swiping the cards sideways moves the focus on touch and with a held mouse button. Taps work as before.
- Icons and fonts. The kit draws its own SVG icons instead of the editor's icon font, so icons no longer show as empty boxes in a play session. MenusHost re-registers the builtin fonts when a look's font is missing, so the pause screen keeps its look's font.
- Editor. Adds the
MenusScreencomponent (theme, layout, start screen, title) andMenus.show(name, opts). - Input map. The input map is renamed
menuInputBlock(wasmenus). - Tests. The tests no longer depend on the running player's saved language or settings; 102 tests.
- Install docs. The install notes now say where controlsKit lands: it arrives as a dependency under
/source/deps/, or the world's own copy is used.
- Safe area. The backdrop now covers the whole screen, under the notch and home bar, and content stays inside the safe area plus the game's
- 1.0.1: settings survive a rejoin however late the player's data arrives.
- Each setting is now its own leaf, and only changed settings are written. Before, defaults that loaded ahead of the saved copy could be written over it.
- A late saved copy or a late player identity is taken up (
Settings.tick). - Rebound buttons are kept per scheme and imported when that scheme becomes active.
- The 1.0.0 table is still read.
- The tests use a stand-in store; 89 tests.
- 1.0.0: first release.
Known limits
Problems that are still open, with their issue numbers where the cause is outside the kit.
- Phones are checked in the editor only, and the editor's play view can clip under the insets (#19210). The backdrop reaching the screen edges and the content staying inside the safe area plus
insetswere measured in the editor with simulated safe areas (a notch, a home bar and a side inset). It has not been tried on a real phone, and the simulated safe area has no effect in a play session. While playing inside the editor with phone safe-area insets, a menu element under the insets (for example the backdrop under the notch or home bar) can show clipped; that is the engine's editor play view, not the kit's layout. - Short screens. At 1280 pt wide, a few screens still run past the bottom of the safe area. With the keyboard or gamepad prompt strip showing, the strip ends up to 44 pt below it on the list victory screen at about 540 pt of usable height (and 8 to 15 pt on the list title in the cartoon and military looks), up to 32 pt below on the carousel victory and game over screens at about 360 pt, and 5 to 28 pt on the side-rail title at about 360 pt. On touch, where there is no prompt strip, only the list victory screen at about 540 pt (9 pt in fantasy, 14 pt in military) and the carousel victory screen at about 360 pt (2 pt) overflow. Where the screen has a bottom inset the overflow lands under the home bar; with none it is clipped at the screen edge. The radial layout fits at every height measured.
- Carousel taps mid-slide. While the cards slide to a new focus (0.34 s), a tap lands on the card whose resting place is under the finger, which can be the neighbour of the card drawn there.
- Per-player pause was checked in one engine (#14448). Two engines signed in to one account collide as one player, so the check ran in one engine: while one player was paused, a stand-in second player's body and a falling physics body kept moving, and the engine never paused or changed time scale. A check with two real players on two accounts has not been run.
- The web build was not run (#20946). An agent inside the engine cannot start a browser engine, so the web player was not checked for this release; the 1.1.0 font fix for the web build was checked in editor play and by reading the code.
- A fresh install takes about 20 seconds (#21420). Installing menusKit on its own brings controlsKit and copies of a few engine files with it, about 540 files in all.
- The guides do not show in ZeroMind library search yet (ZeroMind#3099). They ship inside the package and are found by the engine's
guidestool and the Docs panel once the kit is installed. - The ZeroMind description can lag a release (#19258). For a while after a release, ZeroMind may show the previous version's description; the README inside the package is current.
- Rebinding needs the game to use a controlsKit scheme.
- A guest with no player identity can't keep settings between visits. Their choices apply for the session and
save()returns false. - A game with its own character controller must read
inputBlocked()itself if it doesn't go through input maps or controlsKit.