Copyright © 2025-2026 Candy ArtsText Input
The Input scene provided with Candy Dialogue Engine, Default.tscn in Scenes/Input_Menus, is a text input menu.
It features a LineEdit node for the player to type text, RichTextLabels to display a title, instructions and warnings or information, and a confirm and a cancel button.
It has the Input_Text.gd script attached, which contains logic for the input menu:
• It can check the text written by the player for errors or forbidden words or characters, then display warnings and refuse invalid inputs.
• When an input is accepted, it can store it in a variable so your code or the Dialogue can later use it.
• It can let the player cancel and close the menu without accepting input, or refuse cancelling if it's mandatory that the player enters input.
• It implements various safeguards to ensure the input text won't conflict with Candy Dialogue Engine syntax symbols.
• It can emit the input_received signal, with specific arguments, to let the Engine know what to do when input is confirmed or cancelled.
Note that the above is configurable: either by modifying the code directly, or through the Input command's data keys.
Do not modify Input_Text.gd directly: it will be overwritten during future updates. Instead, make a copy of it, give the copy a different name, then modify and use the copy.
If this page tells you to modify Input_Text.gd, it's implied that you should actually modify a copy.
The Input Command
The keys of the Line, as Candy Dialogue Creator's form displays them:
| Key | Value |
| File | The scene. Empty for the shipped scene. |
| Mode | This is how you select the initial configuration logic for the input menu when the Input command reaches it. Three options are available in the code: Default, Default_L or Default_NS. Those three modes differ in how the text is stored (see Sanitization below). You can freely add your own modes to the code if you need different configurations. |
| Variable | The variable that the input text is stored in, written like in the Set command's Variable field: globals.player_name, $UI/Name/Label.text, file_var('user://save.json').name, etc. See Set. |
| Instructions | A text displayed above the field. For example, to provide the player instructions or tips. |
| Placeholder | A suggested text displayed in the field while it is empty. |
| Text | The field's initial text. |
| Parent | The scene's parent node. Leave empty if you want to use the Engine's default parent node for Input scenes, as set under the input_node_path key in the ui_elements_paths dictionary (see Location below). |
Default, Variable set to globals.player_name, the Instructions "What is your name?" and the Placeholder "Name" asks for the player's name and stores it in the player_name variable in the globals autoload.
Confirm and Cancel
Confirm stores the field's text in the variable and hides the field, and the Dialogue continues after the Input command. While the text fails one of the field's checks, Confirm is refused and the reason is displayed under the field.
Cancel hides the field without storing anything: the variable retains its value, and the Dialogue continues after the Input command as well. To distinguish the two, test the variable in an If command.
Checks
The provided Input scene includes code to perform various checks on the input: minimum and maximum numbers of characters and words, allowed kinds of characters (uppercase, numbers, punctuation, spaces...), a regular expression, and blacklists or whitelists of words.
The Default mode disables every check: you'll need to edit it or add alternate modes that enable the checks you want. See Input Menus.
Blacklists and Whitelists
A blacklist is a list of forbidden words: the input is refused if one of its words is on the list. A whitelist is a list of allowed words: the input is refused if one of its words isn't on the list.
The lists are stored in the input_blacklists and input_whitelists dictionaries, in Input_Blacklists.gd and Input_Whitelists.gd (User_Data/Localization_Tables). Each list has a name, and contains a separate set of words for each language:
var input_blacklists = {
"insults": {
"Default": [["mean*", false], "rude"],
"French": [["méchant*", false], "impoli"],
},
"void": {},
}"void" list, which contains no words:
blacklist = candy_de.input_blacklists["insults"]
whitelist = candy_de.input_whitelists["void"]false after the word: ["mean", false] matches "mean", "Mean" and "MEAN".
• In an entry, * stands for any characters, none included, anywhere in the entry: mean* matches "mean" and "meanie", *mean matches "notmean", and m*n matches "moon" and "mean".
• To match a literal *, escape it by doubling it: star** matches "star*" only.
• An entry that contains a space, a hyphen or an underscore never matches, since the words of the input never contain them.
Only the words of the current language are applied. The current language is the Engine's use_language, else the language setting of Candy_Properties.gd, else Default. When a list has no words for the current language, it doesn't filter the input: a list that only has Default words doesn't filter the input of a French player.
When both lists contain words for the current language, only the whitelist is applied.
Note that you can modify the blacklist/whitelist code to use different logic: it's contained in the Input_Text.gd script.
Sanitization
Sanitization is very important for player text inputs!
Without sanitization, players could write strings that contain Candy Dialogue Engine syntax symbols (¢, ¤, •, ‡, etc.), which could be mistaken for actual symbols by the code.
There are 3 kinds of risks:
1) The player's input is mistaken for an expression by CandyRef:
This could happen in two ways:
• If the input starts with the candy_ref_symbol (default ¢) and if the variable which stores the input appears inside a CandyRef expression: CandyRef would mistake the value for an expression and process it as well.
• If the input contains an expression between text variable symbols, such as ¤¢OS.get_name()¤, anywhere in the text, and if the input is displayed in a Spoken_Line through ¤...¤: the Engine resolves the text variables inside a displayed value too, so the expression would be evaluated.
This could either cause issues or allow players to essentially make your game run code. Luckily, it's easily prevented by the sanitization logic.
2) Characters in the player's input are mistaken for a text variable, a Word Substitution, a Text Event, or BBCode tags:
This could happen if the player's input contains the text variable symbols (¤), the substitution symbols (•), the text event symbols (‡) or characters that match BBCode tags, and if the input is displayed in a Spoken_Line through ¤...¤.
A text variable in the input is the most serious of these cases, since its expression is evaluated (see risk 1). This is also resolved by the sanitization logic.
3) Words in the player's input are mistaken for Lexicon keywords:
This could happen if any words in the input actually match Lexicon keywords.
The sanitization logic also provides a solution to avoid this.
The three Default modes solve these problems in different ways:
• Default: The stored text is sanitized.
Syntax symbols are escaped, so that the text is displayed as written by the player in any Spoken_Line, and so that it's never evaluated as a CandyRef expression.
This means the stored value contains added escape symbols, which you may need to account for: if you want to display the text outside a Dialogue, or compare it with another string, you would need to remove the escape symbols first. You would need to write code for that, which would be fairly easy, but Candy Dialogue Engine leaves this task to you as it can be project-specific.
As an alternative, instead of removing the escape symbols, you could make the Input scene store both the player's original input text, and a sanitized version: you would then have both available to use as needed. This would require adding a bit of code to Input_Text.gd, but it also should be easy.
• Default_L: The variable is added to the list of Literal Variables.
The input text is never modified. CandyRef or a Spoken_Line will check if the variable is listed as a Literal Variable. If so: CandyRef refuses to process the input text as an expression, and the Engine adds escape symbols before letting the text display in a Spoken_Line (the escape symbols are not added to the stored value: it remains clean).
• Default_NS: The text is stored as typed, with no sanitization or protection.
Although this option is provided, make sure you know what you're doing if you use it:
Variables referenced inside Dialogues are likely going to pass through CandyRef, and (with a few exceptions) their values will be processed as Expressions if they're strings that begin with the candy_ref_symbol (¢).
Variables that are only handled by your game code are safe, unless you explicitly design your code to also pass values through CandyRef.
See Sanitization for more information.
Reading the Value
Once stored, the value is read like any variable of your game:
- A text variable displays it in spoken text:
Welcome, ¤¢globals.player_name¤.(see Displaying Variables). - A Name command renames an Actor with it, by writing
¢globals.player_namein its Name key. - An If command tests it, for example whether it's empty.
suspend_dialogue(0) (see Suspending Dialogues).