API Documentation¶

This section provides detailed API documentation for all modules in Yendoria.

Code Quality Standards: All modules follow strict typing, documentation, and quality standards enforced by our CI/CD pipeline including MyPy type checking, Ruff linting, and comprehensive test coverage.

Core Modules¶

Game Engine¶

Main entry point for Yendoria.

This module contains the main function that initializes and starts the game engine.

yendoria.main.main()[source]¶

Main function to start Yendoria.

Initializes the game engine and starts the main game loop.

Return type:: None

Game engine for Yendoria.

This module contains the main GameEngine class that coordinates all game systems and manages the main game loop.

class yendoria.engine.GameEngine(width=80, height=50, headless=False)[source]¶

Bases: object

Main game engine that coordinates all game systems.

game_map¶

The current game map

Type:: GameMap

entities¶

List of all entities in the game

Type:: List[Entity]

player¶

The player entity

Type:: Entity

renderer¶

Rendering system instance

Type:: RenderingSystem

is_running¶

Whether the game is currently running

Type:: bool

context: Context | None¶

handle_events()[source]¶

Handle input events.

Returns:: True if player took a turn-consuming action
Return type:: bool

handle_player_action(action)[source]¶

Handle player actions.

Parameters:: action (str) – Action string from input handler
Returns:: True if action consumed player turn, False otherwise
Return type:: bool

render()[source]¶

Render the current game state.

Return type:: None

run()[source]¶

Main game loop.

Return type:: None

stop()[source]¶

Stop the game.

Return type:: None

update()[source]¶

Update game state.

Return type:: None

update_fov()[source]¶

Update the field of view based on player position.

Return type:: None

update_monsters()[source]¶

Update all monster AI using the AI system.

Return type:: None

Entity System¶

Entity module for Yendoria.

This module contains the Entity class which serves as a container for components in the Entity Component System architecture.

class yendoria.entities.entity.Entity(name='Entity', is_player=False)[source]¶

Bases: object

A generic entity in the game world.

Entities are containers for components. The specific behavior and properties of an entity are determined by its components.

name¶

Display name of the entity

Type:: str

is_player¶

True if this entity is the player

Type:: bool

add_component(component)[source]¶

Add a component to this entity.

Parameters:: component (Component) – The component to add
Return type:: None

get_component(component_type)[source]¶

Get a component by type name.

Parameters:: component_type (str) – Name of the component type (case insensitive)
Return type:: Component | None
Returns:: The component if found, None otherwise

has_component(component_type)[source]¶

Check if entity has a specific component type.

Parameters:: component_type (str) – Name of the component type (case insensitive)
Return type:: bool
Returns:: True if entity has the component, False otherwise

property is_alive: bool¶

Check if the entity is alive.

Returns:: True if entity has health component and current HP > 0

remove_component(component_type)[source]¶

Remove a component from this entity.

Parameters:: component_type (str) – Name of the component type to remove
Return type:: None

Player entity module.

This module contains functions for creating and managing the player entity.

yendoria.entities.player.create_player(x, y)[source]¶

Create a new player entity with all necessary components.

Parameters:

x (int) – Starting x coordinate
y (int) – Starting y coordinate

Returns:

A fully configured player entity

Return type:

Entity

yendoria.entities.player.move_player(player, dx, dy, game_map)[source]¶

Attempt to move the player in the given direction.

Parameters:

player (Entity) – The player entity
dx (int) – Change in x coordinate
dy (int) – Change in y coordinate
game_map (GameMap) – The game map to check for collision

Returns:

True if move was successful, False otherwise

Return type:

bool

Monster entity module.

This module contains functions for creating different types of monster entities.

yendoria.entities.monster.create_orc(x, y)[source]¶

Create an orc monster entity with basic AI and combat capabilities.

Parameters:

x (int) – Starting x coordinate
y (int) – Starting y coordinate

Returns:

A fully configured orc entity with Position, Health,: Graphic, AI, and Damage components

Return type:

Entity

yendoria.entities.monster.create_troll(x, y)[source]¶

Create a troll monster entity with basic AI and combat capabilities.

Parameters:

x (int) – Starting x coordinate
y (int) – Starting y coordinate

Returns:

A fully configured troll entity with Position, Health,: Graphic, AI, and Damage components

Return type:

