Candy Logo Copyright © 2025-2026 Candy Arts
Dispositions
Dispositions are a quick way to make Spoken Lines conditional: if a Spoken Line has a disposition assigned, it will only run and display if the speaker's disposition matches. Lines that don't match are skipped. A disposition is just a word, and can represent anything you want: a relationship status ("Friend", "Rival"), a mood ("Angry", "Tired"), a need ("Hungry"), a preference ("Likes_Cats"), and so on. For example, a shopkeeper could greet the player differently depending on whether they're "Friendly" or "Hostile", all in the same Block:
Shopkeeper (Friendly): "Welcome back, friend! Take a look around." Shopkeeper (Hostile): "You again? Buy something or get out." Shopkeeper (!Friendly, Hostile): "Welcome. What can I get you?"
In the example above, only the line matching the shopkeeper's current disposition is displayed. Actor Dispositions An Actor's dispositions are set in their Disposition property, in the actors dictionary (in Actors.gd). Several dispositions can be features, separated by commas:
"Alice": { "DisplayName": "Alice Turner", "Disposition": "Friendly, Tired", },
  • Spaces around commas are ignored: "Friendly, Tired" and "Friendly,Tired" are the same.
  • Dispositions are case-sensitive: "Friendly" and "friendly" are different dispositions.
  • An empty Disposition, or no Disposition key at all, means the Actor has no dispositions.
Modifying Dispositions Actor dispositions can be changed during Dialogues through the Disposition command (see below), or by your own code:
candy_de.actors["Alice"]["Disposition"] = "Friendly, Happy"
Line Dispositions A Spoken Line's disposition condition is written in its Disposition field. It is checked against the dispositions of the speaker. An empty Disposition field means the line always plays. A dispositions is made of up to three elements:
  • - Optional comparison characters (=, +, - or !).
  • - An optional comparison amount, e.g. (2).
  • - A list of dispositions, separated by commas.
Basic Conditions The examples below use Alice, whose Disposition is "Friendly, Tired".
ConditionPasses when...Alice
Friendly, HappyThe Actor has at least one of the listed dispositions.Passes (Friendly)
+Friendly, HappyThe Actor has all the listed dispositions.Fails (no Happy)
-Friendly, Tired, HappyAll of the Actor's dispositions are in the list.Passes
=Friendly, TiredThe Actor's dispositions are exactly the list, no more and no less.Passes
!Angry, SadThe Actor has none of the listed dispositions.Passes
The order of the dispositions doesn't matter. Note that - passes for an Actor with no dispositions at all, since they have none outside the list. Counting Matches A number between parentheses, after the operators, checks how many of the listed dispositions the Actor has:
ConditionPasses when...Alice
(1)Friendly, HappyThe Actor has exactly n of the listed dispositions.Passes (Friendly)
+(2)Friendly, Tired, HappyThe Actor has n or more of them.Passes (2)
-(2)Friendly, Tired, HappyThe Actor has fewer than n of them.Fails (2)
=(1)Friendly, HappyThe Actor has exactly n of them, and no disposition outside the list.Fails (Tired isn't listed)
Counting Mismatches With !, the number counts the listed dispositions the Actor doesn't have:
ConditionPasses when...Alice
!(1)Friendly, HappyExactly n of the listed dispositions are missing.Passes (Happy)
!+(2)Friendly, Happy, Sadn or more are missing.Passes (2)
!-(2)Friendly, Happy, SadFewer than n are missing.Fails (2)
=!(1)Friendly, Tired, HappyExactly n are missing, and the Actor has no disposition outside the list.Passes (Happy)
Operators can be written in any order, and spaces between them are ignored: "=!(1)" and "! = (1)" are the same. Expressions A CandyRef expression can be provided in the Disposition field of a Spoken Line. Assuming that globals.mood = "Tired":
¢"!" + globals.mood → !Tired
The whole field must be an expression: references written in the middle of plain text (e.g. "Friendly, €mood") are not read, and are treated as a disposition named "€mood". To mix pre-determined dispositions and variables references, you would write this:
¢"!" + "Hostile, " + globals.mood + ", " + "Sad" → !Hostile, Tired, Sad
Notice the quotation marks around the operator and the pre-determined dispositions, as well as the comma after globals.mood. To simplify expression writing, commas can also be part of the disposition value inside the referenced variable, like this:
var globals.mood = "Tired, " ¢"!" + "Hostile, " + globals.mood + "Sad" → !Hostile, Tired, Sad
Ultimately, a disposition expression is just written like a string concatenation in GDScript. Special Cases A speaker who isn't in the actors dictionary is treated as having no dispositions. When a Spoken Line has a disposition and the speaker isn't in the actors dictionary, the Engine prints a warning. When the speaker is a Role Reference (e.g. "°companion"), the dispositions of the Actor currently assigned to that Role are checked. Engine Settings Media Pause A Media_Pause command can resume its media after a number of Lines have been processed. By default, when a Spoken Line is skipped because its disposition didn't match the speaker's, it isn't counted towards that amount. To count skipped Spoken Lines, set the Engine's mp_count_dispositions (in the Inspector, under the Media category) to 'true'. LLM When a line goes through the LLM, the llm_query() function (in User_Data/Functions/Llm_Query.gd) receives all the speaker's dispositions in candy_args["actor_disps"], as an Array. Your function can hand them to the LLM, so the generated text matches the speaker's mood or relationships. Characters to Avoid
  • Don't use commas in disposition names: they separate dispositions.
  • Disposition names must not start with =, +, -, ! or (: they'd be read as part of the condition's prefix.
  • Disposition names must not start with the symbols you set in Candy_Properties.gd (¢, €, °, etc.).