| v0.1.0-beta | v0.9.0-rc1 (current) |
|---|---|
 |
 |
A classic reborn — bilingual UI, an adaptive bot rival, and real online multiplayer, all in pure Python + Pygame.
Features • Installation • Controls • Multiplayer • Roadmap
- Smooth, frame-interpolated snake movement
- Wrap-around edges — no walls; cross one edge and reappear on the opposite side with a seamless transition (solid obstacles may come later)
- Self-collision detection and an in-window score HUD
- Pause (
P/Esc), with a confirmation before quitting a game in progress - Particle bursts and a death flash for extra game feel
- Three food types, on a predictable rhythm instead of random luck:
Type Points Effect Spawns 🔴 Normal apple 1 — default 🟡 Speed apple 2 brief speed boost every 7 points 🟣 Bonus apple 4 — every 15 points - Accessibility-friendly markers — the speed apple carries a
+glyph, and both special foods are visibly larger, so every type reads without relying on color vision
A race, not a survival contest — a rival snake competes with you for food on the same board and sharpens as your score climbs (beatable early, near-perfect past ~70 points). First to 50 points wins on the spot; a collision from either snake ends the match immediately in favor of whoever's ahead. The game over screen declares "You Win!" or "Bot Wins".
Browse and join open rooms — or create your own — and play last-snake-standing against people on other machines, with every screen showing all participants' names (yours highlighted) at the same visual quality as offline. Full details in 🕹️ Online multiplayer below.
- High Score leaderboards — separate top-10 rankings for Solo and VS Snake Bot (menu → High Scores, switch with
◂/▸); you always see the Game Over result first, and only then, if it qualifies, get prompted to save your name - Bilingual UI — English and Portuguese, switchable anytime from the menu, saved across restarts
- Redesigned main menu — grouped sections in a card panel with a clear pill-style selection highlight
- Procedurally synthesized sound — no audio files, tones generated in code, with a 3-level volume control (Off / 50% / 100%)
 Main menu |
 VS Snake Bot |
 Online multiplayer lobby |
 High score leaderboard |
- Python 3.8+
- Pip package manager
git clone https://github.com/mariomthree/snake-game.git
cd snake-game
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements/base.txt
python3 snake.py| Key | Action |
|---|---|
| ← ↑ → ↓ | Move / navigate menus |
| Enter | Select menu option / restart after game over |
| P or Esc | Pause / resume during play |
| Esc | Back to main menu (from difficulty screen, pause confirmation, or game over) |
Solo and VS Snake Bot each keep their own top-10 leaderboard, persisted locally in leaderboard.json next to the script. Any run that scores above 0 and would place in that mode's top 10 shows the Game Over result first, then offers "Enter: Save Score" to record your name.
Language choice (English/Portuguese) and other menu preferences persist locally in settings.json.
Phase 1 rules: everyone moves at once on the same board; the board wraps at the edges (no wall death); hitting your own body or anyone else's eliminates you (you keep spectating live until the match ends); last snake standing wins. No timer or rounds yet — that's planned for a later phase.
Server limits: up to 4 players per room, up to 20 rooms open on the server at once, and a room that sits waiting in its lobby for more than 2 minutes without starting closes automatically.
▶ Hosting the server
One person needs to run the server — either directly with Python, or with Docker (no Python setup needed on the host machine at all):
# Option A: plain Python
pip install -r requirements/server.txt
python3 server.py # listens on ws://0.0.0.0:8765
# Option B: Docker (server only — it's headless, no display needed)
docker compose -f docker/docker-compose.yml up -d --build
# or: docker build -f docker/Dockerfile -t snake-server . && docker run -p 8765:8765 snake-serverThe game client (snake.py) opens a real window, so it isn't containerized — everyone who wants to play still just runs python3 snake.py locally (see Quick Start above).
Playing over the public internet requires hosting server.py somewhere reachable (e.g. Render, Fly.io, a VPS) — that's a separate deployment step, not something this repo does automatically. The docker/Dockerfile here makes that easier: most of those platforms can deploy directly from a Dockerfile/image instead of needing a Python buildpack.
▶ Joining a match
Run the game as usual (python3 snake.py) and pick Online Multiplayer from the main menu. That opens a live-updating room browser:
- + Create New Room at the top makes a fresh room and puts you in its lobby as host.
- Every other open room is listed below (
Room ABCD (2/4)) — select one and press Enter to join it. - The host presses Enter in the lobby once 2+ players have joined to start the match.
By default the client connects to ws://localhost:8765. To play with people on other machines, set the SNAKE_SERVER_URI environment variable on each client to point at wherever the server is reachable, e.g.:
SNAKE_SERVER_URI=ws://192.168.1.20:8765 python3 snake.py # same LAN
SNAKE_SERVER_URI=wss://your-hosted-server.example.com python3 snake.py # public internetpip install -r requirements/dev.txt
pytest tests/ -v▶ File-by-file map
constants.py grid geometry, colors, game states, food/leaderboard config, fonts
utils.py tiny shared helpers (draw_text, lerp, lerp_color)
entities.py Cube, Snake, AISnake, Food, Particle
sound.py procedural tone synthesis + SoundManager
network.py NetworkClient (WebSocket client for online play)
i18n.py English/Portuguese UI strings + translate()
snake.py leaderboard/settings persistence + the Game class (state machine, input, drawing) + entry point
server.py standalone authoritative WebSocket server for online multiplayer
tests/ pytest suite for the client and server
requirements/ base.txt (client), dev.txt (+ pytest), server.txt (server-only, no pygame)
docker/ Dockerfile + docker-compose.yml for the headless server image
- 🧱 Solid obstacles/walls in specific spots (the rest of the board keeps wrapping)
- 🎨 Custom game sprites
- 📱 Touch controls for mobile
This started as a weekend snake clone and grew into bot AI, real-time multiplayer, and a bilingual UI — mostly because people kept showing up with ideas and PRs. If something here is fun, useful, or made you smile, a ⭐ on the repo goes a long way and helps others find it too.
Got an idea, found a bug, or want to tackle something from the Roadmap? Contributions are very welcome:
- Fork the repository
- Create a feature branch
- Submit a pull request
No contribution is too small — docs, tests, and bug reports count just as much as new features.
MIT License - See LICENSE for details.
Mário M. Mabande
