feat: OnEvent name form + Emit node + handler-struct codegen (RFC-PLUGIN-EVENTS phase 3)

[apotema]

Phase 3 of RFC-PLUGIN-EVENTS. Tracker: flow-codegen#11.

Scope

The flow-codegen-side of the new OnEvent form, plus the new Emit node, plus the legacy converter.

flow_io.zig

• Event.OnEvent gains name: ?[]const u8 = null. module/callback/params become optional. buildEvent accepts either form; both-set or neither-set is error.MalformedFlow.
• Add NodeKind.Emit = struct { event: []const u8 }. buildNodeKind parses it; validate accepts it (codegen rejects unknown event names with a sourced diagnostic).
• Round-trip the new fields through renderFlowJsonc / parseFlow.

codegen.zig

• New-form OnEvent (renderEventEntry): resolve the dotted name through the assembler's comptime resolver (phase 1 surface). Reflect the payload's fields via @typeInfo(VariantType).@"struct".fields. Emit a FlowEventHandler struct with game_ptr: *anyopaque = undefined and a method body that is the existing flow lowering. Lift anyNodeNeedsEntity and Subflow rejections for new-form flows (game is in scope via downcast of game_ptr).
• Legacy-form OnEvent: keep the current setup()/flowEvent/raw-slot path verbatim. Removed in phase 6.
• Emit node: lower to game.emit(.{ .<qualified_tag> = .{ .field = pin, ... } });. Inputs are reflected payload fields; unwired field = error.DanglingPin.

Converter

Ship a legacy_onevent_to_name converter that rewrites legacy OnEvent blocks to the name form once module+callback resolve through the merged-union variant map. Parallel to the .flow.zon→.flow.jsonc converter shipped by RFC-FLOWS-JSONC.

Success criteria

• New-form OnEvent codegens a FlowEventHandler struct that is assignable into the GameHooks receiver tuple (phase 4 picks them up).
• Emit lowers to a single game.emit statement; payload field types round-trip.
• Legacy form codegens unchanged.
• Unknown event name → sourced error.UnknownEvent (file + node id in the diagnostic).
• Tests for new-form, legacy form, Emit node, unknown event, and the converter.

Blocked on

• feat: discover plugin Events and merge into AllHookPayloads (RFC-PLUGIN-EVENTS phase 1) labelle-assembler#174 (phase 1 — needs the assembler-exposed name resolver).

References

• RFC: §7 (flow-codegen resolution), §8 (Emit node), §5 (game access via game_ptr).
• Existing renderEventEntry: flow-codegen/src/codegen.zig:517-575.
• v1 OnEvent: flow-codegen/src/flow_io.zig:60-66.

[apotema]

