Gyges game engine functions. More...

#include <stdbool.h>

Include dependency graph for board.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	DIMENSION 6
	Game dimension. More...

#define	NB_SIZE 3
	number of sizes for robustness if the enumeration is modified.

#define	NB_PLAYERS 2
	number of players in the game.

#define	NB_INITIAL_PIECES 2
	number of pieces of each size on each player's line at the beginning. Usually, this value is 2.

Typedefs
typedef struct board_s *	board
	Pointer to the structure that holds the game. More...

typedef enum sizes_e	size

typedef enum players_e	player

typedef enum direction_e	direction

typedef enum return_code_e	return_code

Enumerations
enum	sizes_e { NONE, ONE, TWO, THREE }
	the different sizes of pieces. More...

enum	players_e { NO_PLAYER, SOUTH_P, NORTH_P }
	the different players for further reference. NO_PLAYER is used when informing that a square is empty. SOUTH starts on the side of the board with line number 0, NORTH on the side with line number DIMENSION + 1

enum	direction_e { GOAL, SOUTH, NORTH, EAST, WEST }
	the different directions in the game. GOAL is legal only on the northmost line for south player, southmost line for north player. other directions are natural.

enum	return_code_e { OK, EMPTY, FORBIDDEN, PARAM }
	error codes returned by the function More...

Functions
player	next_player (player current_player)
	return the next player More...

Creation/deletion functionalities.
board	new_game ()
	Defines a new empty board for starting a game of gobblet-gobblers.

board	copy_game (board original_game)
	Makes a deep copy of the game. More...

void	destroy_game (board game)
	Delete the game and frees all required memory. More...

Accessing game data functionalities.
size	get_piece_size (board game, int line, int column)
	returns the size of the piece at the precised position on the board, if any. More...

player	get_winner (board game)
	Tells if the game has a winner. More...

int	southmost_occupied_line (board game)
	Returns the most southern line number which contains a piece. More...

int	northmost_occupied_line (board game)
	Returns the northmost line number which contains a piece. More...

player	picked_piece_owner (board game)
	returns the player whose piece is currently moving More...

size	picked_piece_size (board game)
	returns the size of the piece currently moving (if any) More...

int	picked_piece_line (board game)
	returns the line number of the piece currently moving (if any). More...

int	picked_piece_column (board game)
	returns the column number of the piece currently moving (if any) More...

int	movement_left (board game)
	returns the number of movement units left to the current moving piece More...

Game setting up
Functionalities for the initial phase, initial placing of the pieces.
int	nb_pieces_available (board game, size piece, player player)
	Indicates whether the size of piece is still to be placed by the suggested player. More...

return_code	place_piece (board game, size piece, player player, int column)
	places a piece on the board, during the initial setting up of the game. More...

Playing functionalities
return_code	pick_piece (board game, player current_player, int line, int column)
	Select a piece to start with. More...

bool	is_move_possible (board game, direction direction)
	Indicates whether a move is possible. More...

return_code	move_piece (board game, direction direction)
	Moves the current picked piece, if possible. More...

return_code	swap_piece (board game, int target_line, int target_column)
	swap the current piece with the piece below it, and place the piece below at the given position. More...

return_code	cancel_movement (board game)
	cancels the current movement of the player, putting the piece back where it started. More...

return_code	cancel_step (board game)
	cancels the last step of the current move. More...

Detailed Description

Gyges game engine functions.

In this file, all the functions for having a game of gyges run are defined.

Author: Dorbec

Macro Definition Documentation

◆ DIMENSION

#define DIMENSION 6

Game dimension.

For being general in terms of dimensions, they are defined in a general parameter, though the parameter is not supposed to change. In the following, all indices are given from 0 to DIMENSION - 1. Small line numbers correspond to south.

Typedef Documentation

◆ board

typedef struct board_s* board

Pointer to the structure that holds the game.

Details of the content are not necessary for its use, so the structure is not included here.

Enumeration Type Documentation

◆ return_code_e

enum return_code_e

error codes returned by the function

Enumerator
OK	success
EMPTY	given space should or should not be empty
FORBIDDEN	forbidden request
PARAM	invalid parameter

◆ sizes_e

enum sizes_e

the different sizes of pieces.

This set includes reference to an 'empty' size, for representing no piece at all. They are ordered by increasing size, so that they can be compared with < or >.

Enumerator
NONE	no size, for representing no piece
ONE	size 1
TWO	size 2
THREE	size 3

Function Documentation

◆ cancel_movement()

return_code cancel_movement ( board game )

cancels the current movement of the player, putting the piece back where it started.

