numberlink.config

Configuration dataclasses for the Number Link environment.

This module defines frozen dataclasses that configure runtime reward shaping, gameplay variants, procedural generation parameters, and rendering options. The classes defined here are consumed by numberlink.env and by numberlink.generator.generate_level().

See also

numberlink.config.RewardConfig

Reward shaping parameters used by the environment.

numberlink.config.VariantConfig

Gameplay variant switches used by the generator and environment.

numberlink.config.GeneratorConfig

Parameters that control procedural level generation.

numberlink.config.RenderConfig

Options that control RGB rendering produced by the viewer.

Module Contents

Classes

RewardConfig	Reward shaping parameters used by the environment.
VariantConfig	Gameplay variant switches used by the generator and environment.
GeneratorConfig	Parameters that configure procedural level generation.
RenderConfig	Rendering options for RGB arrays produced by the viewer.

API

class numberlink.config.RewardConfig

Reward shaping parameters used by the environment.

Instances of this dataclass are frozen to allow safe sharing across components. Values from this configuration are applied by numberlink.env when computing the reward for a timestep.

Variables:

• step_penalty (float) – Per-step penalty applied on every environment step.

• invalid_penalty (float) – Extra penalty applied when an invalid action is taken.

• connect_bonus (float) – Bonus awarded when a color connection is completed.

• win_bonus (float) – Bonus awarded when the puzzle is completed and the win condition is satisfied.

See also

numberlink.config.GeneratorConfig

Generation parameters that influence how often connections are completed during play.

step_penalty: float = None

invalid_penalty: float = None

connect_bonus: float = 0.5

win_bonus: float = 5.0

class numberlink.config.VariantConfig

Gameplay variant switches used by the generator and environment.

Instances of this dataclass control rule variations applied by the level generator and by environment logic. For example, enabling allow_diagonal changes adjacency checks used by numberlink.generator._gen_random_walk() and distance calculations performed by numberlink.generator._shortest_dist().

Variables:

• must_fill (bool) – If True, all board cells must be occupied to satisfy the win condition.

• allow_diagonal (bool) – If True, diagonal moves are allowed and shortest-distance calculations use Chebyshev distance instead of Manhattan distance.

• bridges_enabled (bool) – If True, generated puzzles may include bridge cells that permit two lanes of traversal through a single grid cell.

• cell_switching_mode (bool) – If True, use an alternative action mode in which non-endpoint cells can be assigned any color independently of path continuity.

See also

numberlink.generator._shortest_dist()

Function used to compute distances when allow_diagonal affects adjacency.

must_fill: bool = True

allow_diagonal: bool = False

bridges_enabled: bool = False

cell_switching_mode: bool = False

class numberlink.config.GeneratorConfig

Parameters that configure procedural level generation.

Use this dataclass to select the generation algorithm and to tune constraints applied by numberlink.generator.generate_level(). Supported values for mode are 'random_walk' and 'hamiltonian'.

The min_path_length field enforces a minimum shortest-path distance between endpoints. Distance is computed using Manhattan distance by default and Chebyshev distance when the VariantConfig has allow_diagonal set to True.

Variables:

• mode (str) – Generation algorithm identifier. Valid values are 'random_walk' and 'hamiltonian'.

• max_retries (int) – Maximum number of attempts the generator will make when retrying placement constraints.

• width (int) – Board width in cells.

• height (int) – Board height in cells.

• colors (int) – Number of color pairs to generate.

• bridges_probability (float) – Probability in the range [0.0, 1.0] that a bridge cell is added during generation.

• min_path_length (int) – Minimum shortest-path distance enforced between the endpoints for each generated color pair.

• seed (int or None) – Optional random seed used for reproducible generation. If None, generation is non-deterministic.

Note

The procedural Hamiltonian generator does not support bridge placement. See numberlink.generator._gen_hamiltonian_partition() for implementation details.

mode: str = 'hamiltonian'

max_retries: int = 20

width: int = 8

height: int = 8

colors: int = 7

bridges_probability: float = 0.0

min_path_length: int = 3

seed: int | None = None

class numberlink.config.RenderConfig

Rendering options for RGB arrays produced by the viewer.

