Candy Logo Copyright © 2025-2026 Candy Arts
Game State
Many games record what the player is doing in a game state: exploring, fighting, browsing the inventory, in a cutscene... The state decides what the player's inputs do, whether enemies move, whether the pause menu can open. While a dialogue runs, your game usually needs a dialogue state of its own: the player shouldn't walk away mid-conversation, and the key that advances the dialogue shouldn't also swing a sword. The change_game_state() hook function switches your game into that state when a dialogue starts, and back when it ends. Candy Dialogue Engine doesn't read the game state itself: the function only serves your game, and nothing written in it can break the dialogue. The Hook Function change_game_state() is in Change_Game_State.gd, in User_Data/Functions. It's a 'safe' file: updates never overwrite it. The Engine calls it twice per dialogue:
Whencandy_args["method"]
When a dialogue starts, before anything is displayed."start"
When a dialogue ends, before the UI is cleared."end"
candy_args["caller"] is the Engine running the dialogue. custom_data is always empty, since the call comes from no line. See UI Elements for how hook functions work, including your own user_args. A dialogue that ends because it was interrupted calls the function too (see Interrupting Dialogues). A dialogue that moves to another Conversation with a Jump doesn't: it hasn't ended. Setup The function ships as a template, turned off. It shows a common approach: store the current state when the dialogue starts, switch to a dialogue state, then restore the stored state when the dialogue ends.
  1. Set use_game_state to true.
  2. Replace the placeholder variables game_state and previous_state with your game's own (for example, Global.game_state).
  3. Set dialogue_state_value to the value your game uses for the dialogue state.
  4. If your game manages its state differently (a state machine, signals, paused nodes...), rewrite the function accordingly.
func change_game_state(candy_args: Dictionary, user_args: Array, custom_data: Array): var engine = candy_args["caller"] if engine.engine_mode != "UI": return if candy_args["method"] == "start": Global.previous_state = Global.game_state Global.game_state = "dialogue" else: Global.game_state = Global.previous_state
Ending in another state Some dialogues shouldn't return to the state they started from, such as a conversation that ends with a fight. Modify the stored state before the dialogue ends (with a Set or Call command, for example), or write the decision into the "end" branch of the function. Several Engines Every Engine calls change_game_state(), including Engines that only run NPC barks or background chatter, which usually shouldn't take control away from the player. The template only reacts to Engines whose engine_mode (in the Inspector, under Identity) is "UI", the value of the main dialogue UI (Candy_UI.tscn). Assign the same value to the other Engines that should switch the game state, and a different one to those that shouldn't. When two Engines that switch the game state can run at the same time, prevent the second one to start from storing the dialogue state as the state to return to. Related
  • The Engine's mouse_mode_start and mouse_mode_end settings change the mouse mode when a dialogue starts and ends.
  • The x_dialogue_end() hook function and the Engine's dialogue_fully_ended signal notify your game once the dialogue has completely ended (see Ending Dialogues).