color_grid_game package

Subpackages

Submodules

color_grid_game.grid module

class color_grid_game.grid.Grid(n: int, m: int, color: list[list[int]] = None, value: list[list[int]] = None)

Bases: object

A class representing a grid with cells that have colors and values.

Attributes:

nint

Number of rows in the grid.

mint

Number of columns in the grid.

colorlist[list[int]]

The color of each grid cell. color[i][j] is the color value in the cell (i, j). Lines are numbered from 0 to n-1, and columns from 0 to m-1.

valuelist[list[int]]

The value of each grid cell. value[i][j] is the value in the cell (i, j). Lines are numbered from 0 to n-1, and columns from 0 to m-1.

colors_listlist[str]

The mapping between the value of color[i][j] and the corresponding color.

Methods

all_pairs([rules])	Returns all allowed pairs of neighboring cells.
cost(pair)	Returns the cost of a pair of cells.
grid_from_file(file_name[, read_values])	Creates a Grid object from a file.
is_forbidden(i, j)	Checks if a cell is forbidden (black).
plot()	Plots a visual representation of the grid using matplotlib.
vois(i, j)	Returns the list of neighbors of the cell (i, j).

all_pairs(rules='original rules') → list[tuple[tuple[int, int], tuple[int, int]]]

Returns all allowed pairs of neighboring cells.

Parameters:

rulesstr, optional

The rules to apply for determining allowed pairs. Default is “original rules”.

Returns:

list[tuple[tuple[int, int], tuple[int, int]]]

A list of pairs of neighboring cells that are allowed to be paired.

Raises:

ValueError

If the rules parameter is not recognized.

cost(pair: tuple[tuple[int, int], tuple[int, int]]) → int

Returns the cost of a pair of cells.

Parameters:

pairtuple[tuple[int, int], tuple[int, int]]

A pair of cells in the format ((i1, j1), (i2, j2)).

Returns:

int

The cost of the pair, defined as the absolute value of the difference between their values.

Raises:

ValueError

If the pair does not contain valid cell indices.

classmethod grid_from_file(file_name: str, read_values: bool = False) → Grid

Creates a Grid object from a file.

Parameters:

file_namestr

Name of the file to load. The file must be formatted as follows: - The first line contains “n m”. - The next n lines contain m integers representing the colors of the corresponding cells. - The next n lines contain m integers representing the values of the corresponding cells.

read_valuesbool, optional

Indicates whether to read values after reading the colors. Requires the file to have 2n+1 lines.

Returns:

Grid

The initialized Grid object.

Raises:

FileNotFoundError

If the file does not exist.

ValueError

If the file format is incorrect or contains invalid color values.

is_forbidden(i: int, j: int) → bool

Checks if a cell is forbidden (black).

Parameters:

iint

Row index of the cell.

jint

Column index of the cell.

Returns:

bool

True if the cell (i, j) is black, False otherwise.

Raises:

IndexError

If the cell (i, j) is out of the grid boundaries.

plot() → None

Plots a visual representation of the grid using matplotlib.

Raises:

ImportError

If matplotlib is not installed.

vois(i: int, j: int) → list[tuple[int, int]]

Returns the list of neighbors of the cell (i, j).

Parameters:

iint

Row index of the cell.

jint

Column index of the cell.

Returns:

list[tuple[int, int]]

A list of neighboring cell coordinates.

Raises:

IndexError

If the cell (i, j) is out of the grid boundaries.

color_grid_game.main module

color_grid_game.main.main()

color_grid_game.mcts_bot module

class color_grid_game.mcts_bot.MCTS_Bot(grid: Grid, simulations_per_move: int = 20, epsilon: float = 0.1)

Bases: object

A bot that chooses a pair using Monte Carlo Tree Search (MCTS).

Methods

epsilon_greedy_from_pairs(pairs)	Selects a pair of cells to play using an epsilon-greedy strategy: with probability ε, selects randomly among the 5 lowest-cost pairs; otherwise, selects the best (lowest-cost) pair.
mcts_move()	Selects the best move using simplified Monte Carlo Tree Search (MCTS).
simulate_from_pair(initial_pair, initial_pairs)	Simulates a complete game starting from a given initial move, assuming both players play using an epsilon-greedy strategy.