Entity

yendoria.entities.monster.get_managers()[source]¶

Return type:: tuple[ComponentManager, AIManager]

Components¶

Base component class for the Entity Component System.

This module provides the base Component class that all game components inherit from, as well as specific component implementations.

class yendoria.components.component.AI(entity=None)[source]¶

Bases: Component

Base AI component for entity behavior.

This is a base class that specific AI behaviors should inherit from.

perform(game_map, entities)[source]¶

Perform AI action. Override in subclasses.

Parameters:

game_map (GameMap) – The current game map
entities (list[Entity]) – List of all entities in the game

Return type:

None

class yendoria.components.component.BasicMonsterAI(entity=None)[source]¶

Bases: AI

Basic AI that moves towards and attacks the player.

perform(game_map, entities)[source]¶

Move towards player if visible, attack if adjacent.

Parameters:

game_map (GameMap) – The current game map
entities (list[Entity]) – List of all entities in the game

Return type:

None

class yendoria.components.component.Component(entity=None)[source]¶

Bases: object

Base class for all components in the ECS system.

Components store data and state but no behavior logic. Systems operate on entities that have specific components.

class yendoria.components.component.Damage(amount, entity=None)[source]¶

Bases: Component

Component for entity damage dealing capability.

amount¶

Amount of damage this entity deals

Type:: int

class yendoria.components.component.Graphic(char, color, entity=None)[source]¶

Bases: Component

Component for entity visual representation.

char¶

Character code to display

Type:: int

color¶

RGB color tuple

Type:: Tuple[int, int, int]

class yendoria.components.component.Health(max_hp, entity=None)[source]¶

Bases: Component

Component for entity health and hit points.

current_hp¶

Current hit points

Type:: int

max_hp¶

Maximum hit points

Type:: int

heal(amount)[source]¶

Heal damage and return actual healing done.

Parameters:: amount (int) – Healing amount
Returns:: Actual healing done (may be less if at max HP)
Return type:: int

property is_alive: bool¶: Check if the entity is alive.

take_damage(amount)[source]¶

Take damage and return actual damage dealt.

Parameters:: amount (int) – Damage amount
Returns:: Actual damage dealt (may be less if kills entity)
Return type:: int

class yendoria.components.component.Position(x, y, entity=None)[source]¶

Bases: Component

Component for entity position on the game map.

x¶

X coordinate

Type:: int

y¶

Y coordinate

Type:: int

move(dx, dy)[source]¶

Move the entity by the given offset.

Return type:: None

Game Systems¶

Rendering system for Yendoria.

This module handles all rendering operations using libtcod, including map rendering, entity rendering, and UI elements.

class yendoria.systems.rendering.RenderingSystem[source]¶

Bases: object

Handles all rendering operations for the game.

console¶

Main console for rendering

Type:: tcod.Console

map_console¶

Console for map rendering

Type:: tcod.Console

present(context)[source]¶

Present the rendered frame to the screen.

Parameters:: context (Context) – The tcod context to present to
Return type:: None

render_all(game_map, entities, player)[source]¶

Render the complete game state.

Parameters:

game_map (GameMap) – The game map to render
entities (list[Entity]) – List of all entities to render
player (Entity) – The player entity for UI display

Return type:

None

render_entities(entities, game_map)[source]¶

Render all visible entities to the map console.

Parameters:

entities (list[Entity]) – List of entities to render
game_map (GameMap) – The game map for visibility checks

Return type:

None

render_map(game_map)[source]¶

Render the game map to the map console.

Parameters:: game_map (GameMap) – The game map to render
Return type:: None

render_ui(player)[source]¶

Render the user interface elements.

Parameters:: player (Entity) – The player entity for health display
Return type:: None

Event handling system for Yendoria.

This module handles input events from the player including movement, actions, and system commands like quitting the game.

class yendoria.input_handlers.event_handler.BaseEventHandler[source]¶

Bases: object

Base event handler for the game.

Handles keyboard and other input events, returning appropriate actions for the game engine to process.

ev_keydown(event)[source]¶

Handle key press events.

Parameters:: event (KeyDown) – The key down event
Returns:: Action string if action should be taken
Return type:: str or None

ev_quit(event)[source]¶

Handle quit events (like clicking the X button).

