games.core.game.pieces.core_game¶

Game engine for the game framework.

This module defines the base Game class that serves as the central point for game logic, integrating all framework components.

Classes¶

`Game`	Base class for all games.
`GameConfiguration`	Configuration options for a game.
`GameFactory`	Factory for creating game instances.
`GameResult`	Result of a finished game.
`GameStatus`	Status of a game.
`RealTimeGame`	Base class for real-time games.
`TurnBasedGame`	Base class for turn-based games.

Module Contents¶

class games.core.game.pieces.core_game.Game(/, **data)¶

Bases: pydantic.BaseModel, Generic[P, T, S, C, M, PL]

Base class for all games.

The Game class ties together all game components and implements the core game loop. It manages the game state, players, turns, and rules.

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.

Parameters:: data (Any)

abort()¶

Abort the game.

Return type:: None

add_player(player)¶

Add a player to the game.

Parameters:: player (PL) – Player to add
Return type:: None

abstractmethod check_end_condition()¶

Check if the game has reached an end condition.

Returns:: True if the game should end, False otherwise
Return type:: bool

abstractmethod create_position(position_data)¶

Create a Position object from a dictionary representation.

Parameters:: position_data (dict[str, Any]) – Dictionary with position data
Returns:: Position object, or None if invalid
Return type:: P | None

abstractmethod determine_winner()¶

Determine the winner(s) of the game.

This should set the result and winners properties.

Return type:: None

end_turn()¶

End the current turn and move to the next player.

Return type:: None

finish(result, winners=None)¶

Finish the game with a result.

Parameters:

result (GameResult) – Result of the game
winners (list[str]) – List of winning player IDs

Return type:

None

get_container(container_id)¶

Get a container by ID.

Parameters:: container_id (str) – ID of the container
Returns:: The container, or None if not found
Return type:: C | None

get_current_player()¶

Get the current player.

Return type:: PL | None

get_piece(piece_id)¶

Get a piece by ID.

Parameters:: piece_id (str) – ID of the piece
Returns:: The piece, or None if not found
Return type:: T | None

get_property(key, default=None)¶

Get a game property.

Parameters:

key (str) – Property name
default (Any) – Default value if property doesn’t exist

Returns:

Property value or default

Return type:

Any

get_state_for_player(player_id)¶

Get a representation of the game state for a specific player.

This should include only information visible to that player.

Parameters:: player_id (str) – ID of the player
Returns:: Dictionary with game state information
Return type:: dict[str, Any]

abstractmethod get_valid_moves(player_id)¶

Get all valid moves for a player.

Parameters:: player_id (str) – ID of the player
Returns:: List of valid moves
Return type:: list[M]

initialize()¶

Initialize the game.

This should be called after adding players and before starting the game.

Return type:: None

is_finished()¶

Check if the game is finished.

Return type:: bool

pause()¶

Pause the game.

Return type:: None

process_move(move)¶

Process a move from a player.

Parameters:: move (M) – Move to process
Returns:: Result of the move
Return type:: game.core.move.MoveResult[M]

register_callback(event, callback)¶

Parameters:

event (str) – Event name
callback (collections.abc.Callable) – Callback function

Return type:

None

resume()¶

Resume a paused game.

Return type:: None

set_property(key, value)¶

Set a game property.

Parameters:

key (str) – Property name
value (Any) – Property value

Return type:

None

abstractmethod setup_game()¶

Set up the game-specific components.

This should be implemented by subclasses to create the board, pieces, and other game elements.

Return type:: None

start()¶

Start the game.

Return type:: None

start_turn()¶

Start a new turn.

Return type:: None

unregister_callback(event, callback)¶

Unregister a callback for a game event.

Parameters:

event (str) – Event name
callback (collections.abc.Callable) – Callback function

Return type:

None

class games.core.game.pieces.core_game.GameConfiguration(/, **data)¶

Bases: pydantic.BaseModel

Configuration options for a game.

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.

Parameters:: data (Any)

is_valid_player_count(count)¶

Check if a player count is valid for this game.

Parameters:: count (int)
Return type:: bool

classmethod validate_player_count(v)¶

Ensure player counts are valid.

Parameters:: v (int)
Return type:: int

class games.core.game.pieces.core_game.GameFactory¶

Factory for creating game instances.

static create_game(game_type, config, **kwargs)¶

Create a game instance.

Parameters:

game_type (type[Game]) – Type of game to create
config (GameConfiguration) – Game configuration
**kwargs – Additional arguments for the game constructor

Returns:

Game instance

Return type:

Game

class games.core.game.pieces.core_game.GameResult¶

Bases: str, enum.Enum

Result of a finished game.

Initialize self. See help(type(self)) for accurate signature.

class games.core.game.pieces.core_game.GameStatus¶

Bases: str, enum.Enum

Status of a game.

Initialize self. See help(type(self)) for accurate signature.

class games.core.game.pieces.core_game.RealTimeGame¶

Bases: Game[P, T, S, C, M, PL]

Base class for real-time games.

This adds functionality for games that don’t use strict turns.

is_action_on_cooldown(player_id, action_type)¶

Check if an action is on cooldown.

Parameters:

player_id (str) – ID of the player
action_type (str) – Type of action

Returns:

True if the action is on cooldown, False otherwise

Return type:

bool

process_move(move)¶

Process a move from a player, checking cooldowns.

Parameters:: move (M) – Move to process
Returns:: Result of the move
Return type:: game.core.move.MoveResult[M]

set_cooldown(player_id, action_type, ticks)¶

Set a cooldown for an action.

Parameters:

player_id (str) – ID of the player
action_type (str) – Type of action
ticks (int) – Number of ticks until the action is available again

Return type:

None

update(delta_time)¶

Update the game state for a time step.

Parameters:: delta_time (float) – Time in seconds since last update
Return type:: None

abstractmethod update_game_state(delta_time)¶

Update the game state for a time step.

Parameters:: delta_time (float) – Time in seconds since last update
Return type:: None

class games.core.game.pieces.core_game.TurnBasedGame¶

Bases: Game[P, T, S, C, M, PL]

Base class for turn-based games.

This adds additional turn management functionality.

can_take_action(player_id)¶

Check if a player can take another action this turn.

Parameters:: player_id (str) – ID of the player
Returns:: True if the player can take an action, False otherwise
Return type:: bool

end_turn()¶

End the current turn and move to the next player.

Return type:: None

process_move(move)¶

Process a move from a player, tracking actions per turn.

Parameters:: move (M) – Move to process
Returns:: Result of the move
Return type:: game.core.move.MoveResult[M]

record_action(player_id)¶

Record an action taken by a player this turn.

Parameters:: player_id (str) – ID of the player
Return type:: None

reverse_turn_order()¶

Reverse the turn order direction.

Return type:: None

skip_turn()¶

Skip the current player’s turn.

Return type:: None