babylon.engine.history.auto_checkpoint

Auto-checkpointing for the History Stack system.

This module provides: - AutoCheckpointer: A stateful class managing periodic checkpoint creation - create_checkpointed_step: A wrapper for integrating checkpoints with game loop

The checkpointing system follows the Observer pattern: - The game loop (step function) remains pure - The AutoCheckpointer observes state changes and creates checkpoints as side effects

Sprint D: Auto-checkpointing for Phase 3 persistence layer.

Functions

create_checkpointed_step(sim_config, ...)

Create a wrapper function that checkpoints after each step.

Classes

AutoCheckpointer(config[, base_dir])

Stateful checkpoint manager for automatic periodic saves.
class babylon.engine.history.auto_checkpoint.AutoCheckpointer(config, base_dir=None)[source]

Bases: object

Stateful checkpoint manager for automatic periodic saves.

AutoCheckpointer integrates with the game loop to create checkpoints at configurable intervals without modifying the pure step function.

Parameters:
config

The CheckpointConfig controlling behavior.

checkpoint_dir

The directory where checkpoints are saved.

__init__(config, base_dir=None)[source]

Initialize the auto-checkpointer.

Parameters:

  • config (CheckpointConfig) – Configuration for checkpointing behavior.

  • base_dir (Path | None) – Base directory for checkpoint storage. Defaults to current dir.

Return type:

None

property checkpoint_dir: Path

Get the checkpoint directory path.

on_step(state, sim_config)[source]

Check if a checkpoint should be created after a step.

Called after each simulation step. Creates a checkpoint if: - Auto-checkpointing is enabled - The current tick is a multiple of the interval (including 0)

Parameters:
Return type:

Path | None

Returns:

Path to the created checkpoint, or None if no checkpoint was created.

force_checkpoint(state, sim_config, description='')[source]

Force creation of a checkpoint regardless of interval.

Useful for manual saves or important milestones.

Parameters:

  • state (WorldState) – The WorldState to checkpoint.

  • sim_config (SimulationConfig) – The SimulationConfig to include.

  • description (str) – Optional description for the checkpoint.

Return type:

Path

Returns:

Path to the created checkpoint.

rotate_checkpoints()[source]

Remove old checkpoints to stay within max_checkpoints limit.

Removes the oldest checkpoints when the count exceeds max_checkpoints. If max_checkpoints is 0 (unlimited), no rotation occurs.

Return type:

list[Path]

Returns:

List of paths that were removed.

get_latest_checkpoint()[source]

Get the path to the most recent checkpoint.

Return type:

Path | None

Returns:

Path to the newest checkpoint, or None if no checkpoints exist.

babylon.engine.history.auto_checkpoint.create_checkpointed_step(sim_config, checkpointer)[source]

Create a wrapper function that checkpoints after each step.

This enables integration of checkpointing with the pure game loop without modifying the step function itself.

Usage:

checkpointer = AutoCheckpointer(checkpoint_config) checkpointed_step = create_checkpointed_step(sim_config, checkpointer)

for _ in range(100):

state, checkpoint_path = checkpointed_step(state) # checkpoint_path is None unless a checkpoint was created

Parameters:
Return type:

Callable[[WorldState], tuple[WorldState, Path | None]]

Returns:

A callable that takes WorldState and returns (WorldState, Path | None).