Copyright © 2025-2026 Candy ArtsBG Pause
The BG_Pause command pauses the playback of one or more background layers, either until a BG_Resume or for a set number of Lines. Instead of freezing, the playback can repeat a segment of itself until it resumes: a pause loop. Video layers can also play their pause loop at another volume.
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 accepts the following keys.
Lines
Description:
The number of Lines after which the pause ends automatically, counted by the Engine that issued the pause. While a Lines count is active, waits on the entry don't delay the Dialogue, since the Lines couldn't advance during the wait.
Values:
• Positive number: Resume after that many Lines.
• 0 or -1: Remain paused until a BG_Resume.
All
Description:
Which Lines count toward Lines.
Values:
• 0: Only the Spoken_Lines that are displayed.
• 1: Every Line, whatever its command.
Pause_Loop_Start
Description:
A paused entry can repeat a segment of itself until it resumes, instead of freezing: a pause loop. This key sets where the segment starts. When both Pause_Loop_Start and Pause_Loop_End are empty, the entry pauses without a loop. When the pause point is inside the segment, the playback continues to the segment's end before the first repeat; otherwise, it jumps to the segment's start. While the segment loops, the entry still counts as paused for waits, Lines counts and Dialogue suspension.
Values:
• Number of seconds or timestamp: An absolute position in the media, such as 4.5 or 00:04.5.
• +N / -N: N seconds after or before the pause point, such as +2 or -00:01.5.
• f=N: Frame N, counted at FPS when the media has no frames of its own.
• f+N / f-N: N frames after or before the frame displayed at the pause point, counted at FPS when the media has no frames of its own.
• Empty or null: The pause point.
Pause_Loop_End
Description:
Where the pause loop's segment ends (see Pause_Loop_Start). A segment that ends before it starts is reported, and the entry pauses without looping.
Values:
• Number of seconds or timestamp: An absolute position in the media, such as 4.5 or 00:04.5.
• +N / -N: N seconds after or before the pause point, such as +2 or -00:01.5.
• f=N: Frame N, counted at FPS when the media has no frames of its own.
• f+N / f-N: N frames after or before the frame displayed at the pause point, counted at FPS when the media has no frames of its own.
• Empty or null: The pause point.
Pause_Loop_Resume
Description:
How the entry resumes after its pause loop. The value is case-insensitive. A BG_Resume can override it; when a Lines count runs out, this value is used.
Values:
• Return: Resume immediately, from the pause point.
• Continue: Resume immediately, from the loop's current position.
• Finish_Return: Resume once the loop reaches its end, from the pause point.
• Finish_Continue: Resume once the loop reaches its end, continuing from there.
• Empty or null: Return.
Pause_Volume
Description:
The volume the pause loop plays at. Video layers only.
Values:
• Number: A volume in dB, such as -12 (-80 is silent).
• +=N / -=N: Raise or lower the current volume by N dB, such as -=12.
• null: Leave the volume unchanged.
Pause_Volume_Time
Description:
The duration of the fade to Pause_Volume.
Values:
• Number of seconds: Fade over that duration.
• 0: Change the volume instantly.
• !N: Fade over N seconds, and hold the Dialogue until the fade completes, such as !2.
Resume_Volume_Time
Description:
The duration of the fade back to the volume from before the pause, once playback resumes. With a Finish_ resume mode, the fade starts when the loop reaches its end. Video layers only.
Values:
• Number of seconds: Fade over that duration.
• 0: Change the volume instantly.
• !N: Fade over N seconds. When playback resumes immediately, the BG_Resume waits for the fade to complete.
FPS
Description:
The frame rate used to count f= values, for media without a frame rate of its own. SpriteFrames animations count their own frames.
Values:
• Frames per second: Such as 12.
• Empty: The media's own frame rate, otherwise the default frame rate.
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 layer 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.