menuBackKit.package
README.md
menuBackKit
Make Escape close your game's menu instead of opening the pause menu. Version 1.0.2. New in 1.0.2: the press that closes a menu never also pauses, even on slow frames. The app menu's Escape and Start stay stood down until Escape, Start and B are all up and a few frames have passed (RELEASE_FRAMES), not only for a fixed RELEASE_GRACE: a stood-down control that woke while its key was still down read it as a new press.
In Zero, Escape, a gamepad's Start and the on-screen Menu button open the app's pause menu in every world. A game with menus of its own (a crafting menu, a bag, a build mode, a map, a shop, a dialogue) wants Escape to close the open menu first, and to pause only when nothing is open. menuBackKit does that on keyboard, gamepad and touch with one call per menu.
Use it
local Back = require("menuBackKit.menuBack")
local hold
function openMyMenu()
ui.showScreen("myMenu")
hold = Back.hold(function() closeMyMenu() end, { label = "my menu" })
end
function closeMyMenu()
ui.hideScreen("myMenu")
if hold then hold:release() hold = nil end
end
While the hold stands:
- Escape and a gamepad's Start close the menu (the app's pause menu stays shut).
- A gamepad's B on the menu and a phone's back gesture close it too (the engine's own Back).
- With several menus open, the most recent one closes first (a higher
prioritywins over newer ones). - Release the last hold and the next Escape opens the pause menu as usual.
A menu from another kit that does not hold Back itself is followed by its open test, every frame:
function update()
Back.follow("bag", Inventory.isOpen(), function() Inventory.toggle() end)
end
API
hold(onBack, { priority?, label? }) -> hold: take Back for an open menu.hold:release(),hold:held(). Default priorityPRIORITY(10), above a pause menu's own claim (0) and the editor's (-1).follow(key, isOpen, onBack, opts?) -> hold?: hold whileisOpenis true, release when it turns false.count(),labels(): the holds standing.keysUp(): whether Escape and Start are taken from the app menu now.releaseAll(): drop every hold.VERSION("1.0.2"),PRIORITY,PRESS_GUARD(0.15 s),RELEASE_GRACE(0.3 s),RELEASE_FRAMES(3).
How it works
A hold is a claim on the engine's Back (Zin.back.claim), so a pad's B on a menu and a phone's back gesture already reach it. While any hold stands, the kit's backKeys input map is live. It belongs to the menuBack group, suppresses = { "app" } (the app menu's pause action), and its one control, back (Escape, Start), presses Back (Zin.back.press), which the engine routes to the newest, highest claim. Nothing is polled and nothing runs while no menu is open.
What it installs
Installing menuBackKit brings these packages, each from its own world, at the versions it was built and tested with:
| Package | Version |
|---|
Guides
- How do I make Escape close my menu instead of opening the pause menu? (
how-do-i-make-escape-close-my-menu-instead-of-opening-the-pause-menu)
Versions
- 1.0.1: released from the Castaway Isle main line at the same time as the other survival kits, on the current engine library; no behaviour change.
- 1.0.0: hold, follow, the backKeys map; tests and a guide.