World System¶

The world module provides world/map management, locations, tiles, and pathfinding.

World and Locations¶

World and map system.

This module provides the world/map system for managing locations, areas, and navigation.

class barebones_rpg.world.world.Tile(**data)[source]¶

Bases: BaseModel

A single tile in a map.

Tiles can have different properties like walkability, events, etc.

x: int¶

y: int¶

tile_type: str¶

walkable: bool¶

sprite_id: Optional[str]¶

on_enter: Optional[Callable]¶

metadata: Dict[str, Any]¶

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

can_enter(entity)[source]¶

Check if an entity can enter this tile.

Parameters:: entity (Any) – Entity attempting to enter
Return type:: bool
Returns:: True if tile can be entered

class barebones_rpg.world.world.Location(*, id=<factory>, name, description='', width=20, height=20, tiles=<factory>, default_tile_type='grass', entities=<factory>, connections=<factory>, on_enter=None, on_exit=None, metadata=<factory>)[source]¶

Bases: BaseModel

A location in the world (town, dungeon, area, etc.).

Locations contain a grid of tiles and can have entities.

Example

>>> location = Location(
...     name="Village Square",
...     width=20,
...     height=20
... )
>>> # Add some walls
>>> for x in range(20):
...     location.set_tile(x, 0, Tile(x=x, y=0, tile_type="wall", walkable=False))

id: str¶

name: str¶

description: str¶

width: int¶

height: int¶

tiles: Dict[Tuple[int, int], Tile]¶

default_tile_type: str¶

entities: List[Any]¶

connections: Dict[str, str]¶

on_enter: Optional[Callable]¶

on_exit: Optional[Callable]¶

metadata: Dict[str, Any]¶

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

__init__(**data)[source]¶

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

get_tile(x, y)[source]¶

Get a tile at coordinates.

Parameters:

x (int) – X coordinate
y (int) – Y coordinate

Return type:

Optional[Tile]

Returns:

Tile or None if out of bounds

set_tile(x, y, tile)[source]¶

Set a tile at coordinates.

Parameters:

x (int) – X coordinate
y (int) – Y coordinate
tile (Tile) – Tile to set

Return type:

bool

Returns:

True if tile was set successfully (within bounds)

is_walkable(x, y)[source]¶

Check if a position is walkable.

Parameters:

x (int) – X coordinate
y (int) – Y coordinate

Return type:

bool

Returns:

True if position can be walked on

get_entity_at(x, y)[source]¶

Get an entity at a position.

Parameters:

x (int) – X coordinate
y (int) – Y coordinate

Return type:

Optional[Any]

Returns:

Entity at position or None

add_entity(entity, x=None, y=None)[source]¶

Add an entity to the location.

Parameters:

entity (Any) – Entity to add
x (Optional[int]) – X coordinate (uses entity’s position if None)
y (Optional[int]) – Y coordinate (uses entity’s position if None)

Return type:

bool

Returns:

True if entity was added successfully

remove_entity(entity)[source]¶

Remove an entity from the location.

Parameters:: entity (Any) – Entity to remove
Return type:: bool
Returns:: True if entity was found and removed

find_entity_by_name(name)[source]¶

Find an entity by name.

Parameters:: name (str) – Entity name to search for
Return type:: Optional[Any]
Returns:: First entity with matching name or None

find_entities_by_name(name)[source]¶

Find all entities with a given name.

Parameters:: name (str) – Entity name to search for
Return type:: List[Any]
Returns:: List of entities with matching name

find_entities_by_faction(faction)[source]¶

Find all entities of a given faction.

Parameters:: faction (str) – Faction to search for (e.g., “enemy”, “player”, “neutral”)
Return type:: List[Any]
Returns:: List of entities with matching faction

has_entity_named(name)[source]¶

Check if an entity with the given name exists in this location.

Parameters:: name (str) – Entity name to check for
Return type:: bool
Returns:: True if entity exists

add_connection(direction, location_id)[source]¶

Add a connection to another location.

Parameters:

direction (str) – Direction name (north, south, east, west, etc.)
location_id (str) – ID of connected location

Return type:

None

get_connection(direction)[source]¶

Get connected location ID for a direction.

Parameters:: direction (str) – Direction name
Return type:: Optional[str]
Returns:: Location ID or None

create_border_walls(tile_type='wall')[source]¶

Create walls around the border of the location.

This is a helper method for quickly creating enclosed areas.

Parameters:: tile_type (str) – Type of tile to use for walls (default: “wall”)
Return type:: None

create_room(x, y, width, height, wall_type='wall', floor_type=None, fill_interior=False)[source]¶

Create a rectangular room with walls.

Parameters:

x (int) – Top-left X coordinate
y (int) – Top-left Y coordinate
width (int) – Width of the room
height (int) – Height of the room
wall_type (str) – Type of tile to use for walls (default: “wall”)
floor_type (Optional[str]) – Type of tile to use for interior floor (optional)
fill_interior (bool) – Whether to fill the interior with floor tiles

Return type:

None

create_horizontal_wall(start_x, end_x, y, tile_type='wall')[source]¶

