Triggers

Triggers are the entry points to a SoulFire script. When a trigger fires, SoulFire starts a run from that trigger node and follows the connected execution path.

Before you pick a trigger

Keep these engine details in mind:

A script can contain multiple triggers.
Each trigger can fire many times.
Trigger runs are limited by script quotas. The current default is 1 concurrent run per script.
Event-based triggers use buffered delivery. Under heavy load, extra events can be dropped instead of piling up forever.
On Pre Entity Tick and On Post Entity Tick run on the tick thread. They are powerful, but they are the easiest way to build a laggy script.
On Interval does not output a bot. If you need to act on bots, use Get Bots and For Each Bot.

Bot lifecycle triggers

On Bot Init

Fires early when the bot connection is initialized, before the player object is ready.

Output	Type	Meaning
`bot`	Bot	The bot being initialized
`serverAddress`	String	The current server address
`username`	String	The bot account name

Use this when you need early connection setup. If you want to move, chat, or interact with the world, use On Join instead.

On Join

Fires when the bot has fully joined and is ready to interact.

Output	Type	Meaning
`bot`	Bot	The bot that joined
`serverAddress`	String	The current server address
`username`	String	The bot account name

This is the best default startup trigger for most scripts.

On Disconnect

Fires when a bot disconnects.

Output	Type	Meaning
`bot`	Bot	The disconnected bot
`reason`	String	The disconnect message

Use this for cleanup, logging, or reconnect-related workflows.

Gameplay event triggers

On Chat

Fires when a bot receives a chat message.

Output	Type	Meaning
`bot`	Bot	The bot that received the message
`message`	Any	The received message payload
`messagePlainText`	String	The plain-text version of the message
`timestamp`	Number	When the message arrived

Use this for chat commands, alerts, filters, and chatbot flows.

On Damage

Fires when a bot's health decreases.

Output	Type	Meaning
`bot`	Bot	The bot that took damage
`amount`	Number	Damage dealt
`previousHealth`	Number	Health before damage
`newHealth`	Number	Health after damage

This is a good trigger for escape logic, healing logic, and combat alerts.

On Death

Fires when the bot dies.

Output	Type	Meaning
`bot`	Bot	The dead bot
`shouldRespawn`	Boolean	Current respawn intent from the event

Use this with Respawn, Discord notifications, or post-death recovery logic.

On Container Open

Fires when the bot opens a container or inventory-like screen.

Output	Type	Meaning
`bot`	Bot	The bot that opened the container
`containerId`	Number	Internal container ID
`containerName`	String	Display name of the opened container
`containerType`	String	Container type

Use this for chest workflows, menu automation, and shop interactions.

Timer and script lifecycle triggers

On Interval

Fires on a repeating timer.

Input	Type	Default	Meaning
`intervalMs`	Number	`1000`	Delay between runs in milliseconds

Output	Type	Meaning
`executionCount`	Number	How many times this trigger has fired

On Interval is instance-level, not bot-level. If you want to run something for every connected bot, connect On Interval to Get Bots and then For Each Bot.

On Script Init

Fires once when the script starts.

Output	Type	Meaning
`timestamp`	Number	Start time in milliseconds

Good for initialization, startup logs, and loading shared state.

On Script End

Fires once when the script is stopping.

Output	Type	Meaning
`timestamp`	Number	Stop time in milliseconds

On Script End is executed during shutdown and currently has a 5 second wait window in the trigger service. Keep cleanup work short.

Tick triggers

On Pre Entity Tick

Fires before entity physics each tick and runs synchronously on the tick thread.

Output	Type	Meaning
`bot`	Bot	The bot for this tick
`tickCount`	Number	Tick counter for this trigger

Use this for aiming, rotation changes, or other logic that must happen before the tick updates movement.

On Post Entity Tick

Fires after entity physics each tick and runs synchronously on the tick thread.

Output	Type	Meaning
`bot`	Bot	The bot for this tick
`tickCount`	Number	Tick counter for this trigger

Use this when you need the world state after movement has been processed, for example follow-up combat checks.

Tick triggers are low-level tools. Avoid HTTP requests, LLM calls, long waits, or wide loops in these paths.

Which trigger should you use?

Use On Join for most startup behavior.
Use On Bot Init only when On Join is too late.
Use On Chat for anything message-driven.
Use On Interval when you want predictable polling.
Use On Pre Entity Tick and On Post Entity Tick only for timing-sensitive logic.
Use On Script Init and On Script End for whole-script setup and cleanup.

Common mistakes

Using On Interval and expecting a bot output.
Treating On Pre Entity Tick as a safe place for expensive work.
Using On Bot Init for actions that need a loaded player.
Forgetting that one script can have multiple triggers, which is usually cleaner than forcing everything through one giant chain.

On this page