Epic: Lifecycle Hook System #82

New issue

Open

opened 2026-03-15 04:13:03 +00:00 by freemo · 0 comments

freemo commented

2026-03-15 04:13:03 +00:00

Owner

Metadata

Commit Message: feat(lifecycle): implement lifecycle hook system
Branch: feature/lifecycle-hooks

Background and Context

The specification (§ Lifecycle Hook System) describes a comprehensive hook-based event
system that allows subsystems to register callbacks for server, player, and object
lifecycle transitions. Currently, initialization logic is scattered across Manager#initialize,
Server#initialize, and individual object constructors with no decoupled notification
mechanism.

The lifecycle hook system is a prerequisite for:

Event sourcing integration (uses on_boot, on_shutdown, on_save, on_create, on_destroy)
Terminal UI framework (uses on_connect, on_disconnect, on_room_change)
Command dispatch pipeline (uses on_tick for cooldown expiration)

Expected Behavior

A LifecycleHooks registry provides on, once, off, and emit methods. Hooks are
organized into server hooks, player hooks, and object hooks. Each hook receives a
HookEvent with relevant context. Hooks support cancellation and error isolation.

Acceptance Criteria

HookEvent data model implemented with type, source, data, cancelled fields
LifecycleHooks registry with on/once/off/emit API
Server hooks: on_boot, on_shutdown, on_tick, on_save, on_reload
Player hooks: on_connect, on_login, on_logout, on_disconnect, on_death, on_respawn, on_room_change
Object hooks: on_create, on_destroy, on_load, on_object_save
Cancellable hook mechanism prevents downstream handlers from executing
Error isolation ensures one failing hook does not crash the server
BDD test coverage for all hook types

Subtasks

Implement HookEvent data model and LifecycleHooks registry
Implement server lifecycle hooks
Implement player lifecycle hooks
Implement object lifecycle hooks
Implement cancellable hook mechanism and error isolation

Definition of Done

This Epic is complete when all child issues are closed and all acceptance criteria
are satisfied.

## Metadata - **Commit Message**: `feat(lifecycle): implement lifecycle hook system` - **Branch**: `feature/lifecycle-hooks` ## Background and Context The specification (§ Lifecycle Hook System) describes a comprehensive hook-based event system that allows subsystems to register callbacks for server, player, and object lifecycle transitions. Currently, initialization logic is scattered across `Manager#initialize`, `Server#initialize`, and individual object constructors with no decoupled notification mechanism. The lifecycle hook system is a prerequisite for: - Event sourcing integration (uses `on_boot`, `on_shutdown`, `on_save`, `on_create`, `on_destroy`) - Terminal UI framework (uses `on_connect`, `on_disconnect`, `on_room_change`) - Command dispatch pipeline (uses `on_tick` for cooldown expiration) ## Expected Behavior A `LifecycleHooks` registry provides `on`, `once`, `off`, and `emit` methods. Hooks are organized into server hooks, player hooks, and object hooks. Each hook receives a `HookEvent` with relevant context. Hooks support cancellation and error isolation. ## Acceptance Criteria - `HookEvent` data model implemented with `type`, `source`, `data`, `cancelled` fields - `LifecycleHooks` registry with `on`/`once`/`off`/`emit` API - Server hooks: `on_boot`, `on_shutdown`, `on_tick`, `on_save`, `on_reload` - Player hooks: `on_connect`, `on_login`, `on_logout`, `on_disconnect`, `on_death`, `on_respawn`, `on_room_change` - Object hooks: `on_create`, `on_destroy`, `on_load`, `on_object_save` - Cancellable hook mechanism prevents downstream handlers from executing - Error isolation ensures one failing hook does not crash the server - BDD test coverage for all hook types ## Subtasks - [ ] Implement HookEvent data model and LifecycleHooks registry - [ ] Implement server lifecycle hooks - [ ] Implement player lifecycle hooks - [ ] Implement object lifecycle hooks - [ ] Implement cancellable hook mechanism and error isolation ## Definition of Done This Epic is complete when all child issues are closed and all acceptance criteria are satisfied.