Zelda-Style Adventure Game

A complete action-adventure game inspired by classic Zelda titles (NES, SNES, Gameboy), built with Python and Pygame. Features programmatically-generated pixel art, enemy AI, combat system, and full game loop.

🎮 Features

Graphics & Visual Design

• 32×32 Pixel Art: All sprites and tiles generated programmatically in classic retro style
• NES/SNES Color Palette: Authentic colors inspired by classic Nintendo games
• Smooth Animations: Walk cycles, sword swings, and enemy animations
• Clean UI: Heart-based health display and enemy counter

Gameplay Mechanics

• Player Movement: Smooth WASD controls with pixel-based movement (4 pixels/frame at 60 FPS)
• Combat System:
  • Left-click sword attacks that swing in your facing direction (last moved direction)
  • Direction-based sword positioning (up, down, left, right)
  • Hit detection with damage calculation
  • Invulnerability frames (500ms) after taking damage
• Enemy AI:
  • Slimes: Wander randomly, bounce off walls, 1 hit to defeat
  • Skeletons: Chase player within 5-tile range, 3 hits to defeat, faster movement
• Health System: 6 hearts (12 half-hearts) with visual heart display
• Collision Detection: Tile-based world collision for walls and water

Game States

• Title Screen: Start game with instructions
• Gameplay: Full action-adventure experience
• Victory Screen: Defeat all enemies to win
• Game Over Screen: Lose all health and restart

📦 Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Setup Steps

1. Clone or navigate to the project directory:

cd claude-code-game

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

Dependencies include:

• pygame>=2.5.0 - Game framework
• Pillow>=10.0.0 - Image generation
• numpy>=1.24.0 - Array operations
• pytest>=7.4.0 - Testing (optional)

4. Generate game assets:

python assets/generator.py

This creates all sprite and tile images programmatically.

🚀 Running the Game

python main.py

The game window will open at 1024×768 pixels. Use the controls below to play!

🎯 Controls

Input	Action
W	Move up
A	Move left
S	Move down
D	Move right
Left Mouse Click	Swing sword in facing direction
SPACE	Start game / Restart after game over
ESC	Return to title screen / Exit to menu

🎲 Gameplay Guide

Objective

Defeat all 4 enemies (2 slimes + 2 skeletons) to achieve victory!

Combat

• Click to swing your sword in the direction you're facing (last moved with WASD)
• Move up (W) then click = sword swings upward
• Move left (A) then click = sword swings left
• Sword has a brief cooldown between swings (250ms)
• Enemies take damage when hit by your sword
• You take damage when enemies touch you (contact damage)

Health & Survival

• Start with 6 hearts (12 half-hearts)
• Each hit from an enemy deals 1 heart (2 half-hearts) of damage
• After taking damage, you're invulnerable for 0.5 seconds (flashing effect)
• Lose all hearts = Game Over

Enemy Behaviors

• Green Slimes: Wander randomly, easy to avoid, 1 hit to kill
• Gray Skeletons: Chase you when nearby, faster, 3 hits to kill

World Navigation

• Grass tiles are walkable
• Stone tiles are walkable (decorative)
• Walls (dark tiles) block movement
• Water blocks movement

📁 Project Structure

.
├── assets
│   ├── generator.py           # Programmatic pixel art generation
│   ├── __init__.py
│   ├── sprites                # Generated character sprites (14 files)
│   │   ├── player_down.png
│   │   ├── player_down_walk1.png
│   │   ├── player_down_walk2.png
│   │   ├── player_left.png
│   │   ├── player_right.png
│   │   ├── player_up.png
│   │   ├── skeleton1.png
│   │   ├── skeleton2.png
│   │   ├── slime1.png
│   │   ├── slime2.png
│   │   ├── sword_down.png
│   │   ├── sword_left.png
│   │   ├── sword_right.png
│   │   └── sword_up.png
│   └── tiles                  # Generated terrain tiles (4 files)
│       ├── grass.png
│       ├── stone.png
│       ├── wall.png
│       └── water.png
├── game                       # Core game modules
│   ├── combat.py              # Hit detection and damage system
│   ├── constants.py           # Colors, sizes, speeds, game settings
│   ├── enemy.py               # Enemy sprites and AI (Slime, Skeleton)
│   ├── engine.py              # Main game loop and state management
│   ├── __init__.py
│   ├── player.py              # Player sprite with WASD and sword
│   ├── sprites.py             # Base animated sprite classes
│   └── world.py               # Tile-based world and collision
├── tests                      # Unit tests (framework ready)
│   └── __init__.py
├── main.py                    # Game entry point
├── README.md                  # This file
├── requirements.txt           # Python dependencies
└── .gitignore                 # Git ignore patterns

6 directories, 32 files

🔧 Technical Details

Display & Graphics

• Window Size: 1024×768 pixels (2× scaling for modern displays)
• Game Surface: 512×384 pixels (native resolution)
• Tile Size: 32×32 pixels
• Sprite Size: 32×32 pixels
• World Dimensions: 16×12 tiles (512×384 pixels)
• Frame Rate: 60 FPS (locked)

