Systems Module

The systems module contains game systems like fog of war, trading, combat, and respawning.

Fog of War

class simulation_framework.src.systems.fog_of_war.FogOfWar(world_width: int, world_height: int)

Bases: object

Manages what each agent can see and remember

can_see_entity(agent_id: int, entity: Entity) → bool

Check if an agent can currently see a specific entity

can_see_tile(agent_id: int, position: Tuple[int, int]) → bool

Check if an agent can currently see a specific tile

clear_agent_data(agent_id: int) → None

Clear all fog of war data for an agent (when they die, etc.)

forget_old_memories(agent_id: int, current_tick: int) → None

Remove old memories that are beyond the memory duration

get_exploration_targets(agent_id: int, agent_position: Tuple[int, int], max_distance: int = 15) → list[Tuple[int, int]]

Get potential exploration targets (unknown or old tiles) near the agent

get_known_tiles(agent_id: int) → Set[Tuple[int, int]]

Get all tiles that an agent has seen at some point

get_pathfinding_grid(agent_id: int, world: World) → list

Get a pathfinding grid based on what the agent knows

get_remembered_tile_info(agent_id: int, position: Tuple[int, int]) → Dict | None

Get what an agent remembers about a tile

get_visible_entities(agent_id: int, world: World) → Dict[int, Entity]

Get all entities currently visible to an agent

update_agent_vision(agent: Entity, world: World) → None

Update what an agent can currently see

Trading System

class simulation_framework.src.systems.trading.Market

Bases: object

Central market system for tracking supply, demand, and prices

get_current_prices() → Dict[str, float]

Get current market prices

get_market_summary() → Dict

Get current market state summary

get_price(item_name: str) → float

Get current market price of an item

record_trade(item_name: str, quantity: int, price: float) → None

Record a completed trade

update_demand(item_name: str, change: int) → None

Update demand for an item

update_prices(current_tick: int) → None

Update market prices based on time and market dynamics

update_supply(item_name: str, change: int) → None

Update supply of an item

class simulation_framework.src.systems.trading.TradeOffer(id: int, initiator_id: int, target_id: int, offered_items: List[Tuple[str, int]], requested_items: List[Tuple[str, int]], offered_gold: int = 0, requested_gold: int = 0, status: TradeStatus = TradeStatus.PENDING, created_tick: int = 0, expires_tick: int = 0)

Bases: object

Represents a trade offer between two entities

created_tick: int = 0

expires_tick: int = 0

get_total_offered_value() → float

Calculate total value of offered items and gold

get_total_requested_value() → float

Calculate total value of requested items and gold

id: int

initiator_id: int

is_expired(current_tick: int) → bool

offered_gold: int = 0

offered_items: List[Tuple[str, int]]

requested_gold: int = 0

requested_items: List[Tuple[str, int]]

status: TradeStatus = 'pending'

target_id: int

class simulation_framework.src.systems.trading.TradeStatus(value)

Bases: Enum

An enumeration.

ACCEPTED = 'accepted'

CANCELLED = 'cancelled'

COMPLETED = 'completed'

PENDING = 'pending'

REJECTED = 'rejected'

class simulation_framework.src.systems.trading.TradingSystem

Bases: object

Manages trading between entities

accept_trade_offer(accepter: Entity, offer_id: int) → bool

Accept a trade offer and execute the trade

cleanup_expired_offers(current_tick: int) → None

Remove expired trade offers

create_trade_offer(initiator: Entity, target: Entity, offered_items: List[Tuple[str, int]] = None, requested_items: List[Tuple[str, int]] = None, offered_gold: int = 0, requested_gold: int = 0, duration: int = 100) → TradeOffer | None

Create a new trade offer

evaluate_trade_offer(target: Entity, offer_id: int) → Tuple[bool, float]

Evaluate a trade offer and return (should_accept, utility_score)

get_completed_trades() → List[Dict]

Get list of completed trades (for logging)

get_pending_offers_for_entity(entity_id: int) → List[TradeOffer]

Get all pending trade offers for an entity

get_trade_summary() → Dict

Get trading system summary for debugging

