Usage

This guide walks through common workflows with the NumberLink environments, including the single RGB environment, the vectorized batch environment, and the pygame viewer. The examples assume the package is installed and importable. Refer to Installation for environment setup instructions.

Single RGB Environment

The numberlink.env.NumberLinkRGBEnv class implements the Gymnasium interface and yields RGB observations. Each action encodes (color, head, direction), where every color supplies two heads representing its endpoints. Paths can be extended from either endpoint at any time, and the viewer updates focus automatically when you click on a cell.

import gymnasium as gym
import numpy as np

import numberlink  # Importing the package automatically registers the environment

env = gym.make("NumberLinkRGB-v0", render_mode="rgb_array")

observation, info = env.reset(seed=123)
action_mask = info["action_mask"].astype(np.int8)

terminated = False
truncated = False
while not (terminated or truncated):
   action = env.action_space.sample(mask=action_mask)
   observation, reward, terminated, truncated, info = env.step(action)
   action_mask = info["action_mask"]

env.close()

The import numberlink statement automatically calls numberlink.registration.register_numberlink_v0() during module initialization, making the environment id available for gymnasium.make(). The info dictionary includes the binary action mask, the step counter, connectivity status per color, the level identifier (when available), and two flags named solved and deadlocked.

Customize gameplay and rendering by passing structured configuration objects:

import gymnasium as gym
from numberlink import GeneratorConfig, RenderConfig, VariantConfig

env = gym.make(
   "NumberLinkRGB-v0",
   render_mode="rgb_array",
   generator=GeneratorConfig(width=8, height=8, colors=5),
   variant=VariantConfig(must_fill=True, allow_diagonal=False, bridges_enabled=False),
   render_config=RenderConfig(cell_size=48),
)

observation, info = env.reset(seed=7)
env.close()

See numberlink.config.GeneratorConfig, numberlink.config.VariantConfig, and numberlink.config.RenderConfig for the available fields. numberlink.level_setup documents helper functions that assemble these objects from level templates.

Vector Environment

The numberlink.vector_env.NumberLinkRGBVectorEnv class runs multiple puzzles in parallel. It shares all configuration objects with the single environment and exposes batched observations and rewards.

import gymnasium as gym
import numpy as np

from numberlink import GeneratorConfig

vec_env = gym.make_vec(
   "NumberLinkRGB-v0",
   num_envs=8,
   render_mode="rgb_array",
   generator=GeneratorConfig(width=6, height=6, colors=4),
)

observations, infos = vec_env.reset(seed=7)
actions = [vec_env.single_action_space.sample(mask=mask.astype(np.int8)) for mask in infos["action_mask"]]
observations, rewards, terminated, truncated, infos = vec_env.step(actions)
vec_env.close()

When a batch element reaches a terminal state, the vector environment auto-resets it on the next step. The returned info dict mirrors the single-environment keys but stores arrays of shape (num_envs, ...).

Viewer and Human Mode

The numberlink.viewer module provides a pygame viewer that mirrors the human render mode. It supports both mouse and keyboard control. Clicking any endpoint or occupied cell updates the focus to that color and head, so every path can be extended from either endpoint without using keyboard shortcuts.

import gymnasium as gym
import numberlink  # Auto-registration on import
from numberlink.viewer import NumberLinkViewer

env = gym.make("NumberLinkRGB-v0", render_mode="human")
viewer = NumberLinkViewer(env, cell_size=64)
viewer.loop()

Default controls include arrow keys (and Q/E/Z/C for diagonals when enabled), brackets to pin a specific head, Tab to cycle colors, and Space to backtrack the active head by one cell. In cell switching mode the cursor follows mouse clicks, and painting obeys the active color and configuration.

Notebook environments (Jupyter, JupyterLab, Google Colab) can render the same controls inline when the optional extra numberlink[notebook] is installed. Either instantiate numberlink.notebook_viewer.NumberLinkNotebookViewer directly, or call numberlink.viewer.NumberLinkViewer.loop() and the backend will automatically switch to the widget-based viewer.

env = gym.make(
   "NumberLinkRGB-v0",
   render_mode="human",
   generator=GeneratorConfig(
      mode="hamiltonian",
      colors=7,
      width=8,
      height=8,
      min_path_length=3,
   ),
   variant=VariantConfig(
      must_fill=True,
      allow_diagonal=False,
      cell_switching_mode=False,
      bridges_enabled=False
   ),
   render_config=RenderConfig(
      gridline_color=(60, 60, 60),
      gridline_thickness=1,
      show_endpoint_numbers=True,
      render_height=400,
      render_width=400,
   ),
)
env.reset(seed=2)

viewer = NumberLinkViewer(env, cell_size=64)
viewer.loop()

If the extras are missing, the viewer emits a short installation hint instead of trying to open a pygame window in the notebook runtime.

Command Line Interface

The project ships a command-line interface so you can launch the viewer or inspect boards without writing code. Run python -m numberlink --help to see all subcommands.

viewer launches the interactive pygame window. You can load built-in levels or point the CLI to a custom grid file.

python -m numberlink viewer --level-id 6x6_rgb_2 --cell-size 72 --apply-solution

board prints a text rendering of the puzzle and optionally applies the stored solution.

python -m numberlink board --level-id builtin_7x7_ham_6c --apply-solution

levels lists every bundled level id, and register registers the Gymnasium id NumberLinkRGB-v0 for external use. All commands share the same variant flags (for example --allow-diagonal or --bridges-enabled) so you can inspect the same configuration interactively and in text mode.

Configuration Overview

NumberLink uses structured dataclasses to describe gameplay and rendering:

Customize these objects directly or through helper functions in numberlink.level_setup before constructing an environment.

Artifacts and Further Reading

  • Sample level definitions and generator presets live in numberlink.level_setup and numberlink.generator.

  • Example scripts under examples/ demonstrate solving, rendering, and evaluation patterns.

  • The tests/ directory includes unit tests for cell switching, vectorized execution, rendering, and configuration utilities.