# juiceKit **One call makes hits, explosions, pickups and level-ups feel great: `Juice.play("explosionLarge", someEntity)` shakes the camera, flashes the screen, freezes the action for a beat, squashes the target and plays an effect at the spot, all together and correctly for every player.** Version **1.2.8** (`Juice.VERSION`). The version, this README and `package.yaml` move together. ## Install 1. **Add juiceKit to your world.** Search ZeroMind for **juiceKit** and install `juiceKit.package` from the ZeroMind panel, or install it by its guid: `zeromind_install guid=eed55f6d-afaf-4767-83c5-539ef91e0dc5`. It needs no other package. 2. **Require it** from any component or module: `local Juice = require("juiceKit.juice")`. 3. **Call `Juice.play`** with a preset and a target: `Juice.play("explosionLarge", someEntity)`. The first example below is a complete component to start from. ## Guides Two guides ship inside the package, so they are in your world as soon as juiceKit is installed. Open one with the `guides` tool (`path` = the name in brackets), or in the shell with `zero guides read <path>` (`zero guides list` lists them). - **How to add screen shake, hitstop and hit feedback to my game** (`juiceKit.package/how-to-add-screen-shake-hitstop-and-hit-feedback-to-your-game`): what the kit is and how its pieces fit, playing presets, camera shake with any camera, hitstop, flashes, squash, particles and looks, intensity and reduced motion, who sees what in multiplayer and when to call from one player or from code every player runs, and what to do first. - **Make your game feel juicy, step by step** (`juiceKit.package/make-your-game-feel-juicy-step-by-step-with-hit-feedback-explosions-and-damage-numbers`): from an empty world to a small multiplayer arena with juiceKit, SecondWind (health and damage) and markersKit (hit markers and damage numbers). Punching a training dummy, exploding barrels that shake you by distance, coins and heal orbs, hard landings, hurt and death felt only by that player, and a reduced-motion button, with why each choice is made. ## First example 1. Install juiceKit into your world (see [Install](#install)). 2. Create a component named `juiceDemo` (a `juiceDemo.component` folder with this `init.luau`). 3. Add `juiceDemo` to any entity in your scene, press Play and press **E** (Interact). Each press plays the next of the three effects. ```lua local Juice = require("juiceKit.juice") declare {} public = { inputMap = Field.assetRef("inputMap", "@builtin::inputMaps.default", NoSync, "The controls the Interact press comes from."), } local controls = nil local presses = 0 function start() controls = public.inputMap:activate("juiceDemo") controls.interact:onPressed(function() presses += 1 local here = public.entity if presses % 3 == 1 then -- an explosion at this entity: everyone sees it, and each player -- feels the shake as strongly as their distance to it warrants Juice.play("explosionLarge", here) elseif presses % 3 == 2 then -- a coin pickup at a point in the world Juice.play("coinPickup", { 4, 1, 2 }) else -- the local player got hurt by an attacker standing at this entity: -- red vignette, a short freeze, a kick away from it (only this player) Juice.play("hurt", nil, { from = here }) end end) end function onDestroy() if controls then public.inputMap:deactivate(controls) end end ``` Nothing else is needed. Only the player who pressed E calls `play`, so the default routing is right: the explosion and the coin reach every player, and the hurt stays with this one. Requiring `juiceKit.juice` starts listening for other peers' effects, and the first shake attaches the shake components to the camera on screen. To make sure a peer whose own scripts never call `play` still receives world effects, put the **JuiceNet** component on any scene entity. Its `look` field also sets the starting look. ## What's new in 1.2.8 Documentation only. Every call, option, preset, network message and guide works as in 1.2.7. - **Install steps come first.** The README opens with how to install juiceKit (from the ZeroMind panel, or by its guid), require it and play a preset, and the package description says how to install it. - **The release notes moved below the first example,** so the README reads as what the kit gives you and how to start, then what changed. ## What's new in 1.2.7 Only the arena guide's wording changed; its code is exactly 1.2.6's. Every call, option, preset and network message works as in 1.2.6. - **The barrel chain's timing is described as it really plays.** The fuse runs on game time, so a nearby blast's freeze holds it too. Watched from across the arena, the barrels go up about a third of a second apart (0.31 to 0.34 s measured). Close to the line, where each blast freezes your screen, they go up about 0.4 s apart, and up to about two thirds of a second when the blasts are also hurting you. The guide used to say "about a third of a second" everywhere, and that the second blast always hurts you again. It does so only when it lands after your half second of invulnerability, which close to the line it sometimes does and sometimes does not. - **Checked on today's engine** (built-in library 6c67f68): the arena guide was followed word for word from an empty world, with every step working. Walking up and down the ramp played no landing and stepping off the tower played one. The panel left the game's brightness unchanged. The five barrels went up one at a time. ## What's new in 1.2.6 Only the arena guide and its example code changed. Every call, option, preset and network message works as in 1.2.5. - **Walking up a ramp is no longer a hard landing.** The arena's `PlayerFeel` worked out the fall from how far the body dropped between two frames. At the top of the ramp the character controller snaps the body down onto the tower in one frame, which read as a fast fall, so the hard landing played. It now asks the character controller (`grounded` and `velocityY`). Walking up and down the ramp plays nothing, and stepping off the 4 m tower plays exactly one landing (checked three times each way). - **The arena's panel no longer darkens the game.** A screen's root fills the whole view, and the panel's dark background sat on the root, so it tinted everything. The root is now a clear, full-screen layer and only the panel is dark. With the panel shown and hidden, the picture's median brightness is the same (149). - **The barrels really chain.** All five used to go up in the same instant, because each blast killed the next barrel at once. A barrel set off by another blast now fizzes for a 0.3 s fuse before it goes up, and the barrels stand in a straight line 2 m apart, with damage that falls to nothing at the blast's edge, so each blast sets off only the next one. Measured: blasts at 0.02, 0.58, 0.91, 1.26 and 1.59 s. The guide also says what that means for the player: standing beside the line, the second blast can hurt you too, because it comes after your half second of invulnerability. - **Checked on today's engine** (built-in library 6c67f68): the 104 tests pass twice in a row, all 51 presets play, and the arena guide was followed from an empty world to the end. ## What's new in 1.2.5 - **The arena guide's tower can be climbed every time.** Following the guide again from an empty world showed that its ramp stopped a few centimetres short of the tower and just below its top. The character stopped against the tower wall and slid back down, so the tower coin and the hard landing were out of reach unless you held forward in one unbroken run. The ramp now runs past the tower's edge and ends just above the platform. In three climbs with different input rhythms, each reached the top, took the coin and played the hard landing on the way down. Every call, option, preset and network message works as in 1.2.4. Only the guide changed. ## What's new in 1.2.4 - **The arena guide's panel no longer hides under the kill feed.** Its coin count and Motion button moved from the top right, where a barrel chain's kill feed rows covered them, to the top left. The panel now rebuilds only when the coin count or the motion setting changes, instead of every frame (its script time went from 0.11 ms to 0.03 ms a frame, and the UI no longer lays it out again every frame). - **The arena guide says what a barrel chain really does:** every blast shakes, flashes and freezes you by your distance, but only the first one hurts, because SecondWind gives a player half a second of invulnerability after a hit and the whole chain goes off inside it. The guide says how to change that. - **The README no longer says the guides open with `man`;** they open with the `guides` tool and `zero guides read`. See Known issues for `man` and for the package page's description. - **Checked on today's engine** (built-in library 23a3330): the 104 tests pass twice in a row, all 51 presets play, and the arena guide was followed again from an empty world to the end. Every call, option, preset and network message works as in 1.2.3. ## What's new in 1.2.3 - **An entity's position works as a target.** `Juice.play("coinPickup", coin.position)` raised an error on today's engine, because an entity's `.position` now refuses keys it does not have and the kit asked it for an `id`. The kit now asks safely, so every target form in the table below works. A test covers it. - **Two guides** (see [Guides](#guides)). - **Checked on today's engine:** the 104 tests pass twice in a row, all 51 presets play, and the first example below runs word for word in a brand-new world with only juiceKit installed. - **Checked with two players** (two desktop sessions): a second player's camera gets exactly its share of every effect, as described under [Multiplayer](#multiplayer). A blast next to them shook them 0.21 m with a flash and a freeze while the caller 20 m away got 0.006 m and neither; `hurt` aimed at them reached only them, and `hurt` on the caller reached only the caller. The player who joins starts on the spawn facing the stage with the camera behind them, and both players see both characters. A session with no window also joined with its own player and a gameplay camera, and received effects. The two Known issues about joiners (#16913, #19169) no longer happen and are gone from the list. Every call, option, preset and network message works as in 1.2.2. ## Swapping things Everything goes through the same call, so a different preset, look or strength is a one-word change: ```lua Juice.play("hitLight", enemy) -- -> "hitHeavy", "hitCritical" Juice.play("vfxFire", pos, { look = "pixel" }) -- one effect in another look Juice.setLook("realistic") -- every effect from now on Juice.play("shakeExplosion", pos, { intensity = 0.5 }) -- half strength, this call only ``` ## Presets (51) Kinds: `combo`, `shake`, `hitstop`, `flash`, `squash` and `vfx`. Strengths: `light`, `medium` and `heavy`. Scope is `player` (it happens only for the player it is about) or `world` (every peer sees it). `hurt`, `heal`, `death`, `levelUp` and `landingHard` also carry `personal = "player"`: their screen parts play only for a player who is the target, never for whoever called `play`. See the multiplayer rules below. | name | kind | strength | scope | pieces | what it is | |---|---|---|---|---|---| | `coinPickup` | combo | light | world | squash + vfx | A coin sparkle and pulse. | | `death` | combo | heavy | world | shake + hitstop + flash + squash + vfx | A death: crushed flat, smoke, a slow-motion freeze, and a dark fade for the player who died. | | `explosionLarge` | combo | heavy | world | shake + hitstop + flash + squash + vfx | A big blast: fireball, debris, a dust ring, a flash and a shake everyone feels by distance. | | `explosionSmall` | combo | medium | world | shake + squash + vfx | A small blast: fireball, smoke and a distance-scaled shake. | | `heal` | combo | light | world | flash + squash + vfx | Healing: rising green motes and a soft green pulse for the healed player. | | `hitCritical` | combo | heavy | world | shake + hitstop + flash + squash + vfx | A critical: a long freeze into slow motion, a hot flash, a kick away from the attacker and zap sparks. | | `hitHeavy` | combo | medium | world | shake + hitstop + flash + squash + vfx | A heavy hit: bigger sparks, a freeze, a strong shake and a flash. | | `hitLight` | combo | light | world | shake + hitstop + squash + vfx | A light hit: sparks, a tiny freeze, a small shake and a wobble. | | `hurt` | combo | medium | player | shake + hitstop + flash | Taking damage: a red vignette, a kick away from the attacker and a tiny freeze. | | `landingHard` | combo | medium | world | shake + squash + vfx | A hard landing: a dust ring, a landing squash and a short heavy shake. | | `levelUp` | combo | heavy | world | shake + flash + squash + vfx | Level up: a golden column, a ring, confetti, a golden glow and a stretch. | | `spawn` | combo | light | world | squash + vfx | Something appears: a pop-in with a magic burst. | | `shakeEarthquake` | shake | heavy | world | shake | A rolling earthquake that swells, peaks and fades over four seconds for everyone nearby. | | `shakeExplosion` | shake | heavy | world | shake | A blast shake that every player feels, weaker the farther they are from it. | | `shakeHeavy` | shake | heavy | player | shake | A strong jolt for big hits and slams. | | `shakeKick` | shake | medium | player | shake | A directional kick that pushes the view away from where the hit came from (pass `from` or `direction`). | | `shakeLight` | shake | light | player | shake | A quick, small jitter for light hits and footfalls. | | `shakeRecoil` | shake | light | player | shake | A weapon recoil: the view snaps back and up, then settles. | | `shakeRumble` | shake | medium | player | shake | A long, low rumble for engines, collapsing rock or a boss approaching. | | `hitstopCritical` | hitstop | heavy | player | hitstop | A 180 ms freeze that eases out through slow motion, for critical hits and finishers. | | `hitstopHeavy` | hitstop | medium | player | hitstop | A 120 ms freeze for heavy blows. | | `hitstopLight` | hitstop | light | player | hitstop | A 50 ms freeze that lands a light hit. | | `hitstopSlowmo` | hitstop | medium | player | hitstop | Half a second of 25% slow motion with no freeze, for near misses and dramatic moments. | | `flashBlackout` | flash | heavy | player | flash | A fade to black and back, for death, respawn or a scene cut. | | `flashCritical` | flash | heavy | player | flash | A blinding white-orange burst with hot edges. | | `flashDamage` | flash | medium | player | flash | A red vignette that closes in from the screen edges when you take damage. | | `flashExplosion` | flash | medium | world | flash | A bright blast flash every player near the explosion sees. | | `flashFreeze` | flash | light | player | flash | An icy blue vignette for frozen, chilled or shielded. | | `flashHeal` | flash | light | player | flash | A soft green pulse from the edges. | | `flashHit` | flash | light | player | flash | A sharp white flash across the screen. | | `flashLevelUp` | flash | medium | player | flash | A warm golden glow that blooms and fades. | | `flashPoison` | flash | light | player | flash | A sickly purple-green vignette for poison and curses. | | `flatten` | squash | heavy | world | squash | Crushed flat, held, then springs back up, for deaths and stomps. | | `jellyWobble` | squash | light | world | squash | A jelly wobble when something is hit. | | `popIn` | squash | medium | world | squash | Grows from nothing with an overshoot, for spawns and pickups appearing. | | `pulse` | squash | light | world | squash | A quick uniform bump for collect, select or a heartbeat. | | `punch` | squash | heavy | world | squash | A hard punch inward that rings out, for heavy impacts. | | `squashLand` | squash | medium | world | squash | Flattens on landing and springs back. | | `stretchJump` | squash | medium | world | squash | Stretches tall on take-off and settles. | | `vfxCoin` | vfx | light | world | vfx | A coin sparkle. | | `vfxConfetti` | vfx | medium | world | vfx | A confetti burst. | | `vfxDust` | vfx | light | world | vfx | A dust puff. | | `vfxExplosionLarge` | vfx | heavy | world | vfx | A large explosion: fireball, debris and a smoke ring. | | `vfxExplosionSmall` | vfx | medium | world | vfx | A small explosion. | | `vfxFire` | vfx | medium | world | vfx | A burst of fire. | | `vfxHeal` | vfx | medium | world | vfx | Rising healing motes. | | `vfxLevelUp` | vfx | medium | world | vfx | A level-up column and ring. | | `vfxMagic` | vfx | medium | world | vfx | A magic burst. | | `vfxSmoke` | vfx | medium | world | vfx | A smoke cloud. | | `vfxSparks` | vfx | light | world | vfx | Impact sparks. | | `vfxZap` | vfx | medium | world | vfx | An electric zap. | Every `vfx` preset and every combo's effect is drawn in the current look: **cartoon** (solid toon shapes, the default), **realistic** (soft additive glow, smoke and dark debris), **pixel** (chunky cubes snapped to a grid) or **scifi** (cyan and magenta energy). Effect kinds: `sparks`, `dust`, `explosionSmall`, `explosionLarge`, `magic`, `heal`, `levelUp`, `coin`, `smoke`, `fire`, `zap` and `confetti`. ## Interface (`require("juiceKit.juice")`) ### Playing `Juice.play(name, target?, opts?) -> result` plays a preset. It raises on an unknown preset, look or target, and otherwise returns a table saying what ran on this peer: `{ shake = strength, hitstop = true, flash = alpha, squash = true, vfx = particleCount, sent = true, id = playId }`. Every play gets an `id`, even one that intensity 0 turned into nothing, so the result can always be handed to `Juice.stop`. - `target`: an entity, an entity id, an entity name, a position (`{x,y,z}`, `{x=,y=,z=}`, a vector, or an entity's `.position`), or nil for the local player. - `opts`: | option | meaning | |---|---| | `intensity` | Multiplier for this call (multiplied by the global intensity). | | `look` | Draws this call's effect in a look other than the current one. | | `from` | The attacker: an entity or a position. Kicks push away from it, and when the target is a thing (not a player) and `from` is another player's avatar, the personal parts land on that attacking player's screen. | | `direction` | World direction the hit travels, used instead of `from`. | | `scale` | Effect size multiplier. | | `axis` | Squash axis: `"y"` (default), `"x"` or `"z"`. | | `scope` | `"auto"` (default): world parts go to every peer, personal parts to the one player they belong to. `"local"`: play here only what belongs on this peer and send nothing, for code that already runs on every peer. `"world"`: also send a player preset's world parts to every peer. | | `seed` | Seed for a repeatable effect. | `Juice.stop(what) -> boolean` stops one play early and leaves everything else running. `what` is the table `play` returned, its `id`, or a preset name; a name stops every play of that preset on this peer, its own and ones received from other peers. ```lua local charge = Juice.play("shakeRumble") -- the charge was cancelled: Juice.stop(charge) ``` - The shake comes off the camera with no drift; other shakes keep going. - The hitstop lets go: normal speed comes back at once unless another hitstop still holds. - The flash disappears, the squash lands on the exact base scale, and the effect's particles and light vanish. - Stopping a play this peer sent to others stops it on their screens too. - It returns false for a play that has already finished or was stopped, and for nil. An unknown preset name raises. `Juice.isPlaying(what) -> boolean` says whether any part of a play (same `what` as `stop`) is still running here. `Juice.stopAll()` stops every shake, hitstop, flash, squash and effect at once, puts squashed things back at their exact base scale, and releases the time scale. It acts on this peer only and forgets every play id. ### Finding presets - `Juice.list(filter?) -> rows` returns every preset as `{ name, kind, strength, scope, personal, looks, pieces, effects, tags, custom, description }`, sorted by kind and then name. - A **kind name** string (`"shake"`, `"combo"`, …) keeps that kind. - Any other string matches a tag or a name (`"heavy"`, `"world"`, `"explosion"`, `"custom"`). - A table `{ kind?, strength?, scope?, look?, piece?, tag?, custom? }` requires all of its fields. - `Juice.names(filter?) -> { string }` returns the same rows as `list`, names only. - `Juice.get(name) -> row?` returns one row plus `spec`, the resolved pieces. Both are copies: changing them never changes the preset. - `Juice.has(name) -> boolean` says whether a preset by that name exists. - Constants: `Juice.KINDS`, `Juice.STRENGTHS`, `Juice.SCOPES` and `Juice.PIECES`. ### Making your own `Juice.define(name, spec) -> row` adds a preset, or replaces one you defined earlier. Each piece in `spec` is either the name of an existing preset of that kind or a table of its own: ```lua Juice.define("bossSlam", { shake = "shakeEarthquake", hitstop = "hitstopHeavy", flash = "flashExplosion", squash = "punch", vfx = { kind = "explosionLarge", scale = 1.6 }, strength = "heavy", scope = "world", tags = { "boss" }, description = "The boss hits the floor.", }) Juice.play("bossSlam", boss) ``` Besides the pieces, `spec` takes `kind`, `strength`, `scope` (`"player"` or `"world"`, worked out from the pieces when left out), `personal` (`"target"`, the default, or `"player"` for moments that only make sense for a player; see the multiplayer rules), `tags` and `description`. Your presets can be built on each other (`Juice.define("bossSlamBig", { shake = "bossSlam", vfx = { "bossSlam", "confetti" } })`), and changing one never breaks another: - `Juice.remove(name) -> boolean` removes a preset you defined (false when there was none). Presets built on it keep working exactly as before: each keeps its own copy of the pieces it took from it. - Redefining a preset changes what the presets built on it play, except for a piece the new version no longer has: those keep the piece they had. - `define` and `remove` refuse a change that would leave another preset broken, such as two presets naming each other in a loop. They raise `juiceKit.define: 'a' would break 'b': …` (or `'a': …` when `a` itself would break), and every preset stays as it was. ### Settings | call | what it does | |---|---| | `Juice.setLook(name)` / `getLook()` / `looks()` / `hasLook(name)` / `vfxKinds()` | The one look switch every effect follows. | | `Juice.setIntensity(x)` / `getIntensity()` | Global intensity, clamped to 0–2. It scales shake, flash, hitstop and squash strength and effect density; 0 turns the kit off. | | `Juice.setReduceMotion(on)` / `getReduceMotion()` | Motion-sickness comfort: no camera shake at all, and gentler, shorter flashes. Hitstop, squash and effects still play. | | `Juice.stats()` | Counters and live counts from every piece, plus `recent`, the last 12 plays and receives with who got the personal parts, for HUDs, tests and debugging. | Settings are per peer, so each player chooses their own look, intensity and comfort. ## Multiplayer The world is always multiplayer, and `play` routes each piece for you. Every preset is made of two kinds of parts: - **World parts** happen at a spot: the visual effect, the squash, a blast shake (one with distance falloff), a blast flash (one with a radius) and a blast's hitstop. For a `world`-scope preset they run here and on every other peer. Each peer works out **its own** shake, flash and freeze from **its own** distance to the spot. A far player sees the blast without being shaken. Only players within roughly the inner third of the shake's range freeze. - **Personal parts** belong to one player's screen: a fixed camera shake, a screen flash and a hitstop. They play for **exactly one player**, never for everyone: | target | who gets the personal parts | |---|---| | nil, or your own avatar | you | | another player's avatar | only that player (it is sent to them) | | a thing (an NPC, a prop) or a point | you, or the attacking player when `opts.from` is another player's avatar | | a thing or a point, for a preset with `personal = "player"` | nobody: these moments only make sense for a player | The presets with `personal = "player"` are `hurt`, `heal`, `death`, `levelUp` and `landingHard`. A healer never sees the healed player's green pulse, and a killer never gets the victim's blackout. A hit (`hitLight`, `hitHeavy`, `hitCritical`) on an NPC lands on the attacker's screen; on another player it lands on theirs. - **Squash on a shared object**: a synced entity owned by another peer is squashed by its owner, who receives the same play, and its scale reaches everyone from there. Peers never write to an entity they don't own. - `scope = "local"` plays here only what belongs on this peer and sends nothing. Use it from code that already runs on every peer (for example, reacting to a synced health field): each peer then gets exactly its own share. - `Juice.stats().recent` shows, for the last few plays and receives, who got the personal parts (`"here"`, `"nobody"` or the recipient avatar's id) and what ran. - **Stopping travels like playing:** `Juice.stop` on a play this peer sent also sends a small stop message, and each peer that received the play stops exactly that one (matched by sender and play id). Stopping by name stops received plays of that name on your own screen only. A peer on a version before 1.1.2 ignores the stop and lets its share finish. ## Guarantees - **No camera drift:** the shake is added after every camera controller has run and removed before they run again. Measured on all nine builtin controllers (orbital follow, third person follow, first person, orbit, chase, side scroller, bird's eye, isometric and RTS): the camera returns to exactly where it would have been (0.000000 m of drift). - **Hitstop never sticks:** it is one owned time-scale hold. The slowest live request wins, and every span is capped (no freeze longer than 0.6 s). It always releases on end, on `stopAll`, on interruption and on reload. - **Cheap and self-cleaning:** particles are pooled instanced draws, capped at 700 live, with the oldest stolen first. Lights come from a pool of 4. Nothing is spawned per particle, and everything drains to zero and idles when quiet. - **Flashes are part of the picture:** they are drawn by one post-process pass over the lit scene, before the UI, so your HUD stays on top and untinted. The pass is switched off whenever no flash is playing. A copy of the module left behind by a hot reload can never switch it back on. - **Never touches the editor:** the shake only moves the gameplay camera in play mode, never the editor's fly-camera. A peer drops plays sent by other peers until its own scene has arrived. ## Pieces (for advanced use) The `juice` module is the front door. The modules under it can be used directly: | module | what it holds | |---|---| | `juiceKit.shake` | Additive camera shake layers (noise, kick, rumble, quake) with distance falloff. | | `juiceKit.hitstop` | Owned, capped time-scale holds. | | `juiceKit.flash` | Full-screen flashes, vignettes and glows, drawn into the rendered picture by one post-process pass under the UI. | | `juiceKit.squash` | Squash-and-stretch springs that always return to the base scale. | | `juiceKit.vfx` | Pooled particle effects: 12 kinds in 4 looks. | | `juiceKit.net` | The `juiceKit.play` message channel. | | `juiceKit.presets` | The data: presets, looks, palettes and effect recipes. | | `juiceKit.util` | Small vector, quaternion and targeting helpers. | Components: **JuiceNet** (optional; listens from scene load and sets the starting look), **JuiceShakeApply** and **JuiceShakeRestore** (attached to the camera automatically). Assets: `juiceParticle.shader`, `juiceFlash.shader` and the `juiceSolid`, `juiceGlow` and `juiceSmoke` materials. ## Tests Run them the standard way, in edit mode: `tools.use("tests", "run", "juiceKit")` (the shell form is `zero tests run juiceKit`). The suite is named `juiceKit`, not `juiceKit.testSuite`. You can also run it directly with `asset.resolve("juiceKit.juiceKit", "testSuite"):run()`. 104 tests cover every public call. They pass on repeated runs, either way, with or without a player or a scene camera: - **Playing:** every target form, and exactly what a play reports. - **Listing:** every filter, the sort order, and the copies `list` and `get` hand out. - **Defining your own presets:** broken specs are refused, defaults are worked out, redefining replaces, and presets build on presets. - **Presets built on presets:** removing or redefining a base keeps its dependents playing the same thing, a chain survives losing its root and then its middle, and loops are refused with the old preset intact. - **Looks:** each look's material and shape, and a look given to one play. - **Intensity:** flash alpha, shake strength, particle count and hitstop length. - **Reduce motion:** no shake, gentler flashes. - **Stopping early:** `stopAll` mid-shake, mid-hitstop, mid-squash, mid-flash and mid-effect. - **Stopping one play:** `Juice.stop` and `Juice.isPlaying` by result, id and name. Tested per piece (one shake, hitstop, flash, squash or effect stopped while another keeps going) and on whole combos, and a stop sent to and received from another peer reaches only that play. - **Multiplayer routing:** another player's flash and hitstop never land on the caller, blasts are scaled by distance, and squash is left to the owner. ## Watch out for - **Play from code every peer runs, or from one peer with the default scope.** By default (`scope = "auto"`) `play` sends the world parts to everyone. If the same call already runs on every peer (for example, a reaction to a synced health value), pass `scope = "local"`, or each peer receives it once per sender. - **Shakes only move the camera in play mode.** In edit mode `Juice.play` still runs the effects, flashes and squashes, but it never touches the editor's fly-camera. - **The flash is a post-process pass.** It tints the scene camera's picture, under your UI. If you want a flash *over* the UI (a menu fade), use a UI screen instead. The pass also tints offscreen captures and render-to-texture cameras taken while a flash plays, and clamps highlights brighter than white for that moment. - **Heavy scenes slow down joiners.** Every entity a scene bakes in is replicated in play, and a joining peer receives them all as one snapshot before its gameplay starts. Keep static scenery light, or spawn it from code each peer runs, so new players get in quickly. - **Reduce motion is per peer.** It is a comfort setting for the player at this screen. Set it from that player's own options, not from shared state. - **Give every joiner a start view of your own.** A player prototype's camera rig is `OwnerOnly`, so a joiner whose player was spawned on another peer receives the body and no camera. The showroom's Gallery shows one way to handle it: it gives that player a local follow camera, and works out the starting heading from the spawn and the stage rather than from the body. - **Testing with the standard runner.** `tests.run` runs a suite in edit mode with no avatar, an empty scene and fallback lighting, and in edit mode the camera on screen is the editor's. The kit's "where am I" (`U.herePos`) falls back from the avatar to the gameplay camera, then to the camera on screen, then to the world origin, so the suite passes either way. The runner takes the suite's asset name: `juiceKit`, not `juiceKit.testSuite`. - **A second player needs a second client.** Two agent sessions in one engine (`play as <name>`) are one peer, so a real two-player check needs another desktop session or the web, ideally signed in to another account (see #14448). - **Small API traps.** `entity.exists` raises when given a live entity's name, so pass an id. `_G` is sealed. A local named after an engine namespace (`live`, `av`) hides that namespace. ## Known issues These are engine problems met while building the kit or the showroom, each with its engine issue number. The kit or the showroom works around each one where it can; they are listed so a creator who meets one knows what it is. - **A one-shot particle burst `.effect` fails to build** (#19206). The kit draws its effects with its own pooled particles instead, so nothing in the kit depends on it. - **A test clean-up hook registered outside a group is dropped** (#12497). A top-level `Test.afterEach` never runs, so each `describe` in the kit's suite installs its own clean-up. - **A follow camera binding to a body whose look has not loaded starts in front of it** (#19313). The orbital follow camera takes its heading from the body's facing when it binds. A body that has not loaded yet reports the default facing, so the camera lands in front of the player looking away. The showroom sets the heading itself for the first moments after a player appears. - **Harmless `asset-unresolved` warnings** (#12937). The code checker reports them for `~.JuiceShakeApply`, `~.JuiceShakeRestore`, `~.juiceSolid`, `~.juiceGlow`, `~.juiceSmoke` and `~.juiceFlash`; they all resolve when running. - **The two guides inside the package don't show up in a ZeroMind library search yet** (#22181, ZeroMind#3099). Once juiceKit is installed they open with the `guides` tool and `zero guides read` (see [Guides](#guides)), and the engine's own guide search finds them. - **`man` does not find a guide that ships inside a package** (#22192). `man` with the guide's name or path says there is no manual entry, although `zero guides list` lists both guides. Use the `guides` tool or `zero guides read <path>`. - **ZeroMind's description of the package can lag a release behind** (#19258). For a while after a release, the package's page on ZeroMind shows the previous version's README as its description. The package itself, this README and `package.yaml` are current. - **1.2.3 was not checked in a web browser** (#20946: an agent's engine cannot start a web engine of its own). The kit uses only cross-platform engine calls, and 1.2.2 was checked live in a browser tab.

# 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.

# juice The juiceKit front door: `require("juiceKit.juice")`. `play(name, target, opts)` resolves a preset into its pieces, applies the global intensity, the look and reduce motion, routes each piece by scope (player pieces stay with their player, world pieces go to every peer through `net`), and returns what ran. It also holds the preset registry (`list`, `names`, `get`, `has`, `define`, `remove`), the settings (look, intensity, reduce motion), `stopAll`, `stats` and `_receive`, the handler other peers' messages arrive at. Gameplay code and the gallery call it; the package README documents every call.

# 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.