World Module

The world module handles terrain generation and tile management.

Generator

class simulation_framework.src.world.generator.WorldGenerator(seed: int | None = None)

Bases: object

generate_perlin_noise(width: int, height: int, octaves: int = 4, scale: float = 0.05) → ndarray

generate_world(width: int, height: int, add_spawn_zones: bool = True) → List[List[Tile]]

map_noise_to_terrain(noise_array: ndarray) → List[List[Tile]]

Terrain

class simulation_framework.src.world.terrain.TerrainProperties(passable: 'bool', fishable: 'bool', mineable: 'bool', harvestable: 'bool', movement_cost: 'float' = 1.0)

Bases: object

fishable: bool

classmethod for_terrain(terrain_type: TerrainType) → TerrainProperties

harvestable: bool

mineable: bool

movement_cost: float = 1.0

passable: bool

class simulation_framework.src.world.terrain.TerrainType(value)

Bases: Enum

An enumeration.

DESERT = 'desert'

FOREST = 'forest'

GRASS = 'grass'

MOUNTAIN = 'mountain'

WATER = 'water'

Tile

class simulation_framework.src.world.tile.ResourceDeposit(resource_type: 'str', quantity: 'int', respawn_time: 'int' = 75, last_harvested: 'int' = 0, max_quantity: 'int' = 0, partial_respawn_rate: 'int' = 3, partial_respawn_interval: 'int' = 15)

Bases: object

__post_init__()

Initialize max_quantity if not set

can_harvest(current_tick: int) → bool

harvest(amount: int, current_tick: int) → int

last_harvested: int = 0

max_quantity: int = 0

partial_respawn_interval: int = 15

partial_respawn_rate: int = 3

quantity: int

resource_type: str

respawn_time: int = 75

class simulation_framework.src.world.tile.Tile(x: int, y: int, terrain_type: TerrainType)

Bases: object

add_resource(resource: ResourceDeposit) → None

add_spawn_zone(zone_name: str) → None

can_gather(resource_type: str | None = None, current_tick: int = 0) → bool

Check if resources can be gathered from this tile.

Parameters:

• resource_type – Specific resource type to check, or None for any resource

• current_tick – Current simulation tick for respawn checking

can_pass() → bool

get_movement_cost() → float

get_resources() → List[ResourceDeposit]

is_spawn_zone(zone_name: str | None = None) → bool

Resource Manager

Resource Manager for efficient resource tracking and querying.

Provides O(1) resource lookups instead of O(n²) world scanning. Tracks resource availability and respawn timing.

class simulation_framework.src.world.resource_manager.ResourceManager(world: World)

Bases: object

Centralized resource tracking system.

Maintains spatial index of all resources for efficient queries. Tracks resource availability and respawn timing.

cleanup_respawned_resources(current_tick: int) → int

Check depleted resources and mark them available if respawned. Returns count of resources that respawned.

get_all_resource_positions(resource_type: str) → List[Tuple[int, int]]

Get all positions containing a resource type

get_available_resources(resource_type: str, current_tick: int, agent_position: Tuple[int, int] | None = None, max_distance: float | None = None) → List[Tuple[int, int]]

Get list of available (harvestable) resource positions.

Parameters:

• resource_type – Type of resource to find

• current_tick – Current simulation tick

• agent_position – Optional agent position for distance filtering

• max_distance – Optional maximum distance from agent

Returns:

List of (x, y) positions with harvestable resources

get_nearest_resource(resource_type: str, agent_position: Tuple[int, int], current_tick: int) → Tuple[int, int] | None

Find the nearest available resource of given type

get_resource_statistics(resource_type: str | None = None) → Dict

Get statistics about resources

mark_resource_harvested(position: Tuple[int, int], resource_type: str, current_tick: int, respawn_time: int) → None

Mark a resource as harvested/depleted

update_resource_status(position: Tuple[int, int], resource_type: str, quantity: int, current_tick: int) → None

Update resource node status

class simulation_framework.src.world.resource_manager.ResourceNode(position: Tuple[int, int], resource_type: str, last_known_quantity: int = 0, last_checked_tick: int = 0, is_depleted: bool = False, respawn_tick: int = 0)

Bases: object

Represents a resource location in the world

is_depleted: bool = False

last_checked_tick: int = 0

last_known_quantity: int = 0

position: Tuple[int, int]

resource_type: str

respawn_tick: int = 0