Sneks Engine
A Python game engine for creating snake-like games with customizable rules, graphics, and AI submissions.
Architecture
src/sneks/
├── engine/ # Core engine components
│ ├── core/ # Primitives: Cell, Bearing, Direction, Action
│ ├── entity/ # Game entities: Snek, Food, Static/Dynamic
│ ├── config/ # Configuration dataclasses
│ ├── manager/ # Cell and bearing calculations
│ ├── validator/ # Submission validation tests
│ ├── world.py # Base World class (game loop)
│ ├── graphics.py # Pygame rendering
│ ├── recorder.py # Frame capture and video encoding
│ ├── runner.py # Game execution and scoring
│ └── scoring.py # Score normalization
└── games/ # Game variants
├── classic/ # Traditional snek
├── space/ # Asteroids + snek
├── toroidal/ # Infinite growth mode
└── example/ # Example submission
Key Components
- World: Manages the game loop, entities, and board state. Subclass this to create new game modes.
- Entity: Base class for all game objects.
DynamicEntitymoves and grows;StaticEntitymaintains shape. - Snek: The AI interface that submissions implement. Receives game state and returns an
Action. - Config: Singleton configuration system. Each game mode extends
Configwith custom settings.
Creating a New Game Mode
- Create a config class extending
Config:
from dataclasses import dataclass
from sneks.engine.config.base import Config
@dataclass(frozen=True)
class MyGameConfig(Config):
title: str = "My Game"
turn_limit: int = 5000
- Create a world class extending
World:
from sneks.engine.world import World
from sneks.engine.scoring import Criteria
class MyGame(World):
criteria = Criteria.AGE | Criteria.LENGTH # Scoring criteria
def __init__(self, config: MyGameConfig) -> None:
super().__init__(config=config)
# Override hooks as needed:
# - load_entities(): Add custom entities
# - before_step(): Pre-step logic
# - after_step(): Post-step logic (collisions, growth)
Core Concepts
Bearing vs Direction vs Action
The engine uses a velocity-based movement model:
- Bearing: Current velocity as
Bearing(x, y)— cells moved per tick in each axis. A snek atBearing(2, -1)moves 2 cells right and 1 cell down each tick. - Direction: Cardinal directions (
UP,DOWN,LEFT,RIGHT) used for querying neighbors and obstacles. - Action: Acceleration input returned by
get_next_action(). Actions modify the bearing —Action.UPincrementsbearing.yby 1.
Sneks start stationary at Bearing(0, 0). Returning Action.RIGHT twice results in Bearing(2, 0), moving 2 cells right per tick.
Toroidal Board
The game board wraps — moving off the right edge appears on the left. This affects:
- Cell neighbors (e.g.,
Cell(0, 0).get_left()wraps to the rightmost column) - Distance calculations (shortest path may cross edges)
- Collision detection
Relative Coordinates
Submissions receive positions relative to their head, which is always Cell(0, 0):
self.occupiedcontains obstacles offset from the headself.foodcontains food positions offset from the headself.body[0]is alwaysCell(0, 0)(the head)
This simplifies AI logic — you don't need to know absolute board position.
Vision Range
Sneks can only see obstacles within Config().snek.vision_range cells. Food is always visible regardless of distance.
Recording
Install the recording dependency:
pip install -e ".[record]"
Enable recording in your config:
from sneks.engine.config.graphics import GraphicsConfig
MyGameConfig(
graphics=GraphicsConfig(
record=True,
record_prefix="./output", # Output directory
record_fps=12, # Video framerate
)
)
Frames are saved to output/pics/ during gameplay. Call recorder.animate_game() after the run to encode to MP4 in output/movies/. The encoder uses ffmpeg via imageio_ffmpeg.
Metadata
Release files for sneks-engine 1.0.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sneks_engine-1.0.6.tar.gz | 28.0 kB | Without provenance | Details for sneks_engine-1.0.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sneks_engine-1.0.6-py3-none-any.whl | Python 3 | none | any | Details for sneks_engine-1.0.6-py3-none-any.whl |
Total release size: 68.5 kB
Release files / sneks_engine-1.0.6.tar.gz
| Download URL | sneks_engine-1.0.6.tar.gz |
|---|---|
| Size | 28.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1ce71517e8e62c3873dfff9fb13bcc21b09b841640c8328ca91c90e71771aa89
|
|
BLAKE2b-256 checksum How to use checksums |
e74cbb31af9d9b064679e2133fcbc75d5cc4f2cc1524a904d3a0740a7be9e8b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Hatch/1.16.5 cpython/3.14.3 HTTPX/0.28.1
|
Release files / sneks_engine-1.0.6-py3-none-any.whl
| Download URL | sneks_engine-1.0.6-py3-none-any.whl |
|---|---|
| Size | 40.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
15016d0aa8a14cdeae784a99e3098307a6f3c9abd96cc337207d7ddc2bd7ca6c
|
|
BLAKE2b-256 checksum How to use checksums |
55b79553f0ed4bcf9057e458d765aa2cf23207f72fedbe7ca5111851ecc37b41
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Hatch/1.16.5 cpython/3.14.3 HTTPX/0.28.1
|
Security for sneks-engine 1.0.6
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.