gamekit 0.1.0__tar.gz

gamekit-0.1.0/LICENSE

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

gamekit-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: gamekit
+Version: 0.1.0
+Summary: A tiny, dependency-free, headless toolkit for building games: ECS, grids and A* pathfinding, a fixed-timestep loop, timers, and input mapping.
+Author: nehz
+License-Expression: MIT
+Keywords: game,gamedev,ecs,pathfinding,game-loop,roguelike
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Dynamic: license-file
+
+# gamekit
+
+**The game-logic half of a game engine, with no window required.**
+
+gamekit is a small, pure-Python toolkit for the parts of a game that aren't
+graphics: an entity-component-system, tile grids with A* pathfinding, a
+fixed-timestep game loop with timers, and action-based input mapping. It has
+zero dependencies and never opens a display, so your game logic runs the same
+in a terminal, a test suite, a server, or under whatever renderer you bolt on
+later (curses, pygame, a web front end...).
+
+## Features
+
+- **ECS** (`World`): integer entity ids, components are plain objects (dataclasses
+  work well), typed `query()` over component combinations, ordered systems, and
+  deferred `destroy()` so it's safe to remove entities while iterating.
+- **Grids & pathfinding** (`Grid`): build maps from ASCII art, 4-way neighbours,
+  flood-fill reachability, A* shortest paths, and text rendering with overlays.
+- **Fixed-timestep loop** (`GameLoop`): frame-rate-independent updates, an
+  accumulator with a "spiral of death" cap, render interpolation `alpha`,
+  headless `run(ticks)` for tests, and `run_realtime()` with an injectable clock.
+- **Timers** (`Timer`, `GameLoop.every/after`): one-shot and repeating timers in
+  simulated time, with exact catch-up when a big step overshoots.
+- **Input mapping** (`InputMap`): bind any hashable key to named actions; query
+  held / just-pressed / just-released and two-action axes. Backend-agnostic.
+- **`Vec2`**: immutable, hashable 2D vector usable as a dict key.
+- Fully type-hinted (`py.typed`), standard library only, Python 3.10+.
+
+## Install
+
+From a checkout:
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e .
+```
+
+## Quickstart
+
+```python
+from dataclasses import dataclass
+from gamekit import GameLoop, Grid, Vec2, World
+
+@dataclass
+class Pos:
+    at: Vec2
+
+@dataclass
+class Seeker:
+    goal: Vec2
+
+grid = Grid.from_ascii("""
+#######
+#.....#
+#.###.#
+#.....#
+#######
+""")
+
+world = World()
+world.spawn(Pos(Vec2(1, 1)), Seeker(goal=Vec2(5, 3)))
+
+@world.add_system
+def seek(world: World, dt: float) -> None:
+    for eid, pos, seeker in world.query(Pos, Seeker):
+        path = grid.find_path(pos.at, seeker.goal)
+        if path and len(path) > 1:
+            pos.at = path[1]          # one step per tick
+        else:
+            world.destroy(eid)        # arrived (removed at end of step)
+
+loop = GameLoop(world.step, tick_rate=10)
+loop.every(0.5, lambda: print(f"t={loop.time:.1f}s entities={len(world)}"))
+loop.run(10)
+```
+
+A complete example, a tiny terminal chase game that uses every module, lives in
+[`examples/chase.py`](examples/chase.py):
+
+```bash
+python3 examples/chase.py              # coin-collecting player escapes the ghost
+python3 examples/chase.py --idle       # player stands still; the ghost catches it
+python3 examples/chase.py --every 1 --delay 0.1   # watch it frame by frame
+```
+
+## API overview
+
+Everything below is importable from the top-level `gamekit` package.
+
+### `Vec2(x=0, y=0)` (frozen dataclass)
+
+| Member | Description |
+| --- | --- |
+| `+`, `-`, `* k`, `k *`, unary `-` | Vector arithmetic |
+| `iter(v)` | Unpack: `x, y = v` |
+| `length() -> float` | Euclidean length |
+| `manhattan(other)` | Taxicab distance |
+| `normalized() -> Vec2` | Unit vector (zero stays zero) |
+
+`CARDINALS`: tuple of the four unit directions `(1,0), (-1,0), (0,1), (0,-1)`; y grows downward.
+
+### `World()`, the ECS (`Entity` is an alias for `int`)
+
+| Method | Description |
+| --- | --- |
+| `spawn(*components) -> Entity` | Create an entity |
+| `destroy(entity)` | Mark for removal; applied at the end of `step()` or by `flush()` |
+| `flush()` | Apply pending destroys now |
+| `alive(entity) -> bool` | Exists and is not pending destruction |
+| `len(world)` | Number of live entities |
+| `add(entity, component)` | Attach/replace a component (keyed by its type) |
+| `remove(entity, ctype)` | Detach a component type (no-op if absent) |
+| `get(entity, ctype)` | Component, or `KeyError` |
+| `try_get(entity, ctype)` | Component or `None` |
+| `has(entity, *ctypes) -> bool` | Has every listed type |
+| `query(*ctypes)` | Yields `(entity, comp1, comp2, ...)` in creation order |
+| `add_system(fn)` | Register `fn(world, dt)`; usable as a decorator |
+| `step(dt)` | Run all systems in order, then flush destroys |
+
+### `Grid(width, height, walls=())`
+
+| Method | Description |
+| --- | --- |
+| `Grid.from_ascii(text, wall="#")` | Build from ASCII art |
+| `width`, `height` | Dimensions |
+| `in_bounds(p)`, `is_wall(p)`, `passable(p)` | Cell tests (out of bounds counts as wall) |
+| `set_wall(p, wall=True)` | Add/remove a wall (`IndexError` if out of bounds) |
+| `cells()` | All cells, row-major |
+| `neighbors(p) -> list[Vec2]` | Passable 4-connected neighbours |
+| `reachable(start) -> set[Vec2]` | Flood fill |
+| `find_path(start, goal) -> list[Vec2] \| None` | A* shortest path including both endpoints |
+| `render(marks=None, wall="#", floor=".") -> str` | Text rendering with per-cell overrides |
+
+### `GameLoop(update, tick_rate=60.0, max_steps_per_advance=8)`
+
+| Member | Description |
+| --- | --- |
+| `update(dt)` | Your callback, called once per fixed step |
+| `dt`, `ticks`, `time`, `running` | Step size, steps run, simulated seconds, run state |
+| `alpha` | Leftover fraction of a step, for render interpolation |
+| `step()` | Run exactly one step: `update`, advance `ticks`/`time`, then timers |
+| `advance(elapsed) -> int` | Feed real elapsed seconds; returns steps run |
+| `run(ticks)` | Run N steps immediately (headless) |
+| `run_realtime(duration=None, clock=time.perf_counter, sleep=time.sleep)` | Real-time loop |
+| `stop()` | Exit `run`/`run_realtime` after the current step |
+| `every(seconds, cb) -> Timer` / `after(seconds, cb) -> Timer` | Schedule in simulated time |
+
+### `Timer(duration, callback=None, repeat=False)`
+
+`tick(dt) -> int` (times fired), `reset()`, `progress` (0..1), `remaining`, `finished`.
+
+### `InputMap(bindings=None)`
+
+`bindings` is `{"action": [key, ...]}`; keys are any hashable.
+
+| Method | Description |
+| --- | --- |
+| `bind(action, key)` / `unbind(action, key=None)` | Edit bindings |
+| `keys_for(action) -> frozenset` | Keys bound to an action |
+| `press(key)` / `release(key)` | Feed raw events from your backend |
+| `is_held(action)`, `just_pressed(action)`, `just_released(action)` | Action state |
+| `axis(negative, positive) -> int` | -1, 0 or +1 |
+| `end_frame()` | Clear edge state; call once per frame |
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -t .    # or: python3 -m pytest
+```
+
+## License
+
+MIT

