API

Catpure The Flag (Ctf) state machine and game logic.

class ctf.api.Ctf(dimensions=16, 9, num_units=3, max_score=1, jail_timer=5)

Bases: object

Ctf class, handles a game of CTF.

Typical utilization:

>>> import ctf
>>> game = ctf.Ctf()
>>> game.new_game()
>>> while game.winner is None:
>>>     for unit in game.need_to_move:
>>>         game.render() # If you'd like to view the game
>>>         obs = game.observation
>>>         action = # Decide this however you'd like
>>>         game.move(unit, action)

Initialization of Ctf object.

Parameters

  • dimensions (tuple, optional) – Tuple of integers representing board dimensions. Defaults to (16, 9).

  • num_units (int, optional) – Number of units each player controls. Defaults to 3.

  • max_score (int, optional) – Score the game is played to. Defaults to 1.

  • jail_timer (int, optional) – How many turns a unit spends in jail. Defaults to 5.

property board

Board property.

Returns a copy of the board state.

Returns

Copy of board state.

Return type

numpy.array

property key

Key property.

Returns a dictionary representation of the objects and their respective idxs. The key is formatted as such:

0: 'EMPTY'
1: Flag for Team 1
2: Flag for Team 2
3+: Units
Returns

Dictionary representation of key.

Return type

dict

legal_moves()

Method to get all legal moves.

Returns a dictionary of all legal moves for all units. The keys are integers corresponding the the units idxs, and the values are lists of legal moves. This method does not filter the output by only units who may move this turn.

>>> game.legal_moves()
{3: ['N', 'E', 'S', 'W'], 4: ['PASS']} # 4 is in jail or trapped
Returns

Dictionary representing the legal moves

for each unit given the current state.

Return type

legal_moves (dict)

Raises

GameNotFoundError – Raised if this method is called prior to new_game.

property log

Log property.

Returns a copy of submitted actions. Logs are in the format of a list with dictionaries as elements. The dictionaries have only two key value pairs:

'unit': <Idx of unit that moved>
'direction': <direction of movement>
Returns

Copy of submitted actions.

Return type

list

move(unit, direction)

Method for moving units.

This method applies the movement logic for a given unit in a given direction. This method handles all capturing, jailing, logging, and flag picking up / dropping logic.

For a unit’s movement to be eligible, the movement must be in the list of legal_moves for the unit’s idx, and the unit must be present in the need_to_move property.

>>> import ctf
>>> game = ctf.Ctf()
>>> game.new_game()
>>> game.legal_moves()
{3: ['N', 'E'], 4: ['PASS']} # 4 is in jail or trapped
>>> game.need_to_move
[3]
>>> game.move(unit=3, direction='S') # Raises IllegalMoveError
>>> game.move(unit=4, direction='N') # Raises OutOfTurnError
>>> game.move(unit=3, direction='N') # legal
Parameters

  • unit (int) – A unit’s idx.

  • direction (str) – Direction for unit to move.

Raises
property moved_units

Moved Units property.

Returns a copy of the moved units dictionary. The keys are ints representing units idxs, and the values are booleans representing whether or not the unit has moved yet.

Returns

Copy moved units dictionary.

Return type

dict

property need_to_move

Need To Move property.

Returns a list of units who have yet to move this turn.

Returns

List of units who have yet to move this

turn.

Return type

list

new_game()

Method for starting a new game.

This method creates a new game, the previous game’s data, and corresponding state, are erased.

Calling a game’s methods prior to calling new_game will result in a GameNotFoundError.

>>> import ctf
>>> game = ctf.Ctf()
>>> game.move(unit=1, direction='N') # Raises GameNotFoundError
>>> game.new_game()
property observation

Observation property.

Returns a combination of the other properties. Observation contains:

'board': Board property,
'key': Key property,
'log': Log property,
'moved_units': Moved Units property,
'turn': Turn property,
'winner': Winner property
Returns

Dictionary containing each of the other

properties.

Return type

dict

render()

Method for rendering a frame.

If this method is called and the Ctf instance currently has no renderer, the ctf.rendering.Renderer is imported and intialized which requires OpenGL.

Once the renderer is initialized and stored on the Ctf object it will create a window displaying the state of the game. All subsequent calls will utilize the intialized renderer stored on the Ctf object.

>>> import ctf
>>> game = ctf.Ctf()
>>> game.new_game()
>>> game.render()
Raises

