smb2-gym 0.2.0__tar.gz

smb2_gym-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+recursive-include smb2_gym *.py
+recursive-include smb2_gym/_nes *.whl *.nes *.sav

smb2_gym-0.2.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: smb2-gym
+Version: 0.2.0
+Summary: Super Mario Bros 2 (Europe) Gymnasium Environment
+Author: Alexei Quick
+License: MIT
+Project-URL: Homepage, https://github.com/alexeiquickcode/smb2-gym
+Project-URL: Bug Tracker, https://github.com/alexeiquickcode/smb2-gym/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: gymnasium>=0.29.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pygame>=2.1.0
+Requires-Dist: tetanes-py>=0.1.1
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: yapf; extra == "dev"
+Requires-Dist: basedpyright; extra == "dev"
+
+# smb2-gym
+
+[![Python](https://img.shields.io/pypi/pyversions/smb2-gym)](https://pypi.org/project/smb2-gym/)
+[![PyPI](https://img.shields.io/pypi/v/smb2-gym)](https://pypi.org/project/smb2-gym/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Gymnasium environment for Super Mario Bros 2 (Europe/Doki Doki Panic version) using TetaNES emulator Python bindings. Perfect for reinforcement learning experiments and research.
+
+**Features:**
+- Curated action sets for faster training (`simple`, `complex`)
+- Comprehensive game state via info dict (40+ properties)
+- Multiple initialization modes (character/level, custom ROMs, save states)
+- Human-playable interface with keyboard controls
+
+A full list of the available RAM map properties is available at [Data Crystal](https://datacrystal.tcrf.net/wiki/Super_Mario_Bros._2_(NES)/RAM_map).
+
+## Installation
+
+```bash
+pip install smb2-gym
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from smb2_gym import SuperMarioBros2Env
+from smb2_gym.app import InitConfig
+
+# Create environment with character/level mode
+config = InitConfig(level="1-1", character="luigi")
+env = SuperMarioBros2Env(
+    init_config=config,
+    render_mode="human",     # "human" or None
+    action_type="simple"     # "simple" (11), "complex" (16), or "all" (256)
+)
+
+# Reset environment
+obs, info = env.reset()
+
+# Run game loop
+for _ in range(1000):
+    action = env.action_space.sample()
+    obs, reward, terminated, truncated, info = env.step(action)
+
+    # Access game state from info dict
+    print(f"Lives: {info['life']}, Hearts: {info['hearts']}")
+    print(f"Position: ({info['x_pos_global']}, {info['y_pos_global']})")
+
+    if terminated or truncated:
+        obs, info = env.reset()
+
+env.close()
+```
+
+### Initialization Modes
+
+```python
+from smb2_gym.app import InitConfig
+
+# 1. Character/Level mode (default)
+config = InitConfig(level="1-1", character="peach")
+
+# 2. Built-in ROM variant mode
+config = InitConfig(rom="prg0", save_state="level_1_1.sav")
+
+# 3. Custom ROM mode
+config = InitConfig(
+    rom_path="/path/to/your/smb2.nes",
+    save_state_path="/path/to/save.sav"  # Optional
+)
+```
+
+### Custom Reward Function
+
+```python
+from smb2_gym import SuperMarioBros2Env
+from smb2_gym.app import InitConfig
+
+class CustomSMB2Env(SuperMarioBros2Env):
+    def step(self, action):
+        obs, reward, terminated, truncated, info = super().step(action)
+
+        # Custom reward based on x-position progress
+        reward = info['x_pos_global'] / 100.0
+
+        # Bonus for collecting cherries
+        reward += info['cherries'] * 10
+
+        # Bonus for hearts
+        reward += info['hearts'] * 5
+
+        # Penalty for losing a life
+        if info.get('life_lost'):
+            reward -= 100
+
+        return obs, reward, terminated, truncated, info
+
+# Usage
+config = InitConfig(level="1-1", character="luigi")
+env = CustomSMB2Env(init_config=config, action_type="simple")
+```
+
+## Play as Human
+
+The package includes a human-playable interface with multiple initialization modes:
+
+### Character/Level Mode (Default)
+```bash
+# Play as Luigi on level 1-1
+smb2-play --level 1-1 --char luigi --scale 3
+
+# TODO: Yet to implement all levels states
+# Play as Peach on level 2-3
+smb2-play --level 2-3 --char peach 
+```
+
+### Built-in ROM Variant Mode
+```bash
+# Use specific ROM variant with save state
+smb2-play --rom prg0_edited --save-state easy_combined_curriculum.sav
+```
+
+### Custom ROM Mode  
+```bash
+# Use your own ROM file
+smb2-play --custom-rom /path/to/smb2.nes
+
+# Use custom ROM with save state
+smb2-play --custom-rom /path/to/smb2.nes --custom-state /path/to/save.sav
+
+# Start from beginning without save state
+smb2-play --custom-rom /path/to/smb2.nes --no-save-state
+```
+
+### Controls
+
+**Primary Controls:**
+- Arrow Keys: Move
+- Z: A button (Jump)
+- X: B button (Pick up/Throw)
+- Enter: Start
+- Right Shift: Select
+- P: Pause
+- R: Reset  
+- ESC: Quit
+
+**Alternative Controls:**
+- WASD: Move
+- J: A button
+- K: B button
+
+**Save States:**
+- F5: Save state
+- F9: Load state
+
+### CLI Options
+
+**Character/Level Mode:**
+- `--level`: Level to play (1-1 through 7-2, default: 1-1)
+- `--char`: Character (mario, luigi, peach, toad, default: luigi)
+
+**Built-in ROM Mode:**
+- `--rom`: ROM variant (prg0, prg0_edited)
+- `--save-state`: Save state filename
+
+**Custom ROM Mode:**
+- `--custom-rom`: Path to custom ROM file
+- `--custom-state`: Path to custom save state (optional)
+- `--no-save-state`: Start from beginning without loading save state
+
+**Display:**
+- `--scale`: Display scale factor (1-4, default: 3)
+
+## Disclaimer
+
+This project is for educational and research purposes only. Users must provide their own legally obtained ROM files.

smb2_gym-0.2.0/README.md

@@ -0,0 +1,178 @@
+# smb2-gym
+
+[![Python](https://img.shields.io/pypi/pyversions/smb2-gym)](https://pypi.org/project/smb2-gym/)
+[![PyPI](https://img.shields.io/pypi/v/smb2-gym)](https://pypi.org/project/smb2-gym/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Gymnasium environment for Super Mario Bros 2 (Europe/Doki Doki Panic version) using TetaNES emulator Python bindings. Perfect for reinforcement learning experiments and research.
+
+**Features:**
+- Curated action sets for faster training (`simple`, `complex`)
+- Comprehensive game state via info dict (40+ properties)
+- Multiple initialization modes (character/level, custom ROMs, save states)
+- Human-playable interface with keyboard controls
+
+A full list of the available RAM map properties is available at [Data Crystal](https://datacrystal.tcrf.net/wiki/Super_Mario_Bros._2_(NES)/RAM_map).
+
+## Installation
+
+```bash
+pip install smb2-gym
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from smb2_gym import SuperMarioBros2Env
+from smb2_gym.app import InitConfig
+
+# Create environment with character/level mode
+config = InitConfig(level="1-1", character="luigi")
+env = SuperMarioBros2Env(
+    init_config=config,
+    render_mode="human",     # "human" or None
+    action_type="simple"     # "simple" (11), "complex" (16), or "all" (256)
+)
+
+# Reset environment
+obs, info = env.reset()
+
+# Run game loop
+for _ in range(1000):
+    action = env.action_space.sample()
+    obs, reward, terminated, truncated, info = env.step(action)
+
+    # Access game state from info dict
+    print(f"Lives: {info['life']}, Hearts: {info['hearts']}")
+    print(f"Position: ({info['x_pos_global']}, {info['y_pos_global']})")
+
+    if terminated or truncated:
+        obs, info = env.reset()
+
+env.close()
+```
+
+### Initialization Modes
+
+```python
+from smb2_gym.app import InitConfig
+
+# 1. Character/Level mode (default)
+config = InitConfig(level="1-1", character="peach")
+
+# 2. Built-in ROM variant mode
+config = InitConfig(rom="prg0", save_state="level_1_1.sav")
+
+# 3. Custom ROM mode
+config = InitConfig(
+    rom_path="/path/to/your/smb2.nes",
+    save_state_path="/path/to/save.sav"  # Optional
+)
+```
+
+### Custom Reward Function
+
+```python
+from smb2_gym import SuperMarioBros2Env
+from smb2_gym.app import InitConfig
+
+class CustomSMB2Env(SuperMarioBros2Env):
+    def step(self, action):
+        obs, reward, terminated, truncated, info = super().step(action)
+
+        # Custom reward based on x-position progress
+        reward = info['x_pos_global'] / 100.0
+
+        # Bonus for collecting cherries
+        reward += info['cherries'] * 10
+
+        # Bonus for hearts
+        reward += info['hearts'] * 5
+
+        # Penalty for losing a life
+        if info.get('life_lost'):
+            reward -= 100
+
+        return obs, reward, terminated, truncated, info
+
+# Usage
+config = InitConfig(level="1-1", character="luigi")
+env = CustomSMB2Env(init_config=config, action_type="simple")
+```
+
+## Play as Human
+
+The package includes a human-playable interface with multiple initialization modes:
+
+### Character/Level Mode (Default)
+```bash
+# Play as Luigi on level 1-1
+smb2-play --level 1-1 --char luigi --scale 3
+
+# TODO: Yet to implement all levels states
+# Play as Peach on level 2-3
+smb2-play --level 2-3 --char peach 
+```
+
+### Built-in ROM Variant Mode
+```bash
+# Use specific ROM variant with save state
+smb2-play --rom prg0_edited --save-state easy_combined_curriculum.sav
+```
+
+### Custom ROM Mode  
+```bash
+# Use your own ROM file
+smb2-play --custom-rom /path/to/smb2.nes
+
+# Use custom ROM with save state
+smb2-play --custom-rom /path/to/smb2.nes --custom-state /path/to/save.sav
+
+# Start from beginning without save state
+smb2-play --custom-rom /path/to/smb2.nes --no-save-state
+```
+
+### Controls
+
+**Primary Controls:**
+- Arrow Keys: Move
+- Z: A button (Jump)
+- X: B button (Pick up/Throw)
+- Enter: Start
+- Right Shift: Select
+- P: Pause
+- R: Reset  
+- ESC: Quit
+
+**Alternative Controls:**
+- WASD: Move
+- J: A button
+- K: B button
+
+**Save States:**
+- F5: Save state
+- F9: Load state
+
+### CLI Options
+
+**Character/Level Mode:**
+- `--level`: Level to play (1-1 through 7-2, default: 1-1)
+- `--char`: Character (mario, luigi, peach, toad, default: luigi)
+
+**Built-in ROM Mode:**
+- `--rom`: ROM variant (prg0, prg0_edited)
+- `--save-state`: Save state filename
+
+**Custom ROM Mode:**
+- `--custom-rom`: Path to custom ROM file
+- `--custom-state`: Path to custom save state (optional)
+- `--no-save-state`: Start from beginning without loading save state
+
+**Display:**
+- `--scale`: Display scale factor (1-4, default: 3)
+
+## Disclaimer
+
+This project is for educational and research purposes only. Users must provide their own legally obtained ROM files.

smb2_gym-0.2.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["smb2_gym", "smb2_gym.*"]
+
+[tool.setuptools.package-data]
+smb2_gym = ["_nes/**/*"]
+
+[project]
+name = "smb2-gym"
+version = "0.2.0"
+authors = [{ name = "Alexei Quick" }]
+description = "Super Mario Bros 2 (Europe) Gymnasium Environment"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "gymnasium>=0.29.0",
+    "numpy>=1.21.0",
+    "pygame>=2.1.0",
+    "tetanes-py>=0.1.1",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/alexeiquickcode/smb2-gym"
+"Bug Tracker" = "https://github.com/alexeiquickcode/smb2-gym/issues"
+
+[project.optional-dependencies]
+dev = ["pytest", "isort", "yapf", "basedpyright"]
+
+[project.scripts]
+smb2-play = "smb2_gym.play_human:main"
+
+[tool.yapf]
+based_on_style = "google"
+column_limit = 100
+indent_width = 4
+dedent_closing_brackets = true
+INDENT_DICTIONARY_VALUE = true
+split_before_logical_operator = true
+spaces_before_comment = 2
+split_complex_comprehension = true
+split_arguments_when_comma_terminated = true
+split_all_comma_separated_values = false
+SPLIT_ALL_TOP_LEVEL_COMMA_SEPARATED_VALUES = false
+SPLIT_BEFORE_ARITHMETIC_OPERATOR = true
+SPLIT_BEFORE_DOT = true
+
+[tool.isort]
+line_length = 120
+multi_line_output = 3
+include_trailing_comma = true
+force_grid_wrap = 2
+use_parentheses = true
+ensure_newline_before_comments = true
+lines_after_imports = 2
+skip_gitignore = true
+known_first_party = []
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')"
+]

smb2_gym-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smb2_gym-0.2.0/smb2_gym/__init__.py

@@ -0,0 +1,35 @@
+"""Super Mario Bros 2 Gymnasium Environment."""
+
+from .actions import (
+    COMPLEX_ACTIONS,
+    SIMPLE_ACTIONS,
+    ActionType,
+    action_to_buttons,
+    actions_to_buttons,
+    buttons_to_action,
+    buttons_to_action_index,
+    get_action_meanings,
+)
+from .app import (
+    create_info_panel,
+    draw_info,
+    get_required_info_height,
+)
+from .constants import *
+from .smb2_env import SuperMarioBros2Env
+
+__version__ = "0.2.0"
+__all__ = [
+    "SuperMarioBros2Env",
+    "SIMPLE_ACTIONS",
+    "COMPLEX_ACTIONS",
+    "ActionType",
+    "action_to_buttons",
+    "buttons_to_action",
+    "buttons_to_action_index",
+    "actions_to_buttons",
+    "get_action_meanings",
+    "create_info_panel",
+    "get_required_info_height",
+    "draw_info",
+]

smb2_gym-0.2.0/smb2_gym/actions.py

@@ -0,0 +1,168 @@
+"""Action mappings for Super Mario Bros 2."""
+
+from typing import Literal
+
+import numpy as np
+
+from .constants import (
+    BUTTON_A,
+    BUTTON_B,
+    BUTTON_DOWN,
+    BUTTON_LEFT,
+    BUTTON_RIGHT,
+    BUTTON_SELECT,
+    BUTTON_START,
+    BUTTON_UP,
+)
+
+ActionType = Literal["all", "complex", "simple"]
+
+SIMPLE_ACTIONS = [
+    ['NOOP'],
+    ['right'],
+    ['left'],
+    ['up'],  # Enter door
+    ['A'],  # Jump
+    ['B'],  # Pick up/throw
+    ['right', 'A'],  # Jump right
+    ['left', 'A'],  # Jump left  
+    ['right', 'B'],  # Pick up right
+    ['left', 'B'],  # Pick up left
+    ['down'],  # Crouch/charge super jump (hold 77+ frames then press A)
+]
+
+COMPLEX_ACTIONS = [
+    ['NOOP'],
+    ['right'],
+    ['right', 'A'],  # Run right
+    ['right', 'B'],  # Pick up right
+    ['right', 'A', 'B'],  # Jump throw right
+    ['left'],
+    ['left', 'A'],  # Run left
+    ['left', 'B'],  # Pick up left
+    ['left', 'A', 'B'],  # Jump throw left
+    ['down'],  # Charge super jump (hold 77+ frames then press A)
+    ['down', 'B'],  # Pick up from ground
+    ['up'],  # Enter door
+    ['A'],  # Jump
+    ['B'],  # Pick up/throw
+    ['A', 'B'],  # Jump and throw
+]
+
+BUTTON_MAP = {
+    'a': BUTTON_A,
+    'A': BUTTON_A,
+    'b': BUTTON_B,
+    'B': BUTTON_B,
+    'select': BUTTON_SELECT,
+    'start': BUTTON_START,
+    'up': BUTTON_UP,
+    'down': BUTTON_DOWN,
+    'left': BUTTON_LEFT,
+    'right': BUTTON_RIGHT,
+    'noop': None
+}
+
+
+def actions_to_buttons(actions: list[str]) -> np.ndarray:
+    """Convert action list to button array.
+
+    Args:
+        actions: list of action strings (e.g., ['right', 'A'])
+
+    Returns:
+        Boolean array of shape (8,) for button states
+    """
+    buttons = np.zeros(8, dtype=bool)
+
+    for action in actions:
+        action_lower = action.lower()
+        if action_lower in BUTTON_MAP:
+            button_idx = BUTTON_MAP[action_lower]
+            if button_idx is not None:
+                buttons[button_idx] = True
+
+    return buttons
+
+
+def action_to_buttons(action: int) -> np.ndarray:
+    """Convert discrete action to button array using all combinations.
+
+    Args:
+        action: Discrete action (0-255)
+
+    Returns:
+        Boolean array of shape (8,) for button states
+    """
+    # Each bit represents a button
+    buttons = np.zeros(8, dtype=bool)
+    for i in range(8):
+        buttons[i] = bool(action & (1 << i))
+    return buttons
+
+
+def buttons_to_action(buttons: np.ndarray) -> int:
+    """Convert button array to discrete action.
+
+    Args:
+        buttons: Boolean array of shape (8,)
+
+    Returns:
+        Discrete action (0-255)
+    """
+    action = 0
+    for i in range(8):
+        if buttons[i]:
+            action |= (1 << i)
+    return action
+
+
+def buttons_to_action_index(buttons: np.ndarray, action_set: list[list[str]]) -> int:
+    """Convert button array to action index for a given action set.
+
+    Args:
+        buttons: Boolean array of shape (8,)
+        action_set: List of action combinations (e.g., SIMPLE_ACTIONS, COMPLEX_ACTIONS)
+
+    Returns:
+        Action index in the given action set
+    """
+    # Convert button state to action list
+    pressed = []
+    if buttons[BUTTON_RIGHT]:
+        pressed.append('right')
+    elif buttons[BUTTON_LEFT]:
+        pressed.append('left')
+    elif buttons[BUTTON_DOWN]:
+        pressed.append('down')
+    elif buttons[BUTTON_UP]:
+        pressed.append('up')
+
+    if buttons[BUTTON_A]:
+        pressed.append('A')
+    if buttons[BUTTON_B]:
+        pressed.append('B')
+
+    # Find matching action in the action set
+    for i, action_combo in enumerate(action_set):
+        if set(pressed) == set([a for a in action_combo if a.upper() != 'NOOP']):
+            return i
+
+    return 0  # NOOP
+
+
+def get_action_meanings() -> list[list[str]]:
+    """Get human-readable meanings for all 256 actions.
+
+    Returns:
+        list of action meanings
+    """
+    meanings = []
+    button_names = ['A', 'B', 'SELECT', 'START', 'UP', 'DOWN', 'LEFT', 'RIGHT']
+
+    for action in range(256):
+        buttons = action_to_buttons(action)
+        pressed = [button_names[i] for i in range(8) if buttons[i]]
+        meanings.append(pressed if pressed else ['NOOP'])
+
+    return meanings