SoulFire LogoSoulFire
Scripting

Triggers

Learn when each SoulFire scripting trigger runs and what data it provides.

Triggers start SoulFire scripts. When a trigger fires, SoulFire runs 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 triggers use a buffer. Under heavy load, SoulFire can discard extra events when the buffer is full.
  • On Pre Entity Tick and On Post Entity Tick run on the tick thread. Expensive nodes can delay the game loop.
  • On Interval does not output a bot. If you need to act on bots, use Get Bots and For Each Bot.

Bot connection triggers

On Bot Init

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

OutputTypeMeaning
botBotThe bot being initialized
serverAddressStringThe current server address
usernameStringThe 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.

OutputTypeMeaning
botBotThe bot that joined
serverAddressStringThe current server address
usernameStringThe bot account name

This is the best default startup trigger for most scripts.

On Disconnect

Fires when a bot disconnects.

OutputTypeMeaning
botBotThe disconnected bot
reasonStringThe disconnect message

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

Gameplay event triggers

On Chat

Fires when a bot receives a chat message.

OutputTypeMeaning
botBotThe bot that received the message
messageAnyThe received message payload
messagePlainTextStringThe plain-text version of the message
timestampNumberWhen the message arrived

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

On Damage

Fires when a bot's health decreases.

OutputTypeMeaning
botBotThe bot that took damage
amountNumberDamage dealt
previousHealthNumberHealth before damage
newHealthNumberHealth after damage

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

On Death

Fires when the bot dies.

OutputTypeMeaning
botBotThe dead bot
shouldRespawnBooleanCurrent 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.

OutputTypeMeaning
botBotThe bot that opened the container
containerIdNumberInternal container ID
containerNameStringDisplay name of the opened container
containerTypeStringContainer type

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

Timer and script lifecycle triggers

On Interval

Fires on a repeating timer.

InputTypeDefaultMeaning
intervalMsNumber1000Delay between runs in milliseconds
OutputTypeMeaning
executionCountNumberHow 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.

OutputTypeMeaning
timestampNumberStart time in milliseconds

Use it for setup, startup logs, and shared data.

On Script End

Fires once when the script is stopping.

OutputTypeMeaning
timestampNumberStop time in milliseconds

On Script End runs during shutdown. SoulFire waits up to 5 seconds for this trigger, so keep cleanup work short.

Tick triggers

On Pre Entity Tick

Fires before entity movement in each tick. It runs directly on the tick thread.

OutputTypeMeaning
botBotThe bot for this tick
tickCountNumberTick 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 movement in each tick. It runs directly on the tick thread.

OutputTypeMeaning
botBotThe bot for this tick
tickCountNumberTick counter for this trigger

Use this for logic that needs the world state after movement. For example, use it for a combat action after movement.

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

Choose a trigger

  • 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 for a task that runs at a fixed interval.
  • 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.
  • Putting all behavior in one large chain. One script can use several triggers.

How is this page?

Last updated on

Examples

Practical SoulFire scripting examples built with the current node set.

Node Reference

Look up every built-in SoulFire scripting node by category.

On this page

Before you pick a triggerBot connection triggersOn Bot InitOn JoinOn DisconnectGameplay event triggersOn ChatOn DamageOn DeathOn Container OpenTimer and script lifecycle triggersOn IntervalOn Script InitOn Script EndTick triggersOn Pre Entity TickOn Post Entity TickChoose a triggerCommon mistakes