Sequencer Commands

v1.0

The JuicyActions() sequencer command executes Juicy Actions ActionExecutors from within Dialogue System sequences. This allows you to trigger visual effects, animations, sounds, and any other Actions during conversations.

Syntax & Parameters

JuicyActions(actionExecutor, target, [wait], [scope], [id], [duration]);

Parameter	Type	Required	Default	Description
actionExecutor	string	✅ Yes	-	Name of the public ActionExecutor field on the target GameObject
target	string	✅ Yes	speaker	Target GameObject (see Target Resolution below)
wait	bool	❌ No	false	If true, sequence waits for ActionExecutor to complete timeBeforeNextAction before continuing
scope	string	❌ No	Current conversation	Scope identifier for tracking/cleanup (e.g., "global", "conversation", custom ID)
id	string	❌ No	Auto-generated	Custom ID for this specific execution
duration	float	❌ No	None	Duration override in seconds (overrides ActionExecutor's configured duration)

Target Resolution

The target parameter supports several resolution methods:

Dialogue System Keywords:

• speaker - The current speaker in the conversation

• listener - The current listener (usually the player)

• conversant - The conversant in the conversation

• actor - The actor (synonym for speaker)

GameObject References:

• MyGameObject - GameObject name (requires exact match via GameObject.Find())

• tag:TagName - Find GameObject by tag (e.g., tag:Player, tag:MainCamera)

• Root/Child/SubChild - Hierarchical path lookup

Examples

Basic Usage (Fire and Forget):

JuicyActions(OnAngryActions, speaker)

Executes the OnAngryActions executor on the speaker immediately and continues the sequence. Will end when the Conversation ends.

Wait for Completion:

JuicyActions(HitReaction, speaker, true)

Executes HitReaction on the speaker and waits for it to complete before continuing the sequence.

Custom Duration:

JuicyActions(CameraShake, MainCamera, false, global, , 2.5)

Executes CameraShake on MainCamera GameObject with a 2.5-second duration override, using global scope.

Tag-Based Targeting:

JuicyActions(ExplosionEffect, tag:Enemy, false, global)

Finds the first GameObject with tag "Enemy" and executes the effect.

Cancelling Actions

By default ActionExecutors will end with the conversation, though in most cases they will have finished their actions prior to that point.

Global Scope

// This keeps running after conversation.
// To cancel it, use any method provided by Juicy Actions, or let it run its course.
JuicyActions(BackgroundMusicFade, AudioManager, false, global)

Custom Scope

// Start cutscene effects
JuicyActions(CameraZoom, MainCamera, false, cutscene)
JuicyActions(CharacterWalk, speaker, false, cutscene)

// Later in sequence, stop all cutscene effects:
Lua(JuicyActions.Stop("cutscene"))

Mixing Scope

// Camera shake stops with conversation
JuicyActions(CameraShake, MainCamera, false, conversation);

// UI effect persists globally, will end when they're done, or cancelled via some other method.
JuicyActions(QuestNotification, UICanvas, false, global)

---

Lua Functions

The Juicy Actions integration provides Lua functions that can be called from Dialogue System Lua scripts, conditions, and dialogue entry fields. These functions provide programmatic control over ActionExecutor execution.

Available Functions

JuicyActions.Execute()

Executes an ActionExecutor immediately (fire and forget).

Syntax:

JuicyActions.Execute(actionName, targetGameObject, [scope], [id], [duration], [preset])

Parameters:

• actionName (string): Name of the public ActionExecutor field

• targetGameObject (GameObject): Target GameObject reference

• scope (string, optional): Scope identifier (default: current conversation)

• id (string, optional): Custom execution ID (default: auto-generated)

• duration (number, optional): Duration override in seconds

• preset (string, optional): Preset name to use

Returns: void

Example:

-- In a Script field or Lua condition
JuicyActions.Execute("OnQuestComplete", Actor["Player"])

Example with Options:

JuicyActions.Execute("CameraShake", Actor["MainCamera"], "global", "", 1.5, "Intense")

---

JuicyActions.ExecuteAndWait()

Executes an ActionExecutor and waits for it to complete. Only use this in sequencer commands or coroutines.

Syntax:

JuicyActions.ExecuteAndWait(actionName, targetGameObject, [scope], [id], [duration], [preset])

Parameters: Same as Execute()

Returns: void (blocks until completion)

⚠️ Important: This function blocks execution. Only use it:

• In sequencer Lua commands: Lua(JuicyActions.ExecuteAndWait(...))

• In coroutines where blocking is acceptable

• Never in conditions or immediate Lua evaluations (will freeze the conversation!)

Example (in sequencer):

Lua(JuicyActions.ExecuteAndWait("LongAnimation", Actor["Speaker"]))

---

JuicyActions.Stop()

Stops all ActionExecutors with a specific scope or ID.

Syntax:

JuicyActions.Stop(scopeOrId)

Parameters:

• scopeOrId (string): Scope name or execution ID to stop

Returns: void

Example:

-- Stop all actions in "global" scope
JuicyActions.Stop("global")

-- Stop specific execution by ID
JuicyActions.Stop("myCustomEffectID")

---

JuicyActions.StopAll()

Stops all running ActionExecutors across all scopes.

Syntax:

JuicyActions.StopAll()

Parameters: None

Returns: void

Example:

-- Emergency stop everything
JuicyActions.StopAll()

⚠️ Use with caution: This stops ALL Juicy Actions in the entire game, not just conversation-related ones.

---

JuicyActions.IsExecuting()

Checks if any ActionExecutors are currently running in a specific scope or ID.

Syntax:

JuicyActions.IsExecuting(scopeOrId)

Parameters:

• scopeOrId (string): Scope name or execution ID to check

Returns: boolean - true if executing, false otherwise

Example (in a condition):

-- Only proceed if certain effects are still running
JuicyActions.IsExecuting("battleEffects") == true

Example (in a Script field):

if JuicyActions.IsExecuting("myEffect") then
    Debug.Log("Effect is still running")
else
    Debug.Log("Effect has finished")
end

---

Lua vs Sequencer Commands

Understanding when to use Lua functions vs sequencer commands:

Feature	Lua Functions	Sequencer Commands
Timing	Immediate execution	Timed with sequence
Wait Support	ExecuteAndWait (blocks)	wait=trueparameter
Use in Conditions	✅ Yes (Execute, IsExecuting)	❌ No
Use in Scripts	✅ Yes	❌ No
Parallel Execution	Sequential in Lua	✅ Easy with sequence timing
Best For	Programmatic control, branching	Timed cutscenes, cinematics

When to use Lua:

• Dynamic execution based on variable values

• Conditional triggering in dialogue conditions

• Programmatic control from Scripts

• Checking execution state

When to use Sequencer Commands:

• Synchronized timing with camera cuts, animations

• Parallel effects (shake camera + flash screen + play sound)

• Wait for completion before continuing sequence

• Visual sequencing in the Dialogue Editor

---

Common Lua Patterns

Conditional Execution Based on Variables:

if Variable["PlayerHealth"] < 50 then
    JuicyActions.Execute("LowHealthEffect", Actor["Player"])
end

Execute Different Effects Based on Quest State:

local questState = Quest["MainQuest"].State
if questState == "success" then
    JuicyActions.Execute("QuestCompleteEffect", Actor["Player"], "global", "", 2.0)
elseif questState == "failure" then
    JuicyActions.Execute("QuestFailedEffect", Actor["Player"], "global", "", 2.0)
end

Stop Previous Effects Before Starting New Ones:

JuicyActions.Stop("ambientEffects")
JuicyActions.Execute("NewAmbientEffect", Actor["Background"], "ambientEffects")

Check if Effect is Running Before Triggering:

if not JuicyActions.IsExecuting("combatEffect") then
    JuicyActions.Execute("CombatStartEffect", Actor["Player"], "combatEffect")
end

---

Accessing GameObjects in Lua

To reference GameObjects in Lua, use these methods:

Actor References (for participants in conversation):

Actor["Player"]
Actor["NPC_Merchant"]
Actor["Speaker"]  -- Current speaker

GameObject.Find by name:

GameObject.Find("MainCamera")
GameObject.Find("Terminal - Juicy Actions Demo Variant")  -- Must match exactly!

GameObject.FindWithTag:

GameObject.FindWithTag("Player")
GameObject.FindWithTag("Enemy")

Example:

local mainCamera = GameObject.Find("Main Camera")
JuicyActions.Execute("ScreenShake", mainCamera, "global")

---

Troubleshooting

"Conversation freezes when using ExecuteAndWait"

• Only use ExecuteAndWait() in sequencer Lua commands: Lua(JuicyActions.ExecuteAndWait(...))

• Never use it in conditions or Scripts that run during dialogue evaluation

• Use Execute() for fire-and-forget instead

"Lua error: attempt to index nil value"

• Check that GameObject exists: if Actor["Player"] ~= nil then

• Verify Actor names match exactly (case-sensitive)

• Use GameObject.Find() for non-participant GameObjects

"Actions don't stop when conversation ends"

• Make sure you're using the default scope (conversation) or explicitly setting scope="conversation"

• Global scope actions won't auto-cleanup: scope="global"

---

Hope this helps! Let me know if you'd like me to expand on any sections or add more examples! 🎉