Core Module

The core module contains the main simulation orchestration and world management.

Simulation

class simulation_framework.src.core.simulation.Simulation(config: SimulationConfig)

Bases: object

Main simulation orchestrator that manages the game loop and all systems

add_agent(agent: Agent) → None

Add an agent to the simulation

add_agents(agents: List[Agent]) → None

Add multiple agents to the simulation

add_npc(npc: NPC) → None

Add an NPC to the simulation

add_npcs(npcs: List[NPC]) → None

Add multiple NPCs to the simulation

get_analytics_report() → Dict[str, Any] | None

Get comprehensive analytics report

get_statistics() → Dict[str, Any]

Get current simulation statistics

initialize_simulation(name: str, description: str = '') → None

Initialize a new simulation run in the database

pause_simulation() → None

Pause the simulation

resume_simulation() → None

Resume the simulation

run(num_ticks: int | None = None) → None

Run the simulation for a specified number of ticks

run_until(condition: Callable[[Simulation], bool]) → None

Run the simulation until a condition is met

run_with_visualizer(num_ticks: int | None = None) → None

Run the simulation with pygame visualization

step() → None

Execute one simulation tick

stop_simulation() → None

Stop the simulation and finalize

World

class simulation_framework.src.core.world.World(width: int, height: int, seed: int | None = None)

Bases: object

add_entity(entity: Entity) → None

get_entities_at(x: int, y: int) → Set[Entity]

get_entities_in_range(x: int, y: int, radius: float) → List[Tuple[Entity, float]]

get_neighbors(x: int, y: int, diagonal: bool = True) → List[Tuple[int, int]]

get_passable_neighbors(x: int, y: int, diagonal: bool = True) → List[Tuple[int, int]]

get_spawn_points(zone_name: str) → List[Tuple[int, int]]

get_terrain_distribution() → Dict[str, float]

get_tile(x: int, y: int) → Tile | None

is_passable(x: int, y: int) → bool

is_valid_position(x: int, y: int) → bool

move_entity(entity: Entity, new_x: int, new_y: int) → bool

remove_entity(entity_id: int) → None

tick() → None

Configuration

class simulation_framework.src.core.config.SimulationConfig(world_width: int = 50, world_height: int = 50, world_seed: int = 42, max_ticks: int = 10000, tick_rate: float = 0.0, database_path: str = <factory>, save_interval: int = 100, analytics_interval: int = 50, max_agents: int = 100, default_agent_vision_range: int = 5, default_agent_stamina: int = 100, default_agent_health: int = 100, max_npcs: int = 100, npc_respawn_enabled: bool = True, starting_gold: int = 100, trade_cooldown: int = 10, enable_pathfinding_cache: bool = True, max_pathfinding_distance: int = 50, fog_of_war_enabled: bool = True, enable_visualizer: bool = False, visualizer_width: int = 1024, visualizer_height: int = 768, visualizer_tile_size: int = 20, log_level: str = 'INFO', debug_mode: bool = False, log_actions: bool = True, log_file: str | None = None, custom_params: ~typing.Dict[str, ~typing.Any] = <factory>)

Bases: object

Configuration for simulation parameters

analytics_interval: int = 50

copy() → SimulationConfig

Create a copy of this configuration

custom_params: Dict[str, Any]

database_path: str

debug_mode: bool = False

default_agent_health: int = 100

default_agent_stamina: int = 100

default_agent_vision_range: int = 5

enable_pathfinding_cache: bool = True

enable_visualizer: bool = False

fog_of_war_enabled: bool = True

classmethod from_dict(data: Dict[str, Any]) → SimulationConfig

Create configuration from dictionary

classmethod from_file(config_path: str) → SimulationConfig

Load configuration from JSON file

get(key: str, default: Any | None = None) → Any

Get configuration value by key (supports custom params)

log_actions: bool = True

log_file: str | None = None

log_level: str = 'INFO'

max_agents: int = 100

max_npcs: int = 100

max_pathfinding_distance: int = 50

max_ticks: int = 10000

npc_respawn_enabled: bool = True

save_interval: int = 100

set(key: str, value: Any) → None

Set configuration value by key

starting_gold: int = 100

tick_rate: float = 0.0

to_dict() → Dict[str, Any]

Convert configuration to dictionary

to_file(config_path: str) → None

Save configuration to JSON file

trade_cooldown: int = 10

validate() → None

Validate configuration parameters

visualizer_height: int = 768

visualizer_tile_size: int = 20

visualizer_width: int = 1024

world_height: int = 50

world_seed: int = 42

world_width: int = 50

simulation_framework.src.core.config.get_default_database_path() → str

Get default database path with automatic cleanup

Time Manager

class simulation_framework.src.core.time_manager.TimeManager

Bases: object

Manages simulation time and tick progression

__str__() → str

String representation of current time

get_elapsed_real_time() → timedelta

Get elapsed real-world time since simulation start

get_game_time() → Dict[str, Any]

Get current game time representation

get_time_of_day_modifier() → float

Get time of day modifier for various activities

is_day_time() → bool

Check if it’s day time in the game world

is_night_time() → bool

Check if it’s night time in the game world

reset() → None

Reset the time manager to initial state

tick() → None

Advance time by one tick

ticks_since(past_tick: int) → int

Get number of ticks since a past tick