# controlsKit 1.2.3 Ready-made control schemes for **keyboard + mouse, gamepad and touch** in one package. Pick a genre preset with one line and your game is playable on a phone, with a controller and on a keyboard at once. Swap schemes, sticks, button layouts, looks and button-prompt sets live, and the game's own code never changes, because every scheme speaks the same named actions. It stands on the engine's own input stack. The on-foot schemes take their controls from the engine's **walking** map (`@builtin::inputMaps.default`), racing from its **driving** map (`@builtin::inputMaps.vehicle`) and the flying scheme from **walking + flight** (`@builtin::inputMaps.flight`). Rebinding captures keys through the engine's own capture (`Zin.rebind`), and key clashes are found by the engine's own clash index (`Zin.conflicts`). On top of that the kit adds what the engine doesn't have: genre schemes, six on-screen sticks, five button layouts, gestures, prompt glyphs, looks, phone-safe layout, a rebinding screen and bindings each player keeps. ## Guides Two guides ship inside the package, so they install with it. Open one by its address, as written below: with the `guides` tool (`guides { path: "controlsKit.package/how-to-add-touch-gamepad-and-keyboard-controls" }`), or in the engine shell with `zero guides read controlsKit.package/how-to-add-touch-gamepad-and-keyboard-controls`. The guide's name on its own (`how-to-add-touch-gamepad-and-keyboard-controls`) opens it too. - **How to add touch, gamepad and keyboard controls to your game** (`controlsKit.package/how-to-add-touch-gamepad-and-keyboard-controls`): what the kit is and what to do first, picking a scheme, the shared action names, sticks, button layouts, gestures, when touch controls show and hide, looks and prompts, rebinding and remembered bindings, and per-player input in multiplayer. - **Example: a small game with touch, gamepad and keyboard controls** (`controlsKit.package/example-game-with-touch-gamepad-keyboard-controls-platformer-twin-stick-racing`): from an empty world to a small playable game, installing the kit from ZeroMind, then switching it from platformer to twin-stick shooter to racing with one change each. ## Install and use Install the package into your world. It is published on ZeroMind as `controlsKit.package`, guid `889ac3ad-87d6-427a-8bc4-3e955943fa6c`, with no dependencies: ```lua tools.use("zeromind", "installAsset", "889ac3ad-87d6-427a-8bc4-3e955943fa6c") -- from Luau ``` or `zero zeromind installAsset 889ac3ad-87d6-427a-8bc4-3e955943fa6c` in the engine shell, or search ZeroMind for "controlsKit" and install it. It lands at `/source/controlsKit.package`. While the files arrive, the editor may warn once that `ControlsMenu`, `ControlsMover` and `ControlsGallery` are "waiting for content it requires": that is install order, it clears by itself as soon as the modules land, and there is nothing to do. Then try it: open your scene's entrypoint (in a new world, `scenes/main.scene/entrypoint.luau`), replace its contents with this, and press Play. It runs as written: ```lua local Controls = require("controlsKit.controls") local paused = false local walked = 0 local function shoot(aim: { x: number, y: number }) print(string.format("fire towards %.2f, %.2f", aim.x, aim.y)) end local function dash() print("dash!") end local function togglePause() paused = not paused print(if paused then "paused" else "playing") end function onLoad() Controls.use("twinStick") -- keyboard+mouse, pad and touch, all live Controls.on("dash", function() dash() end) -- edge "pressed" (default) Controls.on("pause", function() togglePause() end) end function update(dt: number) local move = Controls.value("move") -- { x, y }, x right / y up (forward), length <= 1 local aim = Controls.value("aim") walked += math.sqrt(move.x * move.x + move.y * move.y) * dt if Controls.held("fire") then shoot(aim) end end ``` Shift dashes, Space (or the left mouse button) fires, Esc pauses, and WASD moves; on a phone the touch controls appear at the first touch. `Controls.use("platformer")` switches scheme mid-game with one call: the action names stay the same. No code at all: add **`controlsKit.ControlsMenu`** to any entity and set its `scheme` field. Add **`controlsKit.ControlsMover`** to a character's body (next to the builtin `CharacterController`) and it walks, sprints, jumps or drives from whatever scheme is active: forward on the stick or W walks into the screen, back walks towards the camera. Touch controls appear by themselves the moment the player touches the screen, and hide again when they pick up a keyboard or pad (`Controls.setVisibility("auto" | "always" | "never")`). A full-screen panel (a map, an inventory, the gallery) holds them hidden while it is open: call `require("controlsKit.overlay").holdHidden("myPanel")` every frame it is up and `releaseHidden("myPanel")` when it closes. A hold that stops being renewed lapses after half a second, so a panel that disappears lets the controls back by itself, and the player's own visibility setting stays as it was. ## Schemes `Controls.schemes()` lists them; `Controls.describe(name)` returns `{ name, label, description, engineMaps, actions = {{ name, kind, label, engine }} }`, where `engine` names the engine control an action's defaults come from (`"walking.jump"`). | Scheme | Engine map | Actions | Keyboard + mouse | Pad (Xbox names) | Touch (default) | |---|---|---|---|---|---| | `platformer` | walking | move, jump, dash, crouch, interact, pause | WASD/arrows, Space/K jump, Shift/J dash, Ctrl/C crouch, E/L interact | left stick or d-pad, A jump, RB/Y dash, B crouch, X interact | 8-way d-pad left, diamond (Jump/Dash/Interact/Crouch) right; swipe up = jump | | `twinStick` | walking | move, aim, fire, dash, bomb, pause | WASD move, mouse (or arrows) aims from screen centre, LMB/Space fire, Shift/RMB dash, Q/E bomb | left stick moves, right stick aims and pushing it fires, RT/RB fire, LT/A dash, LB/B bomb | floating move stick left, fixed aim stick right (aiming fires), Dash + Bomb buttons; double tap = bomb | | `fps` | walking | move, look, fire, aimDown, jump, crouch, sprint, reload, interact, pause | WASD/arrows, mouse look (click locks the pointer), LMB fire, RMB aim, Space jump, Ctrl/C crouch, Shift sprint, R reload, E/F interact | twin sticks, RT fire, LT aim, A jump, B crouch, L3 sprint, Y reload, X interact | follow stick left, drag the right half to look, diamond (Fire/Jump/Reload/Crouch) + Sprint, Aim Sights, Interact buttons | | `flying` | walking + flight | move, look, ascend, descend, sprint, pause | WASD/arrows, mouse look (right button held), Space/E rise, Q/Ctrl sink, Shift sprint | twin sticks, RT rise, LT sink, L3 sprint | floating move stick left, drag the right half to look, Rise/Sink pair + Sprint; swipe up/down = rise/sink | | `racing` | driving | steer, throttle, brake, boost, handbrake, recover, camera, pause | A/D or arrows steer, W/Up throttle, S/Down/Space brake, Shift boost, Ctrl handbrake, R recover, C camera | left stick or d-pad steers, analogue RT throttle / LT brake (A brakes too), Y/LB boost, B/RB handbrake, View recover, R3 camera | arcade stick steers, Throttle/Brake pedal pair, Boost + Handbrake buttons, camera and recover in the corner; swipe up = boost | | `rts` | none | pan, zoom, select, command, attack, stop, build, rally, pause | WASD/arrows pan, Q/E or Minus/Equal zoom, LMB select, RMB command, F attack, X stop, B build, R rally | left stick pans, LT/RT zoom, A select, B command, d-pad orders | drag anywhere pans, pinch zooms, tap selects, long press commands, radial order wheel (Build/Attack/Stop/Rally) | | `rhythm` | none | lane1 to lane4, flick, pause | D F J K lanes, Space flick | d-pad left, d-pad down, A, B lanes; bumpers flick | two pairs of big lane pads, one per thumb; swipe any way = flick | | `card` | none | navigate, select, play, cancel, inspect, prev, next, endTurn, pause | WASD/arrows browse, LMB/Enter select, Space play, Backspace cancel, I/RMB inspect, Q/E prev/next, Tab end turn | left stick browses, A select, Y play, B cancel, X inspect, LB/RB prev/next, View end turn | tap selects, swipe left/right = next/prev, swipe up = play, swipe down = cancel, long press = inspect, Play Card + End Turn buttons | **Built on the engine's maps.** An action marked with an engine control takes that control's keyboard, mouse and pad bindings straight from the engine's map every time the scheme is switched on, then the scheme's extras are added on top (arrows beside WASD, K beside Space). So walking in the kit is walking in the engine, and an engine update to those maps reaches the kit. Where a scheme needs a key for something else, it says so: flying leaves the flight map's Shift (sink) to sprint. `rts`, `rhythm` and `card` are not on-foot genres, so they carry their own bindings. Every scheme ships with no two actions on one key or button. The exact defaults are in the rebinding screen and in `Controls.bindingSlots()`. Every scheme has `pause` (Esc/P, Menu, and a corner button on touch). **Action kinds:** `button` reads 0/1 with `held` / `pressed` / `released` / `charge`; `vec2` reads `{ x, y }` with y up meaning forward; `axis1` reads -1..1 (0..1 for throttle-like actions); `delta2` reads `{ x, y }` screen points moved this frame (`look`). **Shared names.** `move`, `jump`, `dash`, `fire`, `interact`, `crouch`, `sprint`, `select` and `pause` mean the same thing in every scheme that has them. A game written against `move` / `jump` / `pause` keeps working when the scheme changes. Your own scheme: `require("controlsKit.schemes").register("myGame", t)` with the same shape as the presets in `schemes.module` (an action can say `from = "walking.jump"` to stand on an engine control). ## Styles `Controls.styles()` returns all of these as lists. Each is one call and applies live. | Category | Values | Set with | |---|---|---| | On-screen sticks | `fixed`, `floating` (appears where your thumb lands), `follow` (base trails your thumb), `dpad8` (8-way d-pad), `arcade` (chunky gated ball-top), `drag` (invisible drag area) | `Controls.setStick(variant, side?)` (`"left"`, `"right"`, `"both"`) | | Touch button layouts | `single` (one big button), `pair`, `diamond` (four-button), `radial` (action wheel: press and slide), `charge` (hold-to-charge) | `Controls.setButtons(layout)` | | Gestures | `tap`, `doubleTap`, `longPress`, `swipeUp`, `swipeDown`, `swipeLeft`, `swipeRight`, `pinch`, `tilt` (see below) | `Controls.onGesture(kind, fn)`; `"*"` hears all | | Looks (skins) | `minimal`, `scifi`, `cartoon`, `pixel`, `neon` | `Controls.setSkin(name)`; your own with `require("controlsKit.skins").register(name, t)` | | Prompt families | `keyboard`, `xbox`, `playstation`, `switch`, `generic` | auto from the device in hand; force with `Controls.setPromptFamily(f)` (`"auto"` = auto) | | Prompt styles | `minimal`, `pixel` | `Controls.setPromptStyle(s)` | Other settings: `Controls.setScale(s)` scales every touch control (every target stays at 44 pt or larger); `Controls.setVisibility(mode)`; `Controls.setAimOrigin(x, y)` sets the screen point mouse aim is measured from. **Hold-to-charge:** `Controls.charge("jump")` is 0..1 while held; `Controls.lastCharge("jump")` is the charge at release. This works on keyboard and pad too. **Gestures** fire after the finger lifts. A double tap also fires the single `tap`. `pinch` drives an `axis1` action (rts `zoom`) as a per-frame rate. ## Button prompts ```lua local p = Controls.prompt("jump") -- { codes, family, style, label } for the device in hand local node = Controls.promptWidget("jump", 28) -- a canvas node to drop into a HUD ``` The `ControlsMenu` hint strip and the rebinding screen use the same glyphs. Pads are matched by family: PlayStation pads get Cross/Circle, Nintendo pads get Switch labels (B/A swapped by position), anything else gets Xbox. The `generic` set is position-dots for any pad; choose it with `setPromptFamily("generic")`. ## Rebinding The **Controls** button from `ControlsMenu`, or `require("controlsKit.rebindScreen").open()`, opens the rebinding screen. It lists each action with two key slots and a pad slot, drawn as prompts. Click a slot, press a key, mouse button or pad button (Esc cancels, right-click clears). Keys and mouse buttons are captured by the engine's own rebinding session; a modifier pressed and let go on its own (Shift for sprint) binds that modifier. Clashes are outlined in red with a warning line naming both actions, and **Reset to defaults** restores the scheme. From code: ```lua Controls.rebind("jump", "press", "keys", 1, "KeyG") -- action, part, "keys" | "pad", slot, code for _, c in Controls.conflicts() do print(c.device, c.code, #c.uses) end Controls.resetBindings() local saved = Controls.exportBindings() -- a table, if you also keep it in your own save data Controls.importBindings(saved) ``` Parts: buttons use `"press"`, `vec2` uses `"up"` / `"down"` / `"left"` / `"right"`, `axis1` uses `"neg"` / `"pos"`. Custom bindings are kept per scheme across switches. **Players keep their bindings.** A player's rebinds are saved in their own per-player store (`runtime_data.player(id)`, under `controlsKit/bindings/p1/<scheme>`) the moment they change, and come back the next time that player joins the world, on any device. Reset to defaults forgets them. Each peer writes only its own player's store. The kit needs nothing else for this (no save kit). `Controls.setRememberBindings(false)` keeps them for the session only. ## Phones Touch controls are laid out in points from the screen's real size and safe area, and re-laid out on rotation: - every target is at least 44 pt; - sticks sit where the thumb rests in the lower corners; - sticks and buttons are spaced apart, and the kit's own Controls button, scheme chips and prompt hint strip are laid out around them, in every scheme, held sideways or upright; - while the gallery panel is up, the live touch controls step aside for it (it holds them hidden), so its buttons and cards are free to tap; they come back in walk mode, where the Gallery button sits clear of them; - everything stays inside the safe area and clear of notch and punch-hole cut-outs. The kit lays out what it draws. For your own HUD, put buttons along the top edge or the middle of the screen, where the lower corners stay free for thumbs; `Controls.touchButtons()` lists where the kit's buttons are, and a full-screen menu of yours can hold the controls hidden (above). `require("controlsKit.layout").report(placed)` returns `{ overlaps, offscreen, unsafe, tooSmall }` for any layout; the test suite checks every scheme on notched and plain phones in both orientations. ## Multiplayer Each peer runs its own copy of the kit, so `Controls.*` is always the local player. Players come from the scene's player prototype; `ControlsMover` only drives the local player's own body (the one whose `PlayerAvatar` this peer owns and names this peer's user, the same rule the engine's `CharacterController` uses), so one player's input never moves another player's character, on the host and on every joining peer. Both components are safe on a player prototype. For several players on one machine: ```lua local p2 = Controls.player(2, { keyboard = false, mouse = false, pad = 2, touch = false }) p2:use("racing") local steer = p2:value("steer") -- same API as Controls.*, its own bindings and scheme ``` `pad` is the pad's number, counting from 1 (`pad = 2` is the second pad connected); player *n* reads pad *n* unless you say otherwise, and player 1 any pad. Set `ControlsMover.player = 2` on the second body. ## Touch, keyboard and pad reach the same controls Your game can listen to its actions two ways, and every device reaches both. **Through the kit.** `Controls.on("jump", fn)`, `Controls.held("jump")` and the rest read the kit's action from every device at once: the keys and pad buttons the player bound (rebinds included), the kit's on-screen buttons, sticks and gestures, and `Controls.drive`. **Through your own controls.** A game that already has controls of its own (an input map with a `jump` on Space and the pad's south button, a `dash` on Shift) keeps them. Keys and pads press them directly, as they always did. While a scheme is live, the kit presses those same controls for everything a key cannot: a tap on the kit's Jump button, a swipe the scheme turns into a jump, the touch Dash button, the movement stick, a scripted `Controls.drive`. The kit does it through the engine's `Zin.scheme.drive`, by the action's name, so it is the very control Space presses, with its own press and release, in every live map that declares it. Anything hooked to `jump` or `dash` (your character, your HUD, a sound) hears it whatever the player holds: ```lua -- a component of your game, listening to its own controls local map = asset.resolve("controlsKit.exampleGame", "inputMap"):activate() map.jump:onPressed(function() print("jump") end) -- Space, pad south, or the kit's touch Jump map.dash:onPressed(function() print("dash") end) -- Shift, right bumper, or the kit's touch Dash ``` `controlsKit.exampleGame` is a ready example of such a map (`jump`, `dash`, `move`); copy it for your own. Rules worth knowing: - The names match by action: the kit presses your `jump` for its `jump`, your `move` for its `move` (as `{ x, y }`, y up meaning forward). The kit presses the controls whose names match one of its actions. - Keys and pads are not pressed a second time: your control reads those itself, so a key press is one press. A key the player rebound in the kit's rebinding screen reaches your game through the kit (`Controls.*`); bind your own control to it if it must hear that key directly. - A control somebody else is driving (an `inputSim.action`, a script) is left to them. - Your controls must be live and not stood down: the kit's scheme stands the engine's own `player` group (the default walking and flight maps) down while it runs, so keep your game's controls in a group of their own, as `exampleGame` does. ## Testing with the engine's input tools Each scheme's actions are also engine controls: while a scheme is live the kit holds its map (`controlsKit.platformer`, `controlsKit.twinStick` and so on), where every action is a control named `controlsKit_<action>` with the action's label. So the engine's own tools see the kit: - `inputSim.bindings` lists the live scheme's actions (`controlsKit_jump`, labelled "Jump"). - `inputSim.layout` lists the kit's visible on-screen buttons, at the centres the kit draws them (`drawnBy = "controlsKit"`), and `inputSim.tapButton("Jump")` taps the kit's own Jump button. `Controls.touchButtons()` returns the same list. - `inputSim.fired` reports `controlsKit_jump` from `touch` when a kit button or gesture fires it. - `inputSim.action("controlsKit_jump")` presses the kit's jump the way a device would (the engine drives a control by the exact name a live map declares, so use the `controlsKit_` name; `inputSim.bindings` lists them). Keys and pads are read by the kit with each player's own (rebindable) bindings, so they show up in `Controls.*` rather than in `fired`. A radial wheel's orders are reached by press-and-slide, so they are not listed as tappable buttons. ## Components | Component | Fields | What it does | |---|---|---| | `ControlsMenu` | `scheme`, `skin`, `showMenuButton` (true), `showHints` (true), `showSwitcher` (false), `openOnPause` (false) | Switches the scheme on, then shows the Controls button, a prompt hint strip and, optionally, chips cycling scheme / stick / buttons / look / icons, all kept clear of the touch controls | | `ControlsMover` | `player` (1), `speed` (5), `sprintMultiplier` (1.7), `turnRate` (2.6) | Walks a `CharacterController` body from `move` / `navigate` / `pan` camera-relative, `sprint` / `boost` and `jump` / `ascend`; drives like a car under `racing`, starting out facing where the camera looks | | `ControlsGallery` | `scheme` ("platformer") | The whole kit in one place, everything reacting together: every scheme as a card whose Try it button switches the live controls, every stick, button layout, gesture, prompt set and look, a rebinding station, and a Walk button into a two-player walk area. While its panel is up (in play and as the editor's preview) it holds the live touch controls hidden. This world opens on it | ## API at a glance `Controls.` … `use(name, opts?)`, `scheme()`, `schemes()`, `describe(name)`, `styles()`, `capabilities()`, `value`, `held`, `pressed`, `released`, `charge`, `lastCharge`, `point`, `on(action, fn, edge?)`, `off(handle)`, `onGesture(kind, fn)`, `drive(action, value)` (scripted / AI input; `nil` clears), `device()`, `setStick`, `setButtons`, `setSkin`, `setVisibility`, `setScale`, `setAimOrigin`, `setPromptStyle`, `setPromptFamily`, `prompt`, `promptWidget`, `bindingSlots`, `rebind`, `conflicts`, `resetBindings`, `exportBindings`, `importBindings`, `captureNext`, `cancelCapture`, `isCapturing`, `setRememberBindings`, `remembersBindings`, `player(n, filter?)`, `stop()`, `VERSION`, `TILT_REASON`. A controller from `player(n)` also has `moveIntent(basis, dt, heading?, turnRate?)`, the world-space direction `ControlsMover` walks. ## What's inside `controls` (public API), `schemes` (presets and catalogue), `engineMaps` (reads the engine's walking, driving and flying maps), `exampleGame.inputMap` (an example of a game's own controls, which the kit's touch controls press), `overlay` + `widgets` + `layout` (touch controls and phone layout), `skins` (looks), `prompts` (glyphs), `rebindScreen`, `gallery`, `kit.inputMap`, the three components, the two guides, and the `controlsKitTests` suite (51 tests; `tools.use("tests", "run", { suite = "controlsKitTests" })`, edit mode). The tests give themselves the kit for each test (`Controls._isolate()`) and hand the live controls back exactly as they found them, so running them, twice in a row or mid-session, never disturbs the world. ## What changed **1.2.3** - Fixed: the guides and their READMEs gave the guides' addresses as `controlsKit.how-to-...` and `controlsKit.example-game-...`, which open nothing. Every address in the README, both guides and both guide READMEs is now the one the engine opens: `controlsKit.package/how-to-add-touch-gamepad-and-keyboard-controls` and `controlsKit.package/example-game-with-touch-gamepad-keyboard-controls-platformer-twin-stick-racing`, with the `guides` tool or `zero guides read` in the engine shell. Each was opened as written, here and in a fresh install. - Fixed: the guide READMEs and this README said the guides open with `man`; they now name the two routes that open them. **1.2.2** - Fixed: the gallery's panel could end up under the live touch controls (in play once anything reset their visibility, and in the editor's preview after play stopped): the corner Pause button sat on "Rebind controls", racing's Recover and Camera on "Walk around" and "Rebind controls", and the d-pad and arcade stick on the Rhythm card. While its panel is up, the gallery now holds the live touch controls hidden, every frame, in play and as the preview; they come back in walk mode. - Fixed: a tap anywhere on a scheme card in the gallery switched to that scheme, so a tap on what looked like empty space could switch the live controls (to rts, for one). Only a card's Try it button switches scheme now. - New: `require("controlsKit.overlay").holdHidden(name)` / `releaseHidden(name)` let a full-screen panel of your own hold the touch controls hidden while it is open. - Guides: both link the engine's built-in input guide (`topics/input`), say plainly what happens at each step, and carry a short README of their own. In the example game, the gems on the steps appear when the scheme can jump or shoot, so every round can be finished in every scheme, racing included. - Three new tests (51). **1.2.1** - New: two guides inside the package, a how-to guide and a step by step example game (see Guides). - Fixed: on today's engine, touches landed in the wrong place whenever the scene rendered below full resolution (dynamic resolution on phones and the web): the kit measured the touch area from the render raster instead of the picture on screen. Touches now land on the controls as drawn at any render scale, and a test pins it. - Fixed: `inputSim.tapButton` and `inputSim.layout` missed the kit's buttons when the game is shown smaller than the window (the editor's Scene panel). The kit now lists its buttons at the points the engine's touch tools map onto where they are drawn. - Fixed: leaving a world that used the kit and opening another in the same engine left the old world's touch controls drawn over the new one. A starting copy of the kit now removes touch screens an older copy left behind. - Fixed: the README named some touch buttons wrongly (the platformer's are Jump, Dash, Interact and Crouch; the racing pedals are Throttle and Brake). - Checked on the current engine library (@builtin 9b189b9): installed on its own into a fresh world, the first example runs as written, the same actions fire from keyboard, pad and touch, `Controls.use` switches scheme in one call with the action names unchanged, and the suite passes twice in a row both here and in the fresh install. **1.2.0**: An intermediate publish made while writing 1.2.1 (the guide drafts and the render-scale fix); use 1.2.1. **1.1.0** - Fixed: `ControlsMover` walked backwards (forward moved the body back). Forward now walks into the screen and back towards the camera in every scheme, and the racing drive goes forward on throttle, backs up on brake and starts out facing where the camera looks. - Fixed: `ControlsMover` decides which body is yours the way the engine does (the `PlayerAvatar` this peer owns and that names this peer's user), so each player in a multiplayer session drives their own character, on joining peers as well as the host. - Fixed: running the kit's tests stopped the live controls until a reload. Every test now has the kit to itself and puts the live controls back as they were, however many times it runs. - Fixed: the world opened on the default empty scene. It opens on the gallery, laid out so every label reads from where a player spawns, on desktop and phones. - New: the startup gallery holds the whole kit: all eight schemes as cards (engine map, actions, keyboard and pad prompts, Try it), a rebinding station, and a two-player walk area (Walk / Gallery buttons) where every player who joins gets a runner only their own input moves. The separate playground scene is no longer needed to see any of it. - Fixed: the hint strip covered the twin-stick Bomb button and aim stick on a phone held sideways. The menu now keeps clear of every stick and button in every scheme, sideways and upright. - Fixed: a second local player's pad was read from the wrong slot (the engine counts pad slots from 0), so player 2 on the second pad moved nothing. `pad = 2` now means the second pad, as the README always said. - Fixed: the kit lost control of the game after play stopped and started again, after the tests ran, and for players joining later. The engine had let go of the kit's claim while the kit still believed it held it, so the engine's default Jump and Sprint touch buttons came back over the kit's controls and the twin-stick aim stick. The kit now checks its claim whenever the engine's set of live controls changes, and takes it back. - New: the kit's touch buttons, sticks and gestures (and `Controls.drive`) press your game's own controls of the same name through the engine, so anything listening to your `jump` or `dash` hears a tap on the kit's Jump or Dash button exactly as it hears Space or the pad. Keys and pads keep reaching your controls directly, pressed once. `controlsKit.exampleGame` shows such a map. - New: every scheme's actions are engine controls, so `inputSim.bindings`, `fired`, `action`, `layout` and `tapButton` see and reach the kit's actions and on-screen buttons. - Fixed: the README's first example now runs exactly as written in a fresh world. - Fixed: a handler registered with `Controls.on` or `Controls.onGesture` now ends with the script that registered it. Before, the kit kept calling handlers of scripts that had stopped, so after leaving play and playing again (or when a scene script ran `onLoad` once more) every press fired the handler twice. A component's handlers end with the component; a scene script's or plain module's are dropped when play ends and replaced when the same line registers again. - New: players keep their rebinds. They are saved per player and come back when the player returns. - New: schemes stand on the engine's own maps: walking for platformer, twin-stick and FPS, driving for racing, walking + flight for the new `flying` scheme. Racing gains `recover` from the driving map. - Changed: rebinding captures keys and mouse buttons through the engine's own capture (`Zin.rebind`), which also fixes right and middle clicks being captured as a left click; key clashes come from the engine's clash index (`Zin.conflicts`). The kit's parallel copies are gone. - Changed (follows the engine's walking map): FPS reload is Y and interact X on a pad; platformer interact is X and dash RB/Y; racing brakes on S/Space/LT/A, handbrake is Ctrl, and camera moved to R3. **1.0.1**: Install guid and command in the README; notes from a fresh-world install test. **1.0.0**: First release. ## Known limits - **Tilt is not supported** (#19150). The engine has no tilt or motion input: its input snapshot carries no accelerometer, gyroscope or device-orientation data. `Controls.capabilities().tilt` is `false`, `tiltReason` says why, and `onGesture("tilt")` warns once and never fires. Nothing fakes it. - **Other engine maps' touch buttons can still show beside the kit's** (#12118). While a scheme is live the kit holds that scheme's own control map, which stands the engine's `player` controls (walking, flight) and their touch buttons down, and takes it back whenever the engine lets go of it. Touch buttons from any other engine map your game turns on itself (a vehicle map, a weapon map), and the editor's own touch button ("Frame") while you play inside the editor, still draw in the engine's own column; `Controls.use(name, { takeOver = false })` leaves the engine's controls on screen on purpose. - **Pad buttons and a lone Shift / Ctrl are captured by the kit** (#19812). The engine's rebinding capture still listens to the keyboard and mouse only and skips a modifier pressed on its own, so the kit captures those itself; every other key and mouse button goes through the engine's capture. - **Pad clashes are checked by the kit** (#8115). The engine's clash index still covers only its old action registries, not control maps, so the kit hands its key bindings to it for the length of one check and checks pad buttons itself. - **Two copies of the engine on one account count as one player** (#14448). The gallery's two-player walk area needs two different accounts (or two machines signed in as different people) to show two runners. - **The gallery can run slowly in a web browser** (#20750). The engine's per-frame multiplayer cost weighs on the gallery's busy screen on the web; the kit's controls themselves are unaffected. - **The guides are not found by ZeroMind search yet** (ZeroMind#3099). Guides inside a published package install with it and open with the engine's `guides` tool at `controlsKit.package/<guide name>`, but ZeroMind's own search does not list them yet. ## Good to know - **Remembered bindings need a signed-in player.** An anonymous session has no per-player store, so its rebinds last for that session. - **`ControlsMover` keeps a flying character on the ground.** It walks a `CharacterController`, which has gravity; under `flying`, rise is a jump and sink does nothing. A game that really flies reads `ascend` / `descend` itself.

# controlsKit.prompts Button-prompt glyphs drawn as canvas vectors, with no textures: keyboard + mouse, Xbox, PlayStation, Switch and a generic pad, each in a `minimal` and a `pixel` style. `widget(id, family, style, code, size)` returns a ready canvas node, `draw` appends to your own canvas, `label` gives the words ("Cross", "Space"), and `familyForPad` maps the pad in hand to a family. Most games use `Controls.prompt` / `Controls.promptWidget` instead.