Project Classes

Random Number Generation

class universe.rng.RNG[source]

Bases: object

A class to handle random number generation.

choice(seq: list) → any[source]

Choose a random element from a sequence.

Parameters:: seq (list) – The sequence to choose from.
Returns:: A random element from the sequence.
Return type:: any

randint(a: int, b: int) → int[source]

Generate a random integer between a and b.

Parameters:

a (int) – The lower bound.
b (int) – The upper bound.

Returns:

A random integer.

Return type:

int

random() → float[source]

Generate a random float between 0 and 1.

Returns:: A random float.
Return type:: float

random_instance = None

seed = 0

set_random_seed() → int[source]

Set a random seed for the random number generator.

Returns:: The seed that was set.
Return type:: int

set_seed(seed: Any) → None[source]

Set the seed for the random number generator.

Parameters:: seed (Any) – The seed to set.

Universe

class universe.universe.Universe[source]

Bases: object

Class representing the universe.

The universe is the environment in which the simulation takes place.

Variables:

rng – The random number generator.
boundary – The boundary of the universe.
ants – A dictionary of ants.
objects – A dictionary of objects.
nests – A list of nests.

MAX_ANTS = 500

MAX_OBJECTS = 500

ants: Dict[Tuple[int, int], List[Ant]]

ants_count = 0

boundary: Boundary

nests: List[Nest]

objects: Dict[Tuple[int, int], List[Object]]

objects_count = 0

rng: RNG

Updates

class universe.update.Update(_type: UpdateType, ant: Ant | None = None, target: Any | None = None, state: Any | None = None)[source]

Bases: object

Class representing an update in the simulation.

ant: Ant | None = None

target: Any | None = None

to_dict() → Dict[str, Any][source]

Convert the update to a dictionary.

Returns:: The dictionary representation of the update.

type: UpdateType = -1

class universe.update.UpdateType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enum class for update types.

ANT_ATTACK = 13

ANT_DEATH = 12

ANT_MOVE = 11

ANT_PROMOTE = 14

ANT_SPAWN = 10

ERROR_INVALID_ROUNDS = 41

ERROR_INVALID_TPS = 40

ERROR_SIMULATION_NOT_RUNNING = 42

NEST_SPAWN = 20

OBJECT_DESPAWN = 31

OBJECT_SPAWN = 30

SIMULATION_CURRENT_ROUND = 9

SIMULATION_END = 1

SIMULATION_PAUSE = 2

SIMULATION_RESUME = 3

SIMULATION_SET_BOUNDARIES = 6

SIMULATION_SET_ROUNDS = 8

SIMULATION_SET_SEED = 7

SIMULATION_SET_TPS = 5

SIMULATION_START = 0

SIMULATION_TPS = 4

UNKNOWN = -1

Ant Base Class

class universe.ants.ant.Ant(position: Position)[source]

Bases: object

Class representing an ant in the universe.

Variables:

id – The ID of the ant.
role – The role of the ant.
health – The health of the ant.
food – The food of the ant.
damage – The damage of the ant.
speed – The speed of the ant.
position – The position of the ant.
alive – Whether the ant is alive.

NEXT_ID = 0

alive = True

async attack(other: Ant, update_callback: Callable)[source]

Attack another ant.

Parameters:

other (Ant) – The ant to attack.
update_callback (Callable) – The callback function to update the state.

available_directions(boundary: Boundary) → List[Direction][source]

Return the available directions for the ant to move.

Parameters:: boundary (Boundary) – The boundary of the universe.
Returns:: The available directions for the ant to move.
Return type:: List[Direction]

damage = 10

async die(update_callback: Callable)[source]

Kill the ant.

Parameters:: update_callback (Callable) – The callback function to update the state.

food = 60

health = 50

is_alive() → bool[source]

Return whether the ant is alive.

Returns:: True if the ant is alive, False otherwise.
Return type:: bool

abstract async move(universe: Universe, update_callback: Callable)[source]

Move the ant in the universe.

This method should be implemented by the subclasses.

Parameters:

universe (Universe) – The universe.
update_callback (Callable) – The callback function to update the state.

position: Position = None

async process(universe: Universe, update_callback: Callable)[source]

Process the ant.

Parameters:

universe (Universe) – The universe.
update_callback (Callable) – The callback function to update the state.

role: Role = 0

async set_role(role: Role, update_callback: Callable)[source]

Set the role of the ant.

Parameters:

role (Role) – The role to set.
update_callback (Callable) – The callback function to update the state.

async spawn_ants(universe: Universe, max_count: int, update_callback: Callable)[source]

Spawn new ants for the queen.

Parameters:

universe (Universe) – The universe.
max_count (int) – The maximum number of ants to spawn.
update_callback (Callable) – The callback function to update the state.

speed = 3

to_dict()[source]

Return a dictionary representation of the ant.

Returns:: The dictionary representation of the ant.
Return type:: dict