Adding to scope from RFC update: §9 — entity pin on GetComponent/SetField (folded into this phase per the section's note).

GetComponent (flow-codegen/src/codegen.zig:1049) hard-codes entity today. For new-form OnEvent flows it must accept an optional entity input pin — wireable from payload.entity_a / entity_b / etc. Unwired falls back to the in-scope entity (lifecycle flows untouched). This is what lets event flows do ECS work without a "primary entity" marker (O2 was withdrawn — this design replaces it).

Validation: blanket anyNodeNeedsEntity rejection (codegen.zig:531) becomes per-node error.DanglingPin when there is no entity in scope and no wire.

[apotema]

Phase-3 scaffold landed (8e7fb7b)

Partial completion of this ticket — the file-format additions and the entity-pin codegen, which do not depend on phase 1's name resolver (labelle-assembler#174). 83 tests green (70 existing + 13 new).

What landed (in 8e7fb7b)

flow_io.zig

• Event.OnEvent gains name: ?[]const u8 = null; module / callback are now optional. buildEvent accepts either form; both-set, neither-set, and a partial legacy form (module without callback or vice versa) are all error.MalformedFlow.
• NodeKind.Emit = struct { event: []const u8 } added. buildNodeKind parses it; validate accepts it.
• renderFlowJsonc round-trips the new name field on OnEvent and the Emit node.

codegen.zig (entity pin — RFC §9)

• GetComponent and SetField gain an optional entity input pin (wired by an Edge, not a new NodeKind payload field). isInputPin accepts "entity" on these two kinds.
• Lowering: a wired entity pin's producing expression becomes the entity argument; an unwired pin falls back to the in-scope entity identifier; a pin with no wire AND no in-scope entity is error.DanglingPin against the offending node.
• The v1 blanket-rejection of entity-scoped nodes in OnCall entries and Subflow-referenced subgraphs (anyNodeNeedsEntity → EntityUnavailableInSubgraph) is replaced by the per-node DanglingPin check above. A flow can now mix wired and unwired entity-scoped nodes freely.
• The lifecycle entity binding (const entity: EntityId = undefined; for OnUpdate, const entity = <arg_entity>; for OnCreate/OnDestroy when the arg name differs) is emitted only when at least one sibling node still reads entity bare — a flow whose every entity-scoped node wires its pin no longer emits an unused binding.

What is explicitly deferred (waits for phase 1)

• New-form OnEvent codegen. renderEventEntry returns error.UnsupportedNodeKind when name is set. The legacy renderEventEntry path (module/callback/params verbatim, setup() registrar) is unchanged — current users keep working.
• Emit node lowering. writeNodeBody's .Emit arm returns error.UnsupportedNodeKind. The parser accepts the node so flow files can be authored ahead of the resolver.
• legacy_onevent_to_name converter. Needs the resolver to look up module+callback against the merged-union variant map.
• Lifting the blanket anyNodeNeedsEntity rejection inside the legacy OnEvent codegen path. Without new-form codegen, lifting it would emit broken code — kept as v1.

What the follow-up still owes

1. New-form OnEvent codegen in renderEventEntry: resolve the dotted name through the assembler's comptime resolver, reflect the payload fields via @typeInfo(VariantType).@"struct".fields, emit a FlowEventHandler struct with game_ptr: *anyopaque = undefined plus a method-style handler, and lift the entity / Subflow rejections for new-form flows.
2. Emit node lowering in writeNodeBody: game.emit(.{ .<qualified_tag> = .{ .field = pin, … } });; reflected input pins from the resolved payload struct; unwired field = error.DanglingPin.
3. legacy_onevent_to_name converter.

The success criteria the follow-up will need to verify:

• New-form OnEvent codegens a FlowEventHandler struct that is assignable into the GameHooks receiver tuple (phase 4 picks them up).
• Emit lowers to a single game.emit statement; payload field types round-trip.
• Legacy form codegens unchanged.
• Unknown event name → sourced error.UnknownEvent (file + node id in the diagnostic).
• Tests for new-form, legacy form, Emit node, unknown event, and the converter.

Commit

8e7fb7b — feat(plugin-events): phase-3 scaffold — OnEvent name field, Emit node, entity pin

[apotema]

Phase 3 landed across three repos:

flow-codegen main (1182a80)

• New-form OnEvent codegen. renderEventEntry dispatches on ev.name != null; the new-form path (renderNewFormEventEntry) emits a pub const FlowEventHandler = struct { game_ptr: *anyopaque = undefined, pub fn <qualified_tag>(self: *@This(), payload: __EvPayload) void { ... } };. Payload type resolved via @FieldType(game_mod.PluginEvents, "<qualified_tag>"); <qualified_tag> is the mechanical . → __ mapping (box2d.collision_begin → box2d__collision_begin) matching the assembler's _entry.name ++ "__" ++ _d.name at labelle-assembler/src/main_zig.zig:525. The dispatch method body is the existing topo-sorted lowering with game = @ptrCast(@alignCast(self.game_ptr)) available.
• Entity-pin escape hatch live for new-form flows. The §9 scaffold (8e7fb7b) now lights up — GetComponent / SetField / Subflow work when the entity pin is wired; an unwired entity-scoped node is DanglingPin. No lifecycle entity fallback (a payload may carry multiple entity ids).
• Emit node lowering. Replaces the scaffold's UnsupportedNodeKind with game.emit(.{ .<qualified_tag> = .{ .<field> = <pin_expr>, ... } });. Buffered (per RFC §8); the wired-pin set IS the payload field set (sorted by name for deterministic output); a wireless Emit lowers to the one-line game.emit(.{ .<tag> = .{} });. Field validation rides through the Zig compiler against the resolved __EvPayload.
• Converter. pub fn legacy_onevent_to_name(allocator, input) !LoadedFlow rewrites legacy OnEvent → name form. on_collision_begin → collision_begin (RFC §1 — the merged-union variant drops the C-callback on_ prefix); a callback without the prefix passes through verbatim. Errors: NotOnEvent / OnEventAlreadyNew / MalformedCallback. A zig build convert -- <path> driver applies the rewrite in place.

8 new tests; 91/91 pass (was 83/83 after the scaffold). All emitted Zig AST-parses cleanly.

labelle-assembler main (d6591cf + fbf2725)

Phase 1's resolver caveat (pub const PluginEvents only reachable from main.zig, not flow files) is closed by re-exporting it through the game.zig shim:

• game_shim_source → generateGameShim(allocator, cfg). With plugins, the shim appends the same pub const PluginEvents = blk: {...} block main.zig already gets (via the now-pub writePluginEventsBlock). Same @hasDecl(plugin, "Events") walk, same qualified tags.
• overrideImport(game_mod, "<plugin>", plugin_<n>_mod) lines emitted in build_files.generateBuildZig so the shim's @import("<plugin>") resolves. No new modules, no schema changes.

Also includes the MergedGameEvents fix flagged by labelle-box2d 6c44691 ("bouncing-ball end-to-end build requires a matching labelle-assembler / labelle-engine change"): the assembler now emits a MergedGameEvents decl alongside GameEvents / PluginEvents and the engine main template substitutes it into the GameConfig(..., GameEvents) slot (paired commit: labelle-engine b5f8499). Resolution:

• no plugins, no game events → void (every existing game unchanged)
• game events only → GameEvents
• plugins only → PluginEvents
• both → MergeHookPayloads(.{ GameEvents, PluginEvents })

So game.emit(.{ .box2d__collision_begin = .{...} }) from labelle-box2d phase 2 now typechecks against the merged GameEvents parameter — #422's buffered emit/dispatchEvents substrate accepts the qualified-tag variants unchanged.

449/453 tests pass (4 pre-existing skipped); new tests in test/flow_scanner_tests.zig pin the shim's PluginEvents inclusion for plugin-bearing projects and its omission otherwise.

The fbf2725 follow-up bumps the assembler's flow_codegen dep to 1182a80 so the published labelle-assembler consumes the phase-3 codegen.

labelle-engine main (b5f8499)

One-line template change: feed MergedGameEvents to GameConfig instead of GameEvents. The engine code path is otherwise untouched — same internal Payload = MergeHookPayloads(.{ EnginePayload, GameEvents }), just with a richer GameEvents argument.

Verification

• flow-codegen zig build test — 91/91 pass.
• labelle-assembler zig build test — 449/453 pass (4 pre-existing skipped).
• End-to-end — bouncing-ball/scripts/flows/hit_counter.flow.jsonc migrated from legacy form to {"type":"OnEvent","name":"box2d.collision_begin"} via the converter, regenerated with the local assembler, and zig build of bouncing-ball/.labelle/raylib_desktop succeeds. The generated hit_counter.zig is a FlowEventHandler struct emitting the topo-sorted body inside pub fn box2d__collision_begin(self: *@This(), payload: __EvPayload) void. (The game wasn't actually run — no display in this environment; the end-to-end build is the bar phase 3 sets.)

Phase 4 caveats (labelle-assembler#175)

Until phase 4 lands, the new-form FlowEventHandler struct sits idle — the assembler doesn't yet collect it into the GameHooks receiver tuple, so MergeHooks.emit never reaches it. labelle-box2d's Migration phase 1 (legacy pub var on_collision_* slots still live) is what dispatches collisions at runtime today. Phase 4's job is the one-liner of appending each flow file's *FlowEventHandler to the receiver tuple in scanner-sorted order, paired with the existing setHooks loop's game_ptr injection (labelle-engine/src/game.zig:419-429 — unchanged here).

Closes #12.

[apotema]

Update on the cross-repo wiring: Reworked the GameEvents/MergedGameEvents plumbing to avoid a version-skew trap (caught while sanity-checking that flying-platform-labelle, which pins assembler 0.30.0 from cache, would still regenerate cleanly).

What changed

• labelle-engine — reverted b5f8499 via 9df107e. The engine main template keeps the v1 GameConfig(..., GameEvents) token verbatim. A template referencing a new MergedGameEvents name would have failed substitution against any pre-phase-3 cached assembler, breaking unrelated games on a regeneration.

• labelle-assembler — ba8d31a (on top of d6591cf + fbf2725). When plugins declare events, the assembler now emits:

  pub const GameEventsRaw = union(enum) { … };  // events/*.zig scan (only when present)
  pub const PluginEvents  = blk: { … };          // plugin Events walk
  pub const GameEvents    = engine.core.MergeHookPayloads(.{ GameEventsRaw, PluginEvents });
  // or, when no game events:
  pub const GameEvents    = PluginEvents;

  i.e. the meaning of GameEvents widens to the merged set — the name stays the same, the engine template needs no change. AllHookPayloads only references the widened GameEvents (not PluginEvents again — that would double-count and trip MergeHookPayloads' duplicate-field check). Projects without plugin events keep their exact pre-RFC pub const GameEvents = void; / union(enum) {...} shape.

Net result

• flow-codegen 1182a80 (unchanged from the original comment) — new-form OnEvent codegen, Emit lowering, legacy → name converter.
• labelle-assembler ba8d31a — shim PluginEvents re-export + game_mod overrides (d6591cf), flow-codegen dep bump (fbf2725), widened GameEvents (ba8d31a).
• labelle-engine 9df107e — template change reverted; the engine is untouched for phase 3.
• Verification — flow-codegen 91/91 + assembler 449/453 (4 skipped) green; bouncing-ball regenerates and zig build succeeds end-to-end with the new-form hit_counter flow.