reject_trade_offer(rejector: Entity, offer_id: int) → bool

Reject a trade offer

update(current_tick: int) → None

Update trading system - clean up expired offers

Combat Resolver

class simulation_framework.src.systems.combat_resolver.CombatResolver

Bases: object

calculate_damage(attacker: Entity, defender: Entity, base_damage: int, damage_type: str = 'physical', critical_chance: float = 0.0, critical_multiplier: float = 2.0) → Tuple[int, bool, Dict]

calculate_hit_chance(attacker: Entity, defender: Entity, base_accuracy: float = 0.9, range_penalty: float = 0.0) → float

get_combat_modifiers(entity: Entity) → Dict

resolve_attack(attacker: Entity, defender: Entity, weapon_damage: int, damage_type: str = 'physical', critical_chance: float = 0.1, critical_multiplier: float = 2.0, base_accuracy: float = 0.9, attack_range: float = 1.0) → Dict

class simulation_framework.src.systems.combat_resolver.DamageType

Bases: object

DARK = 'dark'

FIRE = 'fire'

HOLY = 'holy'

ICE = 'ice'

MAGICAL = 'magical'

PHYSICAL = 'physical'

POISON = 'poison'

Respawn Manager

class simulation_framework.src.systems.respawn.RespawnEntry(entity_id: int, entity_type: RespawnType, respawn_tick: int, original_position: Tuple[int, int], respawn_data: Dict, death_tick: int, respawn_attempts: int = 0, max_respawn_attempts: int = 3)

Bases: object

Represents an entity scheduled for respawn

death_tick: int

entity_id: int

entity_type: RespawnType

max_respawn_attempts: int = 3

original_position: Tuple[int, int]

respawn_attempts: int = 0

respawn_data: Dict

respawn_tick: int

class simulation_framework.src.systems.respawn.RespawnManager(world_width: int, world_height: int)

Bases: object

Manages entity respawning and resource regeneration

add_restricted_zone(center_x: int, center_y: int, radius: int) → None

Add a restricted zone where entities shouldn’t respawn

add_safe_zone(center_x: int, center_y: int, radius: int) → None

Add a safe zone for respawning

cancel_respawn(entity_id: int) → bool

Cancel a pending respawn

get_entity_respawn_info(entity_id: int) → Dict | None

Get respawn information for a specific entity

get_respawn_summary() → Dict

Get respawn system summary for debugging

maintain_population(world: World) → None

Maintain target population levels

process_respawns(world: World) → List[Entity]

Process all pending respawns and return newly spawned entities

schedule_respawn(entity: Entity, entity_type: RespawnType, world: World, custom_delay: int | None = None) → bool

Schedule an entity for respawn

class simulation_framework.src.systems.respawn.RespawnType(value)

Bases: Enum

An enumeration.

AGENT = 'agent'

NPC = 'npc'

RESOURCE_NODE = 'resource_node'

STRUCTURE = 'structure'

Pathfinding

class simulation_framework.src.systems.pathfinding.Pathfinder(diagonal_movement: bool = True)

Bases: object

can_reach(start: Tuple[int, int], goal: Tuple[int, int], world: World, known_tiles: Set[Tuple[int, int]] | None = None) → bool

clear_cache() → None

distance_heuristic(pos1: Tuple[int, int], pos2: Tuple[int, int]) → float

find_path(start: Tuple[int, int], goal: Tuple[int, int], world: World, known_tiles: Set[Tuple[int, int]] | None = None) → List[Tuple[int, int]]

find_path_to_nearest(start: Tuple[int, int], targets: List[Tuple[int, int]], world: World, known_tiles: Set[Tuple[int, int]] | None = None) → Tuple[Tuple[int, int] | None, List[Tuple[int, int]]]

get_cache_size() → int

get_next_step(start: Tuple[int, int], goal: Tuple[int, int], world: World, known_tiles: Set[Tuple[int, int]] | None = None) → Tuple[int, int] | None

class simulation_framework.src.systems.pathfinding.PathfindingMap(world: World, known_tiles: Set[Tuple[int, int]] | None = None)

Bases: object

get_grid() → Grid

refresh() → None