Create a horizontal wall segment.

Parameters:

start_x (int) – Starting X coordinate
end_x (int) – Ending X coordinate (inclusive)
y (int) – Y coordinate
tile_type (str) – Type of tile to use for walls (default: “wall”)

Return type:

None

create_vertical_wall(x, start_y, end_y, tile_type='wall')[source]¶

Create a vertical wall segment.

Parameters:

x (int) – X coordinate
start_y (int) – Starting Y coordinate
end_y (int) – Ending Y coordinate (inclusive)
tile_type (str) – Type of tile to use for walls (default: “wall”)

Return type:

None

create_corridor(start, end, width=1, floor_type=None)[source]¶

Create a corridor between two points.

Creates an L-shaped corridor (horizontal then vertical).

Parameters:

start (Tuple[int, int]) – Starting position (x, y)
end (Tuple[int, int]) – Ending position (x, y)
width (int) – Width of the corridor (default: 1)
floor_type (Optional[str]) – Type of tile to use for corridor floor (optional)

Return type:

None

fill_rect(x, y, width, height, tile_type, walkable=True)[source]¶

Fill a rectangular area with a specific tile type.

Parameters:

x (int) – Top-left X coordinate
y (int) – Top-left Y coordinate
width (int) – Width of the area
height (int) – Height of the area
tile_type (str) – Type of tile to fill with
walkable (bool) – Whether the tiles should be walkable

Return type:

None

class barebones_rpg.world.world.World(**data)[source]¶

Bases: BaseModel

The game world containing all locations.

Example

>>> world = World(name="Fantasy World")
>>> village = Location(name="Starting Village", width=30, height=30)
>>> forest = Location(name="Dark Forest", width=40, height=40)
>>> world.add_location(village)
>>> world.add_location(forest)
>>> world.connect_locations(village.id, "north", forest.id)

id: str¶

name: str¶

description: str¶

locations: Dict[str, Location]¶

current_location_id: Optional[str]¶

metadata: Dict[str, Any]¶

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

add_location(location)[source]¶

Add a location to the world.

Parameters:: location (Location) – Location to add
Return type:: bool
Returns:: True if location was added successfully

get_location(location_id)[source]¶

Get a location by ID.

Parameters:: location_id (str) – Location ID
Return type:: Optional[Location]
Returns:: Location or None

get_location_by_name(name)[source]¶

Get a location by name.

Parameters:: name (str) – Location name
Return type:: Optional[Location]
Returns:: Location or None

get_current_location()[source]¶

Get the current active location.

Return type:: Optional[Location]
Returns:: Current location or None

set_current_location(location_id, events=None)[source]¶

Set the current location.

Parameters:

location_id (str) – ID of location to make current
events (Optional[EventManager]) – Event manager for publishing events

Return type:

bool

Returns:

True if location was changed

connect_locations(from_location_id, direction, to_location_id, bidirectional=False)[source]¶

Connect two locations.

Parameters:

from_location_id (str) – Starting location ID
direction (str) – Direction of connection
to_location_id (str) – Destination location ID
bidirectional (bool) – If True, create reverse connection too

Return type:

None

move_entity(entity, to_location_id, x=None, y=None)[source]¶

Move an entity to a different location.

Parameters:

entity (Any) – Entity to move
to_location_id (str) – Destination location ID
x (Optional[int]) – X coordinate in new location
y (Optional[int]) – Y coordinate in new location

Return type:

bool

Returns:

True if entity was moved

save()[source]¶

Save world state.

Return type:: Dict[str, Any]
Returns:: Dictionary representation

load(data)[source]¶

Load world state.

Parameters:: data (Dict[str, Any]) – Saved world data
Return type:: None

Action Points¶

Action Points (AP) system for turn-based tile movement.

This module provides an Action Points system commonly used in turn-based tile-based RPGs where movement costs action points per tile.

class barebones_rpg.world.action_points.APManager(player_ap=5, enemy_ap=3, npc_ap=0, ap_cost_per_tile=1)[source]¶

Bases: object

Manages Action Points for turn-based movement.

This class handles: - Tracking AP for entities - Calculating valid moves based on remaining AP - Processing movement with AP costs - Turn management

Parameters:

player_ap (int) – Default AP for player entities (default: 5)
enemy_ap (int) – Default AP for enemy entities (default: 3)
npc_ap (int) – Default AP for NPC entities (default: 0)
ap_cost_per_tile (int) – AP cost to move one tile (default: 1)

__init__(player_ap=5, enemy_ap=3, npc_ap=0, ap_cost_per_tile=1)[source]¶

Initialize the AP manager.

get_default_ap(entity)[source]¶

Get the default AP for an entity based on its faction.

Parameters:: entity (Entity) – The entity to get default AP for
Return type:: int
Returns:: Default AP value for the entity’s faction

start_turn(entity)[source]¶

Start a turn for an entity, resetting their AP.

Parameters:: entity (Entity) – The entity starting their turn
Return type:: int
Returns:: The entity’s starting AP for this turn

get_remaining_ap(entity)[source]¶

