Log inGet started
World

Tumblestep: The Endless Stair

Branchmain
Branchesmain
Commit7c31e3f635

README.md

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.13 (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).
  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.
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.13

  • Shake: the camera applier is looked up by the same reference it is added under, so a world holding two copies of juiceKit no longer re-adds it (and logs an error) on every shake.

What's new in 1.2.12

  • The cartoon look's glow is a glow again. The cartoon look drew every particle with its solid, lit material, the glow puff included, so coinPickup (and every preset with a glow layer) flashed an opaque pale ball about 1.5 m across; a coin or pickup taken right in front of the camera filled the view with it. The cartoon look now draws its glow role with the additive glow material; sparks, rings, debris and confetti stay solid and toon-like. The realistic, pixel and scifi looks are unchanged.

What's new in 1.2.10

Text only. Long dashes in the README and in a code comment are now plain punctuation; every call, option, preset and network message works as in 1.2.9.

What's new in 1.2.9

  • Effects draw in a world where nothing else draws a sphere or a cube. The particle pools draw the built-in sphere and cube; a mesh's GPU buffers exist only while something draws it, so in a fresh world (or any scene with no sphere in it) every effect threw mesh … is not registered as a GPU mesh instead of playing. The vfx module now brings the mesh onto the GPU (renderer.mesh.loadCpu, then renderer.mesh.create) before it makes a draw.

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).
  • 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. 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:

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.

namekindstrengthscopepieceswhat it is
coinPickupcombolightworldsquash + vfxA coin sparkle and pulse.
deathcomboheavyworldshake + hitstop + flash + squash + vfxA death: crushed flat, smoke, a slow-motion freeze, and a dark fade for the player who died.
explosionLargecomboheavyworldshake + hitstop + flash + squash + vfxA big blast: fireball, debris, a dust ring, a flash and a shake everyone feels by distance.
explosionSmallcombomediumworldshake + squash + vfxA small blast: fireball, smoke and a distance-scaled shake.
healcombolightworldflash + squash + vfxHealing: rising green motes and a soft green pulse for the healed player.
hitCriticalcomboheavyworldshake + hitstop + flash + squash + vfxA critical: a long freeze into slow motion, a hot flash, a kick away from the attacker and zap sparks.
hitHeavycombomediumworldshake + hitstop + flash + squash + vfxA heavy hit: bigger sparks, a freeze, a strong shake and a flash.
hitLightcombolightworldshake + hitstop + squash + vfxA light hit: sparks, a tiny freeze, a small shake and a wobble.
hurtcombomediumplayershake + hitstop + flashTaking damage: a red vignette, a kick away from the attacker and a tiny freeze.
landingHardcombomediumworldshake + squash + vfxA hard landing: a dust ring, a landing squash and a short heavy shake.
levelUpcomboheavyworldshake + flash + squash + vfxLevel up: a golden column, a ring, confetti, a golden glow and a stretch.
spawncombolightworldsquash + vfxSomething appears: a pop-in with a magic burst.
shakeEarthquakeshakeheavyworldshakeA rolling earthquake that swells, peaks and fades over four seconds for everyone nearby.
shakeExplosionshakeheavyworldshakeA blast shake that every player feels, weaker the farther they are from it.
shakeHeavyshakeheavyplayershakeA strong jolt for big hits and slams.
shakeKickshakemediumplayershakeA directional kick that pushes the view away from where the hit came from (pass from or direction).
shakeLightshakelightplayershakeA quick, small jitter for light hits and footfalls.
shakeRecoilshakelightplayershakeA weapon recoil: the view snaps back and up, then settles.
shakeRumbleshakemediumplayershakeA long, low rumble for engines, collapsing rock or a boss approaching.
hitstopCriticalhitstopheavyplayerhitstopA 180 ms freeze that eases out through slow motion, for critical hits and finishers.
hitstopHeavyhitstopmediumplayerhitstopA 120 ms freeze for heavy blows.
hitstopLighthitstoplightplayerhitstopA 50 ms freeze that lands a light hit.
hitstopSlowmohitstopmediumplayerhitstopHalf a second of 25% slow motion with no freeze, for near misses and dramatic moments.
flashBlackoutflashheavyplayerflashA fade to black and back, for death, respawn or a scene cut.
flashCriticalflashheavyplayerflashA blinding white-orange burst with hot edges.
flashDamageflashmediumplayerflashA red vignette that closes in from the screen edges when you take damage.
flashExplosionflashmediumworldflashA bright blast flash every player near the explosion sees.
flashFreezeflashlightplayerflashAn icy blue vignette for frozen, chilled or shielded.
flashHealflashlightplayerflashA soft green pulse from the edges.
flashHitflashlightplayerflashA sharp white flash across the screen.
flashLevelUpflashmediumplayerflashA warm golden glow that blooms and fades.
flashPoisonflashlightplayerflashA sickly purple-green vignette for poison and curses.
flattensquashheavyworldsquashCrushed flat, held, then springs back up, for deaths and stomps.
jellyWobblesquashlightworldsquashA jelly wobble when something is hit.
popInsquashmediumworldsquashGrows from nothing with an overshoot, for spawns and pickups appearing.
pulsesquashlightworldsquashA quick uniform bump for collect, select or a heartbeat.
punchsquashheavyworldsquashA hard punch inward that rings out, for heavy impacts.
squashLandsquashmediumworldsquashFlattens on landing and springs back.
stretchJumpsquashmediumworldsquashStretches tall on take-off and settles.
vfxCoinvfxlightworldvfxA coin sparkle.
vfxConfettivfxmediumworldvfxA confetti burst.
vfxDustvfxlightworldvfxA dust puff.
vfxExplosionLargevfxheavyworldvfxA large explosion: fireball, debris and a smoke ring.
vfxExplosionSmallvfxmediumworldvfxA small explosion.
vfxFirevfxmediumworldvfxA burst of fire.
vfxHealvfxmediumworldvfxRising healing motes.
vfxLevelUpvfxmediumworldvfxA level-up column and ring.
vfxMagicvfxmediumworldvfxA magic burst.
vfxSmokevfxmediumworldvfxA smoke cloud.
vfxSparksvfxlightworldvfxImpact sparks.
vfxZapvfxmediumworldvfxAn 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:
optionmeaning
intensityMultiplier for this call (multiplied by the global intensity).
lookDraws this call's effect in a look other than the current one.
fromThe 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.
directionWorld direction the hit travels, used instead of from.
scaleEffect size multiplier.
axisSquash 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.
seedSeed 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.

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:

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

callwhat 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:
targetwho gets the personal parts
nil, or your own avataryou
another player's avataronly that player (it is sent to them)
a thing (an NPC, a prop) or a pointyou, 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:

modulewhat it holds
juiceKit.shakeAdditive camera shake layers (noise, kick, rumble, quake) with distance falloff.
juiceKit.hitstopOwned, capped time-scale holds.
juiceKit.flashFull-screen flashes, vignettes and glows, drawn into the rendered picture by one post-process pass under the UI.
juiceKit.squashSquash-and-stretch springs that always return to the base scale.
juiceKit.vfxPooled particle effects: 12 kinds in 4 looks.
juiceKit.netThe juiceKit.play message channel.
juiceKit.presetsThe data: presets, looks, palettes and effect recipes.
juiceKit.utilSmall 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), 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.