Game events

English | 日本語

Experimental. This came in with core 1.2.0 (framework 1.2.0).

GameEvents lives in the core (DragNWash.ModFramework). The framework receives the game's events once and hands them to each mod separately. If a handler throws, it's logged and shown on the Mods screen under its mod, and the other mods' handlers still run.

Why not subscribe directly

If a handler on SceneManager.sceneLoaded throws, it stops every mod that subscribed after it, and nobody can tell which mod it was. That's exactly what the framework's first principle is there to prevent, so GUIDE rule 9 asks mods to take these events from GameEvents instead.

Use

private void Awake()
{
    GameEvents.OnSceneLoaded(MyMod.Guid, (scene, mode) => ApplyTo(scene));
    GameEvents.OnGameStarted(MyMod.Guid, () => Log("The title screen is up."));
    GameEvents.OnQuitting(MyMod.Guid, SaveMyState);
}

private void OnDestroy() => GameEvents.Remove(MyMod.Guid);

Member	What it does
void OnSceneLoaded(string ownerGuid, Action<Scene, LoadSceneMode> handler)	After every scene load
void OnSceneUnloaded(string ownerGuid, Action<Scene> handler)	After every scene unload
void OnGameStarted(string ownerGuid, Action handler)	Once, when the title screen is first shown and the game's systems exist. A handler added after that runs straight away
void OnQuitting(string ownerGuid, Action handler)	When the game is quitting
bool IsGameStarted	True once the title screen has been shown
void Remove(string ownerGuid)	Takes out every handler that mod registered

What happens when a handler fails

• The exception goes to the log with the mod's GUID and the event's name, and the Mods screen shows the failure under that mod (the same way GameHooks.Unavailable shows a missing game member).
• The other mods' handlers for the same event still run.
• A handler that fails three times in a row is switched off for the session. One success resets the count.
• A handler that takes longer than 100 ms is noted in the debug log, so you can trace a slow scene load back to a mod.

There is no per-frame event

That's on purpose. A MonoBehaviour's Update is the right tool for per-frame work. A framework-wide Update would put every mod's frame work in one place, and then one slow mod would slow everyone down.