Get the remaining AP for an entity.

Parameters:: entity (Entity) – The entity to check AP for
Return type:: int
Returns:: Remaining AP (0 if entity has no AP tracked)

spend_ap(entity, amount)[source]¶

Spend AP for an entity.

Parameters:

entity (Entity) – The entity spending AP
amount (int) – Amount of AP to spend

Return type:

bool

Returns:

True if AP was spent, False if not enough AP

calculate_valid_moves(entity, location, pathfinder=None)[source]¶

Calculate all valid moves for an entity based on their remaining AP.

Parameters:

entity (Entity) – The entity to calculate moves for
location (Location) – The location/map the entity is on
pathfinder (Optional[TilemapPathfinder]) – Optional pathfinder (will create one if not provided)

Return type:

Set[Tuple[int, int]]

Returns:

Set of (x, y) positions the entity can move to

calculate_movement_cost(path)[source]¶

Calculate the AP cost for a movement path.

Parameters:: path (List[Tuple[int, int]]) – List of positions in the path (including start position)
Return type:: int
Returns:: AP cost for the movement (excludes starting position)

can_afford_move(entity, path)[source]¶

Check if an entity can afford to move along a path.

Parameters:

entity (Entity) – The entity attempting to move
path (List[Tuple[int, int]]) – The movement path

Return type:

bool

Returns:

True if entity has enough AP for the move

process_movement(entity, location, target, pathfinder=None, on_move=None)[source]¶

Process a movement for an entity, consuming AP.

Parameters:

entity (Entity) – The entity moving
location (Location) – The location/map the entity is on
target (Tuple[int, int]) – Target position to move to
pathfinder (Optional[TilemapPathfinder]) – Optional pathfinder (will create one if not provided)
on_move (Optional[Callable[[Entity, Tuple[int, int], Tuple[int, int]], None]]) – Optional callback when movement succeeds (entity, old_pos, new_pos)

Return type:

bool

Returns:

True if movement was successful, False otherwise

has_ap_remaining(entity)[source]¶

Check if an entity has any AP remaining.

Parameters:: entity (Entity) – The entity to check
Return type:: bool
Returns:: True if entity has AP remaining

end_turn(entity)[source]¶

End the turn for an entity.

Parameters:: entity (Entity) – The entity ending their turn

reset()[source]¶: Reset all AP tracking (useful for starting a new encounter).

Tilemap Pathfinding¶

Tilemap-specific pathfinding utilities.

This module provides pathfinding algorithms specifically designed for tile-based maps. These utilities work with the Location class and assume grid-based movement.

Note: These pathfinding utilities are designed specifically for tile-based games.: For non-tile-based games, you’ll need different pathfinding approaches.

class barebones_rpg.world.tilemap_pathfinding.TilemapPathfinder(location, allow_diagonal=False)[source]¶

Bases: object

Pathfinding utilities for tile-based maps.

This class provides BFS pathfinding and flood-fill algorithms specifically designed for tile-based grid movement.

Parameters:

location (Location) – The tile-based Location to pathfind within
allow_diagonal (bool) – Whether to allow diagonal movement (default: False)

__init__(location, allow_diagonal=False)[source]¶

Initialize the pathfinder.

Parameters:

location (Location) – The tile-based Location to pathfind within
allow_diagonal (bool) – Whether to allow diagonal movement

get_directions()[source]¶

Get movement directions based on diagonal setting.

Return type:: List[Tuple[int, int]]
Returns:: List of (dx, dy) tuples for movement directions

get_manhattan_distance(pos1, pos2)[source]¶

Calculate Manhattan distance between two tile positions.

Parameters:

pos1 (Tuple[int, int]) – First position (x, y)
pos2 (Tuple[int, int]) – Second position (x, y)

Return type:

int

Returns:

Manhattan distance (sum of absolute differences)

find_path(start, goal, allow_occupied_goal=True)[source]¶

Find shortest path from start to goal using BFS.

Parameters:

start (Tuple[int, int]) – Starting tile position (x, y)
goal (Tuple[int, int]) – Goal tile position (x, y)
allow_occupied_goal (bool) – Whether to allow pathing to an occupied tile

Return type:

List[Tuple[int, int]]

Returns:

List of positions from start to goal (inclusive), or empty list if no path

calculate_reachable_tiles(start, max_distance, allow_occupied=False)[source]¶

Calculate all tiles reachable within a distance using flood fill.

This is useful for showing movement range, spell range, etc.

Parameters:

start (Tuple[int, int]) – Starting tile position (x, y)
max_distance (int) – Maximum distance to flood fill
allow_occupied (bool) – Whether occupied tiles block further flooding

Return type:

Set[Tuple[int, int]]

Returns:

Set of reachable tile positions

get_neighbors(pos, walkable_only=True)[source]¶

Get all neighboring tiles to a position.

Parameters:

pos (Tuple[int, int]) – Tile position (x, y)
walkable_only (bool) – Whether to only return walkable neighbors

Return type:

List[Tuple[int, int]]

Returns:

List of neighboring tile positions