Skip to content

Scripting

Splintertree ships two scripting paths. They run side by side in the same world worker — pick whichever fits the job.

  • Python

    Embedded PyO3 runtime with ~22 AC-style script base classes. Full programming language, typed handles, live reload via .script reload python.

    Use it when you need real logic — branching, state machines, custom DB tables, server-pushed UI (AIO).

    Python API

  • Smart AI

    AzerothCore-compatible declarative event / action / target rules. YAML manifest in, world.smart_scripts rows out via stctl smart build.

    Use it for the typical "on aggro cast spell X at the highest-threat target" pattern — no Python knowledge required, every existing AC SmartAI script ports straight across.

    Smart AI

When to use which

Situation Path
Boss with phase transitions, custom mechanics, RNG branches Python
NPC that casts a spell on aggro and flees at 30% HP Smart AI
Mod that needs its own DB tables or AIO confirm dialogs Python
Porting an existing AC world.smart_scripts row Smart AI
GameObject with conditional gossip + quest reward chain Either — Smart AI is shorter, Python is more flexible
World event that ticks on a timer across instances Python

A single creature can mix both: Smart AI handles routine combat patterns, a Python CreatureScript handles the bespoke phase transitions on top.

Hot reload

Both paths reload without restarting the world worker:

.script reload python      # re-imports all scripts/*.py
.script reload smart        # re-reads world.smart_scripts

Pair the reload commands with splintertree-test-harness for an inner loop measured in seconds.

Where the runtime lives

  • Python runs inside splintertree-world against an embedded PyO3 interpreter. The splintertree module exposes typed handles (Creature, Player, GameObject, Item, Unit, MapInstance, World, …).
  • Smart AI runs in the same splintertree-world process via the Rust-side interpreter under splintertree-world/src/systems/scripting/smart_ai.rs, which mirrors AzerothCore's SmartScriptMgr.

Twelve-plus runnable examples for the Python side live under splintertree-world/scripts/python/examples/ in the repository; Smart AI has the AC corpus to draw from on top of the reference mods.