FolioTier 2
@zoom
Zoom the whole frame, the backdrop, or a single sprite to an absolute scale, pivoting on a chosen focal point.
@zoom scales the visible scene to an absolute multiplier, pulling the camera in or pushing it back. Use it to punctuate a dramatic beat, draw the eye to a prop or character, or simulate a lens push without swapping backgrounds.
Without a target, the effect moves the whole frame at once for a cinematic feel. Pass a sprite tag and only that character or object scales while everything else holds still.
Because the scale value is absolute, a second @zoom call does not stack on top of the first - it sets the new scale outright. To return to normal after a push, call @zoom again with a scale of 1.
The focus point controls which part of the frame stays anchored as the image grows. The center default works for most compositions, but shift focus_x and focus_y toward your subject when they sit off-center.
Setting wait to false lets the zoom run while dialogue continues, so the push can still be settling as the first line reads. Setting wait to true holds the scene until the effect completes, which suits moments where the visual needs to land before the next beat.
Parameters
| Parameter | Kind | Required | Default | Notes |
|---|---|---|---|---|
| scale | number | no | 1.2 | 0.5-3 × multiplier. Default 1.2. |
| duration | number | no | 1 | 0-30 seconds. Default 1. |
| target | string | no | "" | Optional sprite tag; empty targets the whole frame. |
| focus_x | number | no | 0.5 | 0-1 (0-1). Default 0.5. |
| focus_y | number | no | 0.5 | 0-1 (0-1). Default 0.5. |
| wait | boolean | no | false | Block for the effect's duration when true; false fires and continues so effects can overlap. |
Canonical example
bg city-rooftop
@zoom(1.3, duration=1.5)
say "Liam": "Closer."@zoom tweens the camera scale to scale over duration. The zoom
pivots on focus_x / focus_y, which default to the stage middle
(0.5, 0.5). Move them to zoom into a corner, or compose with
@pan for a separate offset.
Absolute, not relative
Calling @zoom(1.5) from 1.0 zooms in; calling it again
from 1.5 is a no-op. To zoom progressively, fire a chain of
absolute values:
@zoom(1.2, duration=1)
@zoom(1.5, duration=1)
@zoom(1, duration=0.8)
Camera vs stage shake
@zoom affects only the in-world layers (backdrop + sprites).
Overlays and stage-frame shake stay unaffected - so @shake during
a zoom-in still jolts the whole frame, not just the zoomed image.
Persistence across scenes
Camera zoom persists until explicitly reset. Fire @zoom(1, duration=0) to snap back to no-zoom.
Notes
@zoom runs on the Pixi stage.