epsilon_greedy_from_pairs(pairs: list[tuple[tuple[int, int], tuple[int, int]]]) → tuple[tuple[int, int], tuple[int, int]] | None

Selects a pair of cells to play using an epsilon-greedy strategy: with probability ε, selects randomly among the 5 lowest-cost pairs; otherwise, selects the best (lowest-cost) pair.

Parameters:

pairslist of tuple[tuple[int, int], tuple[int, int]]

List of valid pairs to choose from.

Returns:

pairtuple[tuple[int, int], tuple[int, int]] or None

The selected pair, or None if the list is empty.

mcts_move() → tuple[tuple[int, int], tuple[int, int]] | None

Selects the best move using simplified Monte Carlo Tree Search (MCTS). For each possible pair of cells, runs multiple full-game simulations and returns the one with the best average score differential.

Returns:

best_pairtuple[tuple[int, int], tuple[int, int]] or None

The best move to play (as a pair of cells), or None if no move is possible.

simulate_from_pair(initial_pair: tuple[tuple[int, int], tuple[int, int]], initial_pairs: list[tuple[tuple[int, int], tuple[int, int]]]) → float

Simulates a complete game starting from a given initial move, assuming both players play using an epsilon-greedy strategy.

Parameters:

initial_pairtuple[tuple[int, int], tuple[int, int]]

The initial pair played by the current player.

initial_pairslist of tuple[tuple[int, int], tuple[int, int]]

All valid pairs at the start of the simulation.

Returns:

score_difffloat

The score differential (player_score - opponent_score) for the simulation.

color_grid_game.minimax_bot module

class color_grid_game.minimax_bot.Minimax_Bot

Bases: object

A bot that plays using the min-max strategy.

Methods

move_to_play(grid: Grid)

Choose the best pair by minimizing the current move’s cost for the bot and maximizing the opponent’s next move cost.

static move_to_play(grid: Grid, rules: str)

Choose the best pair considering that the opponent is playing greedy and will choose the best possible pair with a one-turn prediction.

Parameters:

gridGrid

The grid of the turn to be solved.

rulesstr

The game rules chosen by the player.

Returns:

pairtuple[tuple[int, int], tuple[int, int]]

The pair of cells to be played, or None if no choice is possible.

ComplexityO(n*m * log(n*m))

static move_to_play2(grid: Grid, rules: str) → tuple[tuple[int, int], tuple[int, int]] | None

Choose the best pair by: 1. Minimizing the current move’s cost for the bot. 2. Maximizing the opponent’s next move cost, assuming they choose the minimum cost pair.

Parameters:

gridGrid

The grid of the turn to be solved.

rulesstr

The game rules chosen by the player.

Returns:

pairtuple[tuple[int, int], tuple[int, int]] or None

The pair of cells to be played, or None if no choice is possible.

color_grid_game.run_game module

class color_grid_game.run_game.Game

Bases: object

Manages the game state and flow.

Attributes:

colorsdict

Dictionary mapping color indices to RGB tuples.

colors_titledict

Dictionary mapping title color indices to RGB tuples.

screenpygame.Surface

The screen surface where the game is rendered.

ui_managerUIManager

The UI manager for the game.

grid_managerGridManager

The grid manager for the game.

selected_gridstr

The selected grid filename.

scrollint

The current scroll position.

scroll_bar_draggingbool

Whether the scroll bar is being dragged.

mouse_y_offsetint

The mouse y offset for scrolling.

selected_cellslist

List of selected cells.

game_overbool

Whether the game is over.

show_solutionbool

Whether to show the solution.

pressed_buttonstr

The currently pressed button.

pressed_grid_indexint

The index of the pressed grid option.

rules_scrollint

The current scroll position for the rules.

rules_scroll_bar_draggingbool

Whether the rules scroll bar is being dragged.

rules_mouse_y_offsetint

The mouse y offset for rules scrolling.

player_modestr

The game mode (‘one’, ‘two’, or ‘bot’).

current_playerint

The current player (1 or 2).

player_pairslist

List of player pairs.

player_scoreslist

List of player scores.

volume_button_pressed_timeint

The time the volume button was pressed.

player_initial_timeslist

List of initial times for the players.

player_time_usedlist

List of time used by the players.

