Copyright © 2025-2026 Candy ArtsBG Effect Stop
The BG_Effect_Stop command stops one or more background effects. By default it plays the RESET animation, which restores the properties the effect changed; with a Stop_Frame, it retains the pose of a frame instead.
Keys
Every key also accepts a ¢ expression instead of a fixed value, unless its description says otherwise. See CandyRef Expressions.
Layers
Description:
The layers of the Background Scene to act on. Each key is a layer's name, and its value is a Dictionary of settings for that layer (see below), or an empty Dictionary for none. Every layer must be listed by name; there is no shorthand for all layers. An entry that can't be found is reported and skipped, without affecting the others.
Values:
• Layer name: The name of a layer node in the Background Scene's bg_container, such as Sky.
• ¢ expression: Can also return the layer node itself.
Layer Settings
Each layer in Layers lists its effects under the following key.
Effects
Description:
The effects to act on for this layer. Each key is the name of the animation the effect plays, and its value is a Dictionary of settings for that effect (see below), or an empty Dictionary for none.
Values:
• Animation name: An animation of the AnimationLibrary set in Library, such as Shake.
• Library/Name: When Library is empty, an animation already available on one of the layer's AnimationPlayers.
Effect Settings
Each effect in Effects accepts the following keys.
Stop_Frame
Description:
The frame the animation stops on.
Values:
• Clear or X (case-insensitive): Play the RESET animation of the current animation's library, or the player's own RESET animation, if one exists, then stop.
• 0: Retain the pose of the current frame.
• -1: Retain the pose of the last frame.
• Positive number: Retain the pose of that frame, counted from 1. An animation's frames are its keyframes.
• Empty: Clear.
Loops
Description:
Stops the playback once it has played this many loops, counted from its start, rather than at once. It replaces the Loops and Duration of the Line that started the playback, and the playback then stops on this Line's Stop_Frame. The Dialogue doesn't wait for it. A point that has already passed stops the playback at once, where it is; so does media that isn't playing (held by a Loops of 0, finished or already stopped).
Values:
• Empty or null: No loops: stop at once, unless Duration is set.
• 0 or a positive number: The number of loops, counted from the start of the playback.
Duration
Description:
The time the playback continues after those loops before it stops, counted on playback as the Duration of a Play command is: paused time doesn't count. With an empty Loops, it counts from the start of the playback.
Values:
• Number of seconds: Such as 2.5.
• Timestamp: In the format SS.xx, MM:SS.xx or HH:MM:SS.xx, such as 01:30.5.
• f=N: N frames, counted on the animation's keyframes, otherwise at FPS.
• 0, null or empty: No duration: Loops alone decides.
FPS
Description:
The frame rate used to convert a Stop_Frame number into a position, and that an f= Duration counts with, in animations that have no frames of their own.
Values:
• Frames per second: Such as 12.
• Empty: The default frame rate, default_effect_fps.
Library
Description:
Needed only when two effects on one layer have the same name. When empty, the effect's name matches the layer's effect of that name, whichever library it belongs to.
Values:
• Library name: The library containing the effect's animation.
• Empty: The layer's effect with that name.
Take_Hold
Description:
Whether this command takes hold of the background scene, if it is Public. While an Engine holds it, its Public Mode determines what other Engines can do with it: nothing (Exclusive), only the commands it lists (Semi-Exclusive), or anything (Free). The hold applies to the whole scene, and lasts until the holding Engine's Dialogue ends. Setting Take_Hold on any effect of the Line applies it to the whole scene.
Values:
• Empty: The background scene decides, from its own list of commands that take hold.
• 1: Take hold, even if the background scene doesn't list this command.
• -1: Never take hold.