Scripting

What scripting is in SoulFireCopy Anchor Link

A SoulFire script is a graph of connected nodes.

• Trigger nodes start a run when something happens.
• Action nodes tell bots to do work.
• Data nodes read state from the world, the bot, or SoulFire itself.
• Flow nodes decide which node runs next.
• Utility nodes transform values so the next node gets the shape it needs.

Build scripts in the Scripts tab of an instance. Each script belongs to one instance and can be active or paused. An active script listens for events.

How scripts actually runCopy Anchor Link

SoulFire scripts are event-driven. A script waits for a trigger, then runs the connected nodes.

This design means that:

• Idle scripts cost very little.
• Different triggers in the same script can start separate runs.
• Script limits control how many trigger runs can happen at once. The default is 1 run per script.
• Event triggers use a buffer. If the buffer fills, SoulFire can discard new events.
• On Pre Entity Tick and On Post Entity Tick run on the tick thread. Use them only for per-tick timing.

The mental modelCopy Anchor Link

1. Triggers start runsCopy Anchor Link

SoulFire currently ships with 12 trigger nodes:

• On Bot Init
• On Chat
• On Container Open
• On Damage
• On Death
• On Disconnect
• On Interval
• On Join
• On Pre Entity Tick
• On Post Entity Tick
• On Script Init
• On Script End

SoulFire does not have one general On Tick trigger. Use On Pre Entity Tick or On Post Entity Tick instead.

2. Execution connections decide the orderCopy Anchor Link

An execution connection tells SoulFire which node runs next.

If you connect On Join -> Send Chat -> Wait -> Pathfind To, SoulFire runs those nodes in that order when the trigger fires.

3. Data connections carry valuesCopy Anchor Link

Data connections move values such as:

• numbers
• strings
• booleans
• vectors
• bots
• entities
• blocks
• items
• lists

For example, On Chat provides the plain-text message. String Contains reads it, and Branch selects the next path.

4. Not every trigger gives you a botCopy Anchor Link

This is one of the most important implementation details.

• Most bot event triggers output a bot.
• On Interval, On Script Init, and On Script End do not give you a bot.
• If you want to act on bots from On Interval, start with Get Bots and then loop with For Each Bot.

Quick startCopy Anchor Link

Build a simple "say hello on join" script:

1. Open an instance and go to Scripts.
2. Create a new script.
3. Add On Join.
4. Add Send Chat.
5. Connect the exec output of On Join to the exec input of Send Chat.
6. Set the message on Send Chat, for example hello from SoulFire.
7. Save the script and make sure it is active.

That is enough to make each joining bot send a message once it is fully ready in the world.

Choose the right triggerCopy Anchor Link

Use this table when you are deciding where to start.

Common building blocksCopy Anchor Link

You will use these node groups in most scripts:

• Actions for movement, chat, inventory, combat, and pathfinding
• Data for reading bot state, inventory, position, light, weather, effects, and nearby targets
• Flow Control for branching, looping, rate limiting, and iterating over bots or lists
• Variables and State for session data, saved metadata, and data in memory
• Network, Integration, and AI for web requests, Discord webhooks, and LLM calls

SoulFire currently exposes 163 built-in nodes across 17 categories.

Practical adviceCopy Anchor Link

• Start with On Join, On Chat, or On Interval unless you specifically need lower-level timing.
• Keep tick-trigger scripts small. Expensive chains do not belong in pre-tick or post-tick paths.
• Use Print while building. It is the fastest way to see what your script is doing.
• Use Wait, Debounce, or Rate Limit before repeated network calls or chat actions.
• Prefer Vector3 values for movement-related logic when a node supports them.
• Store saved data in persistent variables. Use session variables for temporary data.

Learn moreCopy Anchor Link