start_timeslist

List of start times for the players.

player_timerslist

List of player timers.

timer_pausedbool

Whether the timer is paused.

Methods

main()	The main game loop.
reset_game_state()	Resets the game state to the initial settings.
show_rules()	Displays the rules screen.
update_timer_display(grid, solver_manager, ...)	Met à jour l'affichage du timer pendant le délai des bots.

create_grid_copy

create_grid_copy(grid, player_pairs)

main()

The main game loop.

reset_game_state()

Resets the game state to the initial settings.

show_rules()

Displays the rules screen.

update_timer_display(grid, solver_manager, cell_size, window_size, top_margin)

Met à jour l’affichage du timer pendant le délai des bots.

class color_grid_game.run_game.GridManager(data_path)

Bases: object

Manages the grid files and their difficulties.

Attributes:

data_pathstr

The path to the directory containing the grid files.

grid_fileslist

List of grid files.

difficultieslist

List of difficulties for the grid files.

min_dint

The minimum difficulty.

max_dint

The maximum difficulty.

range_dint

The range of difficulties.

grid_colorslist

List of colors for the grid files.

Methods

extract_difficulty(filename)	Extracts the difficulty from the filename.
get_difficulty_color(difficulty)	Gets the color for a given difficulty.
load_grid(selected_grid)	Loads a grid from a file.

extract_difficulty(filename)

Extracts the difficulty from the filename.

Parameters:

filenamestr

The filename to extract the difficulty from.

Returns:

int

The extracted difficulty.

get_difficulty_color(difficulty)

Gets the color for a given difficulty.

Parameters:

difficultyint

The difficulty to get the color for.

Returns:

tuple

The RGB color for the difficulty.

load_grid(selected_grid)

Loads a grid from a file.

Parameters:

selected_gridstr

The filename of the grid to load.

Returns:

Grid

The loaded grid.

class color_grid_game.run_game.SolverManager(grid, rules)

Bases: object

Manages the solver for the game.

Attributes:

solverSolver

The solver for the game.

solver_generalSolver_Hungarian or Solver_Blossom

The general solver for the game.

general_scoreint

The score of the general solver.

Methods

calculate_player_score(player_pairs, grid)	Calculates the score for a player.
calculate_two_player_score(player_pairs, grid)	Calculates the score for two players.
can_pair(color1, color2)	Checks if two colors can be paired.
pair_is_valid(pair, existing_pairs, grid, ...)	Checks if a pair is valid.

calculate_player_score(player_pairs, grid)

Calculates the score for a player.

Parameters:

player_pairslist

List of player pairs.

gridGrid

The game grid.

Returns:

int

The calculated score.

calculate_two_player_score(player_pairs, grid)

Calculates the score for two players.

Parameters:

player_pairslist

List of player pairs.

gridGrid

The game grid.

Returns:

int

The calculated score.

can_pair(color1, color2)

Checks if two colors can be paired.

Parameters:

color1int

The first color.

color2int

The second color.

Returns:

bool

Whether the colors can be paired.

pair_is_valid(pair, existing_pairs, grid, player_pairs, rules)

Checks if a pair is valid.

Parameters:

pairtuple

The pair to check.

existing_pairslist

List of existing pairs.

gridGrid

The game grid.

player_pairslist

List of player pairs.

rulesstr

The rules to use for the solver.

Returns:

bool

Whether the pair is valid.

class color_grid_game.run_game.UIManager(screen, colors, colors_title)

Bases: object

Manages the user interface elements and interactions for the game.

Attributes:

screenpygame.Surface

The screen surface where the game is rendered.

colorsdict

Dictionary mapping color indices to RGB tuples.

colors_titledict

Dictionary mapping title color indices to RGB tuples.

volume_themefloat

Volume level for the theme music.

volumefloat

Volume level for sound effects.

game_themepygame.mixer.Sound

Sound object for the game theme music.

win_soundpygame.mixer.Sound

Sound object for the win sound effect.

lose_soundpygame.mixer.Sound

Sound object for the lose sound effect.

sound_on_imgpygame.Surface

Image surface for the sound on icon.

sound_off_imgpygame.Surface

Image surface for the sound off icon.

color_indexint

Index for cycling through title colors.

color_timerint

Timer for changing title colors.

