Events and Systems

What modules and events are#

Most of your scripts react to one thing: a player clicks an NPC, types a command, uses an item. Those are covered by the per-entity script classes on NPC, object and interaction scripts and Commands. When you need logic that runs across the whole game — a minigame lobby, health regeneration, a quest tracker that watches every kill, a once-a-minute world event — you write a module and subscribe it to events.

• An event is a C# object the server publishes when something happens (PlayerLoginEvent, NpcDeathEvent, GameTickEvent, ...). Handlers run in priority order and some events can be cancelled to stop the default behavior.
• A module is a class under server/modules/ that extends ModuleBase and has a lifecycle (OnLoad, OnEnable, OnDisable, OnUnload). Modules are where subscriptions, shared state and shared helper code live.

Every gameplay system that ships with a template (dialogue, drops, shops, quests, social, combat, movement...) is itself a module in server/modules/, so the files already in your project are working examples of everything on this page.

When to use a module instead of a script#

Write a module#

Step 1: Create the file#

1. Open the Script editor and click New Script….
2. Pick the Module kind. The dialog shows Creates: server/modules/Systems/<Name>.cs. You can also create the file anywhere under server/modules/ — the server compiles every .cs file in that folder tree, including subfolders.
3. Name the class and click Create.

Step 2: Extend ModuleBase#

public class RegenModule : ModuleBase<RegenModule>
{
    public override string Id => "regen";
    public override string Name => "Health Regen";
    public override string Version => "1.0.0";
    public override string Description => "Heals players a little every 10 seconds.";
    public override string Author => "You";
    public override string[] Dependencies => new[] { "player" };

    private EventSubscription? _tickSub;

    public override Task OnEnable()
    {
        _tickSub = Events.Subscribe<GameTickEvent>(OnTick, EventPriority.NORMAL);
        Log("Regen enabled");
        return Task.CompletedTask;
    }

    public override Task OnDisable()
    {
        if (_tickSub != null) Events.Unsubscribe(_tickSub);
        return Task.CompletedTask;
    }

    private void OnTick(GameTickEvent evt)
    {
        if (evt.TickCount % 40 != 0) return;           // 40 ticks = 10 seconds
        foreach (var p in WorldManager.Instance.GetAllPlayers())
        {
            if (p.Health < p.MaxHealth) new ScriptPlayer(p).Heal(1f);
        }
    }
}

What each member does:

