Game events
StoneForge tells a mod what happens in the game: a unit dies, a door opens, a save is written, the player picks something up. Each event is registered from the class it's about, as Area.OnSomething(context, handler):
Units.OnDied(context, (unit, killer) =>
{
if (Units.IsPlayer(killer))
context.Log($"You killed {ActionsLog.NameOf(unit)}");
});
Doors.OnChanged(context, (door, open) => context.Log(open ? "A door opens" : "A door closes"));
Rooms.OnEntered(context, room => context.Log($"Entered {Rooms.CurrentName}"));
Register them in Load. A mod's handlers go with it when it's switched off, and an exception in one is that mod's, as with any other handler: it's reported, and a mod that keeps failing is paused. You don't need [assembly: HookScript] for any of these; StoneForge makes the scripts they need hookable itself.
For anything not listed here, hook the game's own scripts and events: see Hooks.
Every event
| Event | Runs |
|---|---|
| World | |
Rooms.OnEntered(room) |
Once the game has gone into a room of the game being played, its instances set up. Each dungeon floor counts. |
Rooms.OnLeaving(room) |
As the game leaves one, its instances still there. |
Turns.OnTurn() |
After each world turn has passed. |
Locations.OnSaved(preset) |
The game has saved the place the player is leaving. |
Doors.OnChanged(door, open) |
A door starts opening or closing, whoever does it. |
MapMarkers.OnPlaced(marker), OnRemoved(marker) |
The player places a marker on the world map or takes one off. |
| Saves | |
SaveData.OnLoaded(save) |
A save has been read, before the game sets itself up from it. |
SaveData.OnSaving(save) |
A save is about to be written: the save data can still be changed. |
| Units and combat | |
Units.OnSpawned(unit) |
A unit comes into play: summoned, spawned, made by a mod. |
Units.OnDied(unit, killer) |
A unit dies, before it's destroyed. |
Combat.OnAttack(attack), OnHit(attack) |
Any attack is resolved; any attack strikes. |
Skills.OnUsed(cast) |
Anyone uses a skill. |
| The player | |
Player.OnDying() |
The player is about to die. Return true to stop it. |
Player.OnLevelUp(level) |
The player levels up. |
Quests.OnStarted, OnProgress, OnCompleted, OnFailed |
A quest starts, moves on a step, is done or fails. |
| Items | |
Inventory.OnAdded(item), OnRemoved(item), OnEquipped(item, on) |
The player gains or loses an item, puts one on or takes one off. |
Containers.OnOpened, OnClosed, OnItemAdded, OnItemRemoved |
A container opens or closes; an item goes into an open one or comes out. |
GroundItems.OnAdded(item), OnRemoved(item) |
An item comes onto the ground or leaves it. |
| UI | |
ContextMenus.OnOpen(menu) |
A right-click menu opens. |
What counts
Events report what happens in play. The units, items and doors a place already has as it loads, or a room is built with, don't count as spawned or added. Where an event says "on the frame after", the thing is set up by then (its data filled in); one that's gone again by then isn't reported.