Scripting

What scripting is in SoulFire

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 what should run next.
• Utility nodes transform values so the next node gets the shape it needs.

You build scripts in the Scripts tab for an instance. Each script belongs to one instance, can be paused or active, and starts listening for events when it is active.

How scripts actually run

SoulFire scripting is event-driven. A script does not sit in a busy loop. It waits for a trigger, then runs the connected chain for that trigger.

That matters because:

• Idle scripts cost very little.
• Different triggers in the same script can start separate runs.
• Concurrency is limited by script quotas. The current default is 1 concurrent trigger run, not 8.
• Event-based triggers use backpressure. If a trigger floods faster than SoulFire can process it, extra events can be dropped.
• On Pre Entity Tick and On Post Entity Tick run synchronously on the tick thread. Use them only when you truly need per-tick timing.

The mental model

1. Triggers start runs

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

The old idea of a single generic On Tick trigger is outdated. The current engine splits tick work into pre-physics and post-physics phases.

2. Execution edges decide order

Execution edges answer the question "what 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 edges carry values

Data edges move values like:

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

For example, On Chat can output the plain-text message, then String Contains can inspect it, then Branch can choose a path.

4. Not every trigger gives you a bot

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 start

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 trigger

Use this table when you are deciding where to start.

Common building blocks

These node groups do most of the heavy lifting in real 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, persistent metadata, and in-memory caches
• Network, Integration, and AI for web requests, Discord webhooks, and LLM calls

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

Practical advice

• 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 durable data in persistent variables. Use session variables for throwaway run-time state.

Learn more