Project Info

Status: Keeping updating
Tech: Python
Repo: https://github.com/CrazyJassBread/nesylink

NesyLink

A Gymnasium-compatible Zelda-like dungeon environment for reinforcement learning.

Installation · Quick Start · Built-in Tasks · Architecture · Rewards · Training

nesylink provides a small, configurable dungeon game environment for RL experiments. It separates game mechanics, JSON maps, Python task specs, reward modules, and Gymnasium wrappers so users can start with built-in tasks or compose new environments without changing the core engine.

Installation

From source:

git clone https://github.com/CrazyJassBread/nesylink.git
cd nesylink
python -m venv .venv
source .venv/bin/activate
# use '.venv\Scripts\Activate.ps1' for PowerShell
pip install -e .

Optional extras:

pip install -e ".[pygame]"   # human-play/debug runner
pip install -e ".[dreamer]"  # Dreamer-style image helper dependencies

Quick Start

Use Gymnasium registration:

import gymnasium as gym
import nesylink

env = gym.make("NesyLink-CollectKeyEasy-v0")
obs, info = env.reset(seed=0)

obs, reward, terminated, truncated, info = env.step(env.action_space.sample())

env.close()

Use the direct factory when you want to override task defaults:

from nesylink.env import make_env

env = make_env(
    task_id="collect_key_easy",
    max_steps=500,
    reward_kwargs={"step": -0.01},
)

Built-in Tasks

task_id	Gymnasium ID	Objective
`collect_key_easy`	`NesyLink-CollectKeyEasy-v0`	Collect a key and open the exit.
`kill_monsters_easy`	`NesyLink-KillMonstersEasy-v0`	Defeat the monster, collect the key, and exit.
`avoid_traps_easy`	`NesyLink-AvoidTrapsEasy-v0`	Reach the exit while avoiding traps.

List tasks in Python:

from nesylink.tasks import list_tasks

for task in list_tasks():
    print(task.task_id, task.gym_id)

Architecture

nesylink/
  env.py              make_env(...) facade and Gymnasium registration
  tasks/              Python TaskSpec registry
  core/               runtime, state, mechanics, world loading, rendering
  rewards/            reward modules and reward signal extraction
  wrappers/           Gymnasium and Dreamer-facing adapters
  map_data/           built-in JSON maps
  tools/              map utilities

Design boundaries:

JSON maps define only the world: rooms, layouts, objects, exits, and spawns.
Python tasks compose maps, rewards, episode limits, action repeat, and mission text.
Reward modules compute scalar rewards and reward-driven termination.
Gymnasium wrappers expose reset, step, render, spaces, and info.

Rewards

Select built-in rewards by reward_id:

env = make_env(
    map_id="key_door",
    reward_id="collect_key",
    reward_kwargs={
        "step": -0.01,
        "keys_delta": 5.0,
        "door_opened": 3.0,
        "exit_reached": 20.0,
    },
)

Training

Start with a random rollout smoke test:

env = make_env(task_id="collect_key_easy")
obs, info = env.reset(seed=0)

for _ in range(100):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        break

print(info["terminal_reason"], info["reward"]["reward_signals"])
env.close()

Appendix

for more details, please refer to the GitHub repository.