# menuBack
The one module of menuBackKit. `hold(onBack, opts)` takes Back for an open menu: while the hold stands, Escape, a gamepad's Start or B and a phone's back gesture run `onBack`, newest and highest hold first, and the app's pause menu stays shut. `hold:release()` gives it up. `follow(key, isOpen, onBack)` keeps a hold by a menu's own open test, for a menu from another kit. `count()`, `labels()` and `keysUp()` say what stands. Called by any kit or game that draws its own menus.
# 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
```lua
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 `priority` wins 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:
```lua
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 priority `PRIORITY` (10), above a pause menu's own claim (0) and the editor's (-1).
- `follow(key, isOpen, onBack, opts?) -> hold?`: hold while `isOpen` is 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.