Candy Logo Copyright © 2025-2026 Candy Arts
LLM
Candy Dialogue Engine can have the text of a Spoken Line generated or rewritten by a language model (LLM). Implementation LLM API Candy Dialogue Engine doesn't connect to an LLM API itself: your game must. Once it does, the Engine queries the LLM through your code to generate the text of Spoken Lines. Basic Method For a Line that uses the LLM, the Engine calls the llm_query() function of the Llm_Query.gd script (a 'safe' file: updates never overwrite it), waits for it to return, and displays the text it returns. Detailed Method llm_query() is empty by default, aside from comments that explain what to write in it. The function must: 1. Build a prompt from the arguments the Engine passes to it, and from any other data of your game. 2. Send the prompt to the LLM. 3. Wait for the LLM's response. 4. Optionally, review the response: edit it, or query the LLM again when the response contains errors or other issues. 5. Return the response to the Engine. Arguments Like every hook function, llm_query() receives three arguments: candy_args, user_args and custom_data (see Hook Functions). candy_args contains the Engine's own values: • "caller": the Engine running the Line. • "actor_ref": the Actor Reference of the speaker (e.g. "Alice"). • "actor_name": the speaker's DisplayName, or their Actor Reference if they have none, translated into the Engine's current language (see Translating Names). • "actor_disps": the speaker's Dispositions, as an Array (e.g. ["Likes", "Trusts"]), from their Disposition property (see Dispositions). Empty if they have none. • "text": the Line's text, as it would be displayed without the LLM: Variation chosen, variables and Word Substitution applied. It can serve as the prompt itself, or as a description of what the speaker should say. • "variation": the name of the Variation chosen for the Line (e.g. "Default"). • "dialogue": the name of the dialogue file the Line comes from (e.g. "Intro"), as passed to load_scripted_dialogue() and written in running_dialogue_file (Candy_Engine.gd). • "conversation", "block": the Conversation and Block the Line is in. • "line_index": the Line's position in its Block, counted from 0. • "line_data": the whole Line, as written in the dialogue file: every data field, every Variation and their Meta. Values are as written: ¢ expressions aren't evaluated, and BBCode tags remain present. user_args contains your own values: the entries of "llm_query" in the hook_arguments dictionary (Hook_Arguments.gd): anything else your prompts require, such as the current location or the time of day. custom_data contains the Custom Data written in the Line and in its chosen Variation: [[line values], [Variation values]]. Per-Line instructions for the LLM, such as a mood or a length, can be written there. Other data can be read directly from the function: the speaker's entry in candy_de.actors (for example, a custom prompt key you add to each Actor), Flags, variables, or the Dialogue History, to pass the LLM the conversation so far (see Dialogue History). The function must return a String: the text to display. If it returns anything else, the Line's own text is displayed instead. Configuration Engine Settings To generate spoken text with the LLM, enable LLM mode in the Engine settings: in the Inspector, under the LLM Speech category, set llm_mode to true. UI Overrides A UI Element can override the Engine setting. In the Inspector: 1. Set enable_llm_mode to true, so that the UI Element overrides the Engine. 2. Set llm_mode to true or false, to force or forbid the LLM for the speech this UI Element displays. Actor Overrides An Actor overrides the Engine and UI settings through the LLM property (in the actors dictionary): • true forces the LLM for every Line the Actor speaks. • false forbids it. • null, or no LLM property, leaves the decision to the Engine or the UI Element. Line Overrides A Spoken Line overrides the Engine, UI and Actor settings through its LLM data field: • 1 forces the LLM for this Line. • 0 forbids it. • null leaves the decision to the Engine, the UI Element or the Actor.