numberlink.levels

Level definitions for the numberlink.env.NumberLinkRGBEnv environment.

This module defines the numberlink.levels.Level dataclass and the numberlink.levels.LEVELS mapping of built-in level definitions. Each numberlink.levels.Level stores a row oriented grid where uppercase letters denote endpoint cells and '.' denotes empty cells. Optional bridge coordinates may be supplied to mark bridge cells used by level construction in numberlink.

Use numberlink.levels.Level to define custom levels or access numberlink.levels.LEVELS for examples.

Module Contents

Classes

Level

Static representation of a NumberLink puzzle board.

Functions

_read_text_lines	Read non-empty, stripped lines from a package resource file.
_load_solution_json	Attempt to load a JSON solution adjacent to a grid file.
_level_from_asset	Create a Level from a packaged assets/levels/*.txt resource.
load_level_from_file	Load a level from a text file with an optional adjacent solution.
_scan_asset_levels	Load up to limit levels from packaged assets into a mapping.

Data

BUILTIN_LEVELS
LEVELS

API

class numberlink.levels.Level

Static representation of a NumberLink puzzle board.

Represent a board as a list of row strings. Uppercase letters denote endpoint cells and '.' denotes an empty cell. Optionally include a sequence of bridge coordinates to indicate bridge cells. An optional precomputed solution can be attached for O(1) retrieval by the viewer or tools.

Parameters:

• grid (list[str]) – Row oriented grid where each string represents a board row.

• bridges (collections.abc.Iterable[tuple[int, int]] or None) – Coordinates treated as bridge cells by numberlink.level_setup.build_level_template() when building an environment instance. May be None when not used.

• solution (list[list[tuple[int, int]]] or None) – Optional list of paths where each path is a list of (row, column) coordinate tuples. Path order corresponds to the color order implied by the grid letters.

grid: list[str] = None

bridges: collections.abc.Iterable[Coord] | None = None

solution: list[list[Coord]] | None = None

numberlink.levels._read_text_lines(res_file: importlib.resources.abc.Traversable) → list[str]

Read non-empty, stripped lines from a package resource file.

numberlink.levels._load_solution_json(res_file: importlib.resources.abc.Traversable) → list[list[Coord]] | None

Attempt to load a JSON solution adjacent to a grid file.

Expected JSON format: list of paths, where each path is a list of [row, col] pairs. Returns None when the file doesn’t exist.

numberlink.levels._level_from_asset(txt_name: str) → numberlink.levels.Level

Create a Level from a packaged assets/levels/*.txt resource.

Also attempts to load an optional .sol.json with the same stem for solution coordinates.

numberlink.levels.load_level_from_file(txt_path: str | pathlib.Path) → numberlink.levels.Level

Load a level from a text file with an optional adjacent solution.

The grid file must contain one row per line. Leading/trailing whitespace and empty lines are ignored. If a solution file is present alongside the grid with suffix .sol.json appended to the grid filename, it is parsed and attached to the returned Level.

Example: /path/to/board.txt with optional /path/to/board.txt.sol.json.

numberlink.levels._scan_asset_levels(limit: int = 20) → dict[str, numberlink.levels.Level]

Load up to limit levels from packaged assets into a mapping.

Level ids are derived from the filename stem with a file_ prefix, for example file_5x5_01.

numberlink.levels.BUILTIN_LEVELS: dict[str, numberlink.levels.Level] = None

numberlink.levels.LEVELS: dict[str, numberlink.levels.Level] = None