eliaspc2/z_survival
Este projeto é um jogo 2D top-down de sobrevivência, construído em Python com Pygame, onde o jogador enfrenta ondas crescentes de zombies, inimigos especiais e bosses. O código foi reorganizado de forma modular para garantir desempenho, clareza e facilidade de manutenção.
Z Survival
Z Survival is an open-source 2D Top-Down Survival Shooter built with Python and Pygame.
📖 About
Survive endless waves of mutating zombies in this arcade-style game. Features infinite difficulty scaling, boss encounters, and a robust save system.
Version: v2.2 (Maintenance & Autoplay Update)
Status: Stable Release
🏗️ Project Structure
Note
For LLMs & Contributors:
- Documentation: All technical docs are in
docs/. - Methodology: Follow
docs/methodology.md(MGID) strictly. - Maintenance: Check
docs/maintenance.mdfor mandatory tasks. - Traceability: Log all technical changes in
docs/dev_changelog.md.
z_survival/
├── docs/ # 📚 Technical Documentation
├── img/ # 🎨 Game Assets (organized by type)
│ ├── enemies/ # Zombie/Boss sprites
│ ├── player/ # Hero sprites
│ ├── projectiles/ # Bullets, rocks, orbs
│ ├── ui/ # Icons, backgrounds, splash screens
│ └── items/ # Powerup icons
├── snd/ # 🔊 Sound Effects
├── src/
│ ├── core/ # 🧠 Game Engine (Controller, Logic, Settings)
│ ├── entities/ # 🎮 Game Objects (Player, Zombies, Bosses)
│ ├── managers/ # ⚙️ Systems (Spawn, Collision, Data, Assets)
│ ├── ui/ # 🖥️ User Interface (Menus, HUD)
│ └── utils/ # 🔧 Utilities (Paths, Timer)
├── tools/ # 🛠️ Development Scripts
├── .venv/ # 🐍 Virtual Environment
├── requirements.txt # 📦 Dependencies
├── run_game.bat # 🚀 Smart Launcher
└── main.py # Entry Point
🚀 Quick Start
Option 1: Auto-Launch (Recommended)
Double-click run_game.bat. It automatically:
- Creates a virtual environment
- Installs dependencies
- Launches the game
Option 2: Manual Installation
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python main.pyRequirements
- Windows 10/11
- Python 3.10+
⚙️ Configuration (src/settings/)
Debug Flags
| Flag | Description |
|---|---|
ALLOW_DEBUG |
Master switch. If False, all debug flags are ignored. |
GOD_MODE |
Invincibility. Player cannot die, score not counted. |
DEBUG_AUTOPLAY_MODE |
Enable QA Automation Bot. |
DEBUG_OVERLAY |
Logs entity creation/destruction to console. |
DEBUG_INPUT_LOG |
Logs all key presses to console. |
Other Flags
| Flag | Description |
|---|---|
ENABLE_AUDIO |
Set to False to mute all audio. |
INVERT_MOUSE_BUTTONS |
Swap Left/Right mouse buttons. |
🎮 Game Modes
Classic Mode
- 10 Levels with fixed difficulty progression
- Boss at Level 5 (Goliath) and Level 10 (Hive)
- Victory on defeating The Hive
Progressive Mode (Infinite)
- Difficulty scales continuously over time
- Bosses spawn periodically (every 5/10 levels)
- No end condition — survive as long as possible
💾 Save System (v3)
- Exact State Restoration: All entities saved with position, velocity, and lifetime.
- Auto-Migration: Legacy saves automatically upgraded.
Save file: save_data.json
🔧 Troubleshooting
| Issue | Solution |
|---|---|
| Audio Lag | Update audio drivers or set ENABLE_AUDIO = False |
| Visual Glitches | Update graphics drivers |
| Crash on Startup | Delete save_data.json if corrupted |
| Missing Sprites | Enable DEBUG_ASSET_LOADING = True to see what's failing |
📚 Documentation
See docs/ for detailed technical documentation:
- Architecture: System design and logic flows.
- Entities Manual: Stats and behaviors of all game objects.
- Systems Manual: Technical breakdown of Input, Render, Collision, and Spawn systems.
- Gameplay Rules: Detailed mechanics and scaling formulas.
- Changelog: Version history.
🔮 Roadmap
- Asset Organization
- Debug Flag System
- Save/Load System v3
- Autoplay QA Automation
Note: For detailed technical specs, refer to
docs/.