Candy Logo Copyright © 2025-2026 Candy Arts
CS Move
The CS_Move command moves nodes in the game world with movement code that you write. Candy Dialogue Engine can't know how your game moves its characters, such as along a path, with a navigation agent or with a tween, so it ships no movement of its own. Each movement is a script that you add to the Candy_DE/Scripts/Move_Events folder, and each target's Movement key names the script that moves it. The scripts you add to that folder are 'safe': updates never overwrite them. For example, this Line walks the Hero node to the Door marker:
{"CS_Move": {"Targets": {"Actors/Hero": {"Movement": "Walk", "Data": "Pins/Door"}}}}
Movement Scripts A movement script extends CandyMoveEvent and declares one function, handle(). Its file name is the Movement value, which is Walk.gd in the example above. This script moves the node to the marker named by Data in two seconds, and delays the Dialogue until the node has arrived:
extends CandyMoveEvent func handle(engine: CandyEngine, node: Node, data: Variant, _ctx: CandyContext, _custom_data: Array) -> String: var marker := CandyCutscene.get_shared().resolve_target(engine, self, data, "CS_Move") if marker == null: return "Continue" var tween := node.create_tween() tween.tween_property(node, "global_position", marker.global_position, 2.0) await tween.finished return "Continue"
ArgumentValue
engineThe Engine running the CS_Move command.
nodeThe target to move. The command has already resolved it.
dataThe target's Data value. If it was written as an expression, it's already evaluated, so it can be any type of value.
ctxThe Line holding the CS_Move command, a CandyContext: conversation, block, line_index, line_data.
custom_dataThe Custom Data of the Line and of the target, as [[line values], [target values]].
  • handle() returns what the Dialogue does next, as a Command script does: "Continue", "Return" or "END".
  • Every target of a Line starts moving at the same time. The Dialogue continues once every script has returned.
  • A script that uses await until its movement is over delays the Dialogue. A script that starts its movement and returns immediately leaves the Dialogue to continue while the node moves.
  • CandyCutscene.get_shared().resolve_target() resolves a node named as targets are, such as the marker in the example. It reports a node it can't find, and returns null.
  • A Movement value with no script is reported, and that target doesn't move.
Script names aren't case-sensitive, and nothing needs registering: see How Drop-In Scripts Work, on the Code Modification page. No script ships in this folder. Keys Every key also accepts a ¢ expression instead of a fixed value, unless its description says otherwise. See CandyRef Expressions. Targets Description: The nodes to move. Each key identifies a node, and its value is a Dictionary of settings for that node (see below). The Engine reports an entry it can't find and skips it, without affecting the others. Values: • Container/Name: A node inside one of the containers listed in the Engine's cs_paths, such as Actors/Hero for the node Hero in the Actors container. The name can be a longer path, such as Actors/Hero/Hat. • Container/°role: The node named after the Actor assigned to that Role, such as Actors/°guard. A Role always needs its container. • Node path: A path relative to the Engine, or an absolute path such as /root/Game/Hero. • ¢ expression: Can also return the node itself, such as ¢$Level/Hero (a path from the Engine). Target Settings Each target in Targets accepts the following keys. Movement Description: The movement that moves this node, which is the file name of its script in Candy_DE/Scripts/Move_Events. The value is case-insensitive. Values: • Script name: Such as walk for Walk.gd. • Empty: The target is reported and doesn't move. Data Description: The value passed to the script's handle() function as its data argument, after evaluation. The script decides its meaning: the marker to walk to, for example. Values: • Any value