Parameters:: event (Quit) – The quit event
Returns:: “quit” action
Return type:: str

handle_events(event)[source]¶

Handle events using modern tcod pattern.

Parameters:: event (Event) – The tcod event to handle
Return type:: str | None
Returns:: Action string or None

class yendoria.input_handlers.event_handler.EventHandler(*args, **kwargs)[source]¶

Bases: Protocol

Protocol for event handlers in the game.

Modern tcod event handling using Protocol instead of deprecated EventDispatch.

handle_events(event)[source]¶

Handle an event and return an action string or None.

Return type:: str | None

class yendoria.input_handlers.event_handler.GameEventHandler[source]¶

Bases: BaseEventHandler

Event handler for the main game state.

Extends the base event handler with game-specific actions.

ev_keydown(event)[source]¶

Handle key press events during normal gameplay.

Parameters:: event (KeyDown) – The key down event
Returns:: Action string if action should be taken
Return type:: str or None

yendoria.input_handlers.event_handler.handle_events()[source]¶

Process all pending events and return the first action.

Returns:: Action string if an action should be taken
Return type:: str or None

Game Map¶

Game map module for Yendoria.

This module contains the GameMap class which manages the game world, including tiles, dungeon generation, and field of view calculations.

class yendoria.game_map.game_map.GameMap(width=80, height=43)[source]¶

Bases: object

The game map containing all tiles and providing dungeon generation.

width¶

Map width in tiles

Type:: int

height¶

Map height in tiles

Type:: int

tiles¶

2D array of Tile objects

Type:: np.ndarray

visible¶

2D boolean array for currently visible tiles

Type:: np.ndarray

explored¶

2D boolean array for previously seen tiles

Type:: np.ndarray

rooms¶

List of generated rooms

Type:: List[RectangularRoom]

generate_dungeon()[source]¶

Generate a dungeon with rooms and corridors.

Returns:: Starting position (player spawn point)
Return type:: Tuple[int, int]

in_bounds(x, y)[source]¶

Check if coordinates are within map bounds.

Parameters:

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

Returns:

True if coordinates are within bounds

Return type:

bool

is_walkable(x, y)[source]¶

Check if a tile is walkable.

Parameters:

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

Returns:

True if tile exists and is walkable

Return type:

bool

update_fov(player_x, player_y, radius=8)[source]¶

Update field of view calculations.

Parameters:

player_x (int) – Player’s x coordinate
player_y (int) – Player’s y coordinate
radius (int) – Sight radius

Return type:

None

Tile module for Yendoria.

This module defines the Tile class which represents individual tiles on the game map, including their visual and gameplay properties.

class yendoria.game_map.tile.Tile(walkable, transparent, dark, light)[source]¶

Bases: object

A tile on the game map with visual and gameplay properties.

walkable¶

True if entities can walk through this tile

Type:: bool

transparent¶

True if this tile doesn’t block field of view

Type:: bool

dark¶

Graphics to use when tile is not visible

Type:: TileGraphic

light¶

Graphics to use when tile is visible

Type:: TileGraphic

Room generation for dungeon creation.

This module contains classes for creating rectangular rooms and managing room placement in the dungeon.

class yendoria.game_map.room.RectangularRoom(x, y, width, height)[source]¶

Bases: object

A rectangular room for dungeon generation.

Parameters:

x (int) – Top-left x coordinate
y (int) – Top-left y coordinate
width (int) – Room width
height (int) – Room height

property center: tuple[int, int]¶: Return the center coordinates of the room.

property inner: tuple[slice, slice]¶: Return the inner area of the room as slices (excludes walls).

intersects(other)[source]¶

Check if this room intersects with another room.

Parameters:: other (RectangularRoom) – Another RectangularRoom to check intersection with
Returns:: True if rooms intersect, False otherwise
Return type:: bool

yendoria.game_map.room.tunnel_between(start, end)[source]¶

Create an L-shaped tunnel between two points.

Parameters:

start (tuple[int, int]) – Starting coordinates (x, y)
end (tuple[int, int]) – Ending coordinates (x, y)

Yields:

Tuple[int, int] – Coordinates along the tunnel path

Return type:

Iterator[tuple[int, int]]

Utilities¶

Constants used throughout Yendoria.

This module contains all game constants including colors, dimensions, and key mappings for Yendoria.