pygame-gb 0.1.0__tar.gz

pygame_gb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chawanwit Akarajirathanachot
+
+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.

pygame_gb-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: pygame-gb
+Version: 0.1.0
+Summary: A Game Boy-style 2D game making library for Python
+Author-email: Chawanwit Akarajirathanachot <chawanwit.akarajirathanachot@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Chawanwit Akarajirathanachot
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/Karibura-Cyber/PyGB
+Project-URL: Documentation, https://github.com/Karibura-Cyber/PyGB#readme
+Project-URL: Bug Tracker, https://github.com/Karibura-Cyber/PyGB/issues
+Project-URL: Source, https://github.com/Karibura-Cyber/PyGB
+Keywords: gameboy,game-boy,retro,pixel,pygame,2d,game-engine,tilemap,tiled,sprite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame-ce>=2.5
+Provides-Extra: tmx
+Requires-Dist: pytmx>=3.31; extra == "tmx"
+Provides-Extra: image
+Requires-Dist: Pillow>=9.0; extra == "image"
+Provides-Extra: all
+Requires-Dist: pytmx>=3.31; extra == "all"
+Requires-Dist: Pillow>=9.0; extra == "all"
+Dynamic: license-file
+
+# PyGB
+
+A **Game Boy-style 2D game making library** for Python, built on [pygame-ce](https://pyga.me).
+
+160×144 viewport · 4-colour palette · GB-authentic audio channels · Tiled TMX map support · Collision editor
+
+---
+
+## Install
+
+```bash
+pip install pygb
+```
+
+**Optional extras:**
+
+```bash
+pip install "pygb[tmx]"    # Tiled .tmx map support (pytmx)
+pip install "pygb[image]"  # PNG tileset loading   (Pillow)
+pip install "pygb[all]"    # Both of the above
+```
+
+---
+
+## Quick Start
+
+```python
+from pygb import GameBoy, Tile
+import pygb.color as color
+
+gb = GameBoy(title="My Game", scale=3, palette=color.DMG)
+
+player_tile = Tile([
+    [0, 0, 1, 1, 1, 1, 0, 0],
+    [0, 1, 3, 3, 3, 3, 1, 0],
+    [0, 1, 3, 2, 2, 3, 1, 0],
+    [0, 1, 3, 3, 3, 3, 1, 0],
+    [0, 0, 1, 1, 1, 1, 0, 0],
+    [0, 0, 1, 0, 0, 1, 0, 0],
+    [0, 0, 1, 0, 0, 1, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0],
+])
+player = gb.create_sprite(player_tile, x=76, y=68)
+
+@gb.on_update
+def update():
+    dx, dy = gb.input.direction()
+    player.move(dx * 2, dy * 2)
+    player.clamp(0, 0, 152, 136)
+    if dx < 0:  player.flip_x = True
+    elif dx > 0: player.flip_x = False
+
+gb.run()
+```
+
+---
+
+## TMX Map Example
+
+Load a full-colour Tiled map with camera and tile collision:
+
+```python
+import os, json
+from pygb import GameBoy, Tile, Camera, CollisionMap, load_tmx, clamp
+
+gb = GameBoy(title="TMX Demo", scale=3)
+
+@gb.on_start
+def init():
+    global result, cmap, player, cam, px, py
+
+    result = load_tmx(gb, "level.tmx")
+    gb.graphics.bg_enabled = False  # full-colour rendering via on_draw
+
+    cmap = CollisionMap(result.map_cols, result.map_rows, tile_size=result.tile_size)
+    if os.path.exists("level_collision.json"):
+        with open("level_collision.json") as f:
+            saved = json.load(f)
+        cmap.from_grid(saved["data"], solid_value=1)
+
+    px, py = float(result.world_w // 2), float(result.world_h // 2)
+    cam = Camera(gb.graphics,
+                 world_w=result.world_w, world_h=result.world_h,
+                 screen_w=gb.width, screen_h=gb.height)
+    cam.follow(px, py, smooth=1.0)
+
+@gb.on_update
+def update():
+    global px, py
+    dx, dy = gb.input.direction()
+    px, py = cmap.resolve(px, py, 8, 8, dx * 2, dy * 2)
+    px = clamp(px, 0, result.world_w - 8)
+    py = clamp(py, 0, result.world_h - 8)
+    cam.follow(px, py, smooth=0.15)
+
+@gb.on_draw
+def draw():
+    ts, sx, sy = result.tile_size, gb.graphics.scroll_x, gb.graphics.scroll_y
+    gb.surface.fill((0, 0, 0))
+    for name in result.layer_order:
+        tilemap = result.layers[name]
+        cols, rows = gb.width // ts + 2, gb.height // ts + 2
+        for ty in range(rows):
+            for tx in range(cols):
+                idx = tilemap.get((tx + sx // ts) % tilemap.WIDTH,
+                                  (ty + sy // ts) % tilemap.HEIGHT)
+                if idx in result.surfaces:
+                    gb.surface.blit(result.surfaces[idx],
+                                    (tx * ts - sx % ts, ty * ts - sy % ts))
+
+gb.run()
+```
+
+---
+
+## Collision Editor
+
+Paint solid/passable tiles on a PNG tileset or a Tiled `.tmx` map and save as JSON:
+
+```bash
+# PNG tileset
+pygb-editor tileset.png
+pygb-editor tileset.png output.json
+
+# Tiled TMX map (all layers rendered automatically)
+pygb-editor level.tmx
+pygb-editor level.tmx level_collision.json
+
+# Advanced editor with startup dialog
+pygb-collision
+pygb-collision tileset.png
+pygb-collision --blank 20x18 blank_collision.json
+```
+
+| Key | Action |
+|-----|--------|
+| Left click / drag | Mark tiles solid |
+| Right click / drag | Mark tiles passable |
+| Middle drag | Pan |
+| Scroll | Zoom in / out |
+| `S` | Save JSON |
+| `Z` | Undo |
+| `R` | Clear all |
+| `Escape` | Quit |
+
+---
+
+## Features
+
+| Feature | Details |
+|---------|---------|
+| Viewport | 160×144 px (configurable) |
+| Tile size | Any size (default 8×8, auto-detected) |
+| VRAM | 256 tiles max |
+| Sprites | Position, flip, palette, AABB collision |
+| Tilemaps | BG (scrollable) + Window (HUD overlay) |
+| Palettes | DMG · GRAY · POCKET · GBC |
+| Audio | 2× Pulse · Wave · Noise (GB-style) |
+| TMX loader | Full-colour rendering via pytmx |
+| Collision | Tile-resolution AABB with wall sliding |
+| Font | Built-in 8×8 bitmap font |
+| Utilities | Camera · Timer · Animation · RNG · Rect |
+
+---
+
+## Lifecycle Hooks
+
+```python
+@gb.on_start    # called once before the loop
+@gb.on_update   # called every frame — game logic
+@gb.on_draw     # called every frame — raw pygame drawing
+@gb.on_stop     # called once on exit
+```
+
+---
+
+## Requirements
+
+- Python ≥ 3.9
+- pygame-ce ≥ 2.5
+- pytmx ≥ 3.31 *(optional, for TMX loading)*
+- Pillow ≥ 9.0 *(optional, for PNG tileset loading)*
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

pygame_gb-0.1.0/README.md

@@ -0,0 +1,188 @@
+# PyGB
+
+A **Game Boy-style 2D game making library** for Python, built on [pygame-ce](https://pyga.me).
+
+160×144 viewport · 4-colour palette · GB-authentic audio channels · Tiled TMX map support · Collision editor
+
+---
+
+## Install
+
+```bash
+pip install pygb
+```
+
+**Optional extras:**
+
+```bash
+pip install "pygb[tmx]"    # Tiled .tmx map support (pytmx)
+pip install "pygb[image]"  # PNG tileset loading   (Pillow)
+pip install "pygb[all]"    # Both of the above
+```
+
+---
+
+## Quick Start
+
+```python
+from pygb import GameBoy, Tile
+import pygb.color as color
+
+gb = GameBoy(title="My Game", scale=3, palette=color.DMG)
+
+player_tile = Tile([
+    [0, 0, 1, 1, 1, 1, 0, 0],
+    [0, 1, 3, 3, 3, 3, 1, 0],
+    [0, 1, 3, 2, 2, 3, 1, 0],
+    [0, 1, 3, 3, 3, 3, 1, 0],
+    [0, 0, 1, 1, 1, 1, 0, 0],
+    [0, 0, 1, 0, 0, 1, 0, 0],
+    [0, 0, 1, 0, 0, 1, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0],
+])
+player = gb.create_sprite(player_tile, x=76, y=68)
+
+@gb.on_update
+def update():
+    dx, dy = gb.input.direction()
+    player.move(dx * 2, dy * 2)
+    player.clamp(0, 0, 152, 136)
+    if dx < 0:  player.flip_x = True
+    elif dx > 0: player.flip_x = False
+
+gb.run()
+```
+
+---
+
+## TMX Map Example
+
+Load a full-colour Tiled map with camera and tile collision:
+
+```python
+import os, json
+from pygb import GameBoy, Tile, Camera, CollisionMap, load_tmx, clamp
+
+gb = GameBoy(title="TMX Demo", scale=3)
+
+@gb.on_start
+def init():
+    global result, cmap, player, cam, px, py
+
+    result = load_tmx(gb, "level.tmx")
+    gb.graphics.bg_enabled = False  # full-colour rendering via on_draw
+
+    cmap = CollisionMap(result.map_cols, result.map_rows, tile_size=result.tile_size)
+    if os.path.exists("level_collision.json"):
+        with open("level_collision.json") as f:
+            saved = json.load(f)
+        cmap.from_grid(saved["data"], solid_value=1)
+
+    px, py = float(result.world_w // 2), float(result.world_h // 2)
+    cam = Camera(gb.graphics,
+                 world_w=result.world_w, world_h=result.world_h,
+                 screen_w=gb.width, screen_h=gb.height)
+    cam.follow(px, py, smooth=1.0)
+
+@gb.on_update
+def update():
+    global px, py
+    dx, dy = gb.input.direction()
+    px, py = cmap.resolve(px, py, 8, 8, dx * 2, dy * 2)
+    px = clamp(px, 0, result.world_w - 8)
+    py = clamp(py, 0, result.world_h - 8)
+    cam.follow(px, py, smooth=0.15)
+
+@gb.on_draw
+def draw():
+    ts, sx, sy = result.tile_size, gb.graphics.scroll_x, gb.graphics.scroll_y
+    gb.surface.fill((0, 0, 0))
+    for name in result.layer_order:
+        tilemap = result.layers[name]
+        cols, rows = gb.width // ts + 2, gb.height // ts + 2
+        for ty in range(rows):
+            for tx in range(cols):
+                idx = tilemap.get((tx + sx // ts) % tilemap.WIDTH,
+                                  (ty + sy // ts) % tilemap.HEIGHT)
+                if idx in result.surfaces:
+                    gb.surface.blit(result.surfaces[idx],
+                                    (tx * ts - sx % ts, ty * ts - sy % ts))
+
+gb.run()
+```
+
+---
+
+## Collision Editor
+
+Paint solid/passable tiles on a PNG tileset or a Tiled `.tmx` map and save as JSON:
+
+```bash
+# PNG tileset
+pygb-editor tileset.png
+pygb-editor tileset.png output.json
+
+# Tiled TMX map (all layers rendered automatically)
+pygb-editor level.tmx
+pygb-editor level.tmx level_collision.json
+
+# Advanced editor with startup dialog
+pygb-collision
+pygb-collision tileset.png
+pygb-collision --blank 20x18 blank_collision.json
+```
+
+| Key | Action |
+|-----|--------|
+| Left click / drag | Mark tiles solid |
+| Right click / drag | Mark tiles passable |
+| Middle drag | Pan |
+| Scroll | Zoom in / out |
+| `S` | Save JSON |
+| `Z` | Undo |
+| `R` | Clear all |
+| `Escape` | Quit |
+
+---
+
+## Features
+
+| Feature | Details |
+|---------|---------|
+| Viewport | 160×144 px (configurable) |
+| Tile size | Any size (default 8×8, auto-detected) |
+| VRAM | 256 tiles max |
+| Sprites | Position, flip, palette, AABB collision |
+| Tilemaps | BG (scrollable) + Window (HUD overlay) |
+| Palettes | DMG · GRAY · POCKET · GBC |
+| Audio | 2× Pulse · Wave · Noise (GB-style) |
+| TMX loader | Full-colour rendering via pytmx |
+| Collision | Tile-resolution AABB with wall sliding |
+| Font | Built-in 8×8 bitmap font |
+| Utilities | Camera · Timer · Animation · RNG · Rect |
+
+---
+
+## Lifecycle Hooks
+
+```python
+@gb.on_start    # called once before the loop
+@gb.on_update   # called every frame — game logic
+@gb.on_draw     # called every frame — raw pygame drawing
+@gb.on_stop     # called once on exit
+```
+
+---
+
+## Requirements
+
+- Python ≥ 3.9
+- pygame-ce ≥ 2.5
+- pytmx ≥ 3.31 *(optional, for TMX loading)*
+- Pillow ≥ 9.0 *(optional, for PNG tileset loading)*
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

pygame_gb-0.1.0/pygame_gb.egg-info/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: pygame-gb
+Version: 0.1.0
+Summary: A Game Boy-style 2D game making library for Python
+Author-email: Chawanwit Akarajirathanachot <chawanwit.akarajirathanachot@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Chawanwit Akarajirathanachot
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/Karibura-Cyber/PyGB
+Project-URL: Documentation, https://github.com/Karibura-Cyber/PyGB#readme
+Project-URL: Bug Tracker, https://github.com/Karibura-Cyber/PyGB/issues
+Project-URL: Source, https://github.com/Karibura-Cyber/PyGB
+Keywords: gameboy,game-boy,retro,pixel,pygame,2d,game-engine,tilemap,tiled,sprite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame-ce>=2.5
+Provides-Extra: tmx
+Requires-Dist: pytmx>=3.31; extra == "tmx"
+Provides-Extra: image
+Requires-Dist: Pillow>=9.0; extra == "image"
+Provides-Extra: all
+Requires-Dist: pytmx>=3.31; extra == "all"
+Requires-Dist: Pillow>=9.0; extra == "all"
+Dynamic: license-file
+
+# PyGB
+
+A **Game Boy-style 2D game making library** for Python, built on [pygame-ce](https://pyga.me).
+
+160×144 viewport · 4-colour palette · GB-authentic audio channels · Tiled TMX map support · Collision editor
+
+---
+
+## Install
+
+```bash
+pip install pygb
+```
+
+**Optional extras:**
+
+```bash
+pip install "pygb[tmx]"    # Tiled .tmx map support (pytmx)
+pip install "pygb[image]"  # PNG tileset loading   (Pillow)
+pip install "pygb[all]"    # Both of the above
+```
+
+---
+
+## Quick Start
+
+```python
+from pygb import GameBoy, Tile
+import pygb.color as color
+
+gb = GameBoy(title="My Game", scale=3, palette=color.DMG)
+
+player_tile = Tile([
+    [0, 0, 1, 1, 1, 1, 0, 0],
+    [0, 1, 3, 3, 3, 3, 1, 0],
+    [0, 1, 3, 2, 2, 3, 1, 0],
+    [0, 1, 3, 3, 3, 3, 1, 0],
+    [0, 0, 1, 1, 1, 1, 0, 0],
+    [0, 0, 1, 0, 0, 1, 0, 0],
+    [0, 0, 1, 0, 0, 1, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0],
+])
+player = gb.create_sprite(player_tile, x=76, y=68)
+
+@gb.on_update
+def update():
+    dx, dy = gb.input.direction()
+    player.move(dx * 2, dy * 2)
+    player.clamp(0, 0, 152, 136)
+    if dx < 0:  player.flip_x = True
+    elif dx > 0: player.flip_x = False
+
+gb.run()
+```
+
+---
+
+## TMX Map Example
+
+Load a full-colour Tiled map with camera and tile collision:
+
+```python
+import os, json
+from pygb import GameBoy, Tile, Camera, CollisionMap, load_tmx, clamp
+
+gb = GameBoy(title="TMX Demo", scale=3)
+
+@gb.on_start
+def init():
+    global result, cmap, player, cam, px, py
+
+    result = load_tmx(gb, "level.tmx")
+    gb.graphics.bg_enabled = False  # full-colour rendering via on_draw
+
+    cmap = CollisionMap(result.map_cols, result.map_rows, tile_size=result.tile_size)
+    if os.path.exists("level_collision.json"):
+        with open("level_collision.json") as f:
+            saved = json.load(f)
+        cmap.from_grid(saved["data"], solid_value=1)
+
+    px, py = float(result.world_w // 2), float(result.world_h // 2)
+    cam = Camera(gb.graphics,
+                 world_w=result.world_w, world_h=result.world_h,
+                 screen_w=gb.width, screen_h=gb.height)
+    cam.follow(px, py, smooth=1.0)
+
+@gb.on_update
+def update():
+    global px, py
+    dx, dy = gb.input.direction()
+    px, py = cmap.resolve(px, py, 8, 8, dx * 2, dy * 2)
+    px = clamp(px, 0, result.world_w - 8)
+    py = clamp(py, 0, result.world_h - 8)
+    cam.follow(px, py, smooth=0.15)
+
+@gb.on_draw
+def draw():
+    ts, sx, sy = result.tile_size, gb.graphics.scroll_x, gb.graphics.scroll_y
+    gb.surface.fill((0, 0, 0))
+    for name in result.layer_order:
+        tilemap = result.layers[name]
+        cols, rows = gb.width // ts + 2, gb.height // ts + 2
+        for ty in range(rows):
+            for tx in range(cols):
+                idx = tilemap.get((tx + sx // ts) % tilemap.WIDTH,
+                                  (ty + sy // ts) % tilemap.HEIGHT)
+                if idx in result.surfaces:
+                    gb.surface.blit(result.surfaces[idx],
+                                    (tx * ts - sx % ts, ty * ts - sy % ts))
+
+gb.run()
+```
+
+---
+
+## Collision Editor
+
+Paint solid/passable tiles on a PNG tileset or a Tiled `.tmx` map and save as JSON:
+
+```bash
+# PNG tileset
+pygb-editor tileset.png
+pygb-editor tileset.png output.json
+
+# Tiled TMX map (all layers rendered automatically)
+pygb-editor level.tmx
+pygb-editor level.tmx level_collision.json
+
+# Advanced editor with startup dialog
+pygb-collision
+pygb-collision tileset.png
+pygb-collision --blank 20x18 blank_collision.json
+```
+
+| Key | Action |
+|-----|--------|
+| Left click / drag | Mark tiles solid |
+| Right click / drag | Mark tiles passable |
+| Middle drag | Pan |
+| Scroll | Zoom in / out |
+| `S` | Save JSON |
+| `Z` | Undo |
+| `R` | Clear all |
+| `Escape` | Quit |
+
+---
+
+## Features
+
+| Feature | Details |
+|---------|---------|
+| Viewport | 160×144 px (configurable) |
+| Tile size | Any size (default 8×8, auto-detected) |
+| VRAM | 256 tiles max |
+| Sprites | Position, flip, palette, AABB collision |
+| Tilemaps | BG (scrollable) + Window (HUD overlay) |
+| Palettes | DMG · GRAY · POCKET · GBC |
+| Audio | 2× Pulse · Wave · Noise (GB-style) |
+| TMX loader | Full-colour rendering via pytmx |
+| Collision | Tile-resolution AABB with wall sliding |
+| Font | Built-in 8×8 bitmap font |
+| Utilities | Camera · Timer · Animation · RNG · Rect |
+
+---
+
+## Lifecycle Hooks
+
+```python
+@gb.on_start    # called once before the loop
+@gb.on_update   # called every frame — game logic
+@gb.on_draw     # called every frame — raw pygame drawing
+@gb.on_stop     # called once on exit
+```
+
+---
+
+## Requirements
+
+- Python ≥ 3.9
+- pygame-ce ≥ 2.5
+- pytmx ≥ 3.31 *(optional, for TMX loading)*
+- Pillow ≥ 9.0 *(optional, for PNG tileset loading)*
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.