Lua Functions

v1.0

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(actionExecutorFieldName, targetName)

Parameters:

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

• targetGameObject (GameObject): Target GameObject reference

Returns:

void

Scope:

Automatically uses current conversation scope (or "lua" if called outside a conversation)

Example:

-- Execute on player
JuicyActions.Execute("OnQuestComplete", "Player")

-- Execute on speaker using keyword
JuicyActions.Execute("CharacterGlow", "speaker")

-- Execute using tag
JuicyActions.Execute("ExplosionEffect", "tag:Enemy")

JuicyActions.ExecuteAndWait()

Executes an ActionExecutor and waits for it to complete. Blocks Lua execution - use only in sequencer Lua commands!

Syntax:

JuicyActions.ExecuteAndWait(actionExecutorFieldName, targetName)

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()

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

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")