games.core.game.core_position¶

Position models for the game framework.

This module defines the base Position class and its specific implementations for different coordinate systems used in games.

Classes¶

`GridPosition`	Position on a grid-based board with row and column coordinates.
`HexPosition`	Position on a hexagonal grid using cube coordinates.
`PointPosition`	Position using floating point coordinates in a 2D space.
`Position`	Base class for all position types in games.

Module Contents¶

class games.core.game.core_position.GridPosition(/, **data)¶

Bases: Position

Position on a grid-based board with row and column coordinates.

Used in games like Chess, Checkers, Scrabble, etc. where the board is organized as a rectangular grid of cells.

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)

chebyshev_distance(other)¶

Calculate the Chebyshev distance to another grid position.

This is the maximum of the horizontal and vertical distances, which corresponds to the number of moves a king in chess would need.

Parameters:: other (GridPosition)
Return type:: int

manhattan_distance(other)¶

Calculate the Manhattan distance to another grid position.

Parameters:: other (GridPosition)
Return type:: int

neighbors()¶

Get all adjacent grid positions (orthogonal).

Returns:: Dictionary mapping direction names to positions.
Return type:: dict[str, GridPosition]

neighbors_with_diagonals()¶

Get all adjacent grid positions including diagonals.

Returns:: Dictionary mapping direction names to positions.
Return type:: dict[str, GridPosition]

offset(row_offset, col_offset)¶

Create a new position that is offset from this one.

Parameters:

row_offset (int)
col_offset (int)

Return type:

GridPosition

classmethod validate_coordinates(v)¶

Ensure coordinates are valid.

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

property coordinates: tuple[int, int]¶

Get the row and column as a tuple.

Return type:: tuple[int, int]

property display_coords: str¶

Return human-readable coordinates.

For chess-style notation, this returns coordinates like ‘A1’, ‘B2’, etc. where the column is a letter (A-Z) and the row is a number (1-based).

Return type:: str

class games.core.game.core_position.HexPosition(/, **data)¶

Bases: Position

Position on a hexagonal grid using cube coordinates.

Used in games like Catan, hex-based war games, etc.

This uses cube coordinates (q, r, s) where q + r + s = 0.

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)

distance(other)¶

Calculate the distance to another hex position.

Parameters:: other (HexPosition)
Return type:: int

classmethod from_axial(q, r)¶

Create a hex position from axial coordinates (q, r).

Parameters:

q (int)
r (int)

Return type:

HexPosition

neighbors()¶

Get all adjacent hex positions.

Returns:: Dictionary mapping direction names to positions.
Return type:: dict[str, HexPosition]

classmethod validate_cube_coords(v, values)¶

Ensure cube coordinates are valid (q + r + s = 0).

Parameters:

v (int)
values (dict)

Return type:

int

property axial_coords: tuple[int, int]¶

Get the axial coordinates (q, r) as a tuple.

Return type:: tuple[int, int]

class games.core.game.core_position.PointPosition(/, **data)¶

Bases: Position

Position using floating point coordinates in a 2D space.

Used in games with continuous coordinates like territory maps or physics-based games.

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)

distance_to(other)¶

Calculate the Euclidean distance to another point position.

Parameters:: other (PointPosition)
Return type:: float

offset(x_offset, y_offset)¶

Create a new position that is offset from this one.

Parameters:

x_offset (float)
y_offset (float)

Return type:

PointPosition

property coordinates: tuple[float, float]¶

Get the x and y as a tuple.

Return type:: tuple[float, float]

class games.core.game.core_position.Position(/, **data)¶

Bases: pydantic.BaseModel

Base class for all position types in games.

A Position represents a location in a game. Different games use different coordinate systems, so this base class is extended for specific needs.

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)

serialize()¶

Convert the position to a serializable dictionary.

Return type:: dict[str, Any]