Autodocs

Autodocs#

Auto-generated documentation via Sphinx and autodoc, translated from numpy-style docstrings via napoleon.

Constants#

class src.constants.Cell(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Represents a cell or tile in a level.

src.constants.Coordinate#

Represents a map coordinate.

alias of tuple[int, int]

class src.constants.DirectionalMove(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Represents a valid move in one of four directions: LEFT, RIGHT, FORWARDS, or BACKWARDS.

Console rendering#

src.console_render.clear_screen()#

Clears the terminal screen.

src.console_render.render_game(game_state, clear=True, move_history=False, moves_remaining=False, points=False)#

Renders the current game state.

Optionally allows for extra information such as move history, moves remaining, and points earned to be displayed after the map.

Parameters:

  • game_state (GameState) – The current game state.

  • clear (bool) – Whether to clear the screen before rendering the game.

  • optional – Whether to clear the screen before rendering the game.

  • move_history (bool) – Display move history.

  • optional – Display move history.

  • moves_remaining (bool) – Display the number of moves remaining.

  • optional – Display the number of moves remaining.

  • points (bool) – Display the total number of points earned.

  • optional – Display the total number of points earned.

Game logic#

class src.game_logic.GameState(map_data, total_moves, moves_remaining=0, points=0, move_history=<factory>, points_history=<factory>, map_changes=<factory>)#

Represents the current game state, including map data, total moves allowed, move history, points history, and the egg changes between each move (for undo purposes).

Note that move_history, points_history, and map_changes must all have the same length.

map_data#

The game’s level map data.

Type:

list[list[Cell]]

total_moves#

The number of moves allowed for this level.

Type:

int

moves_remaining#

The number of moves the user has left. Defaults to 0.

Type:

int

points#

The total number of points earned. Defaults to 0.

Type:

int

move_history#

A list of all directional moves done on the level. Defaults to an empty list ([]).

Type:

list[DirectionalMove]

points_history#

A list of all the points earned on every directional move. Defaults to an empty list ([]).

Type:

list[int]

map_changes#

A list of 2-tuples representing the map changes caused by the move at that index.

The first element is a list of Coordinate objects representing the locations of the eggs prior to executing the move, and the second element is a list of Coordinate objects representing the locations of the nests filled after executing the move.

Type:

list[tuple[list[Coordinate], list[Coordinate]]]

property has_moves_remaining: bool#

Checks if there are moves remaining.

property is_solved: bool#

Checks if the game is in a solved state.

move_direction(move)#

Tilts a given map_data in the specified direction.

WARNING: This will mutate the inner lists in-place.

Parameters:

move (DirectionalMove) – The move to process

Yields:

A 3-tuple of the format (num_eggs, points, iteration), where –

  • num_eggs is the number of eggs left that can be moved

  • points is the number of points earned as a result of the current state change, and

  • iteration is a number denoting that number of map state changes that have currently been processed

Return type:

Generator[tuple[int, int, int]]

classmethod read_file(filename)#

Receives a filename, attempts to open it, loads the map data, and creates a corresponding new GameState instance.

Parameters:

filename (str) – The filename to load.

Return type:

Self

Returns:

A new GameState instance loaded with the map data. Note that moves_remaining is initialized to total_moves.

update()#

Reconciles the game state based on points and move history.

This updates the game state’s points and moves_remaining attributes based off of the game state’s current points_history and move_history.

Raises:

ValueError – Game state histories have different lengths.

src.game_logic.get_egg_coordinates(map_data, move)#

Returns a list of pairs (i, j) representing the coordinates of all the eggs (🥚) in map_data, in the correct order to process a move in direction.

Parameters:

  • map_data (list[list[Cell]]) – The map data to process.

  • move (DirectionalMove) – The move to process. Determines the order of the output values.

Return type:

list[tuple[int, int]]

Returns:

A list of Coordinates representing every egg in the map, ordered correctly to process a move in the specified direction.

src.game_logic.process_map_data(map_data)#

Processes map data read from a file.

This function also validates that the map data satisfies the following conditions:

  • Grid must not be empty.

  • Grid must have the same number of columns in each row.

  • Grid must be at least 4x4 and at most 35x50. (row x col)

  • Grid must only contain valid characters.

  • Grid must be surrounded by walls.

Parameters:

map_data (list[list[str]]) – The map data to check.

Return type:

list[list[Cell]]

Returns:

The processed map data.

Raises:

ValueError – The level data is invalid (failed one or more conditions).

Leaderboard handling#

src.extension.leaderboards.get_leaderboard_place(leaderboard, target_score)#

Returns the index on a leaderboard where the score can be inputted.

Parameters:

  • leaderboard (list[list[str, int]]) – A list of lists representing the leaderboard data.

  • target_score (int) – The score that is trying to enter the leaderboard.

Returns:

An integer representing the index in the leaderboard. Is -1 if it can not be inserted without reaching the leaderboard cutoff.

Return type:

int

src.extension.leaderboards.get_leaderboards_data(level_source)#

Returns the leaderboards data of a given level source as a list of tuples.

Parameters:

level_source (str) – Represents the filename of the level_source.

Returns:

A list of tuples representing the leaderboard data. The tuples contain a string and an integer, respectively representing the name and score.

Return type:

list[tuple[str, int]]

src.extension.leaderboards.get_leaderboards_filename(level_source)#

Returns the filename for the leaderboards of a given level source, given that the level source does exist.

Parameters:

level_source (str) – A string representing the filepath for the map data of the level.

Returns:

A string representing the filepath for the leaderboards.

Return type:

str

Raises:

FileNotFoundError – Raises if the given level_source does not actually exist.

src.extension.leaderboards.insert_leaderboard_score(level_source, score)#

A function that attempts to insert a score into the leaderboard of a given level. If the leaderboard of a given level doesn’t exist. It will create a level.

Parameters:

  • level_source (str) – A string representing the source of a level.

  • score (int) – The score that it is trying to put in the leaderboard.

src.extension.leaderboards.set_leaderboards_data(leaderboards_data, level_source)#

Saves leaderboards data on a given level source’s leaderboard file, if the level source’s file exist.

Parameters:

  • leaderboards_data (list[tuple[str, int]]) – A list of tuples representing the leaderboards data that is to be saved.

  • level_source (str) – A string that represents the filename of the level.

src.extension.leaderboards.tabulate_leaderboard(leaderboard)#

Displays a given leaderboard in a table format.

Parameters:

leaderboard (list) – A list representing the leaderboard.

main.py#

main.ask_for_moves(message)#

Prompts the user for input, processes valid characters, discards invalid characters, and returns a list of valid moves.

Parameters:

message (str) – The message to display before waiting for input.

Return type:

list[DirectionalMove]

Returns:

A list of valid moves.

main.ask_for_moves_loop(moves_remaining, preamble='Choices: L = left, R = right, F = forwards, B = backwards', first_prompt='Input one or more moves: ', invalid_prompt='No valid moves detected! Please try again: ', exceeded_prompt='Too many moves! Please try again: ')#

Repeatedly ask for moves until a valid input is given.

A valid input is defined as an input consisting of at least one valid character (L/R/F/B). The total number of valid characters must also not exceed the number of moves remaining.

If the user input is deemed invalid (either zero valid moves or too many moves), the user is notified of the specific issue and is prompted again to input moves.

Parameters:

  • moves_remaining (int) – The number of moves the user can still execute.

  • preamble (str) – The text displayed before first_prompt.

  • first_prompt (str) – The prompt displayed before asking for input.

  • invalid_prompt (str) – The prompt displayed when zero (0) valid moves are detected.

  • exceeded_prompt (str) – The prompt displayed when the number of valid characters exceeds moves_remaining

Return type:

list[DirectionalMove]

Returns:

A list of valid letters (L/R/F/B) representing valid moves.

main.main(*argv)#

The main function to start the game.

Raises:

NotImplementedError – No filename was provided and map select is not implemented.

main.process_and_display_move(game_state, move, delay=0.25)#

Process a move and display it to the user, including intermediate game states or animation “frames”.

Parameters:

  • game_state (GameState) – The current game state.

  • move (DirectionalMove) – The move to process.

  • delay (float) – How long to wait before displaying each frame, in seconds.

main.start_game(filename)#

Loads a file and starts a game with the loaded level data.

Parameters:

filename (str) – The file to load.

Raises:

OSError – An error occurred while reading the file.