Studio

FolioTier 2

@sprite-opacity

Tween a sprite's opacity by slug. Standalone, or what `sprite show`/`sprite hide ... with fade` lowers to.

@sprite-opacity smoothly animates a sprite's transparency over time, letting you dim or reveal a character without a hard visibility snap. Reach for it when you need an intermediate opacity - dimming a character to signal distraction or detachment, or landing a sprite at partial opacity to suggest memory, dream, or distance.

When sprite show or sprite hide plays a fade transition, it is @sprite-opacity working behind the scenes. Use @sprite-opacity directly when you need opacity that stops short of full visibility or full darkness, or when you want to animate transparency independently from a character entering or leaving the scene.

The wait parameter matters most when layering effects. Set wait to false and the tween fires while the script advances, so you can start a fade on one sprite and immediately queue an effect on another. Set wait to true and the script holds until the tween finishes, which is the right call when a character must visibly dim before the next dialogue line appears.

A sprite at zero opacity is still present in the scene and holds its position on stage - invisible, but not removed. If you need to clear the sprite entirely, use sprite hide after the tween rather than treating a zero-opacity sprite as a substitute for a hidden one.

Parameters

ParameterKindRequiredDefaultNotes
targetstringyes""Sprite tag to target.
tonumberno10-1 (0-1). Default 1.
durationnumberno0.40.05-3 seconds. Default 0.4.
waitbooleannotrueBlock for the effect's duration when true; false fires and continues so effects can overlap.

Canonical example

sprite show ada
say "Ada": "Don't look at me like that."
@sprite-opacity(0.4, target=ada, to=0.4)

@sprite-opacity targets a sprite by its slug - the name the sprite has in the project's Sprite Manager (the same token the sprite verb uses). The effect tweens the sprite's opacity from its current value to to over duration seconds, then resolves so the script can advance.

Two ways to fire it

Mid-scene, standalone. When the sprite is already on stage and you want to fade it down or back up during the scene, fire @sprite-opacity on its own line with an explicit target:

sprite show ada
say "Ada": "I need a moment."
@sprite-opacity(0.5, target=ada, to=0.3)

On the sprite verb, as the with fade tail. When the sprite is being revealed, removed, or re-posed, write the fade as the sprite verb's transition tail - the codec lowers with fade on a show / hide to this tween and fills in target from the verb's slug:

sprite show ada with fade
say "Ada": "..."
sprite set ada frame worried with fade(0.8)
sprite hide ada with fade

The tail is the Sprite Action card's one Transition field, not a Show or Hide property, so a sprite set frame change takes it as well - there it reads as a crossfade between the two frames and stays on the set step rather than lowering to this standalone tween (an opacity tween on one sprite cannot show two textures at once). Direction is derived from stage state at playback, never authored.

Only the with fade form fires as the sprite mounts or unmounts. The standalone form requires a sprite already on stage; if target doesn't match anything, the effect is a silent no-op and the script advances at duration.

Notes

@sprite-opacity runs on the Pixi stage.

When two @sprite-opacity calls hit the same sprite in quick succession, the second pre-empts the first via GSAP's per-property tween management.

See also