Thumbstick Studio: Touch, Gamepad and Keyboard Controls Kit
- ..
- .metadata175 B
- ControlsGallery.component
- ControlsMenu.component
- ControlsMover.component
- README.md44.5 KB
- arpg.inputMap
- card.inputMap
- controls.module
- controlsKitTests.testSuite
- engineMaps.module
- example-game-with-touch-gamepad-keyboard-controls-platformer-twin-stick-racing.guide
- exampleGame.inputMap
- flying.inputMap
- fps.inputMap
- gallery.module
- how-to-add-touch-gamepad-and-keyboard-controls.guide
- kit.inputMap
- layout.module
- overlay.module
- package.yaml1.2 KB
- platformer.inputMap
- prompts.module
- racing.inputMap
- rebindScreen.module
- rhythm.inputMap
- rts.inputMap
- schemes.module
- skins.module
- twinStick.inputMap
- widgets.module
README.md
controlsKit 1.4.7
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, six 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:
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:
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
An action in a scheme of your own can carry touchLabel, a short word for its on-screen button (glider = { kind = "button", label = "Wingsuit (open / fold)", touchLabel = "Glide" }); the rebinding screen and prompts keep label.
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 |
arpg | walking | move, moveTo, attack, skill1 to skill4, potion, interact, inventory, pause | WASD/arrows walk, LMB moveTo (click to walk there), Space/RMB attack, 1/Q skill 1, 2/E skill 2, 3/R skill 3, 4/F skill 4, Z/H potion, G/X interact, I/Tab inventory | left stick walks, X/RT attack, A skill 1, B skill 2, Y skill 3, RB skill 4, LB/d-pad down potion, LT/d-pad up interact, View inventory (moveTo is pointer-only: a pad walks with the stick) | floating move stick left, big Attack with the four skills arced around it (arc), Potion + Interact above it, Bag (inventory) beside Pause in the top corner; tap open screen = moveTo |
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), arc (a big primary button with up to four smaller skills arced around it, the mobile action RPG layout; skills take the look's accent colours) | 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.
Click and tap to move (arpg). moveTo is a pointing action: the left mouse button presses it at the mouse, and on touch a tap on open screen (anywhere that is not a kit control and not the floating move stick's lower-left zone) presses it for one frame at the tap. The kit hands over the screen point; turning it into a spot on the ground is the game's (a camera ray against its floor).
Controls.use("arpg")
Controls.on("moveTo", function()
local p = Controls.lastPoint("moveTo") -- { x, y, device, frame, time } in logical screen points
walkTowards(screenToGround(p.x, p.y)) -- your camera ray + navigation
end)
Controls.point(action) answers only while the action is held (a tap: its one frame); Controls.lastPoint(action) keeps the most recent press point until the next one, with the device it came from and the kit frame it landed on, so a game polling in update can tell a new tap from the last. Holding the left button keeps moveTo held (Controls.held("moveTo")), so a game can keep walking towards the live mouse position while it is down. Controls.on("moveTo", fn) and inputSim.fired (controlsKit_moveTo from touch) see taps too.
Button prompts
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:
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.
Remapping on a touch screen. On a phone, remapping is moving the buttons. The rebinding screen has a Touch layout row: tap one on-screen button's chip and then another's to swap their places (a button can move from the big cluster into an extra slot and back), tap Left-handed to mirror the controls (stick on the right, buttons on the left; the drag-to-look side follows), and pick the stick (floating, fixed, follow or d-pad). The arrangement is kept with the player's bindings, per scheme, and Reset to defaults puts it back. From code: Controls.touchSlots() (each side's buttons in slot order), Controls.swapTouch("jump", "dash"), Controls.setTouchMirrored(true).
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:
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:
-- 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
jumpfor itsjump, yourmovefor itsmove(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
playergroup (the default walking and flight maps) down while it runs, so keep your game's controls in a group of their own, asexampleGamedoes.
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.bindingslists the live scheme's actions (controlsKit_jump, labelled "Jump").inputSim.layoutlists the kit's visible on-screen buttons, at the centres the kit draws them (drawnBy = "controlsKit"), andinputSim.tapButton("Jump")taps the kit's own Jump button.Controls.touchButtons()returns the same list.inputSim.firedreportscontrolsKit_jumpfromtouchwhen 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 thecontrolsKit_name;inputSim.bindingslists 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), cameraLook (true), lookSpeed (0.005), lookPitchSpeed (0.004), invertLookY (false) | 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. Turns the orbit camera from the scheme's look action (mouse, right stick, touch drag): the scheme stands the engine's own look down while it is live, so without this the camera would not turn |
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, lastPoint, 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 (57 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.4.7: Controls.VERSION says the release it ships in. It still read "1.4.5" in 1.4.6 (controls.module), so code checking the kit's version saw the wrong one. The suite's "VERSION matches package.yaml" test, which failed in 1.4.6, passes again.
1.4.6: touch buttons stay clear of the engine's folded buttons and of each other on a phone. On a short screen the engine folds the buttons that do not fit into a fan behind a "..." button, which its touch layout lists under fan, apart from buttons, so the kit never saw it and drew Sense and Throw on it (stealthKit's Two Lanterns, phone held sideways, 844x390). overlay.module now treats the fan's button (and, while it is open, the buttons it spreads out) as cutouts. And a control pushed off an engine button looked for a spot clear of the engine's buttons only, so on a phone held upright the corner Pause button was shoved down the right edge onto the cluster's Next button; a pushed control now also clears every control of the kit already placed (layout.module). New test "pushes a corner button clear of the kit's own controls too". Checked in Two Lanterns at 390x844, 844x390, 1024x768 and 1280x720 with touch controls: no two buttons overlap. The suite's two failures (gallery paging, touch mapping over the picture) predate this change and are unchanged.
1.4.5: touch buttons clear every engine button at once. A control pushed off one of the engine's own buttons was checked only against that button, so with the engine's walking column on the right edge (Jump, Interact, Sprint) and a takedown button beside Jump it bounced between neighbours and stayed drawn on one (seen in stealthKit's Two Lanterns at 1280x720: Sense on Jump, Sneak on Interact). layout.module now moves it to the nearest spot clear of every cutout, searched in rings of growing radius and kept on screen; a single cutout gives the same result as before. Checked there: no button overlaps. The suite's two failures (gallery paging, touch mapping over the picture) predate this change and are unchanged.
1.4.4: a scheme ends with the play session that switched it on. When play stopped, the kit dropped its play listeners but kept every controller, its scheme and its takeover of the engine's walking map in module state, so the next play session in the same client started with that scheme live before anything asked for it: the walking map stood down and the player could not move off the spawn (seen in Quiet Reach's Takedown Gallery, where the twin-stick fallback from an earlier session froze the player at the gallery start). Leaving play now stops the controllers and hands the default controls back; a game that wants a scheme switches it on again at play start (onLoad, ControlsMenu), as before. Tests inside _isolate are untouched. Checked: switch twinStick on in play, stop, play again: no scheme is live and W walks the player 4.7 m (before: 0 m).
1.4.3: context touch buttons, and two fixes found building lanternKit's stealth layouts. Controls.setTouchHidden(action, hidden) hides or shows one action's on-screen button at run time (throw only while a lure is in hand, takedown only near a guard), rebuilding only when the set changes. A control pushed off one of the engine's buttons now becomes a cutout for the controls placed after it, so the push never lands it on another of the kit's controls; controls left where the layout put them are not cutouts, so a diamond keeps its shape. Schemes.register records game-registered schemes in Schemes.registered, and the test "has an engine control for every action of every scheme" checks the presets only, since a registered scheme runs on the shared controlsKit.kit map by design.
1.4.2: two touch fixes found in Skyhook. A corner button (the Controls button) that started inside an engine button at the screen edge (the engine's Menu) was pushed toward the edge, clamped back on screen and drawn on top of it; the kit now tries every way out of the engine button and keeps the nearest spot that is on screen and clear. And a scheme action can give a short touchLabel for its on-screen button ("Glide" on a button whose action is labelled "Wingsuit (open / fold)"), so a long label is no longer cut to six letters; the rebinding screen keeps the full label. New tests "moves a corner button clear of an engine button at the edge" and "uses an action's touchLabel on its touch button".
1.4.1: on a touch screen the button clusters keep their shape. The kit lists its own on-screen buttons in the engine's touch layout (so inputSim.tapButton finds them), and then read that same layout back as the engine's buttons to keep clear of, so every rebuild pushed each button away from where it was last drawn, onto its neighbours (in Skyhook the diamond drew Hook on top of Jump and Reel on top of Wingsuit). The kit now keeps clear of the engine's own buttons only. New test "does not dodge its own buttons in the engine layout".
1.4.0: players remap touch controls too: the rebinding screen swaps on-screen buttons between slots, mirrors the layout for the left hand and picks the stick, kept per player like key rebinds (Controls.touchSlots, swapTouch, setTouchMirrored). ControlsMover turns the orbit camera from the scheme's look action: a live scheme stands the engine's own look down, so in 1.3.2 the camera stopped turning under the fps, flying or a registered scheme with look. Found while building Skyhook's remappable grapple, glide, jump and boost controls on a registered scheme.
1.3.2: the kit names its own modules and input maps relatively (require("~.controls"), asset.resolve("~.platformer", "inputMap")) instead of by package name. A file that named controlsKit.<module> recorded the controlsKit release it was last saved against, so 1.3.1 still pointed 14 of its files at 1.3.0 and every install landed two controlsKit releases side by side (menusKit, saveKit, inventoryKit, questKit, economyKit and arpgKit all inherited the second copy). Installing controlsKit now lands exactly one release. No behaviour changed.
1.3.1: the on-screen controls keep clear of the buttons the engine draws itself (the app menu button among them), the same way they keep clear of a notch: on a phone, a driving layout's Gas button is no longer under the engine's Menu button.
1.3.0
- New: the
arpgscheme ("Action RPG") for Diablo / Torchlight style isometric hack and slash and dungeon crawlers:move(on the engine's walking map),moveTo(click or tap to walk there),attack,skill1toskill4,potion,interact,inventoryandpause, every one with its own key and pad button and no clash (skills on 1-4 and Q E R F, so W stays with movement). It has its engine control map,controlsKit.arpg, soinputSimbindings / fired / action / tapButton reach it, and a card in the gallery. - New: the
arctouch button layout: a big primary button under the thumb with up to four smaller skills arced around its inner and upper side, every skill at least 44 pt, laid out on phones in both orientations, around notches, and on desktop screens. Every look applies; the skills wear the look's accent colours. - New:
Controls.lastPoint(action)(andplayer(n):lastPoint) keeps where the most recent press of a pointing action landed, after a one-frame tap has ended.Controls._gesture(kind, ev)queues a gesture for tests and headless tools. - Five new tests (57).
1.2.8
- Fixed: 1.2.6 shipped with
Controls.VERSIONstill reading"1.2.5". The frame loop is keyed by that version (one loop per kit version, see 1.2.5), so a 1.2.6 copy and a 1.2.5 copy in one world shared a loop key and retired each other's controllers, the very fight 1.2.5 was made to end.VERSIONnow reads the package's own version, and the README title and package description name it too. The packages built on controlsKit that ship together in sideScrollerKit (menusKit, saveKit, twoDKit, abilitiesKit, interactKit, navUiKit, slash2D and sideScrollerKit) move to this release together, so a world that installs them holds one controlsKit.
1.2.7: the first draft of 1.2.8, published from its review branch before the README fixes the review asked for; use 1.2.8.
1.2.6: republished the 1.2.5 controls module with a reworded comment above the loop key. No behaviour change; use 1.2.8.
1.2.5
- Fixed: every installed copy of the kit shared one frame-loop key, so a world holding two versions (a package pinning an older controlsKit beside a newer one) had the two copies retire each other's controllers in turn, wiping player 1's scheme. Each kit version now runs its own loop.
1.2.4
- Fixed:
ControlsMoverwrote the controller's intent at execution order -120, after scripts that read and replace it for the frame (platformsKit's ropes, ladders and conveyors run at -250). On a rope the player's stick overwrote the rope's own steering, so a swing never built up and the player slid off. The mover now writes at -300, the moment the engine's own walking map writes the same fields, so anything after it sees and can replace the player's input exactly as with the builtin controls.
1.2.3
- Fixed: the guides and their READMEs gave the guides' addresses as
controlsKit.how-to-...andcontrolsKit.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-controlsandcontrolsKit.package/example-game-with-touch-gamepad-keyboard-controls-platformer-twin-stick-racing, with theguidestool orzero guides readin 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.tapButtonandinputSim.layoutmissed 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.useswitches 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:
ControlsMoverwalked 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:
ControlsMoverdecides which body is yours the way the engine does (thePlayerAvatarthis 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 = 2now 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 yourjumpordashhears 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.exampleGameshows such a map. - New: every scheme's actions are engine controls, so
inputSim.bindings,fired,action,layoutandtapButtonsee 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.onorControls.onGesturenow 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 ranonLoadonce 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
flyingscheme. Racing gainsrecoverfrom 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().tiltisfalse,tiltReasonsays why, andonGesture("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
playercontrols (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
guidestool atcontrolsKit.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.
ControlsMoverkeeps a flying character on the ground. It walks aCharacterController, which has gravity; underflying, rise is a jump and sink does nothing. A game that really flies readsascend/descenditself.