Skip to main content

KEG

KEG is an Engine for Games. More specifically, it is a small, typed, archetype-based ECS for Python 3.12 and newer.

KEG does not require components to inherit from anything. A dataclass will do. So will any other arbitrary object, although please exercise some judgment.

from dataclasses import dataclass

from keg import World


@dataclass(slots=True)
class Position:
    x: float
    y: float


@dataclass(slots=True)
class Velocity:
    x: float
    y: float


world = World()
player = world.spawn(
    Position(10.0, 20.0),
    Velocity(4.0, -2.0),
)

for entities, positions, velocities in world.query(Position, Velocity):
    for row in range(len(entities)):
        position = positions[row]
        velocity = velocities[row]
        position.x += velocity.x
        position.y += velocity.y

Queries return columns

A query yields one batch per matching archetype. Each batch contains the entity IDs followed by the requested component columns, in request order:

for entities, positions, velocities in world.query(Position, Velocity):
    ...

The sequences in a batch are aligned: entities[row], positions[row], and velocities[row] all belong to the same entity. They expose KEG's underlying column storage and should be treated as read-only. The component objects remain yours to mutate.

This avoids manufacturing a tuple for every entity merely to take it apart again in a hot loop. Queries are precisely typed for up to sixteen component types.

An entity may contain at most one component of each exact runtime type. Component inheritance has no special meaning to KEG.

Structural changes

Spawning and despawning entities, or adding and removing components, can move entities between archetypes. KEG applies those operations immediately during ordinary use and defers them automatically while a query is being iterated. The pending changes are committed after the last active query finishes.

You can request the same behaviour explicitly when applying a batch of changes:

with world.defer_structural_changes():
    projectile = world.spawn(Position(0.0, 0.0))
    world.add_component(projectile, Velocity(12.0, 3.0))

Pending entities and components remain accessible through get_component() and set_component(), while queries continue to see the committed archetype layout until the changes are flushed.

Queries release their structural guard when exhausted or explicitly closed. If you retain a query iterator and stop consuming it early, whether through break or an exception in surrounding code, call its close() method so pending structural work can be committed. Do not rely on garbage collection.

Installation

KEG currently has no runtime dependencies:

python -m pip install keg-engine

Example

The bouncing-balls example uses Kivy to exercise a small position and velocity system in a real update loop:

git clone https://github.com/Cheaterman/KEG.git
cd KEG
python -m pip install -e '.[examples]'
python examples/bouncing_balls/main.py

License

KEG is distributed under the MIT license.

Metadata

Release files for keg-engine 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for keg-engine 0.2.1
File Size Uploaded Provenance Actions
keg_engine-0.2.1.tar.gz 14.7 kB Without provenance Details for keg_engine-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for keg-engine 0.2.1
File Interpreter ABI Platform Actions
keg_engine-0.2.1-py3-none-any.whl Python 3 none any Details for keg_engine-0.2.1-py3-none-any.whl

Total release size: 24.7 kB

Release files / keg_engine-0.2.1.tar.gz

Download URL keg_engine-0.2.1.tar.gz
Size 14.7 kB
Tags Source
SHA-256 checksum
How to use checksums
848a6c5126ec1e7acfe720ba4649778c4c428c44defe2c54e922b54ad10d86db
BLAKE2b-256 checksum
How to use checksums
b9ab62ee85a9897aa21a933de874637ed2fc69f125838e4991c89d61704893b0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / keg_engine-0.2.1-py3-none-any.whl

Download URL keg_engine-0.2.1-py3-none-any.whl
Size 10.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ed037ebaf90b7053b07decab6e6e646926868d56d7060df917e085a1f1ae0426
BLAKE2b-256 checksum
How to use checksums
e347a6edb78ff879ec8b33f51f0ae490f362dc5cc6ac891eb850dfa00e0e8acf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for keg-engine 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page