NumberLink Documentation¶

NumberLink connects matching endpoints with non overlapping paths on a grid.

numberlink provides a Gymnasium RGB environment, a vectorized batch variant, and a pygame viewer described in Usage. This environment was inspired by Puzzle Baron’s NumberLinks.

Gameplay Rules¶

NumberLink boards follow these invariants:

Every pair of endpoints must be connected by a single path. Endpoints are enumerated in numberlink.level_setup.LevelTemplate and copied into the environment state.
Paths cannot branch or reuse grid cells. The environment enforces this through the action mask returned by numberlink.env.NumberLinkRGBEnv.reset() and numberlink.env.NumberLinkRGBEnv.step().
Unless the chosen variant disables the requirement, every cell must belong to a path. Toggle this rule with numberlink.config.VariantConfig.must_fill.
Bridge cells yield independent vertical and horizontal lanes governed by numberlink.config.VariantConfig.bridges_enabled.
Diagonal moves are allowed only when numberlink.config.VariantConfig.allow_diagonal is set. Cell switching is controlled by numberlink.config.VariantConfig.cell_switching_mode.

Quick Install¶

Install the published package from PyPI:

pip install numberlink

For a reproducible workflow, uv can manage the virtual environment and dependencies:

uv pip install numberlink

See Installation for Conda, Pixi, and source builds.

Quick Start¶

Explore the workflows below or launch the interactive Google Colab example.

Setup Example¶

import gymnasium as gym
import numpy as np

import numberlink  # Importing the package automatically registers NumberLinkRGB-v0

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

observation, info = env.reset(seed=42)
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 registers the environment id with Gymnasium, making it immediately available for use. When installed from PyPI, Gymnasium can also discover the environment through package entry points without needing an explicit import.

Vectorized execution¶

import gymnasium as gym
import numpy as np

import numberlink  # Auto-registration on import

vec_env = gym.make_vec("NumberLinkRGB-v0", num_envs=4, render_mode="rgb_array")

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()

Single environments and vector environments share numberlink.config.GeneratorConfig, numberlink.config.VariantConfig, and numberlink.config.RenderConfig. See Usage for parameter tables and composition utilities in numberlink.level_setup.

Human mode viewer¶

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)
viewer.loop()