MagmaCore/com.magmaguy.magmacore.scripting/ScriptInstance

ScriptInstance

Represents a running instance of a Lua script bound to a ScriptableEntity.

Manages the Lua VM lifecycle, per-entity state, task ownership, and hook dispatch. The Lua table is lazily instantiated on the first event or query hook call.

Constructors

ScriptInstance

public void ScriptInstance(ScriptDefinition definition, ScriptableEntity entity)

Properties

currentDirectTarget

public LivingEntity currentDirectTarget

currentEvent

public Event currentEvent

currentEventActor

public LivingEntity currentEventActor

definition

public final ScriptDefinition definition

entity

public final ScriptableEntity entity

Functions

cancelOwned

public void cancelOwned(int taskId)

Cancel an owned task by id.

getCooldownRemainingTicks

public long getCooldownRemainingTicks(String key)

getCurrentDirectTarget

public LivingEntity getCurrentDirectTarget()

The direct target of the event being dispatched, or null (e.g.

getCurrentEvent

public Event getCurrentEvent()

The event currently being dispatched, or null (e.g.

getCurrentEventActor

public LivingEntity getCurrentEventActor()

The actor (e.g.

getDefinition

public ScriptDefinition getDefinition()

getEntity

public ScriptableEntity getEntity()

handleEvent

public void handleEvent(ScriptHook hook, Event event, LivingEntity directTarget, LivingEntity eventActor)

Invokes the Lua hook function with a lazily-built context table.

handleQuery

public ScriptQueryResult handleQuery(ScriptHook hook, Event event, LivingEntity directTarget, LivingEntity eventActor)

Invokes a Lua hook synchronously and returns its immutable scalar result.

hasOwnedWorkExcept

public boolean hasOwnedWorkExcept(int hostGuardTask)

Allows a single-input host to release an idle activation without counting its own lifetime guard.

invokeOwnedCallback

public void invokeOwnedCallback(String failureContext, LuaFunction callback, Array<LuaValue> args)

Invoke a Lua callback with explicit args under the CPU-time/instruction watchdog.

isClosed

public boolean isClosed()

isCooldownReady

public boolean isCooldownReady(String key)

isPaused

public boolean isPaused()

onTick

public void onTick()

Called each server tick when ON_TICK is supported.

ownCleanup

public void ownCleanup(Runnable cleanup)

ownLater

public int ownLater(int ticks, Runnable runnable)

Schedule a one-shot owned Java task; auto-cancelled on shutdown.

ownLuaLater

public int ownLuaLater(int ticks, LuaFunction callback)

Schedule a one-shot owned Lua callback, invoked with a fresh context table.

ownLuaRepeating

public int ownLuaRepeating(int delayTicks, int intervalTicks, LuaFunction callback)

Schedule a repeating owned Lua callback, each invoked with a fresh context table.

ownRepeating

public int ownRepeating(int delayTicks, int intervalTicks, Runnable runnable)

Schedule a repeating owned Java task; auto-cancelled on shutdown.

setCooldown

public void setCooldown(String key, long ticks)

setPaused

public void setPaused(boolean paused)

Freezes hook and owned-callback execution without discarding the Lua VM or script state.

shutdown

public void shutdown()

Shuts down this script instance: cancels all owned tasks, clears state, and notifies the entity.

start

public void start()

Eagerly instantiates the Lua VM and registers the per-tick task (if the script declares on_game_tick) WITHOUT firing any hook.