gamekit 0.1.0__py3-none-any.whl

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/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

gamekit/grid.py

@@ -0,0 +1,130 @@
+"""Tile grids with walls, neighbour lookup, flood fill, and A* pathfinding."""
+
+from __future__ import annotations
+
+import heapq
+from collections import deque
+from itertools import count
+from typing import Iterable, Iterator
+
+from .vec import CARDINALS, Vec2
+
+
+class Grid:
+    """A rectangular grid of cells; each cell is either open or a wall.
+
+    Coordinates are ``Vec2(x, y)`` with ``0 <= x < width`` and ``0 <= y < height``.
+    Movement is 4-directional.
+    """
+
+    def __init__(self, width: int, height: int, walls: Iterable[Vec2] = ()) -> None:
+        if width <= 0 or height <= 0:
+            raise ValueError("grid dimensions must be positive")
+        self.width = width
+        self.height = height
+        self._walls: set[Vec2] = set()
+        for w in walls:
+            self.set_wall(w)
+
+    @classmethod
+    def from_ascii(cls, text: str, wall: str = "#") -> "Grid":
+        """Build a grid from lines of text where ``wall`` characters are walls.
+
+        Leading/trailing blank lines are ignored; short lines are padded as open.
+        """
+        lines = [ln for ln in text.strip("\n").splitlines()]
+        if not lines:
+            raise ValueError("empty map")
+        width = max(len(ln) for ln in lines)
+        walls = [
+            Vec2(x, y)
+            for y, ln in enumerate(lines)
+            for x, ch in enumerate(ln)
+            if ch == wall
+        ]
+        return cls(width, len(lines), walls)
+
+    def in_bounds(self, p: Vec2) -> bool:
+        """True if ``p`` lies inside the grid."""
+        return 0 <= p.x < self.width and 0 <= p.y < self.height
+
+    def is_wall(self, p: Vec2) -> bool:
+        """True if ``p`` is a wall. Out-of-bounds cells count as walls."""
+        return not self.in_bounds(p) or p in self._walls
+
+    def passable(self, p: Vec2) -> bool:
+        """True if ``p`` is in bounds and not a wall."""
+        return not self.is_wall(p)
+
+    def set_wall(self, p: Vec2, wall: bool = True) -> None:
+        """Make ``p`` a wall (or open it with ``wall=False``)."""
+        if not self.in_bounds(p):
+            raise IndexError(f"{p} is out of bounds")
+        if wall:
+            self._walls.add(p)
+        else:
+            self._walls.discard(p)
+
+    def cells(self) -> Iterator[Vec2]:
+        """Iterate every cell in row-major order."""
+        for y in range(self.height):
+            for x in range(self.width):
+                yield Vec2(x, y)
+
+    def neighbors(self, p: Vec2) -> list[Vec2]:
+        """Passable 4-connected neighbours of ``p``."""
+        return [q for q in (p + d for d in CARDINALS) if self.passable(q)]
+
+    def reachable(self, start: Vec2) -> set[Vec2]:
+        """All cells reachable from ``start`` (flood fill). Empty if start is a wall."""
+        if not self.passable(start):
+            return set()
+        seen = {start}
+        queue = deque([start])
+        while queue:
+            for q in self.neighbors(queue.popleft()):
+                if q not in seen:
+                    seen.add(q)
+                    queue.append(q)
+        return seen
+
+    def find_path(self, start: Vec2, goal: Vec2) -> list[Vec2] | None:
+        """Shortest 4-directional path from ``start`` to ``goal`` using A*.
+
+        Returns the list of cells including both endpoints, ``[start]`` when
+        ``start == goal``, or ``None`` if no path exists or an endpoint is blocked.
+        """
+        if not (self.passable(start) and self.passable(goal)):
+            return None
+        tie = count()  # stable tie-breaker so heap never compares Vec2s
+        frontier: list[tuple[int, int, Vec2]] = [(0, next(tie), start)]
+        came_from: dict[Vec2, Vec2 | None] = {start: None}
+        cost: dict[Vec2, int] = {start: 0}
+        while frontier:
+            _, _, cur = heapq.heappop(frontier)
+            if cur == goal:
+                path = [cur]
+                while (prev := came_from[path[-1]]) is not None:
+                    path.append(prev)
+                return path[::-1]
+            for nxt in self.neighbors(cur):
+                new_cost = cost[cur] + 1
+                if new_cost < cost.get(nxt, new_cost + 1):
+                    cost[nxt] = new_cost
+                    came_from[nxt] = cur
+                    prio = new_cost + int(nxt.manhattan(goal))
+                    heapq.heappush(frontier, (prio, next(tie), nxt))
+        return None
+
+    def render(self, marks: dict[Vec2, str] | None = None,
+               wall: str = "#", floor: str = ".") -> str:
+        """Render the grid as text; ``marks`` overrides characters at given cells."""
+        marks = marks or {}
+        rows = []
+        for y in range(self.height):
+            row = []
+            for x in range(self.width):
+                p = Vec2(x, y)
+                row.append(marks.get(p, wall if p in self._walls else floor))
+            rows.append("".join(row))
+        return "\n".join(rows)

