netris 0.1.0__tar.gz

netris-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python caches and bytecode
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.hypothesis/
+.ipynb_checkpoints/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Game Boy ROM (copyrighted, never commit)
+*.gb
+*.gb.ram
+
+# Local logs
+logs/

netris-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Aranda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

netris-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: netris
+Version: 0.1.0
+Summary: Gymnasium environment for Game Boy Tetris emulated with PyBoy
+Project-URL: Homepage, https://github.com/javi-aranda/netris
+Author: Javier Aranda
+License: MIT License
+        
+        Copyright (c) 2026 Javier Aranda
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: gameboy,gymnasium,pyboy,reinforcement-learning,tetris
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: gymnasium>=1.0
+Requires-Dist: numpy>=1.23
+Requires-Dist: pyboy>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# netris
+
+A [Gymnasium](https://gymnasium.farama.org/) environment for **Game Boy Tetris**,
+emulated with [PyBoy](https://github.com/Baekalfen/PyBoy).
+
+- Placement-based action space: `rotation (0-3) * 10 + column (0-9)` (40 actions).
+- Dict observation: board, current/next piece, row completion, holes,
+  bumpiness and aggregate height.
+- Line clears are confirmed against the game's own on-screen counter, so
+  phantom clears (e.g. at game over) cannot happen.
+- Optional 1-piece lookahead information via the on-screen NEXT panel
+  (`NetrisEnvConfig(include_next_piece=True)`).
+
+## Install
+
+```bash
+pip install netris
+```
+
+## ROM
+
+The Game Boy Tetris ROM is **not** distributed with this package. Provide your
+own dump:
+
+```bash
+export NETRIS_ROM=/path/to/tetris.gb
+```
+
+## Quickstart
+
+```python
+import gymnasium as gym
+import netris  # registers "Netris/GameBoyTetris-v0"
+
+env = gym.make("Netris/GameBoyTetris-v0")  # uses NETRIS_ROM
+obs, info = env.reset(seed=0)
+obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
+env.close()
+```
+
+Or directly:
+
+```python
+from netris import NetrisEnvConfig, TetrisEnv
+
+env = TetrisEnv("/path/to/tetris.gb", config=NetrisEnvConfig())
+obs, info = env.reset()
+```
+
+## License
+
+MIT. PyBoy is an LGPL-3.0 dependency; the Tetris ROM is copyrighted and must be
+supplied by the user.

netris-0.1.0/README.md

@@ -0,0 +1,53 @@
+# netris
+
+A [Gymnasium](https://gymnasium.farama.org/) environment for **Game Boy Tetris**,
+emulated with [PyBoy](https://github.com/Baekalfen/PyBoy).
+
+- Placement-based action space: `rotation (0-3) * 10 + column (0-9)` (40 actions).
+- Dict observation: board, current/next piece, row completion, holes,
+  bumpiness and aggregate height.
+- Line clears are confirmed against the game's own on-screen counter, so
+  phantom clears (e.g. at game over) cannot happen.
+- Optional 1-piece lookahead information via the on-screen NEXT panel
+  (`NetrisEnvConfig(include_next_piece=True)`).
+
+## Install
+
+```bash
+pip install netris
+```
+
+## ROM
+
+The Game Boy Tetris ROM is **not** distributed with this package. Provide your
+own dump:
+
+```bash
+export NETRIS_ROM=/path/to/tetris.gb
+```
+
+## Quickstart
+
+```python
+import gymnasium as gym
+import netris  # registers "Netris/GameBoyTetris-v0"
+
+env = gym.make("Netris/GameBoyTetris-v0")  # uses NETRIS_ROM
+obs, info = env.reset(seed=0)
+obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
+env.close()
+```
+
+Or directly:
+
+```python
+from netris import NetrisEnvConfig, TetrisEnv
+
+env = TetrisEnv("/path/to/tetris.gb", config=NetrisEnvConfig())
+obs, info = env.reset()
+```
+
+## License
+
+MIT. PyBoy is an LGPL-3.0 dependency; the Tetris ROM is copyrighted and must be
+supplied by the user.

netris-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "netris"
+version = "0.1.0"
+description = "Gymnasium environment for Game Boy Tetris emulated with PyBoy"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "Javier Aranda" }]
+keywords = ["reinforcement-learning", "gymnasium", "tetris", "gameboy", "pyboy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "gymnasium>=1.0",
+    "pyboy>=2.6",
+    "numpy>=1.23",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://github.com/javi-aranda/netris"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/netris"]
+
+[tool.pytest.ini_options]
+markers = ["rom: requires a GameBoy Tetris ROM"]
+addopts = "-m \"not rom\""
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

netris-0.1.0/src/netris/__init__.py

@@ -0,0 +1,10 @@
+"""Netris: a Gymnasium environment for GameBoy Tetris."""
+
+from .envs import NetrisEnvConfig, TetrisEnv
+from .registration import ENV_ID, register_env
+
+__version__ = "0.1.0"
+
+__all__ = ["ENV_ID", "NetrisEnvConfig", "TetrisEnv", "__version__", "register_env"]
+
+register_env()

netris-0.1.0/src/netris/envs/__init__.py

@@ -0,0 +1,4 @@
+from .config import NetrisEnvConfig
+from .tetris_env import TetrisEnv
+
+__all__ = ["NetrisEnvConfig", "TetrisEnv"]

netris-0.1.0/src/netris/envs/config.py

@@ -0,0 +1,36 @@
+"""Environment configuration."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class NetrisEnvConfig:
+    """Knobs that do not change the observation/action spaces."""
+
+    include_next_piece: bool = False
+    watchdog_steps: int = 1000
+    collect_metrics: bool = True
+
+    line_clear_rewards: dict = field(
+        default_factory=lambda: {1: 5.0, 2: 15.0, 3: 40.0}
+    )
+    tetris_reward: float = 100.0
+    hole_penalty: float = 0.5
+    aggregate_height_penalty: float = 0.005
+    bumpiness_penalty: float = 0.01
+    game_over_penalty: float = -10.0
+    survival_bonus: float = 1.0
+
+    def to_dict(self):
+        return {
+            "include_next_piece": self.include_next_piece,
+            "watchdog_steps": self.watchdog_steps,
+            "collect_metrics": self.collect_metrics,
+            "line_clear_rewards": dict(self.line_clear_rewards),
+            "tetris_reward": self.tetris_reward,
+            "hole_penalty": self.hole_penalty,
+            "aggregate_height_penalty": self.aggregate_height_penalty,
+            "bumpiness_penalty": self.bumpiness_penalty,
+            "game_over_penalty": self.game_over_penalty,
+            "survival_bonus": self.survival_bonus,
+        }

netris-0.1.0/src/netris/envs/metrics.py

@@ -0,0 +1,136 @@
+import json
+from collections import Counter
+from datetime import UTC, datetime
+
+import numpy as np
+
+
+class MetricsCollector:
+    """In-memory per-episode metrics.
+
+    Persisting metrics to disk is the responsibility of the main-process
+    callbacks: environments may run in subprocesses (SubprocVecEnv) and must
+    not race on shared files.
+    """
+
+    def __init__(self):
+        self._reset_episode()
+
+    def _reset_episode(self):
+        self.episode_actions = Counter()
+        self.episode_rotations = 0
+        self.episode_placement_columns = []
+        self.episode_placement_heights = []
+        self.episode_reward_breakdowns = []
+        self.episode_line_clears = []
+        self.episode_max_height = 0
+        self.episode_bumpiness_values = []
+        self.episode_holes_values = []
+
+    def register_action(self, action):
+        self.episode_actions[int(action)] += 1
+
+    def register_rotation(self):
+        self.episode_rotations += 1
+
+    def register_piece_placed(self, column, height):
+        self.episode_placement_columns.append(column)
+        self.episode_placement_heights.append(height)
+
+    def register_reward_breakdown(self, *, reward_lines=0.0, reward_holes=0.0,
+                                   reward_height=0.0, reward_bumpiness=0.0,
+                                   reward_clean=0.0, reward_total=0.0):
+        self.episode_reward_breakdowns.append({
+            "lines": reward_lines,
+            "holes": reward_holes,
+            "height": reward_height,
+            "bumpiness": reward_bumpiness,
+            "clean": reward_clean,
+            "total": reward_total,
+        })
+
+    def register_line_clear(self, lines_delta):
+        self.episode_line_clears.append(lines_delta)
+
+    def update_max_height(self, height):
+        self.episode_max_height = max(self.episode_max_height, height)
+
+    def record_bumpiness(self, bumpiness):
+        self.episode_bumpiness_values.append(bumpiness)
+
+    def record_holes(self, holes):
+        self.episode_holes_values.append(holes)
+
+    def episode_summary(self, episode, steps, pieces, total_lines, total_reward):
+        total_lines_from_breakdown = sum(
+            d.get("lines", 0) for d in self.episode_reward_breakdowns
+        )
+        total_holes = sum(
+            d.get("holes", 0) for d in self.episode_reward_breakdowns
+        )
+        total_height = sum(
+            d.get("height", 0) for d in self.episode_reward_breakdowns
+        )
+        total_bumpiness = sum(
+            d.get("bumpiness", 0) for d in self.episode_reward_breakdowns
+        )
+
+        avg_placement_col = (
+            np.mean(self.episode_placement_columns)
+            if self.episode_placement_columns else 0.0
+        )
+        avg_placement_height = (
+            np.mean(self.episode_placement_heights)
+            if self.episode_placement_heights else 0.0
+        )
+        avg_bumpiness = (
+            np.mean(self.episode_bumpiness_values)
+            if self.episode_bumpiness_values else 0.0
+        )
+        avg_holes = (
+            np.mean(self.episode_holes_values)
+            if self.episode_holes_values else 0.0
+        )
+
+        return {
+            "timestamp": datetime.now(UTC).isoformat(),
+            "episode": episode,
+            "steps": steps,
+            "pieces": pieces,
+            "lines_cleared": total_lines,
+            "max_height": self.episode_max_height,
+            "avg_bumpiness": round(float(avg_bumpiness), 3),
+            "avg_holes": round(float(avg_holes), 3),
+            "reward_total": round(float(total_reward), 4),
+            "reward_lines": round(total_lines_from_breakdown, 4),
+            "reward_holes": round(total_holes, 4),
+            "reward_height": round(total_height, 4),
+            "reward_bumpiness": round(total_bumpiness, 4),
+            "rotations": self.episode_rotations,
+            "avg_placement_col": round(float(avg_placement_col), 3),
+            "avg_placement_height": round(float(avg_placement_height), 3),
+            "action_distribution": json.dumps(dict(self.episode_actions)),
+            "line_clear_distribution": json.dumps(dict(Counter(self.episode_line_clears))),
+        }
+
+    def reset_episode(self):
+        self._reset_episode()
+
+    def get_placement_heatmap(self):
+        heatmap = np.zeros((18, 10), dtype=np.int32)
+        for col, height in zip(self.episode_placement_columns, self.episode_placement_heights):
+            row = 18 - 1 - height
+            row = max(0, min(17, row))
+            col = max(0, min(9, col))
+            heatmap[row, col] += 1
+        return heatmap
+
+
+class NullMetricsCollector:
+    """No-op collector used when metrics collection is disabled."""
+
+    def __getattr__(self, name):
+        return lambda *args, **kwargs: None
+
+    def episode_summary(self, **kwargs):
+        return {}