class universe.ants.ant.Role(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enum class for ant roles.

QUEEN = 2

SOLDIER = 1

WORKER = 0

Black Ant

class universe.ants.black_ant.BlackAnt(position: Position)[source]

Bases: Ant

BlackAnt is a subclass of Ant with default attributes.

async move(universe: Universe, update_callback: Callable) → None[source]

Move the black ant in the universe.

Parameters:

universe (Universe) – The universe.
update_callback (Callable) – The callback function to update the state.

Red Ant

class universe.ants.red_ant.RedAnt(position: Position)[source]

Bases: Ant

RedAnt is a subclass of Ant with specific attributes. It has a health of 40, damage of 15, and speed of 4.

damage: int = 15

health: int = 40

async move(universe: Universe, update_callback: Callable) → None[source]

Move the red ant in the universe.

Parameters:

universe (Universe) – The universe.
update_callback (Callable) – The callback function to update the state.

speed: int = 4

Area

class universe.map.area.Area(position_1: Position, position_2: Position)[source]

Bases: object

direction_from_position(position: Position) → Direction | None[source]

Determine the direction from a position to the area.

Parameters:: position (Position) – The position.
Returns:: The direction from the position to the area.
Return type:: Direction

size() → int[source]

Calculate the size of the area.

Returns:: The size of the area.
Return type:: int

smallest_distance(other: Position | Area) → float[source]

Calculate the smallest distance from the area to another position or area.

Parameters:: other (Union[Position, Area]) – The other position or area.
Returns:: The smallest distance.
Return type:: float

to_dict() → dict[source]

Convert the area to a dictionary.

Returns:: The dictionary representation of the area.
Return type:: dict

Boundary

class universe.map.boundary.Boundary[source]

Bases: Area

Class representing the boundary of the universe.

Variables:: width – The width of the boundary.

contains(position) → bool[source]

Check if the given position is within the boundary.

Parameters:: position (Position) – The position to check.
Returns:: True if the position is within the boundary, False otherwise.
Return type:: bool

height: int = 200

set_boundary_by_size(size: int) → None[source]

Set the boundary by size.

The x and y coordinates are set to negative half of the size, and the width and height are set to the size.

Parameters:: size (int) – The size to set the boundary.

set_boundary_by_width_height(width: int, height: int) → None[source]

Set the boundary by width and height. The x and y coordinates are set to zero.

Parameters:

width (int) – The width of the boundary.
height (int) – The height of the boundary.

size() → int[source]

Get the size of the boundary.

Returns:: The size of the boundary.
Return type:: int

width: int = 200

Nest

class universe.map.nest.Nest(area: Area)[source]

Bases: object

Class representing a nest in the universe.

Variables:

area – The area of the nest.
queen – The queen ant of the nest.

ants_type() → Type[Ant][source]

Get the type of the queen ant.

Returns:: The type of the queen ant.
Return type:: Type[Ant]

static generate_random_nest_area(universe: Universe, size_from: int = 10, size_to: int = 20, min_distance: int = 40, min_distance_from: Area | None = None) → Area[source]

Generate a random nest area.

Parameters:

universe (Universe) – The universe to generate the nest area in.
size_from (int) – The minimum size of the nest area.
size_to (int) – The maximum size of the nest area.
min_distance (int) – The minimum distance from the given area.
min_distance_from (Optional[Area]) – The area to keep distance from.

Returns:

The generated nest area.

Return type:

Area

queen: Ant = None

to_dict() → dict[source]

Convert the nest to a dictionary.

Returns:: The dictionary representation of the nest.
Return type:: dict

Object

class universe.map.object.Object(position: Position, object_type: ObjectType)[source]

Bases: object

Class representing an object in the universe.

Variables:

position – The position of the object.
object_type – The type of the object.
usages_left – The number of usages left for the object.

async interact(boundary: Boundary, ant: Ant, update_callback: Callable)[source]

Interact with an ant.

Parameters:

boundary (Boundary) – The boundary of the universe.
ant (Ant) – The ant to interact with.
update_callback (Callable) – The callback function to update the state.

to_dict() → dict[source]

Convert the object to a dictionary.

Returns:: The dictionary representation of the object.
Return type:: dict

usages_left: int = 3

class universe.map.object.ObjectType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enum class for object types.

FOOD = 0

ROCK = 2

WATER = 1

Position

class universe.map.position.Direction(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enum class for directions.

EAST = 90

NORTH = 0

SOUTH = 180

WEST = 270

static from_angle(angle: int) → Direction[source]

Convert an angle to a direction.

Parameters:: angle (int) – The angle.
Returns:: The direction.
Return type:: Direction

to_angle() → int[source]

Convert the direction to an angle.

Returns:: The angle.
Return type:: int

to_arrow() → str[source]

Convert the direction to an arrow.

Returns:: The arrow.
Return type:: str

class universe.map.position.Position(x: int, y: int, direction: Direction = Direction.NORTH)[source]

Bases: object

calculate_new_position(boundary: Boundary, direction: Direction, distance: int = 1) → Position[source]

Calculate a new position based on a direction and distance.

Parameters:

boundary (Boundary) – The boundary of the universe.
direction (Direction) – The direction to move.
distance (int) – The distance to move, defaults to 1.

Returns:

The new position.

Return type:

Position

can_move(boundary: Boundary, direction: Direction, distance: int = 1) → bool[source]

Check if the position can move in a direction.

Parameters:

boundary (Boundary) – The boundary of the universe.
direction (Direction) – The direction to move.
distance (int) – The distance to move, defaults to 1.

Returns:

True if the position can move, False otherwise.

Return type:

bool

chebyshev_distance(other: Position) → int[source]: Calculate the Chebyshev distance to another position.

euclidean_distance(other: Position) → float[source]: Calculate the Euclidean distance to another position.

get_neighbors(distance: int = 1) → list[Position][source]

Get the neighbors of the position.

Parameters:: distance (int) – The distance to get the neighbors from, defaults to 1.
Returns:: The neighbors of the position.
Return type:: list[Position]

manhattan_distance(other: Position) → int[source]: Calculate the Manhattan distance to another position.

move(boundary: Boundary, direction: Direction = None, distance: int = 1, new_position: Position = None)[source]

Move the position.

Parameters:

boundary (Boundary) – The boundary of the universe.
direction (Direction) – The direction to move, defaults to None.
distance (int) – The distance to move, defaults to 1.
new_position (Position) – The new position to move to, defaults to None.

to_dict() → dict[source]

Convert the position to a dictionary.

Returns:: The dictionary representation of the position.
Return type:: dict