numberlink 0.1.0

NumberLink puzzle environment for Gymnasium

NumberLink Environment for Gymnasium

A Gymnasium environment for the NumberLink puzzle game.

Gameplay Rules

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

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 links

• Quick start: Quick Start
• Google Colab: Open in Colab
• Installation guide: Installation - documentation site
• CLI reference: CLI - documentation site
• Python usage (API snippets): API reference - documentation site
• Citing this project: Cite this project
• Contact: Contact

Demo

Quick start

The NumberLink documentation covers every workflow in detail. The highlights below show the recommended Gymnasium >= 1.0 usage patterns. You can also try it out in the Google Colab example.

Install from PyPI

Using pip

pip install numberlink

Install with uv

uv pip install numberlink

See the installation guide for Pixi, Conda, and source build instructions.

Create a single environment

import gymnasium as gym

# Gymnasium discovers NumberLinkRGB-v0 from the package entry points
env = gym.make("NumberLinkRGB-v0", render_mode="rgb_array")

observation, info = env.reset(seed=42)
action_mask = info["action_mask"]

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

Configuration objects such as GeneratorConfig, VariantConfig, and RenderConfig customize generation, gameplay rules, and rendering. Examples live in the usage guide and the level setup module.

Run vectorized environments

import gymnasium as gym
from numberlink import GeneratorConfig

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

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

Gymnasium auto resets terminated slots when the vector environment is configured with the default autoreset mode. See the vector API section of the docs for batched workflows.

Human render mode

import gymnasium as gym
import numberlink
from numberlink.viewer import NumberLinkViewer

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

The pygame viewer mirrors the CLI command shown in examples/run_human.py and is documented at viewer API.

Auto-registration

Recommended usage is to install the package (for example via PyPI), and Gymnasium then discovers the environments via the package's entry-points and you can call gymnasium.make(...) / gymnasium.make_vec(...) directly. If you need to register the env id in-process (for development or interactive use), call:

import numberlink
numberlink.register_numberlink_v0()

See the docs for details on packaging entry-points and the registration helper: https://misaghsoltani.github.io/NumberLink/usage.html and https://misaghsoltani.github.io/NumberLink/apidocs/index.html.

License

MIT License - see LICENSE.

Cite this work

If you use NumberLink in your research, please cite:

@misc{numberlinkenv2025soltani,
  author = {Soltani, Misagh},
  title  = {NumberLink Puzzle},
  url    = {https://misaghsoltani.github.io/NumberLink},
  year   = {2025}
}

Contact

If you have any questions or issues, please contact Misagh Soltani ([e-mail])