This is necessary since a player could start a movement with some piece which have no possible issue. Using this function, the moving piece is placed back where it started, and no piece is consiedered picked anymore. The function returns OK when the operation succeeds, otherwise a return_code corresponding the the problem met:

EMPTY if there is no piece currently in movement.

Parameters

game	the game where to cancel the movement.

Returns: a return code encoding the result of swap, OK if things went smoothly.

◆ cancel_step()

return_code cancel_step ( board game )

cancels the last step of the current move.

This function cancels only the last step of the current move. If the last step was just picking the piece, this is equivalent to cancelling the movement.

The function returns OK when the operation succeeds, otherwise a return_code corresponding the the problem met:

EMPTY if there is no piece currently in movement.

Parameters

game	the game where to cancel the movement.

Returns: a return code encoding the result of swap, OK if things went smoothly.

◆ copy_game()

board copy_game ( board original_game )

Makes a deep copy of the game.

Parameters

original_game the game to copy.

Returns: a new copy fully independent of the original game.

◆ destroy_game()

void destroy_game ( board game )

Delete the game and frees all required memory.

Parameters

game	the game to destroy.

◆ get_piece_size()

size get_piece_size	(	board	game,
		int	line,
		int	column
	)

returns the size of the piece at the precised position on the board, if any.

Return the size of a piece on the board, NONE if there is no piece. If there is a piece being moved on that place, it is not taken into account by this function. If the coordinates do not correspond to a valid place on the board, returns NONE.

Parameters

game	the game from which to collect information.
line	the line number, South has small values.
column	the column number.

Returns: the size of the holding piece.

◆ get_winner()

player get_winner ( board game )

Tells if the game has a winner.

Recall that winning condition is that one player reached the goal, placing one piece there.

Parameters

game	the game to test.

Returns: the player who wins, possibly NO_PLAYER.

◆ is_move_possible()

bool is_move_possible	(	board	game,
		direction	direction
	)

Indicates whether a move is possible.

Returns true if the move is possible for the current piece. The direction GOAL is possible if the piece is on the northmost line and south is playing, or reversely. Other moves are possible if the place indicated by the direction, or if it contains a piece and the piece has only one movement unit left. Additionnally, if the piece has already made a move along this line, the movement should no longer be possible.

Parameters

game	the game where to move a piece.
direction	the direction where the movement is aimed

Returns: whether a move in that direction is possible.

◆ move_piece()

return_code move_piece	(	board	game,
		direction	direction
	)

Moves the current picked piece, if possible.

Moves the piece according to the given direction. If the piece arrived over another piece at the end of its previous movement, calling this function set that the piece bounced and continues its movement. The direction may be GOAL if the piece is on the closest line to the goal. If moving the piece is not possible, returns a return_code encoding the identified problem. EMPTY: there is no piece currently in the players hand. PARAM: the target position is off the board FORBIDDEN: moving toward that position is not allowed (e.g. occupied while the piece movement is not finished or target is GOAL but not reachable) Otherwise, returns OK for success.

Parameters

game	the game where to move a piece.
direction	the direction where the movement is aimed.

Returns: a return_code encoding the result of the placement.

◆ movement_left()

int movement_left ( board game )

returns the number of movement units left to the current moving piece

If a piece is currently being moved, this function returns the number of movement unit left to that piece (ignoring future bouncing) This function returns 0 if and only if the piece just finished its movement over another piece (i.e. the player must choose whether to bounce or to substitute the piece with the one under.) If there is no piece under movement, this function returns -1.

Parameters

game	the game to consider.

Returns: the number of moves left to the piece.

◆ nb_pieces_available()

int nb_pieces_available	(	board	game,
		size	piece,
		player	player
	)

Indicates whether the size of piece is still to be placed by the suggested player.

returns the number of pieces of the given size the players still need to place, -1 if the parameters are invalid. The behaviour of this function simply assumes the game is in initial phase, no verification is made.

Parameters

game	the game to be considered
piece	the piece size requested
player	the player whose piece is to check

Returns: the number of pieces of that size to be placed by the player

◆ next_player()

player next_player ( player current_player )

return the next player

This function simply return the player following current_player in the game turn. It does not use any information from the board game it is merely a turn among the players. It also serve as an example for the unit tests.

Parameters

player the player to change

Returns: the next player

◆ northmost_occupied_line()

int northmost_occupied_line ( board game )

Returns the northmost line number which contains a piece.

This can be used for deciding whether a north player move is legal. This is the largest line number to carry a piece that can move for player North. If there is no piece that can move on any line, return -1 (the board is empty)

Parameters

game	the game to consider.

