Module event 

Event taxonomy, handler signature, and effect registration types for the Showdown-style effect-stack battle engine (design doc §1).

Everything here is 100% game-agnostic: no game-specific concrete types appear. The game registers Effects carrying HandlerFn pointers via the EffectProvider trait.

The broadened taxonomy (design §1, P0b)

The enum below is the multi-gen authoring surface (design §1.4): the 6 groups / 31 kinds + the Custom(u16) escape hatch + the legacy Residual kept for the Gen-1 slices (see the note on Residual). Adding a variant is a non-breaking engine change: handlers subscribe by listing EventHook { event: Event::X, .. } and never match the whole enum — the only exhaustive matches live inside the engine driver, which we control. So growing this enum only offers new subscription points; it forces no existing handler or game to change. Kinds the engine driver does not yet fire are simply never collected for, hence inert (zero behavioral change), exactly as Start/End/Faint were in the POC.

Structs

Effect

An effect = id/type + a sparse table of hooks (design §1.5). Moves, statuses, abilities, items all share this shape (Showdown’s BasicEffect). The hook table is 'static so registrations are zero-alloc constants.

EffectId

An effect identifier. The engine treats it opaquely; the game assigns ids to moves/statuses/volatiles. Used as the binary-search key into the EffectState arena and to address handler source_effect.

EventHook

One (Event → HandlerFn) subscription with its ordering metadata (design §1.5). order/priority/sub_order mirror Showdown’s on<Event>Order / on<Event>Priority / effect-type sub-order.

Enums

EffectType

The effect category, feeding the comparator’s sub_order default (design §1.3). Gen-1 leaves this defaulting; kept for generality.

Event

The closed taxonomy of dispatch kinds (design §1.1, broadened §1.4).

HandlerResult

The verdict a handler returns, mirroring Showdown’s undefined / value / false / null (design §1.2).

RelayVar

The typed value threaded through a dispatch fold (design §1.2). Mirrors Showdown’s relay variable.

Type Aliases

HandlerFn

A handler is a zero-capture fn pointer (design §1.2): it cannot capture or alias battle state, so the only mutable path is through ctx. Per-effect counter state lives in EffectState, not a closure.