NesyLink

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

Installation · Quick Start · Built-in Tasks · Architecture · Rewards · Training · Documentation · 简体中文

---

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.

对于 26 年春季数理逻辑课程的大作业设置，详情见 数理逻辑大作业说明。

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-MathematicalLogic-Task1-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="mathematical_logic/task_1",
    max_steps=500,
    reward_kwargs={"step": -0.01},
)

Built-in Tasks

task_id	Gymnasium ID	Objective
mathematical_logic/task_1	NesyLink-MathematicalLogic-Task1-v0	Collect a key and open the exit.
mathematical_logic/task_2	NesyLink-MathematicalLogic-Task2-v0	Defeat the monster, collect the key, and exit.
mathematical_logic/task_3	NesyLink-MathematicalLogic-Task3-v0	Travel across rooms, collect the key, return, and unlock the exit.
mathematical_logic/task_4	NesyLink-MathematicalLogic-Task4-v0	Rotate the bridge, collect equipment, defeat the guardian, and open the final chest.
mathematical_logic/task_5	NesyLink-MathematicalLogic-Task5-v0	Explore the multi-room dungeon and complete its chest objectives.

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="mathematical_logic/task_1",
    reward_id="mathematical_logic/task_1",
    reward_kwargs={
        "step": -0.01,
        "keys_delta": 5.0,
        "door_opened": 3.0,
        "exit_reached": 20.0,
    },
)

Custom rewards are Python modules exposing make_reward(**kwargs). See reward reference.

Training

Start with a random rollout smoke test:

env = make_env(task_id="mathematical_logic/task_1")
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()

For PPO-style and Dreamer-style configuration notes, see training configuration.

Documentation

• Documentation hub
• Environment overview
• Map creation
• Training configuration
• Environment API
• Rewards
• Tasks