gamekit-0.1.0/README.md

@@ -0,0 +1,173 @@
+# gamekit
+
+**The game-logic half of a game engine, with no window required.**
+
+gamekit is a small, pure-Python toolkit for the parts of a game that aren't
+graphics: an entity-component-system, tile grids with A* pathfinding, a
+fixed-timestep game loop with timers, and action-based input mapping. It has
+zero dependencies and never opens a display, so your game logic runs the same
+in a terminal, a test suite, a server, or under whatever renderer you bolt on
+later (curses, pygame, a web front end...).
+
+## Features
+
+- **ECS** (`World`): integer entity ids, components are plain objects (dataclasses
+  work well), typed `query()` over component combinations, ordered systems, and
+  deferred `destroy()` so it's safe to remove entities while iterating.
+- **Grids & pathfinding** (`Grid`): build maps from ASCII art, 4-way neighbours,
+  flood-fill reachability, A* shortest paths, and text rendering with overlays.
+- **Fixed-timestep loop** (`GameLoop`): frame-rate-independent updates, an
+  accumulator with a "spiral of death" cap, render interpolation `alpha`,
+  headless `run(ticks)` for tests, and `run_realtime()` with an injectable clock.
+- **Timers** (`Timer`, `GameLoop.every/after`): one-shot and repeating timers in
+  simulated time, with exact catch-up when a big step overshoots.
+- **Input mapping** (`InputMap`): bind any hashable key to named actions; query
+  held / just-pressed / just-released and two-action axes. Backend-agnostic.
+- **`Vec2`**: immutable, hashable 2D vector usable as a dict key.
+- Fully type-hinted (`py.typed`), standard library only, Python 3.10+.
+
+## Install
+
+From a checkout:
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e .
+```
+
+## Quickstart
+
+```python
+from dataclasses import dataclass
+from gamekit import GameLoop, Grid, Vec2, World
+
+@dataclass
+class Pos:
+    at: Vec2
+
+@dataclass
+class Seeker:
+    goal: Vec2
+
+grid = Grid.from_ascii("""
+#######
+#.....#
+#.###.#
+#.....#
+#######
+""")
+
+world = World()
+world.spawn(Pos(Vec2(1, 1)), Seeker(goal=Vec2(5, 3)))
+
+@world.add_system
+def seek(world: World, dt: float) -> None:
+    for eid, pos, seeker in world.query(Pos, Seeker):
+        path = grid.find_path(pos.at, seeker.goal)
+        if path and len(path) > 1:
+            pos.at = path[1]          # one step per tick
+        else:
+            world.destroy(eid)        # arrived (removed at end of step)
+
+loop = GameLoop(world.step, tick_rate=10)
+loop.every(0.5, lambda: print(f"t={loop.time:.1f}s entities={len(world)}"))
+loop.run(10)
+```
+
+A complete example, a tiny terminal chase game that uses every module, lives in
+[`examples/chase.py`](examples/chase.py):
+
+```bash
+python3 examples/chase.py              # coin-collecting player escapes the ghost
+python3 examples/chase.py --idle       # player stands still; the ghost catches it
+python3 examples/chase.py --every 1 --delay 0.1   # watch it frame by frame
+```
+
+## API overview
+
+Everything below is importable from the top-level `gamekit` package.
+
+### `Vec2(x=0, y=0)` (frozen dataclass)
+
+| Member | Description |
+| --- | --- |
+| `+`, `-`, `* k`, `k *`, unary `-` | Vector arithmetic |
+| `iter(v)` | Unpack: `x, y = v` |
+| `length() -> float` | Euclidean length |
+| `manhattan(other)` | Taxicab distance |
+| `normalized() -> Vec2` | Unit vector (zero stays zero) |
+
+`CARDINALS`: tuple of the four unit directions `(1,0), (-1,0), (0,1), (0,-1)`; y grows downward.
+
+### `World()`, the ECS (`Entity` is an alias for `int`)
+
+| Method | Description |
+| --- | --- |
+| `spawn(*components) -> Entity` | Create an entity |
+| `destroy(entity)` | Mark for removal; applied at the end of `step()` or by `flush()` |
+| `flush()` | Apply pending destroys now |
+| `alive(entity) -> bool` | Exists and is not pending destruction |
+| `len(world)` | Number of live entities |
+| `add(entity, component)` | Attach/replace a component (keyed by its type) |
+| `remove(entity, ctype)` | Detach a component type (no-op if absent) |
+| `get(entity, ctype)` | Component, or `KeyError` |
+| `try_get(entity, ctype)` | Component or `None` |
+| `has(entity, *ctypes) -> bool` | Has every listed type |
+| `query(*ctypes)` | Yields `(entity, comp1, comp2, ...)` in creation order |
+| `add_system(fn)` | Register `fn(world, dt)`; usable as a decorator |
+| `step(dt)` | Run all systems in order, then flush destroys |
+
+### `Grid(width, height, walls=())`
+
+| Method | Description |
+| --- | --- |
+| `Grid.from_ascii(text, wall="#")` | Build from ASCII art |
+| `width`, `height` | Dimensions |
+| `in_bounds(p)`, `is_wall(p)`, `passable(p)` | Cell tests (out of bounds counts as wall) |
+| `set_wall(p, wall=True)` | Add/remove a wall (`IndexError` if out of bounds) |
+| `cells()` | All cells, row-major |
+| `neighbors(p) -> list[Vec2]` | Passable 4-connected neighbours |
+| `reachable(start) -> set[Vec2]` | Flood fill |
+| `find_path(start, goal) -> list[Vec2] \| None` | A* shortest path including both endpoints |
+| `render(marks=None, wall="#", floor=".") -> str` | Text rendering with per-cell overrides |
+
+### `GameLoop(update, tick_rate=60.0, max_steps_per_advance=8)`
+
+| Member | Description |
+| --- | --- |
+| `update(dt)` | Your callback, called once per fixed step |
+| `dt`, `ticks`, `time`, `running` | Step size, steps run, simulated seconds, run state |
+| `alpha` | Leftover fraction of a step, for render interpolation |
+| `step()` | Run exactly one step: `update`, advance `ticks`/`time`, then timers |
+| `advance(elapsed) -> int` | Feed real elapsed seconds; returns steps run |
+| `run(ticks)` | Run N steps immediately (headless) |
+| `run_realtime(duration=None, clock=time.perf_counter, sleep=time.sleep)` | Real-time loop |
+| `stop()` | Exit `run`/`run_realtime` after the current step |
+| `every(seconds, cb) -> Timer` / `after(seconds, cb) -> Timer` | Schedule in simulated time |
+
+### `Timer(duration, callback=None, repeat=False)`
+
+`tick(dt) -> int` (times fired), `reset()`, `progress` (0..1), `remaining`, `finished`.
+
+### `InputMap(bindings=None)`
+
+`bindings` is `{"action": [key, ...]}`; keys are any hashable.
+
+| Method | Description |
+| --- | --- |
+| `bind(action, key)` / `unbind(action, key=None)` | Edit bindings |
+| `keys_for(action) -> frozenset` | Keys bound to an action |
+| `press(key)` / `release(key)` | Feed raw events from your backend |
+| `is_held(action)`, `just_pressed(action)`, `just_released(action)` | Action state |
+| `axis(negative, positive) -> int` | -1, 0 or +1 |
+| `end_frame()` | Clear edge state; call once per frame |
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -t .    # or: python3 -m pytest
+```
+
+## License
+
+MIT

