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:

python3 -m venv .venv && . .venv/bin/activate
pip install -e .

Quickstart

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:

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)

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)

Grid(width, height, walls=())

GameLoop(update, tick_rate=60.0, max_steps_per_advance=8)

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.

Development

python3 -m unittest discover -s tests -t .    # or: python3 -m pytest

License

MIT