color_intervalint

Interval for changing title colors.

Methods

draw_volume_button(window_size, pressed)	Draws the volume button on the screen.
toggle_volume()	Toggles the volume between on and off.
draw_return_button(window_size, pressed)	Draws the return button on the screen.
draw_title(window_size)	Draws the title on the screen with cycling colors.
draw_grid_options(window_size, scroll, scroll_bar_rect, scroll_bar_height, grid_files, grid_colors, pressed_index)	Draws the grid options on the screen.
draw_rule_choice(window_size, pressed_button)	Draws the rule choice options on the screen.
darken_color(color, factor=0.7)	Darkens a color by a given factor.
draw_grid(grid, solver, cell_size, selected_cells, game_mode, player_pairs, top_margin, new_rules)	Draws the game grid on the screen.
darken_pair_cells(pair, grid, cell_size, top_margin)	Darkens the cells of a pair without drawing the line.
draw_pair_line(pair, color, cell_size, top_margin)	Draws the line between the centers of two cells.
draw_pair_frame(pair, color, cell_size, top_margin)	Draws a frame around a pair of cells.
draw_score(solver, window_size, cell_size, player1_score, player2_score, game_mode, player_timers, current_player)	Draws the score on the screen.
draw_turn_indicator(current_player, window_size, top_margin, game_mode)	Draws the turn indicator on the screen.
draw_end_screen(message, color, window_size)	Draws the end screen on the screen.
draw_error_message(message, window_size, mode, cell_size)	Draws an error message on the screen.
draw_restart_button(window_size, pressed, mode)	Draws the restart button on the screen.
draw_solution_button(window_size, pressed)	Draws the solution button on the screen.
draw_menu_button(window_size, pressed)	Draws the menu button on the screen.
draw_rules_button(window_size, pressed)	Draws the rules button on the screen.
draw_player_choice(window_size, pressed_button)	Draws the player choice options on the screen.
draw_rules(window_size, scroll, scroll_bar_rect, scroll_bar_height)	Draws the rules on the screen.

darken_color(color, factor=0.7)

Darkens a color by a given factor.

Parameters:

colortuple

The RGB color to darken.

factorfloat, optional

The factor by which to darken the color.

Returns:

tuple

The darkened RGB color.

darken_pair_cells(pair, grid, cell_size, top_margin)

Darkens the cells of a pair without drawing the line.

Parameters:

pairtuple

The pair of cells to darken.

gridGrid

The game grid.

cell_sizeint

The size of each cell.

top_marginint

The top margin for the grid.

draw_end_screen(message, color, window_size)

Draws the end screen on the screen.

Parameters:

messagestr

The message to display.

colortuple

The color to use for the message.

window_sizetuple

The size of the window (width, height).

draw_error_message(message, window_size, mode, cell_size)

Draws an error message on the screen.

Parameters:

messagestr

The error message to display.

window_sizetuple

The size of the window (width, height).

modestr

The game mode (‘one’, ‘two’, or ‘bot’).

cell_sizeint

The size of each cell.

draw_grid(grid, solver, cell_size, selected_cells, game_mode, player_pairs, top_margin, new_rules)

Draws the game grid on the screen.

Parameters:

gridGrid

The game grid.

solverSolver

The solver for the game.

cell_sizeint

The size of each cell.

selected_cellslist

List of selected cells.

game_modestr

The game mode (‘one’, ‘two’, or ‘bot’).

player_pairslist

List of player pairs.

top_marginint

The top margin for the grid.

new_rulesbool

Whether the new rules are being used.

draw_grid_options(window_size, scroll, scroll_bar_rect, scroll_bar_height, grid_files, grid_colors, pressed_index)

Draws the grid options on the screen.

Parameters:

window_sizetuple

The size of the window (width, height).

scrollint

The current scroll position.

scroll_bar_rectpygame.Rect

The rectangle for the scroll bar.

scroll_bar_heightint

The height of the scroll bar.

grid_fileslist

List of grid files.

grid_colorslist

List of colors for the grid files.

pressed_indexint

The index of the pressed grid option.

draw_menu_button(window_size, pressed)

Draws the menu button on the screen.

Parameters:

window_sizetuple

The size of the window (width, height).

pressedbool

Whether the button is pressed.