Movement & Physics

• Player Speed: 4 pixels/frame (240 pixels/second)
• Slime Speed: 2 pixels/frame (120 pixels/second)
• Skeleton Speed: 3 pixels/frame (180 pixels/second)
• Movement Type: Pixel-based (smooth) with tile-based collision detection

Combat Parameters

• Player Health: 12 half-hearts (6 full hearts)
• Sword Damage: 2 half-hearts (1 full heart)
• Enemy Damage: 2 half-hearts (1 full heart)
• Slime Health: 2 half-hearts (1 hit to kill)
• Skeleton Health: 6 half-hearts (3 hits to kill)
• Invulnerability Duration: 500 milliseconds
• Sword Swing Duration: 250 milliseconds
• Skeleton Chase Range: 160 pixels (5 tiles)

Animation Details

• Walk Cycle: 4 frames at 8-10 ticks per frame (0.4-0.5s cycle)
• Sword Swing: 3 frames at 5 ticks per frame (0.25s total)
• Enemy Idle: 2 frames at 15 ticks per frame (0.5s cycle)

Code Architecture

• Object-Oriented Design: Sprite-based architecture using Pygame's sprite system
• State Machine: Game states (title, playing, game over, victory)
• Component-Based: Separate modules for combat, AI, world, and player
• Event-Driven: Pygame event loop with input handling

🎨 Asset Generation

All pixel art is generated programmatically using Python and Pillow (PIL). The assets/generator.py script creates 32×32 pixel sprites by scaling up 16×16 pixel art definitions:

Player Sprites

• 4 directional idle poses (up, down, left, right)
• Walking animations with leg movement
• Color palette: green tunic, yellow hair, peach skin

Enemy Sprites

• Slime: Animated blob with eyes (2 frames)
• Skeleton: Humanoid with bones (2 frames)
• Multiple color variants possible

Sword Sprites

• 4 directional sword images (up, down, left, right)
• Silver blade with brown handle

Terrain Tiles

• Grass: Light green with darker blade patterns
• Stone: Gray floor tiles
• Wall: Dark brick pattern
• Water: Blue with wave patterns

Customization

Edit game/constants.py to modify colors, speeds, damage values, and other parameters.

🧪 Testing

The project includes a testing framework (pytest). Run tests with:

source venv/bin/activate
pytest tests/

🚧 Future Enhancement Ideas

• Multiple rooms with screen transitions (classic Zelda room-to-room)
• Item pickups (hearts, keys, power-ups)
• Boss enemies with attack patterns
• Inventory system
• Save/load game state
• Sound effects and background music
• More enemy types and behaviors
• Procedural dungeon generation
• Particle effects for hits and deaths
• Controller/gamepad support

📝 Development Notes

Architecture Decisions

• Pixel + Tile Hybrid: Player moves smoothly in pixels but world collision uses tiles
• Sprite Groups: Pygame's built-in sprite groups for efficient rendering and collision
• Component Separation: Combat, AI, and world systems are separate modules
• Programmatic Art: No external art tools needed, all assets generated via code

Performance

• Runs smoothly at 60 FPS on modern hardware
• Minimal memory footprint (~50MB including Python runtime)
• All sprites loaded once at startup
• Efficient collision detection using tile grid

🤖 Credits & Attribution

Built by: Claude (Anthropic's AI assistant)

• Model: Claude Sonnet 4.5
• Built via: Claude Code CLI
• Date: January 2026

Developed for: Jonathan

Inspired by: The Legend of Zelda series by Nintendo

• Original Zelda (NES, 1986)
• A Link to the Past (SNES, 1991)
• Link's Awakening (Game Boy, 1993)

Technologies Used:

• Python 3.13
• Pygame 2.6.1
• Pillow 12.1.0
• NumPy 2.4.1

License: This is a personal project. The Zelda franchise and all related trademarks are property of Nintendo.

---

Development Process: This entire game was created through an interactive AI-assisted development session. The AI (Claude) designed the architecture, wrote all the code, generated all the pixel art programmatically, and created a complete, playable game from scratch. All code is original and generated specifically for this project.

🐛 Troubleshooting

Game won't start

• Ensure virtual environment is activated: source venv/bin/activate
• Verify assets exist: ls assets/sprites/ should show PNG files
• Regenerate assets if needed: python assets/generator.py

Display issues

• Game requires a graphical display (X11/Wayland on Linux, GUI on Windows/Mac)
• For headless servers, you'll need virtual framebuffer (xvfb)

Performance issues

• Game is optimized for 60 FPS on modern hardware
• Lower-end systems can modify FPS in game/constants.py

📞 Support

This is a demonstration project. For issues or questions about the code:

1. Check the inline code comments
2. Review the architecture in this README
3. Examine game/constants.py for tunable parameters

Enjoy the game! 🎮⚔️