babylon.engine.observer

Observer protocol for simulation state change notifications.

The Observer Pattern separates the Material Base (simulation mechanics) from the Ideological Superstructure (AI narrative generation).

Observers are notified AFTER each tick completes and receive both the previous and new state for delta analysis. All state objects are frozen and immutable - observers cannot modify simulation state.

Design Decisions (Sprint 3.1): - Observer location: Simulation facade ONLY (step() remains pure) - Notification order: After state reconstruction - Error handling: Log and ignore (ADR003: “AI failures don’t break game”) - Lifecycle hooks: on_simulation_start, on_tick, on_simulation_end

Classes

SimulationObserver(*args, **kwargs)

Protocol for entities observing simulation state changes.

class babylon.engine.observer.SimulationObserver(*args, **kwargs)

Bases: Protocol

Protocol for entities observing simulation state changes.

Observers receive notifications at three lifecycle points: 1. on_simulation_start() - when simulation begins (first step) 2. on_tick() - after each tick completes 3. on_simulation_end() - when simulation ends (explicit end() call)

Note: All state objects (WorldState) are frozen and immutable. Attempting to modify them will raise AttributeError.

Example

>>> class MyObserver:
...     @property
...     def name(self) -> str:
...         return "MyObserver"
...
...     def on_simulation_start(
...         self, initial_state: WorldState, config: SimulationConfig
...     ) -> None:
...         print(f"Started at tick {initial_state.tick}")
...
...     def on_tick(
...         self, previous_state: WorldState, new_state: WorldState
...     ) -> None:
...         print(f"Tick {previous_state.tick} -> {new_state.tick}")
...
...     def on_simulation_end(self, final_state: WorldState) -> None:
...         print(f"Ended at tick {final_state.tick}")

property name: str

Observer identifier for logging and debugging.

Returns:

A string identifying this observer instance.

on_simulation_start(initial_state, config)

Called when simulation begins (on first step call).

Use this hook to initialize resources, establish context, or prepare for observing the simulation run.

Parameters:

• initial_state (WorldState) – The WorldState at tick 0 (before any steps).

• config (SimulationConfig) – The SimulationConfig for this run.

Return type:

None

on_tick(previous_state, new_state)

Called after each tick completes with both states for delta analysis.

This is the primary notification hook. Observers receive both the previous and new state to enable delta analysis (what changed).

Parameters:

• previous_state (WorldState) – WorldState before the tick.

• new_state (WorldState) – WorldState after the tick.

Return type:

None

on_simulation_end(final_state)

Called when simulation ends (on explicit end() call).

Use this hook to cleanup resources, generate summaries, or finalize any accumulated data.

Parameters:

final_state (WorldState) – The final WorldState when simulation ends.

Return type:

None

__init__(*args, **kwargs)