Candy Logo Copyright © 2025-2026 Candy Arts
Effects
In this tutorial, you will learn to play an effect with the Effect_Play command: a fade to black, and a fade back from it. A new scene shows the passing of a night: John says good night, the screen fades to black for a few seconds, and fades back on the next morning, when the construction worker returns. The scene also uses three other commands: UI_Z, which changes the drawing order of the dialogue box, UI_Clear, which clears it, and Wait, which pauses the Dialogue. Before You Start This tutorial uses the Actors and portraits of the Beginner tutorials: Alice, John and the construction worker. Write its scene in the Dialogue of your choice: the Dialogue of the Beginner tutorials, or a new one (File > New Dialogue). The Fade Animations Effects are animations, played by effect players. The dialogue UI provided with Candy Dialogue Engine contains one, named Effect: the EffectPlayer node of the dialogue UI scene, an AnimationPlayer. Two of its animations change the color of ScreenEffects, a ColorRect that covers the screen: • "Fade Black 1" turns it from transparent to black, in one second. • "Unfade Black 1" turns it from black to transparent, in one second. Both are already in the scene: no file needs to be added to your project. 1. Writing the Scene 1. Add a Conversation named "Night", as in the Conversations tutorial. 2. In its Block_1, add three Spoken Lines, then an End command after the last one:
SpeakerPortraitText
John(empty)Good night, Alice. See you tomorrow.
construction_worker(empty)Good morning, folks. Ready for another day of work?
John(empty)Not again.
The effect and the other commands go between John's first Line and the construction worker's Line. 2. Placing the Dialogue Box Behind the Black Nodes with a higher z index are drawn in front of the others. The ColorRect's z index is 80, and the dialogue box's is 100: without a change, the dialogue box would remain visible on the black screen. A UI_Z command lowers the dialogue box's z index, so that the black covers it. 1. Select John's Line "Good night, Alice. See you tomorrow." 2. Open the UI tab of the Buttons panel, and click UI Z. The UI_Z command is added after John's Line, and its form is displayed. 3. In the Field Tree, click + Node. Node 1 is added to the command, and selected. 4. Click the v button of the name field, at the top of Node 1's fields, and select Dialogue box in the UI Elements submenu. The field displays "dialogue_box_path", the name that designates the dialogue box. 5. In the Z Index field, write "-1", or click the field's v button and select Behind Relative To. The Relative To field is displayed below it. 6. In the Relative To field, write "UI_Layer/MediaPlayers/ScreenEffects", the path of the ColorRect in the dialogue UI scene.
Tutorial Effects UI Z
How UI_Z Works A UI_Z command sets the z index of each node it lists. A Z Index of "-1" places the node one step behind the node of the Relative To field: the dialogue box receives a z index of 79, and the ColorRect is drawn in front of it. A Z Index written without a sign, such as "79", sets the z index exactly. 3. Fading to Black 1. Select the UI_Z command. 2. Open the Effect tab of the Buttons panel, and click Effect Play. The Effect_Play command is added after the UI_Z command. 3. In the Field Tree, click + Player. 4. In the name field, replace "Player_1" with "Effect", or click the field's v button and select Effect in the list. 5. In the Animation field, write "Fade Black 1", with its spaces and capital letters. 6. In the Wait Loops field, write "1", or click the field's v button and select Until one loop ends.
Tutorial Effects Fade
Leave the other fields at their default value. The empty Library field plays the animations already in the effect player. How Effect_Play Works An Effect_Play command plays an animation on each effect player it lists. • Wait Loops makes the Dialogue wait until the animation has played that many times. With "1", the Dialogue waits one second, until the screen is black. The wait is set on the command that starts the playback. • Stop Frame "0" keeps the pose the animation ends on: the screen remains black after the animation has finished. 4. Clearing the Box and Waiting 1. Select the Effect_Play command. 2. Open the UI tab of the Buttons panel, and click UI Clear. Leave its fields at their default value. 3. Click Wait. The Wait command is added after the UI_Clear command. 4. In the Wait Time field, write "3".
Tutorial Effects Clear Wait
How UI_Clear and Wait Work The UI_Clear command empties the dialogue box, its name and its portrait, and hides it, so that John's Line isn't displayed again when the screen brightens. It also restores the dialogue box's z index to 100: the next Line is displayed in front of the ColorRect. The Wait command pauses the Dialogue for its Wait Time, in seconds: the screen remains black for three seconds. 5. Fading Back 1. Select the Wait command. 2. Add an Effect_Play command as in section 3, with the player Effect and the animation "Unfade Black 1". Leave its Wait Loops field at 0. With a Wait Loops of 0, the Dialogue doesn't wait for the animation: the construction worker's Line is displayed at once, in front of the black, while the screen brightens behind it. The Lines of Block_1 are now, in order: John's Line, UI_Z, Effect_Play (Fade Black 1), UI_Clear, Wait, Effect_Play (Unfade Black 1), the construction worker's Line, John's Line and End. 6. Testing the Scene 1. Right-click Night in the Dialogue Navigator, and select Test Here. 2. After John's Line, press the key assigned to Dialogue_Advance. The screen and the dialogue box darken together, for one second, and the screen remains black for three seconds. The construction worker's Line is then displayed while the screen brightens. The testing scene has no background of its own: the fade darkens its plain gray. If the Test Fails • The dialogue box remains visible on the black screen: check the UI_Z command: its node must be dialogue_box_path, its Z Index "-1", and its Relative To "UI_Layer/MediaPlayers/ScreenEffects", written exactly so. • The screen doesn't darken: check that the player of the first Effect_Play command is named Effect, and that its Animation is "Fade Black 1", with the same spaces and capital letters. • The dialogue box disappears as soon as the fade starts: check that the Wait Loops of the first Effect_Play command is "1", and that the UI_Clear command comes after it. • The screen remains black: check that the Animation of the second Effect_Play command is "Unfade Black 1". A night now passes between two Lines of the Dialogue: the screen fades to black, and the next morning begins as the scene reappears.