gamekit-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gamekit"
+version = "0.1.0"
+description = "A tiny, dependency-free, headless toolkit for building games: ECS, grids and A* pathfinding, a fixed-timestep loop, timers, and input mapping."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "nehz" }]
+keywords = ["game", "gamedev", "ecs", "pathfinding", "game-loop", "roguelike"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+gamekit = ["py.typed"]

gamekit-0.1.0/setup.cfg

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

gamekit-0.1.0/src/gamekit/__init__.py

@@ -0,0 +1,29 @@
+"""gamekit: a small, dependency-free, headless toolkit for building games.
+
+Modules:
+    vec   -- immutable :class:`Vec2`
+    ecs   -- entity-component-system :class:`World`
+    grid  -- tile :class:`Grid` with flood fill and A* pathfinding
+    loop  -- fixed-timestep :class:`GameLoop` and :class:`Timer`
+    input -- action-based :class:`InputMap`
+"""
+
+from .ecs import Entity, World
+from .grid import Grid
+from .input import InputMap
+from .loop import GameLoop, Timer
+from .vec import CARDINALS, Vec2
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CARDINALS",
+    "Entity",
+    "GameLoop",
+    "Grid",
+    "InputMap",
+    "Timer",
+    "Vec2",
+    "World",
+    "__version__",
+]

