Skip to main content

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. DynamicEntity moves and grows; StaticEntity maintains shape.
  • Snek: The AI interface that submissions implement. Receives game state and returns an Action.
  • Config: Singleton configuration system. Each game mode extends Config with custom settings.

Creating a New Game Mode

  1. 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
  1. 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 at Bearing(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.UP increments bearing.y by 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.occupied contains obstacles offset from the head
  • self.food contains food positions offset from the head
  • self.body[0] is always Cell(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)

Source distribution for sneks-engine 1.0.6
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)

Table of built distributions (wheels) for sneks-engine 1.0.6
File Interpreter ABI Platform Actions
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.

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