Hooks and ingress identity

Package	Value
Distribution	archetype-ecs
Import package	archetype

Extension API. React to world lifecycle events and define the identity record used by trusted ingress adapters.

ActorCtx

Stable caller identity and its flat role grants.

Field	Type	Default	Description
id	UUID	required	Stable actor identifier used by access evidence.
roles	set[str]	generated by <lambda>	Flat role grants authenticated for this actor.

HookEvent dataclass

HookEvent(world_id)

Base type for all world lifecycle hook events.

Field	Type	Default
world_id	str	required

PreTick dataclass

PreTick(world_id, tick)

Fire before processors run for a tick.

Field	Type	Default
world_id	str	required
tick	int	required

PostTick dataclass

PostTick(world_id, tick, results)

Fire after processors finish and the tick is persisted.

tick is the next tick; the completed tick is tick - 1.

Field	Type	Default
world_id	str	required
tick	int	required
results	dict[ArchetypeSignature, DataFrame]	required

OnSpawn dataclass

OnSpawn(world_id, entity_id, components)

Fire after an entity is registered but before its first row is persisted.

Field	Type	Default
world_id	str	required
entity_id	int	required
components	list[Component]	required

OnDespawn dataclass

OnDespawn(world_id, entity_id)

Fire after an entity is removed from active state.

Field	Type	Default
world_id	str	required
entity_id	int	required

OnComponentAdded dataclass

OnComponentAdded(world_id, entity_id, components)

Fire after component types are added to an entity.

components contains the supplied additions, not the entity's complete component set.

Field	Type	Default
world_id	str	required
entity_id	int	required
components	list[Component]	required

OnComponentRemoved dataclass

OnComponentRemoved(world_id, entity_id, component_types)

Fire after component types are removed from an entity.

Field	Type	Default
world_id	str	required
entity_id	int	required
component_types	list[type[Component]]	required

OnDestroy dataclass

OnDestroy(world_id)

Fire immediately before a world is destroyed.

Handlers can perform cleanup or final reads while the world is still live.

Field	Type	Default
world_id	str	required

HookHandle dataclass

HookHandle(_id, _event_type, _registry_token)

Opaque token used to remove a registered hook.

Handles are scoped to the world and hook registry that created them.

id property

id

Registry-local identifier (stable for the handle's lifetime).

event_type property

event_type

The event type this handle's handler is registered for.