Candy Logo Copyright © 2025-2026 Candy Arts
Security Risks
A Dialogue file is a program: it can do anything your game's own code can do. The Dialogues you write and ship with your game are as safe as any of your scripts. The risk arises with mods: once your game runs Dialogues made by players, it runs arbitrary code. This is not specific to Candy Dialogue Engine. Most moddable games carry the same risks: a mod that can change how a game behaves can usually do harm too, and players are generally expected to install only mods they trust or to accept the risks. Warn your players about what a Dialogue mod can do, listed below: What Dialogues Can Do Call any function The Call command, and any CandyRef expression, can call any function your game can reach: your autoloads, the Engine's nodes, and Godot's own singletons. That includes OS.execute(), which runs a program on the player's computer, and OS.shell_open(), which opens a file or a web page. Expressions are accepted almost everywhere: in nearly every key of every Command, and inside the text of a Spoken Line, between ¤ symbols. A line that only seems to display text can run code. Read and change any variable The Set command can write to any variable in your game: the player's progress, locked content, the game's options, even Godot native properties. Write files The Export command writes a file wherever its Path points, including absolute paths outside the game's folders. A Set writing into a file_var() creates or overwrites that file, in any format file_var() supports. Load scenes and resources that contain scripts Commands that load a file accept a res:// path, and most also accept a user:// path: BG_Scene, VN_Scene, CS_Scene, Input, the scenes of Choice_List and media files. A path of any other form is read as a file name inside the Command's folder. file_var() accepts an absolute path as well, including when it reads a .tres or .res file. A Godot scene or resource (.tscn, .scn, .tres, .res) can contain a script, which runs when it is loaded or instanced. A mod that ships such a file next to its Dialogue ships code. Images, audio and video files (.png, .ogg, .ogv...) don't carry scripts. Leave code behind A value that starts with ¢ is evaluated whenever an expression reads it (see 'Expressions Inside Values' in CandyRef Expressions). A Dialogue can store such a value in a variable, a save or a file, so that it runs later, when another Dialogue, even one of yours, reads it. Removing a mod doesn't remove what it stored. Sources of Risk Mods and player-made Dialogues Running a mod's Dialogues is running the mod's code, as with any game whose mods are programs. Players are often accustomed to that risk with code mods, but a Dialogue mod looks like a text file, like a translation, and players may not expect it to run code. Shared files Anything a Dialogue reads can carry an expression: a save file your game reads back with Import or file_var(), a file of variables, a data file downloaded from a server. A save file shared between players carries the same risks as a mod. The network Never design your game to run Dialogues, or read values from Dialogues, that your game receives from other players or from a server it doesn't control. Anyone who can send such a Dialogue through a network can run code on another player's computer. Reducing Risks Candy Dialogue Engine has no option to restrict what a Dialogue can do: every Dialogue it runs has the full power described above. What reduces the risk:
  • Warn players. State in your game, and wherever mods are shared, that mods can run code, and that players should only install mods they trust. A message when the game detects a new mod, before running it, is where the warning belongs.
  • Leave the choice to players. Only run mods that players placed in the game's mod folder themselves, and allow them to enable and disable each mod. Don't design your game to download and run any third-party Dialogues automatically.
  • Review what you host. If you host mods yourself, a Dialogue file is plain text, so its expressions can be read: search it for ¢, and examine calls to OS, load(), file_var(), and Export commands. A determined author can hide what an expression does, for example by building it from pieces at runtime, so a review catches careless or obvious cases, not every one.
  • Treat shared saves like mods. If players can share save files, the same warnings apply to them.
  • Sanitize values from outside. A value your game reads from a shared save or a server, and stores for its Dialogues, is evaluated if it starts with ¢. Sanitize it before storing it: CandySanitizer.expressions() neutralizes its leading ¢, so it's read as text (see Sanitization). This protects values only: a Dialogue file a mod ships still runs its own expressions.