gamekit-0.1.0/src/gamekit/ecs.py

@@ -0,0 +1,128 @@
+"""A minimal entity-component-system.
+
+Entities are integer ids. Components are arbitrary Python objects stored by
+their type, so each entity holds at most one component of a given type.
+Systems are callables ``system(world, dt)`` run in registration order.
+"""
+
+from __future__ import annotations
+
+from itertools import count
+from typing import Any, Callable, Iterator, TypeVar, overload
+
+T = TypeVar("T")
+A = TypeVar("A")
+B = TypeVar("B")
+C = TypeVar("C")
+
+Entity = int
+System = Callable[["World", float], None]
+
+
+class World:
+    """Container for entities, their components, and the systems that act on them."""
+
+    def __init__(self) -> None:
+        self._ids = count(1)
+        self._entities: dict[Entity, dict[type, Any]] = {}
+        self._systems: list[System] = []
+        self._pending_destroy: set[Entity] = set()
+
+    # -- entities -----------------------------------------------------------
+
+    def spawn(self, *components: Any) -> Entity:
+        """Create a new entity with the given components and return its id."""
+        eid = next(self._ids)
+        self._entities[eid] = {}
+        for comp in components:
+            self.add(eid, comp)
+        return eid
+
+    def destroy(self, entity: Entity) -> None:
+        """Mark ``entity`` for removal at the end of the current :meth:`step`.
+
+        Outside of a step, call :meth:`flush` (or the next ``step``) to apply it.
+        Deferring keeps iteration inside systems safe.
+        """
+        if entity in self._entities:
+            self._pending_destroy.add(entity)
+
+    def flush(self) -> None:
+        """Apply pending destroys immediately."""
+        for eid in self._pending_destroy:
+            self._entities.pop(eid, None)
+        self._pending_destroy.clear()
+
+    def alive(self, entity: Entity) -> bool:
+        """True if ``entity`` exists and is not pending destruction."""
+        return entity in self._entities and entity not in self._pending_destroy
+
+    def __len__(self) -> int:
+        return sum(1 for e in self._entities if e not in self._pending_destroy)
+
+    # -- components ---------------------------------------------------------
+
+    def add(self, entity: Entity, component: Any) -> None:
+        """Attach ``component`` to ``entity``, replacing any of the same type."""
+        self._require(entity)[type(component)] = component
+
+    def remove(self, entity: Entity, ctype: type) -> None:
+        """Detach the component of type ``ctype``; no-op if absent."""
+        self._require(entity).pop(ctype, None)
+
+    def get(self, entity: Entity, ctype: type[T]) -> T:
+        """Return the ``ctype`` component of ``entity``; raise ``KeyError`` if absent."""
+        return self._require(entity)[ctype]
+
+    def try_get(self, entity: Entity, ctype: type[T]) -> T | None:
+        """Return the ``ctype`` component of ``entity`` or ``None``."""
+        return self._require(entity).get(ctype)
+
+    def has(self, entity: Entity, *ctypes: type) -> bool:
+        """True if ``entity`` has every component type in ``ctypes``."""
+        comps = self._entities.get(entity)
+        return comps is not None and all(c in comps for c in ctypes)
+
+    @overload
+    def query(self, a: type[A], /) -> Iterator[tuple[Entity, A]]: ...
+    @overload
+    def query(self, a: type[A], b: type[B], /) -> Iterator[tuple[Entity, A, B]]: ...
+    @overload
+    def query(
+        self, a: type[A], b: type[B], c: type[C], /
+    ) -> Iterator[tuple[Entity, A, B, C]]: ...
+    @overload
+    def query(self, *ctypes: type) -> Iterator[tuple[Any, ...]]: ...
+
+    def query(self, *ctypes: type) -> Iterator[tuple[Any, ...]]:
+        """Yield ``(entity, comp1, comp2, ...)`` for live entities having all ``ctypes``.
+
+        Entities are yielded in creation order. The entity set is snapshotted,
+        so spawning/destroying while iterating is safe.
+        """
+        if not ctypes:
+            raise ValueError("query() needs at least one component type")
+        for eid, comps in list(self._entities.items()):
+            if eid in self._pending_destroy:
+                continue
+            if all(c in comps for c in ctypes):
+                yield (eid, *(comps[c] for c in ctypes))
+
+    # -- systems ------------------------------------------------------------
+
+    def add_system(self, system: System) -> System:
+        """Register a system; returns it so this can be used as a decorator."""
+        self._systems.append(system)
+        return system
+
+    def step(self, dt: float) -> None:
+        """Run every system once with timestep ``dt``, then flush destroys."""
+        for system in self._systems:
+            system(self, dt)
+        self.flush()
+
+    def _require(self, entity: Entity) -> dict[type, Any]:
+        try:
+            return self._entities[entity]
+        except KeyError:
+            raise KeyError(f"no such entity: {entity}") from None