Copyright © 2025-2026 Candy ArtsModding
Candy Dialogue Engine can be used to make games moddable through player-created Dialogues.
This can be done even if your game does not use Candy Dialogue Engine for its actual dialogues and cutscenes.
General Principle
Dialogues can be used as a Turing-complete programming layer:
- They can call any functions in the game code, including Godot natives → Call command.
- They can emit and wait any signals → Emit and Await commands.
- They can read and modify any variables → Set command.
- They can declare new variables → Export/Import commands.
- They can use conditions and loops → If/Elif/Else + For/While commands.
- They can access files from the res:// and user:// folders (various commands).
In addition to the above, CandyRef expressions are also capable of calling functions and methods.
This makes Dialogues incredibly powerful: beyond their use as actual game dialogues, they can be used as runtime programs within a game, capable of modifying the entire game state.
It also makes them as risky as any other code mod. A Dialogue can run programs on the player's computer, overwrite files and change saves. Read Security Risks before you let players install Dialogue/Mods.
Implementation
All your game needs to do is load and run user-made Dialogues TXT files.
There are various ways you could do that, but here is a basic idea:
Mod Folders
First, decide on user:// folders where users will place their Dialogue/Mods.
You may want to provide multiple folders depending on when/how a Dialogue/Mod should be loaded and run by the game.
You should also design your code so that each Dialogue/Mod is placed inside its own sub-folder, along with custom resource files a Dialogue/Mod may use (e.g. custom portraits or sprites).
Running Mods
Your game should probably offer to load and run Dialogue/Mods at the following points:
- Immediately at startup (or at least upon reaching the main menu).
- Once players start a new game or load a saved game.
- From a menu, where players can manually run any Dialogue/Mods at any time.
Your game code just needs to be designed the following way:
1. Scan the mod folders.
2. For each mod, create an Engine instance, load the Dialogue/Mod and run it.
3. For mods intended to be run manually by players, make your code list them in a menu, with a button to run each mod.
That's a basic implementation, and the rest is up to the modders: since Dialogues can touch anything in your game, they should be able to design their Dialogue/Mods to do anything they want.
Limitations
Candy Dialogue Engine is a programming layer stacked on top of GDScript, so Dialogues are not as efficient as direct code.
As an example, a Set command, which modifies a variable, is made of many lines of code. During normal Dialogue, this is not noticeable: a Set command resolves instantly.