draw_pair_frame(pair, color, cell_size, top_margin)

Draws a frame around a pair of cells.

Parameters:

pairtuple

The pair of cells to frame.

colortuple

The color to use for the frame.

cell_sizeint

The size of each cell.

top_marginint

The top margin for the grid.

draw_pair_line(pair, color, cell_size, top_margin)

Draws the line between the centers of two cells.

Parameters:

pairtuple

The pair of cells to connect.

colortuple

The color of the line.

cell_sizeint

The size of each cell.

top_marginint

The top margin for the grid.

draw_player_choice(window_size, pressed_button)

Draws the player choice options on the screen.

Parameters:

window_sizetuple

The size of the window (width, height).

pressed_buttonstr

The currently pressed button.

draw_restart_button(window_size, pressed, mode)

Draws the restart button on the screen.

Parameters:

window_sizetuple

The size of the window (width, height).

pressedbool

Whether the button is pressed.

modestr

The game mode (‘one’, ‘two’, or ‘bot’).

draw_return_button(window_size, pressed)

Draws the return button on the screen.

Parameters:

window_sizetuple

The size of the window (width, height).

pressedbool

Whether the button is pressed.

draw_rule_choice(window_size, pressed_button)

Draws the rule choice options on the screen.

Parameters:

window_sizetuple

The size of the window (width, height).

pressed_buttonstr

The currently pressed button (‘classic’ or ‘new’).

draw_rules(window_size, scroll, scroll_bar_rect, scroll_bar_height)

Draws the rules on the screen.

Parameters:

window_sizetuple

The size of the window (width, height).

scrollint

The current scroll position.

scroll_bar_rectpygame.Rect

The rectangle for the scroll bar.

scroll_bar_heightint

The height of the scroll bar.

draw_rules_button(window_size, pressed)

Draws the rules button on the screen.

Parameters:

window_sizetuple

The size of the window (width, height).

pressedbool

Whether the button is pressed.

draw_score(solver, window_size, cell_size, player1_score, player2_score, game_mode, player_timers, current_player, player1_bot_type, player2_bot_type)

Draws the score on the screen.

Parameters:

solverSolver

The solver for the game.

window_sizetuple

The size of the window (width, height).

cell_sizeint

The size of each cell.

player1_scoreint

The score of player 1.

player2_scoreint

The score of player 2.

game_modestr

The game mode (‘one’, ‘two’, or ‘bot’).

player_timerslist

List of player timers.

current_playerint

The current player (1 or 2).

draw_solution_button(window_size, pressed)

Draws the solution button on the screen.

Parameters:

window_sizetuple

The size of the window (width, height).

pressedbool

Whether the button is pressed.

draw_title(window_size)

Draws the title on the screen with cycling colors.

Parameters:

window_sizetuple

The size of the window (width, height).

draw_turn_indicator(current_player, window_size, top_margin, game_mode, player1_bot_type, player2_bot_type)

Draws the turn indicator on the screen.

Parameters:

current_playerint

The current player (1 or 2).

window_sizetuple

The size of the window (width, height).

top_marginint

The top margin for the grid.

game_modestr

The game mode (‘one’, ‘two’, or ‘bot’).

draw_volume_button(window_size, pressed)

Draws the volume button on the screen.

Parameters:

window_sizetuple

The size of the window (width, height).

pressedbool

Whether the button is pressed.

toggle_volume()

Toggles the volume between on and off.

color_grid_game.solver module

class color_grid_game.solver.Solver(grid: Grid, rules='original rules')

Bases: object

A solver class for finding optimal pairs in a grid.

Attributes:

gridGrid

The grid to be solved.

pairslist[tuple[tuple[int, int], tuple[int, int]]]

A list of pairs, each being a tuple ((i1, j1), (i2, j2)) representing paired cells.

rulesstr

The rules to apply for solving the grid. Default is “original rules”.

Methods

score()

Computes the score of the list of pairs in self.pairs.

score() → int

Computes the score of the list of pairs in self.pairs.

The score is calculated as the sum of the values of unpaired cells excluding black cells, plus the sum of the cost of each pair of cells.

Returns:

int

The computed score.

Raises:

ValueError

If any cell in pairs is invalid.

Module contents

color_grid_game package initializer