GameNotFoundError – Raised if this method is called prior to new_game.

property score

Score property.

Returns a dictionary representing the score, indexed by teams.

Returns

Current score.

Return type

dict

property turn

Turn property.

Returns an integer representing whose turn it is:

1: Player 1
2: Player 2
Returns

Whose turn it is.

Return type

int

property winner

Winner property.

Returns a integer or None depending on if game is finished:

1: Player 1 wins
2: Player 2 wins
None: No one has won yet
Returns

Integer corresponding to player if a

player has one, or None if no player has won yet.

Return type

int | None

PIECES

Pieces used in Capture The Flag (Ctf) game.

class ctf.pieces.Flag(idx, team, position, grounded=True)

Bases: ctf.pieces.Piece

Flag piece, representing one of the team’s flags.

Parameters

grounded (bool, optional) – Whether or not this flag is on the ground. True meaning this flag is on the ground, False meaning a unit is currently carrying this flag. Defaults to True.

class ctf.pieces.Piece(idx, team, position)

Bases: object

This class initializes the storage of standard attributes, shared amongst the other pieces.

Parameters

  • idx (int) – Index of Piece.

  • team (int) – The team this piece belongs to.

  • position (tuple) – Location of the piece on the board.

class ctf.pieces.Unit(idx, team, position, has_flag=False, in_jail=False)

Bases: ctf.pieces.Piece

Unit piece, representing a controllable character on the board.

Parameters

  • has_flag (bool, optional) – Whether or not the unit has the flag. Defaults to False.

  • in_jail (bool, optional) – Whether or not the unit is in jail. Defaults to False.

RENDERING

Rendering Capture The Flag (Ctf) board.

class ctf.rendering.Renderer(width, height, x_pad, y_pad, box, unit_pad)

Bases: object

Renderer class, handles the rendering of a Ctf game.

Initialization of Renderer object.

Parameters

  • width (int) – Width of window.

  • height (int) – Height of window.

  • x_pad (float) – Amount of padding to add to left / right of the window. The higher this number is, the more white space will exist to the left of the grid and right of the logs / scoreboard.

  • y_pad (float) – Amount of padding to add to top / bottom of the window. The higher this number is, the more white space will exist to the left of the grid and right of the logs / scoreboard.

  • box (float) – How large should a box in the grid be. This number corresponds to the length of the sides of the square.

  • unit_pad (float) – How much padding should exist between the sides of the box the unit is within, and the unit itself. if box is 30, and unit_pad is 5, the unit will be a 20x20 glyph within a 30x30 box. (A Unit side length is = box - unit_pad * 2, a Flag side length is = box - unit_pad * 2 * 2)

draw_grid(dims)

Method for drawing a grid on the window.

This method draws a gray and white grid on the left side of the window. This grid is where the pieces drawn by draw_pieces will go.

Parameters

dims (tuple) – Dimensions of the board being drawn.

draw_pieces(dims, key)

Method for drawing the pieces on the window.

This method draws each of the games pieces within boxes on the grid drawn by draw_grid.

Parameters

  • dims (tuple) – Dimensions of the board being drawn.

  • key (dict) – Private _key key from Ctf.

draw_scoreboard_logs(dims, score, logs, key)

Method for drawing the scoreboard and logs on the window.

This method draws a pixelart inspired scoreboard in the top right of the window and then draws the games logs underneath it.

Parameters

  • dims (tuple) – The dimensions of the board being drawn.

  • score (dict) – The score of the game being drawn.

  • logs (list) – The logs of the game being drawn.

  • key (dict) – Private _key object from Ctf.

init_window()

Method for initializing the window to be drawn on.

This method clears the window, sets the background to white, sets the window as the current OpenGL context, and dispatches event handlers.

show()

Method for showing the window.

This method swaps the OpenGL front and back buffers.

ERROR

exception ctf.error.GameNotFoundError

Bases: Exception

Raised when a user attempts to move a piece or render a frame before invoking new_game.

exception ctf.error.IllegalMoveError

Bases: Exception

Raised when a user attempts to move a unit in an illegal direction.

exception ctf.error.OutOfTurnError

Bases: Exception

Raised when a user attempts to move a unit out of turn.

IO

I/O module.

ctf.io.resource_path(filename)

Returns the path to a resource.

Parameters

filename (str) – Filename to get path to, must be in resources directory.

Returns

Path to <filename>, relative to resources directory.

Return type

str