Modules need no using lines for engine namespaces: the server prepends a prelude covering System, System.Linq, System.Numerics, System.Threading.Tasks, the events, modules, services, entities, world, data store, scripting and networking namespaces before compiling. Add your own using lines only for things outside that list (the template's DialogueModule adds System.IO and System.Text.Json, for example).

Step 3: Expose it to scripts#

Declare the module as ModuleBase<TSelf> (as above) and it gets a typed singleton. From any script:

var regen = RegenModule.Instance;        // null if the module failed to compile or is disabled
regen?.Log("hello from a command");

// or, without the generic base:
var mod = ModuleLoader.Module<RegenModule>();

Both return null when the module is not loaded, so null-check and degrade rather than crash.

Step 4: Verify it loaded#

Start a Dev Test and read the server console (see IDE setup for reading logs). You should see [ModuleLoader] Compiling: RegenModule.cs followed by your own Log line. A compile error is printed and the file is skipped — the server keeps running without it, so always check the log after adding a module.

Subscribe to events#

Events.Subscribe<T>(handler, priority, ignoreCancelled) returns an EventSubscription; keep it in a field and pass it to Events.Unsubscribe(...) in OnDisable. Handlers can be synchronous (Action<T>) or asynchronous (Func<T, Task>).

Cancellation rules, verified in the event bus:

• evt.Cancel() marks the event cancelled. The publisher then skips its default behavior (a cancelled PlayerLoginEvent rejects the login with evt.KickMessage; a cancelled PlayerChatEvent is not broadcast; a cancelled NpcInteractEvent never reaches task triggers).
• Once cancelled, later handlers are skipped unless they subscribed with ignoreCancelled: false — except MONITOR handlers, which always run.
• Events marked IUncancellable (ticks, logouts, deaths, level-ups, location enter/exit, ...) still have Cancel(), but nothing honors it.
• An exception inside a handler is logged and the remaining handlers still run.

Some events also carry a Handled flag (ObjectInteractEvent, ItemOnObjectEvent, ItemUseEvent). Setting evt.Handled = true tells the server the click was consumed so it does not fall through to scripts and task triggers, without cancelling the event for other listeners.

Example: greet on login and track logouts#

public class WelcomeModule : ModuleBase
{
    public override string Id => "welcome";
    public override string Name => "Welcome";

    private EventSubscription? _login, _logout;

    public override Task OnEnable()
    {
        _login = Events.Subscribe<PlayerLoginEvent>(evt =>
        {
            var p = new ScriptPlayer(evt.Player);
            long visits = p.IncrementVar("welcome.visits");   // persistent, saves with the character
            _ = p.SendGameMessage($"Welcome back! Visit #{visits}.");
        });
        _logout = Events.Subscribe<PlayerLogoutEvent>(evt =>
            Log($"{evt.Player.Username} left ({evt.Reason})"), EventPriority.MONITOR);
        return Task.CompletedTask;
    }

    public override Task OnDisable()
    {
        if (_login != null) Events.Unsubscribe(_login);
        if (_logout != null) Events.Unsubscribe(_logout);
        return Task.CompletedTask;
    }
}

Event handlers receive raw engine entities (Player, NPC, WorldObject). Wrap a Player in new ScriptPlayer(player) to get the friendly API (SendGameMessage, GiveItem, Teleport, SetVar, After, ...) documented in the Script API reference.

Events the server fires#

Every class below is published by the engine or by a template module in the current server, so a subscription will actually receive it. Properties marked settable can be changed by a handler to alter the outcome.

Server and tick#

Players#

Clicks and item use#

Combat, death and NPCs#

Movement#

The tick loop#

The server runs a fixed loop at 4 ticks per second (250 ms). Every tick, in this order:

1. GameTickEvent is published to all subscribers.
2. Scheduled tasks run (player.After, player.Every, TaskManager.Submit).
3. NpcScript.Process(npc) runs for every living NPC that has a script.
4. ObjectScript.Process(obj) runs for scripted objects.
5. Per-player script ticks: equipment effects, buffs, then LocationScript.OnTick.
6. The core game systems update (movement, combat, NPC AI, and so on).
7. Every 40 ticks the world stores are flushed to disk.

Practical rules that follow from this:

• Convert seconds to ticks by multiplying by 4: 10 seconds = 40 ticks, 1 minute = 240 ticks.
• GameTickEvent fires for every module every tick. Gate work with evt.TickCount % N == 0 as the regen example does; do not loop over every player every tick unless you need to.
• There is no OnTick on ModuleBase. Subscribe to GameTickEvent instead.
• For one-off or repeating timers tied to a player, prefer player.After(ticks, action), player.Every(ticks, action) and player.EveryStartingNow(ticks, action) — those tasks are bound to the player and are cancelled when they log out, and player.CancelAllTasks() clears them. player.CurrentTick exposes the tick counter.
• For delayed world changes use the ScriptWorld.SetObjectState(obj, newId, respawnTicks, respawnToId) overload, which schedules the swap-back for you.

Persistent state#

Modules are recreated on every server start and on a hot reload, so fields on a module are runtime-only. For anything that must survive:

Keys are free-form strings; the template uses dotted names such as social.friends and quest.stage. The template's SocialModule keeps friends and ignore lists entirely in player vars, which is a good reference for the pattern.

Gameplay systems and systems.json#

Template modules are grouped into gameplay systems (Dialogue, Quests, Shops, Social, Combat, Drops, ...). Turning a system off in the New Project wizard or in Game Config → Gameplay Systems deletes its module files and records the decision in server/data/systems.json:

{
  "version": 1,
  "enabled_systems": ["dialogue", "quests", "shops"],
  "disabled_systems": ["trading"],
  "disabled_modules": ["trade"]
}

Only disabled_modules is enforced: the loader refuses to register any module whose Id is listed there, even if its .cs file is still present. A missing or unreadable file means "load everything". See Templates and gameplay systems for the list of systems and the files each one owns.

Troubleshooting#

With AI (MCP)#

write_server_script with root: "modules" and kind: "custom" writes a module file under server/modules/<category>/; read_server_script, list_server_scripts, move_server_script and delete_server_script manage existing files. generate_script_project creates the companion project that compile-checks modules and scripts together, and read_server_logs shows the load output after a Dev Test.