Returns: the line number.

◆ pick_piece()

return_code pick_piece	(	board	game,
		player	current_player,
		int	line,
		int	column
	)

Select a piece to start with.

The piece must be taken from the player's line. Whether the player is allowed to play the piece is tested. The piece is then ready to be moved with the other functions,

If picking the piece is not possible, the return_code indicates why, in this order:

PARAM: invalid parameters.
EMPTY: the position is empty.
FORBIDDEN: the piece does not belong to the line the player is supposed to move from, or the game already has a winner. Otherwise, returns OK for success.

Parameters

game	the game where to pick a piece.
current_player	the player who is supposed to be playing.
line	the line number of where to pick the piece (from 0 to DIMENSION - 1).
column	the column number of where to pick the piece (from 0 to DIMENSION - 1).

Returns: an integer encoding the result of the placement, 0 if things went smoothly.

◆ picked_piece_column()

int picked_piece_column ( board game )

returns the column number of the piece currently moving (if any)

If a player is currently moving, return the column number of the moving piece. Returns -1 if no piece is being moved.

Parameters

game	the game to consider.

Returns: the column number of the moving piece.

◆ picked_piece_line()

int picked_piece_line ( board game )

returns the line number of the piece currently moving (if any).

If a player is currently moving, return the line number of the moving piece. returns -1 if no piece is being moved.

Parameters

game	the game to consider.

Returns: the line number of the moving piece.

◆ picked_piece_owner()

player picked_piece_owner ( board game )

returns the player whose piece is currently moving

If a player is currently in a move, returns that player's side. Otherwise, returns NO_PLAYER.

Parameters

game	the game to consider.

Returns: the player who is currently moving.

◆ picked_piece_size()

size picked_piece_size ( board game )

returns the size of the piece currently moving (if any)

If a player is currently in a move, returns the piece size, returns NONE if there is no piece currently in hand.

Parameters

game	the game to consider.

Returns: the size of the piece currently moving.

◆ place_piece()

return_code place_piece	(	board	game,
		size	piece,
		player	player,
		int	column
	)

places a piece on the board, during the initial setting up of the game.

The piece is placed on the given player's side, which determines the line number. If placing the piece is not possible, the function returns in this order:

PARAM: if the parameters are invalid (wrong player, piece size or position out of the board)
EMPTY: the indicated position is not empty.
FORBIDDEN: this player has already placed his maximum number of pieces of that size.

Parameters

game	the game to consider
piece	the piece size requested
player	the player whose piece to place
column	the column where to place the piece (from 0 to DIMENSION - 1)

Returns: a return code stating the result of the placement

◆ southmost_occupied_line()

int southmost_occupied_line ( board game )

Returns the most southern line number which contains a piece.

This can be used for deciding whether a south player move is legal This is the smallest line number to carry a piece that can move for player South. If there is no piece that can move on any line, return -1 (the board is empty).

Parameters

game	the game to consider.

Returns: the line number.

◆ swap_piece()

return_code swap_piece	(	board	game,
		int	target_line,
		int	target_column
	)

swap the current piece with the piece below it, and place the piece below at the given position.

If the piece moving just finished its movement over another piece, this function allows the player to swap the two pieces, and place the piece below anywhere. A successful swap finishes the movement of the player (no picked piece, no moves left, etc.) The function returns OK when the operation succeeds, otherwise a return_code corresponding the the problem met:

EMPTY if the swapping is not possible at the moment (the current moving piece has not finished its movement over another piece)
PARAM when the position proposed is off the board.
FORBIDDEN when the position proposed is not free or the move is not currently possible.
Parameters

game the game where to move a piece.

target_line the line number of where to move the swapped piece.

target_column the column number of where to move the swapped piece.

Returns
a return code encoding the result of swap, OK if things went smoothly.

game	the game where to move a piece.
target_line	the line number of where to move the swapped piece.
target_column	the column number of where to move the swapped piece.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DIMENSION

Typedef Documentation

◆ board

Enumeration Type Documentation

◆ return_code_e

◆ sizes_e

Function Documentation

◆ cancel_movement()

◆ cancel_step()

◆ copy_game()

◆ destroy_game()

◆ get_piece_size()

◆ get_winner()

◆ is_move_possible()

◆ move_piece()

◆ movement_left()

◆ nb_pieces_available()

◆ next_player()

◆ northmost_occupied_line()

◆ pick_piece()

◆ picked_piece_column()

◆ picked_piece_line()

◆ picked_piece_owner()

◆ picked_piece_size()

◆ place_piece()

◆ southmost_occupied_line()

◆ swap_piece()