Entities Module

The entities module defines agents, NPCs, and their components.

Base Entity

class simulation_framework.src.entities.base.Entity(position: Tuple[int, int], name: str = 'Entity', stats: Stats | None = None, inventory_capacity: int = 50)

Bases: ABC

apply_status_effect(effect: StatusEffect) → None

can_see(other: Entity, range_override: float | None = None) → bool

can_see_position(x: int, y: int, range_override: float | None = None) → bool

distance_to(other: Entity) → float

distance_to_position(x: int, y: int) → float

has_status_effect(effect_name: str) → bool

move_to(x: int, y: int, world: World) → bool

abstract on_death(killer: Entity | None = None) → None

remove_status_effect(effect_name: str) → None

take_damage(amount: int, attacker: Entity | None = None) → int

abstract update(world: World) → None

update_status_effects() → None

class simulation_framework.src.entities.base.StatusEffect(name: str, duration: int, effect_type: str = 'neutral', power: float = 0)

Bases: object

apply_effect(entity: Entity) → None

refresh(additional_duration: int) → None

update(entity: Entity) → bool

Agent

class simulation_framework.src.entities.agent.Agent(position: Tuple[int, int], name: str = 'Agent', personality: Personality | None = None, character_class: CharacterClass | None = None, stats: Stats | None = None)

Bases: Entity

act(world: World) → None

Execute actions based on current goals

add_relationship(entity_id: int, relationship_change: float) → None

Modify relationship with another entity

decide(world: World) → None

Make decisions about what to do next

get_agent_summary() → Dict

Get a summary of the agent’s state for debugging/analysis

get_dominant_skills(threshold: int = 5) → List[Tuple[str, int]]

Get skills above the threshold

get_relationship(entity_id: int) → float

Get relationship level with another entity (-1 to 1)

get_skill_level(skill_name: str) → int

Get current level in a skill

is_hostile_to(entity: Entity) → bool

Check if this agent is hostile to another entity

on_death(killer: Entity | None = None) → None

Handle agent death

perceive(world: World) → None

Update agent’s knowledge of the world

update(world: World) → None

Main update loop for agent AI

simulation_framework.src.entities.agent.create_agent_with_archetype(position: Tuple[int, int], archetype: str, name: str | None = None) → Agent

Create an agent based on a personality archetype

simulation_framework.src.entities.agent.create_random_agent(position: Tuple[int, int], name: str | None = None) → Agent

Create an agent with randomized personality and class

NPC

class simulation_framework.src.entities.npc.NPC(position: Tuple[int, int], name: str = 'NPC', npc_type: str = 'neutral', stats: Stats | None = None, loot_table: LootTable | None = None, spawn_point: Tuple[int, int] | None = None, tether_radius: int = 10)

Bases: Entity

add_patrol_point(point: Tuple[int, int]) → None

get_threat_level() → str

is_hostile_to(entity: Entity) → bool

on_death(killer: Entity | None = None) → None

set_aggressive(aggressive: bool = True) → None

set_patrol_route(points: List[Tuple[int, int]]) → None

set_target(target: Entity) → None

Set a target for combat - called by simulation when agent comes within aggro range

update(world: World) → None

simulation_framework.src.entities.npc.create_basic_goblin(position: Tuple[int, int]) → NPC

simulation_framework.src.entities.npc.create_forest_wolf(position: Tuple[int, int]) → NPC

simulation_framework.src.entities.npc.create_peaceful_villager(position: Tuple[int, int]) → NPC

Stats

class simulation_framework.src.entities.stats.Stats(max_health: 'int' = 100, health: 'int' = 100, max_stamina: 'int' = 100, stamina: 'int' = 100, max_magic: 'int' = 50, magic: 'int' = 50, attack_power: 'int' = 10, defense: 'int' = 5, speed: 'int' = 5)

Bases: object

attack_power: int = 10

defense: int = 5

classmethod from_dict(data: Dict) → Stats

get_health_percentage() → float

get_magic_percentage() → float

get_stamina_percentage() → float

heal(amount: int) → int

health: int = 100

is_alive() → bool

magic: int = 50

max_health: int = 100

max_magic: int = 50

max_stamina: int = 100

reset() → None

restore_magic(amount: int) → int

restore_stamina(amount: int) → int

speed: int = 5

stamina: int = 100

take_damage(amount: int) → int

to_dict() → Dict

use_magic(amount: int) → bool

use_stamina(amount: int) → bool

Inventory

class simulation_framework.src.entities.inventory.Inventory(capacity: int = 50)

Bases: object

add_item(item: Item, quantity: int = 1) → int

clear() → None

equip_tool(tool: Item, tool_type: str) → Item | None

equip_weapon(weapon: Item) → Item | None

classmethod from_dict(data: Dict, item_loader) → Inventory

get_all_items() → List[InventorySlot]

get_equipped_tool(tool_type: str) → Item | None

get_equipped_weapon() → Item | None

get_item_count(item_name: str) → int

get_total_items() → int

has_item(item_name: str, quantity: int = 1) → bool

remove_item(item_name: str, quantity: int = 1) → bool

to_dict() → Dict

class simulation_framework.src.entities.inventory.InventorySlot(item: 'Item', quantity: 'int')

Bases: object

add(amount: int) → int

item: Item

quantity: int