Metadata-Version: 2.4
Name: charforge
Version: 0.1.0
Summary: A small, generic Python library for building 2D character-matrix games.
Author: charforge contributors
License: MIT
Project-URL: Homepage, https://github.com/charforge/charforge
Project-URL: Repository, https://github.com/charforge/charforge
Project-URL: Documentation, https://github.com/charforge/charforge#readme
Project-URL: Issues, https://github.com/charforge/charforge/issues
Project-URL: Changelog, https://github.com/charforge/charforge/blob/main/CHANGELOG.md
Keywords: game,game-engine,2d,ascii,matrix,roguelike,tile,grid
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# charforge

**A small, generic Python library for building 2D character-matrix games.**

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-232%20passing-brightgreen.svg)](#tests)

`charforge` provides reusable building blocks for games whose levels are
described by a matrix of single characters: a `Matrix` engine, a configurable
`Tile` system, a generic `Entity` class, collision and movement helpers, a tiny
event bus, an interaction layer, modular renderers and a plugin system.
Everything is tied together by the `World` class.

The library is **pure Python**, has **no required third-party dependency**, runs
on **Python 3.10+** and works on **Linux, macOS and Windows**.

It is intentionally **genre-agnostic**: it is not a RPG engine, nor a
platformer engine, nor a roguelike engine. It is a toolbox from which you can
build any of these.

---

## Table of contents

- [Goals](#goals)
- [Features](#features)
- [Installation](#installation)
- [Quick start](#quick-start)
- [A complete example](#a-complete-example)
- [Main API](#main-api)
- [Architecture](#architecture)
- [Examples](#examples)
- [Tests](#tests)
- [License](#license)

---

## Goals

1. **Simplicity first.** A beginner should be able to build a playable
   mini-game in a few minutes by editing a matrix and a handful of parameters.
2. **Generic, not opinionated.** The library does not assume a genre. Build a
   roguelike, a puzzle game, a turn-based tactical game, a Sokoban-like, etc.
3. **Modular.** Every system (collisions, movement, rendering, events,
   interactions, plugins) can be swapped, extended or replaced.
4. **No required dependencies.** Pure Python, standard library only.
5. **Type-safe and well-documented.** Modern type hints, full docstrings,
   comprehensive test suite.

## Features

- **Matrix engine** – build matrices from strings or lists, mutate them,
  search, replace, resize, copy, compare, serialise to JSON and load from
  text files.
- **Tile system** – describe the meaning of each character (solid, walkable,
  category, color, arbitrary metadata).
- **Entity system** – lightweight, subclassable entities with position,
  symbol, properties, active state and an `update()` hook.
- **Collision system** – composable strategies (bounds, tiles, entities,
  callable, none); write your own by implementing a single method.
- **Movement system** – cardinal directions, multi-step moves with intermediate
  collision checks, teleport, absolute moves, event emission.
- **World** – the central hub that ties everything together with a clean API.
- **Event system** – pub/sub event bus with `move`, `collision`, `tile_enter`,
  `tile_leave`, `interact`, `entity_added`, `entity_removed`, `map_changed`
  events and a `*` wildcard.
- **Interaction helpers** – entity-at, entities-in-zone, line-of-sight
  (Bresenham), adjacent entities, etc.
- **Rendering** – ASCII renderer, ANSI-color renderer, layered renderer with
  overlays; the architecture makes adding a graphical backend trivial.
- **Plugin system** – register, enable, disable and detach plugins that can
  install tiles, listeners, collision strategies or anything else.
- **Optional game loop** – a tiny blocking loop for quick prototyping.

## Installation

From PyPI (once published):

```bash
pip install charforge
```

From source (development):

```bash
git clone https://github.com/charforge/charforge.git
cd charforge
pip install -e ".[dev]"
```

## Quick start

```python
from charforge import Matrix, World, Entity, Tile

matrix = Matrix([
    "##########",
    "#........#",
    "#..P.....#",
    "#........#",
    "#.....E..#",
    "##########",
])

world = World(matrix)
world.register_tile("#", Tile(solid=True))
world.register_tile(".", Tile(solid=False))

# spawn() creates entities from matrix markers and clears the markers.
players = world.spawn("P", name="player")
enemies = world.spawn("E", name="enemy", solid=True)
player = players[0]

print(world.render())

world.move(player, "right")
print(world.render())
```

Output:

```
##########
#........#
#..P.....#
#........#
#.....E..#
##########

##########
#........#
#...P....#
#........#
#.....E..#
##########
```

## A complete example

A small "collect the coins" mini-game in 25 lines:

```python
from charforge import Matrix, World, Entity, Tile

level = [
    "###########",
    "#..C......#",
    "#.........#",
    "#....P....#",
    "#.........#",
    "#......C..#",
    "###########",
]

world = World(Matrix(level))
world.register_tile("#", Tile(name="wall", solid=True, color="blue"))
world.register_tile(".", Tile(name="floor"))
world.register_tile("C", Tile(name="coin"))  # just metadata, not solid

player = world.spawn("P", name="player")[0]
coins = world.spawn("C", name="coin", background=".")
remaining = len(coins)

@world.on("tile_enter")
def on_enter(ev):
    global remaining
    if ev.tile.name == "coin":
        # Pick up the coin: replace it with floor.
        world.set(ev.x, ev.y, ".")
        remaining -= 1
        print(f"Coin collected! {remaining} remaining.")
        if remaining == 0:
            print("You win!")

# Move the player around to collect the coins.
for direction in ["up", "left", "left", "down", "down", "right", "right",
                   "right", "right", "right", "right", "up", "up", "left",
                   "left", "left", "left"]:
    world.move(player, direction)

print(world.render())
```

## Main API

| Class / function         | Purpose                                            |
| ------------------------ | -------------------------------------------------- |
| `Matrix`                 | 2D grid of characters with rich operations.        |
| `Tile`, `TileRegistry`   | Configure the meaning of each character.           |
| `Entity`                 | A movable thing with position, symbol, properties. |
| `World`                  | The central hub: matrix + tiles + entities + more. |
| `EventBus`, `Event`      | Tiny pub/sub event system.                         |
| `*Collision` classes     | Composable collision strategies.                   |
| `AsciiRenderer` etc.     | Modular renderers.                                 |
| `PluginManager`          | Register / enable / disable plugins.               |
| `run_game_loop`          | Optional blocking game loop.                       |

See the [docs](docs/) for details.

## Architecture

```
charforge
├── matrix.py        # Matrix class (2D grid)
├── tiles.py         # Tile + TileRegistry
├── entities.py      # Entity base class
├── world.py         # World (the central hub)
├── collisions.py    # Collision strategies
├── movement.py      # Direction constants + helpers
├── events.py        # EventBus + Event
├── interactions.py  # entity_at, line_of_sight, etc.
├── rendering.py     # AsciiRenderer, AnsiRenderer, LayeredRenderer
├── plugins.py       # PluginManager + FunctionPlugin
├── exceptions.py    # Exception hierarchy
└── utils.py         # Direction helpers, clamp, etc.
```

The `World` is the only object that knows about every subsystem; the other
modules can be used in isolation. There are **no circular imports**.

## Examples

The `examples/` directory contains small, runnable scripts:

| File                  | Demonstrates                                |
| --------------------- | ------------------------------------------- |
| `basic_map.py`        | Creating a matrix and rendering it.         |
| `movement.py`         | Moving entities and observing events.       |
| `collisions.py`       | Tile and entity collisions.                 |
| `entities.py`         | Subclassing `Entity` for custom behaviour.  |
| `events.py`           | Subscribing to world events.                |
| `custom_tiles.py`     | Defining custom tile types with metadata.   |

Run any of them with `python examples/<file>.py`.

## Tests

The library ships with 232 pytest tests covering every module:

```bash
python -m pytest
```

Lint with ruff:

```bash
python -m ruff check .
```

## License

MIT — see [LICENSE](LICENSE).