Fields in this dataclass control how endpoints and connections are visualized when rendering the puzzle as an RGB image. The configuration is consumed by numberlink.viewer and by rendering utilities in numberlink.render_utils.

Variables:

• endpoint_border_thickness (int) – Thickness in pixels of the border drawn for endpoints. 0 disables borders.

• endpoint_border_color (RGBInt) – RGB color triple used for endpoint borders, for example (255, 255, 255) for white.

• connection_color_adjustment (int) – Integer adjustment to connection colors when endpoint borders are not drawn. Positive values brighten colors and negative values darken them.

• render_height (int or None) – Total height in pixels of the rendered RGB observation. If None, defaults to one pixel per grid row. When specified, each grid cell will be rendered as render_height // grid_height pixels tall.

• render_width (int or None) – Total width in pixels of the rendered RGB observation. If None, defaults to one pixel per grid column. When specified, each grid cell will be rendered as render_width // grid_width pixels wide.

• grid_background_color (RGBInt) – RGB color triple used for the grid background.

• gridline_color (RGBInt or None) – RGB color triple used for grid lines between cells. If None, no gridlines are drawn.

• gridline_thickness (int) – Thickness in pixels of gridlines drawn between cells. Ignored if gridline_color is None.

• show_endpoint_numbers (bool) – If True, endpoint cells display their color index number starting from 0. Endpoints of the same color share the same number.

• number_font_color (RGBInt) – RGB color triple used for endpoint number text.

• number_font_border_color (RGBInt) – RGB color triple used for number outline.

• number_font_border_thickness (int) – Thickness in pixels for the font outline drawn around endpoint numbers.

• number_font_min_scale (int) – Minimum integer font scale unit for endpoint labels. If None, automatic sizing based on cell pixels is allowed.

• number_font_max_scale (int or None) – Maximum integer font scale unit for endpoint labels. If None, automatic sizing based on cell pixels is allowed.

• help_overlay_font_color (RGBInt) – RGB color triple used for help overlay text.

• help_overlay_font_border_color (RGBInt) – RGB color triple used for help overlay text outline.

• help_overlay_font_border_thickness (int) – Thickness in pixels for the help-overlay font outline.

• help_overlay_background_color (RGBInt) – RGB color triple used for the overlay background.

• help_overlay_background_alpha (int) – Alpha value for the help overlay background in the range 0 to 255.

• active_head_highlight_color (RGBInt) – RGB color triple used for the active head highlight in the human viewer.

• active_head_highlight_thickness (int) – Thickness in pixels for the active head highlight.

• cursor_highlight_thickness (int) – Thickness in pixels for cursor highlights.

• cursor_endpoint_highlight_color (RGBInt) – RGB color triple used for the cursor endpoint highlight.

• print_text_in_human_mode (bool) – If True, print the text representation of the grid to standard output when render mode is 'human'. If False, text output is only returned but not printed.

See also

numberlink.render_utils

Helpers that convert board state to RGB arrays using these settings.

endpoint_border_thickness: int = 1

endpoint_border_color: RGBInt = (255, 255, 255)

connection_color_adjustment: int = 0

render_height: int | None = None

render_width: int | None = None

grid_background_color: RGBInt = (0, 0, 0)

gridline_color: RGBInt | None = (128, 128, 128)

gridline_thickness: int = 1

show_endpoint_numbers: bool = True

number_font_color: RGBInt = (255, 255, 255)

number_font_border_color: RGBInt = (0, 0, 0)

number_font_border_thickness: int = 0

number_font_min_scale: int = 1

number_font_max_scale: int | None = None

help_overlay_font_color: RGBInt = (220, 220, 220)

help_overlay_font_border_color: RGBInt = (0, 0, 0)

help_overlay_font_border_thickness: int = 0

help_overlay_background_color: RGBInt = (30, 30, 30)

help_overlay_background_alpha: int = 200

active_head_highlight_color: RGBInt = (255, 255, 255)

active_head_highlight_thickness: int = 2

cursor_highlight_thickness: int = 3

cursor_endpoint_highlight_color: RGBInt = (220, 80, 80)

print_text_in_human_mode: bool = False