Game Management

Core chess game aggregate, PGN header tag roster, comments, boundary positions, and move merging.

Types

	Name
enum	scid_game_merge_moves_modes { SCID_GAME_MERGE_MOVES_REPLACE = 2, SCID_GAME_MERGE_MOVES_INSERT_VARIATION = 1, SCID_GAME_MERGE_MOVES_APPEND = 0} Merge mode enumerators.
typedef int	scid_game_merge_moves_mode Mode specifier controlling how moves from a source game are merged into a target game.
typedef struct scid_game_cursor	scid_game_cursor
typedef struct scid_game	scid_game Opaque handle representing a chess game entity.

Functions

	Name
scid_error	scid_game_tag_set(scid_game * game, const char * name, const char * value) Sets or updates the value of a PGN header tag.
scid_error	scid_game_tag_remove(scid_game * game, const char * name, int * out_removed) Removes a PGN header tag by name.
scid_error	scid_game_tag_get(const scid_game * game, const char * name, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the value of a PGN header tag by name.
scid_error	scid_game_tag_count_get(const scid_game * game, size_t * out_count) Retrieves the total number of PGN header tags present in the game.
scid_error	scid_game_tag_at_get(const scid_game * game, size_t index, char * out_name, size_t out_name_capacity, size_t * out_name_size, char * out_value, size_t out_value_capacity, size_t * out_value_size) Retrieves a PGN tag key-value pair by zero-based index.
scid_error	scid_game_start_position_get(const scid_game * game, scid_position * out_position) Populates a board position handle with the initial starting position of the game.
scid_error	scid_game_merge_moves(scid_game * target_game, const scid_game_cursor * target_cursor, const scid_game * source_game, scid_game_merge_moves_mode mode, scid_game_cursor ** out_cursor) Merges the mainline move sequence from a source game into a target game at the cursor position.
scid_error	scid_game_mainline_halfmove_count_get(const scid_game * game, size_t * out_count) Retrieves the total number of halfmoves (ply) in the mainline of the game.
scid_error	scid_game_initial_comment_get(const scid_game * game, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the initial comment text appearing before the first move of the game.
void	scid_game_free(scid_game * game) Releases a game handle and all associated resources.
scid_error	scid_game_final_position_get(const scid_game * game, scid_position * out_position) Populates a board position handle with the final position reached at the end of the mainline.
scid_error	scid_game_create_blank(const scid_position * position, scid_game ** out_game) Creates a new blank game starting from a specified board position.
scid_error	scid_game_create(const scid_position * position, const char * pgn, size_t pgn_size, scid_game ** out_game, char * out_diagnostic, size_t out_diagnostic_capacity, size_t * out_diagnostic_size) Creates a new game by parsing PGN text.

Types Documentation

enum scid_game_merge_moves_modes

Enumerator	Value	Description
SCID_GAME_MERGE_MOVES_REPLACE	2	Replace subsequent moves in the current line by truncating and appending source moves.
SCID_GAME_MERGE_MOVES_INSERT_VARIATION	1	Insert source moves as a new sub-variation branching off the current position.
SCID_GAME_MERGE_MOVES_APPEND	0	Append source moves to the end of the current line (requires cursor at line end).

Merge mode enumerators.

typedef scid_game_merge_moves_mode

typedef int scid_game_merge_moves_mode;

Mode specifier controlling how moves from a source game are merged into a target game.

typedef scid_game_cursor

typedef struct scid_game_cursor scid_game_cursor;

typedef scid_game

typedef struct scid_game scid_game;

Opaque handle representing a chess game entity.

See:

Encapsulates the Seven Tag Roster (STR) metadata, supplemental PGN tags, initial board starting position, and the hierarchical movetext tree (mainline, variations, comments, and NAGs).

Instances are created using scid_game_create_blank() or scid_game_create(), and must be released when no longer needed using scid_game_free().

Functions Documentation

function scid_game_tag_set

scid_error scid_game_tag_set(
    scid_game * game,
    const char * name,
    const char * value
)

Sets or updates the value of a PGN header tag.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
name Null-terminated tag name. Must not be NULL.
value Null-terminated tag value. Must not be NULL.

Returns:

SCID_OK Tag updated successfully.
SCID_ERROR_BAD_ARG If game, name, or value is NULL, or if value is invalid for restricted tags (e.g. malformed "Result").

See:

Updates an existing tag or adds a new supplemental tag. When updating the "Result" tag, the value is validated against standard PGN result strings ("1-0", "0-1", "1/2-1/2", "*").

function scid_game_tag_remove

scid_error scid_game_tag_remove(
    scid_game * game,
    const char * name,
    int * out_removed
)

Removes a PGN header tag by name.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
name Null-terminated tag name to remove. Must not be NULL.
out_removed Pointer receiving non-zero (1) if the tag was present and removed; 0 if the tag was not found or is non-removable. Must not be NULL.

Returns:

SCID_OK Tag removal processed successfully.
SCID_ERROR_BAD_ARG If game, name, or out_removed is NULL.

See: scid_game_tag_set()

Standard mandatory Seven Tag Roster (STR) tags and "FEN" cannot be removed (writes 0 to out_removed).

function scid_game_tag_get

scid_error scid_game_tag_get(
    const scid_game * game,
    const char * name,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the value of a PGN header tag by name.

Parameters:

game Pointer to the game. Must not be NULL.
name Null-terminated tag name (e.g. "Event", "ECO"). Must not be NULL.
out_text Caller-allocated buffer receiving the null-terminated tag value. May be NULL if out_text_capacity is 0 to query required capacity.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving the number of bytes written (excluding null terminator), or required capacity if the buffer is too small. Must not be NULL.

Returns:

SCID_OK Tag value retrieved successfully.
SCID_ERROR_BAD_ARG If game, name, or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_game_tag_set()

Queries standard Seven Tag Roster (STR) tags (e.g. "Event", "Site", "Date", "Round", "White", "Black", "Result"), well-known supplemental tags (e.g. "ECO", "EventDate", "FEN"), and arbitrary extra tags.

If the specified tag is not present in the game, an empty string "" is written to out_text with *out_text_size = 0.

function scid_game_tag_count_get

scid_error scid_game_tag_count_get(
    const scid_game * game,
    size_t * out_count
)

Retrieves the total number of PGN header tags present in the game.

Parameters:

game Pointer to the game. Must not be NULL.
out_count Pointer receiving the total tag count. Must not be NULL.

Returns:

SCID_OK Tag count retrieved successfully.
SCID_ERROR_BAD_ARG If game or out_count is NULL.

See: scid_game_tag_at_get()

function scid_game_tag_at_get

scid_error scid_game_tag_at_get(
    const scid_game * game,
    size_t index,
    char * out_name,
    size_t out_name_capacity,
    size_t * out_name_size,
    char * out_value,
    size_t out_value_capacity,
    size_t * out_value_size
)

Retrieves a PGN tag key-value pair by zero-based index.

Parameters:

game Pointer to the game. Must not be NULL.
index Zero-based index of the tag to retrieve.
out_name Caller-allocated buffer receiving the tag name. May be NULL if out_name_capacity is 0 to query required capacity.
out_name_capacity Capacity of out_name in bytes.
out_name_size Pointer receiving bytes written to out_name (excluding null terminator), or required capacity. Must not be NULL.
out_value Caller-allocated buffer receiving the tag value. May be NULL if out_value_capacity is 0 to query required capacity.
out_value_capacity Capacity of out_value in bytes.
out_value_size Pointer receiving bytes written to out_value (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Tag name and value retrieved successfully.
SCID_ERROR_BAD_ARG If game, out_name_size, or out_value_size is NULL, or if index is out of bounds.
SCID_ERROR_BUFFER_FULL If out_name_capacity or out_value_capacity is insufficient.

See: scid_game_tag_count_get()

Enables enumeration of all tags present in the game from index 0 to count - 1.

function scid_game_start_position_get

scid_error scid_game_start_position_get(
    const scid_game * game,
    scid_position * out_position
)

Populates a board position handle with the initial starting position of the game.

Parameters:

game Pointer to the game. Must not be NULL.
out_position Pointer to an existing scid_position handle to populate. Must not be NULL.

Returns:

SCID_OK Position populated successfully.
SCID_ERROR_BAD_ARG If game or out_position is NULL.

See: scid_game_final_position_get()

function scid_game_merge_moves

scid_error scid_game_merge_moves(
    scid_game * target_game,
    const scid_game_cursor * target_cursor,
    const scid_game * source_game,
    scid_game_merge_moves_mode mode,
    scid_game_cursor ** out_cursor
)

Merges the mainline move sequence from a source game into a target game at the cursor position.

Parameters:

target_game Pointer to the target game being modified. Must not be NULL.
target_cursor Pointer to the cursor indicating the insertion position in target_game. Must not be NULL.
source_game Pointer to the source game providing moves. Must not be NULL.
mode Merge strategy (SCID_GAME_MERGE_MOVES_APPEND, SCID_GAME_MERGE_MOVES_INSERT_VARIATION, or SCID_GAME_MERGE_MOVES_REPLACE).
out_cursor Pointer to a handle pointer receiving a newly allocated cursor positioned at the end of the merged moves. Must not be NULL.

Returns:

SCID_OK Moves merged successfully.
SCID_ERROR_BAD_ARG If any argument is NULL, mode is invalid, or cursor position does not satisfy preconditions for mode.
SCID_ERROR_INVALID_MOVE If board positions do not match or illegal moves are encountered.

Note: The caller acquires ownership of out_cursor and must release it with scid_game_cursor_free().

Applies moves from source_game according to the chosen mode. The starting position of source_game must match the board position at target_cursor.

function scid_game_mainline_halfmove_count_get

scid_error scid_game_mainline_halfmove_count_get(
    const scid_game * game,
    size_t * out_count
)

Retrieves the total number of halfmoves (ply) in the mainline of the game.

Parameters:

game Pointer to the game. Must not be NULL.
out_count Pointer receiving the mainline ply count. Must not be NULL.

Returns:

SCID_OK Count retrieved successfully.
SCID_ERROR_BAD_ARG If game or out_count is NULL.

function scid_game_initial_comment_get

scid_error scid_game_initial_comment_get(
    const scid_game * game,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the initial comment text appearing before the first move of the game.

Parameters:

game Pointer to the game. Must not be NULL.
out_text Caller-allocated buffer receiving the null-terminated comment text. May be NULL if out_text_capacity is 0 to query required capacity.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving the number of bytes written (excluding null terminator), or required capacity if the buffer is too small. Must not be NULL.

Returns:

SCID_OK Comment retrieved successfully.
SCID_ERROR_BAD_ARG If game or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_game_free

void scid_game_free(
    scid_game * game
)

Releases a game handle and all associated resources.

Parameters:

game Pointer to the game handle to release. If NULL, this function performs no action.

Note: Passing NULL is guaranteed to be a safe no-op.

function scid_game_final_position_get

scid_error scid_game_final_position_get(
    const scid_game * game,
    scid_position * out_position
)

Populates a board position handle with the final position reached at the end of the mainline.

Parameters:

game Pointer to the game. Must not be NULL.
out_position Pointer to an existing scid_position handle to populate. Must not be NULL.

Returns:

SCID_OK Position populated successfully.
SCID_ERROR_BAD_ARG If game or out_position is NULL.
SCID_ERROR_INVALID_MOVE If a corrupt move sequence prevents reaching the end position.

See: scid_game_start_position_get()

function scid_game_create_blank

scid_error scid_game_create_blank(
    const scid_position * position,
    scid_game ** out_game
)

Creates a new blank game starting from a specified board position.

Parameters:

position Pointer to the starting board position. Must not be NULL.
out_game Pointer to a handle pointer receiving the newly allocated scid_game instance. Must not be NULL.

Returns:

SCID_OK Game created successfully.
SCID_ERROR_BAD_ARG If position or out_game is NULL.

See:

Note: Ownership of the created game is transferred to the caller. The caller must release it using scid_game_free().

Initialises standard default PGN tags ([Event "?"], [Site "?"], [Date "????.??.??"], [Round "?"], [White "?"], [Black "?"], [Result "*"]). If position is a non-standard setup, a [FEN "..."] tag is automatically attached.

function scid_game_create

scid_error scid_game_create(
    const scid_position * position,
    const char * pgn,
    size_t pgn_size,
    scid_game ** out_game,
    char * out_diagnostic,
    size_t out_diagnostic_capacity,
    size_t * out_diagnostic_size
)

Creates a new game by parsing PGN text.

Parameters:

position Pointer to the starting position context. Must not be NULL.
pgn Pointer to the PGN text buffer. Must not be NULL.
pgn_size Length of pgn in bytes.
out_game Pointer to a handle pointer receiving the newly allocated game. Must not be NULL.
out_diagnostic Optional caller-allocated buffer receiving parser diagnostic messages. May be NULL if not requested.
out_diagnostic_capacity Capacity of out_diagnostic in bytes.
out_diagnostic_size Optional pointer receiving bytes written to out_diagnostic. May be NULL if not requested.

Returns:

SCID_OK Game parsed and created successfully.
SCID_ERROR_BAD_ARG If position, pgn, or out_game is NULL.
SCID_ERROR_CORRUPT If PGN syntax is invalid or illegal moves are encountered.
SCID_ERROR_BUFFER_FULL If out_diagnostic_capacity is insufficient.

See: scid_game_free()

Parses PGN tags, move notations, nested variations, comments, and NAGs from the provided string buffer.

Updated on 2026-09-02 at 15:26:09 +0000