gamekit/input.py

@@ -0,0 +1,72 @@
+"""Device-agnostic input mapping: bind raw keys to named actions.
+
+Feed raw key events (any hashable: strings, key codes) from whatever backend
+you use, then query actions. Call :meth:`InputMap.end_frame` once per frame so
+"just pressed" / "just released" edges are tracked correctly.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Hashable, Iterable
+
+
+class InputMap:
+    """Maps raw keys to actions and tracks held / just-pressed / just-released state."""
+
+    def __init__(self, bindings: dict[str, Iterable[Hashable]] | None = None) -> None:
+        self._bindings: dict[str, set[Hashable]] = defaultdict(set)
+        self._held: set[Hashable] = set()
+        self._pressed: set[Hashable] = set()
+        self._released: set[Hashable] = set()
+        for action, keys in (bindings or {}).items():
+            for key in keys:
+                self.bind(action, key)
+
+    def bind(self, action: str, key: Hashable) -> None:
+        """Bind ``key`` to ``action``. A key may drive several actions."""
+        self._bindings[action].add(key)
+
+    def unbind(self, action: str, key: Hashable | None = None) -> None:
+        """Remove one binding, or all bindings for ``action`` if ``key`` is None."""
+        if key is None:
+            self._bindings.pop(action, None)
+        else:
+            self._bindings[action].discard(key)
+
+    def keys_for(self, action: str) -> frozenset[Hashable]:
+        """Keys currently bound to ``action``."""
+        return frozenset(self._bindings.get(action, ()))
+
+    def press(self, key: Hashable) -> None:
+        """Record a key-down event."""
+        if key not in self._held:
+            self._held.add(key)
+            self._pressed.add(key)
+
+    def release(self, key: Hashable) -> None:
+        """Record a key-up event."""
+        if key in self._held:
+            self._held.discard(key)
+            self._released.add(key)
+
+    def is_held(self, action: str) -> bool:
+        """True while any key bound to ``action`` is down."""
+        return not self._held.isdisjoint(self._bindings.get(action, ()))
+
+    def just_pressed(self, action: str) -> bool:
+        """True on the frame a key bound to ``action`` went down."""
+        return not self._pressed.isdisjoint(self._bindings.get(action, ()))
+
+    def just_released(self, action: str) -> bool:
+        """True on the frame a key bound to ``action`` went up."""
+        return not self._released.isdisjoint(self._bindings.get(action, ()))
+
+    def axis(self, negative: str, positive: str) -> int:
+        """-1, 0 or +1 from two opposing held actions (e.g. ``"left"``, ``"right"``)."""
+        return int(self.is_held(positive)) - int(self.is_held(negative))
+
+    def end_frame(self) -> None:
+        """Clear per-frame edge state. Call once after game logic each frame."""
+        self._pressed.clear()
+        self._released.clear()

gamekit/loop.py

@@ -0,0 +1,160 @@
+"""Headless fixed-timestep game loop and countdown timers.
+
+The loop never sleeps or reads the wall clock unless you ask it to, which makes
+simulations deterministic and easy to test: feed it frame times with
+:meth:`GameLoop.advance`, or run a set number of ticks with :meth:`GameLoop.run`.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Callable
+
+UpdateFn = Callable[[float], None]
+
+
+class Timer:
+    """A countdown timer that fires a callback when it elapses.
+
+    With ``repeat=True`` it re-arms itself and can fire several times in one
+    large :meth:`tick` (catch-up), keeping long-run timing exact.
+    """
+
+    def __init__(self, duration: float, callback: Callable[[], None] | None = None,
+                 repeat: bool = False) -> None:
+        if duration <= 0:
+            raise ValueError("duration must be positive")
+        self.duration = duration
+        self.callback = callback
+        self.repeat = repeat
+        self.remaining = duration
+        self.finished = False
+
+    def tick(self, dt: float) -> int:
+        """Advance by ``dt`` seconds; return how many times the timer fired."""
+        if self.finished:
+            return 0
+        self.remaining -= dt
+        fired = 0
+        while self.remaining <= 1e-12:
+            fired += 1
+            if self.callback is not None:
+                self.callback()
+            if not self.repeat:
+                self.finished = True
+                self.remaining = 0.0
+                break
+            self.remaining += self.duration
+        return fired
+
+    def reset(self) -> None:
+        """Restart the countdown from the full duration."""
+        self.remaining = self.duration
+        self.finished = False
+
+    @property
+    def progress(self) -> float:
+        """Fraction of the current cycle elapsed, in ``[0, 1]``."""
+        return 1.0 - max(self.remaining, 0.0) / self.duration
+
+
+class GameLoop:
+    """Fixed-timestep loop: real elapsed time is accumulated and consumed in
+    equal ``1 / tick_rate`` steps, so game logic is frame-rate independent.
+
+    ``update(dt)`` is called once per fixed step. Timers added with
+    :meth:`every` / :meth:`after` are ticked after ``update`` on each step.
+    """
+
+    def __init__(self, update: UpdateFn, tick_rate: float = 60.0,
+                 max_steps_per_advance: int = 8) -> None:
+        if tick_rate <= 0:
+            raise ValueError("tick_rate must be positive")
+        self.update = update
+        self.dt = 1.0 / tick_rate
+        self.max_steps_per_advance = max_steps_per_advance
+        self.ticks = 0
+        self.time = 0.0
+        self.running = False
+        self._accumulator = 0.0
+        self._timers: list[Timer] = []
+
+    @property
+    def alpha(self) -> float:
+        """Leftover fraction of a step, in ``[0, 1)``, for render interpolation."""
+        return self._accumulator / self.dt
+
+    def every(self, seconds: float, callback: Callable[[], None]) -> Timer:
+        """Call ``callback`` every ``seconds`` of simulated time."""
+        t = Timer(seconds, callback, repeat=True)
+        self._timers.append(t)
+        return t
+
+    def after(self, seconds: float, callback: Callable[[], None]) -> Timer:
+        """Call ``callback`` once after ``seconds`` of simulated time."""
+        t = Timer(seconds, callback)
+        self._timers.append(t)
+        return t
+
+    def step(self) -> None:
+        """Run exactly one fixed step: ``update``, advance the clock, then timers.
+
+        Timer callbacks therefore observe the post-step ``ticks`` / ``time``.
+        """
+        self.update(self.dt)
+        self.ticks += 1
+        self.time = self.ticks * self.dt
+        for t in list(self._timers):
+            t.tick(self.dt)
+        self._timers = [t for t in self._timers if not t.finished]
+
+    def advance(self, elapsed: float) -> int:
+        """Feed ``elapsed`` real seconds; run as many fixed steps as fit.
+
+        At most ``max_steps_per_advance`` steps run per call (the rest of the
+        backlog is dropped) to avoid a "spiral of death". Returns steps run.
+        """
+        if elapsed < 0:
+            raise ValueError("elapsed must be non-negative")
+        self._accumulator += elapsed
+        steps = 0
+        while self._accumulator + 1e-12 >= self.dt:
+            if steps >= self.max_steps_per_advance:
+                self._accumulator = 0.0
+                break
+            self.step()
+            self._accumulator -= self.dt
+            steps += 1
+        self._accumulator = max(self._accumulator, 0.0)
+        return steps
+
+    def run(self, ticks: int) -> None:
+        """Run ``ticks`` fixed steps immediately (headless / tests)."""
+        self.running = True
+        for _ in range(ticks):
+            if not self.running:
+                break
+            self.step()
+        self.running = False
+
+    def run_realtime(self, duration: float | None = None,
+                     clock: Callable[[], float] = time.perf_counter,
+                     sleep: Callable[[float], None] = time.sleep) -> None:
+        """Run against a real clock until :meth:`stop` or ``duration`` seconds.
+
+        ``clock`` and ``sleep`` are injectable for testing.
+        """
+        self.running = True
+        start = last = clock()
+        while self.running:
+            now = clock()
+            self.advance(now - last)
+            last = now
+            if duration is not None and now - start >= duration:
+                break
+            sleep(max(0.0, self.dt - self._accumulator))
+        self.running = False
+
+    def stop(self) -> None:
+        """Ask :meth:`run` / :meth:`run_realtime` to exit after the current step."""
+        self.running = False

gamekit/vec.py

@@ -0,0 +1,58 @@
+"""Immutable 2D integer/float vector used for positions and directions."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Iterator, Union
+
+Number = Union[int, float]
+
+
+@dataclass(frozen=True, slots=True)
+class Vec2:
+    """An immutable 2D vector.
+
+    Works with ints (grid coordinates) or floats (continuous positions).
+    Hashable, so it can be used as a dict key or set member.
+    """
+
+    x: Number = 0
+    y: Number = 0
+
+    def __add__(self, other: "Vec2") -> "Vec2":
+        return Vec2(self.x + other.x, self.y + other.y)
+
+    def __sub__(self, other: "Vec2") -> "Vec2":
+        return Vec2(self.x - other.x, self.y - other.y)
+
+    def __mul__(self, k: Number) -> "Vec2":
+        return Vec2(self.x * k, self.y * k)
+
+    __rmul__ = __mul__
+
+    def __neg__(self) -> "Vec2":
+        return Vec2(-self.x, -self.y)
+
+    def __iter__(self) -> Iterator[Number]:
+        yield self.x
+        yield self.y
+
+    def length(self) -> float:
+        """Euclidean length."""
+        return math.hypot(self.x, self.y)
+
+    def manhattan(self, other: "Vec2") -> Number:
+        """Manhattan (taxicab) distance to ``other``."""
+        return abs(self.x - other.x) + abs(self.y - other.y)
+
+    def normalized(self) -> "Vec2":
+        """Unit vector in the same direction; the zero vector stays zero."""
+        n = self.length()
+        if n == 0:
+            return Vec2(0.0, 0.0)
+        return Vec2(self.x / n, self.y / n)
+
+
+#: The four cardinal unit directions (right, left, down, up), y grows downward.
+CARDINALS: tuple[Vec2, ...] = (Vec2(1, 0), Vec2(-1, 0), Vec2(0, 1), Vec2(0, -1))

gamekit-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+gamekit/__init__.py,sha256=LTTugKX1V-4G28N9YdsSh0v6eemh4Z1ffuO5QDMBdas,674
+gamekit/ecs.py,sha256=xqRTQt1aiTpL3asFRGF4B_CubMdt1f0ApBDyPO_TLs0,4844
+gamekit/grid.py,sha256=pz2PvYPIr_TP8wjnWK8osfcpJpa3hmDxKcjI4UlmXug,4874
+gamekit/input.py,sha256=k-sCGOnsjThuVP7f1igPhOQ7hhWQx7ekV0RDkW_UznI,2884
+gamekit/loop.py,sha256=TEooWdqqI8kwW00wtFuhXXsS5jCyhvcQQizXhG954Dk,5663
+gamekit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gamekit/vec.py,sha256=CU-maOWjhaMeJYFIpFI4bRYO1gAm870hO1ndxfHByMk,1639
+gamekit-0.1.0.dist-info/licenses/LICENSE,sha256=pAfYREEW9GAy7cnK20OXjDn7ofJahYny9GCuIZQTDAA,1061
+gamekit-0.1.0.dist-info/METADATA,sha256=u7_CXCE8PHeayvIgDDRAEngK2mZXmAOmcBi8QqV64VY,7563
+gamekit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+gamekit-0.1.0.dist-info/top_level.txt,sha256=B7Oj60S5AlHspUApEv0EDMOTYSRmi3YCAyPhHBYEPd8,8
+gamekit-0.1.0.dist-info/RECORD,,

gamekit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gamekit-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+gamekit