README.md

metadata

title: Retro Tetris
emoji: 🎮
colorFrom: blue
colorTo: purple
sdk: docker
app_file: index.html
pinned: false

🎮 Retro Tetris

A stunning retro-styled Tetris game with authentic CRT TV aesthetics, dynamic backdrops, and procedurally generated music. Built with Phaser 3 and modern web technologies.

✨ Features

🖥️ Authentic CRT TV Experience

• Realistic CRT Shader Effects
  • Barrel distortion/curvature for authentic tube TV look
  • 480i-style scanlines
  • Subtle static noise with 4x4 pixel grains
  • Dynamic flicker effect with multiple frequencies
  • Phosphor glow on bright areas
  • Edge vignetting
• Vintage TV Frame - Game displayed inside a beautiful retro TV bezel
• Pixel-Perfect Rendering - Crisp 8x8 pixel blocks with nearest-neighbor filtering

🎨 Dynamic Visual System

• 10 Unique Level Backdrops - Each level features a distinct hand-crafted backdrop
• Adaptive Color Palette - Block colors automatically extract and enhance from each level's backdrop for perfect visual harmony
• Sprite-Based Blocks - Detailed block rendering with depth and shading
• Smooth Animations - Crush animations, level transitions, and particle effects

🎵 Dynamic Music System

• 10 Unique Tracks - Each level has its own AI-generated music track created with Suno AI
• Thematic Soundscapes - Music complements each level's visual theme
• Retro Sound Effects - Authentic 8-bit style procedurally generated sound effects

🎯 Two Game Modes

1. Classic Mode - Traditional Tetris with 7 standard pieces (I, O, T, S, Z, J, L)
2. Advanced Mode - Extended gameplay with additional unique pieces for extra challenge

🏆 Advanced Gameplay Features

• Progressive Difficulty - 10 levels with increasing speed
• Combo System - Chain multiple line clears for bonus points
• Perfect Clear Bonus - Extra points for clearing the entire board
• T-Spin Detection - Bonus points for advanced T-piece maneuvers
• Hard Drop - Instant piece placement with space bar
• Ghost Piece - Preview where your piece will land
• Next Piece Preview - Plan your strategy ahead
• Pause Functionality - Press P to pause/resume

📊 Scoring System

• Single line: 100 points × level
• Double lines: 300 points × level
• Triple lines: 500 points × level
• Tetris (4 lines): 800 points × level
• T-Spin: 400 points × level
• Combo multiplier: +50 points per combo × level
• Perfect Clear: 2000 points × level

🎮 Controls

• Arrow Keys - Move and rotate pieces
  • ← → : Move left/right
  • ↓ : Soft drop (faster descent)
  • ↑ : Rotate piece
• Space Bar - Hard drop (instant placement)
• P - Pause/Resume game
• Mouse/Touch - Navigate menus

🚀 Getting Started

Prerequisites

• Node.js (v14 or higher)
• npm or yarn

Installation

1. Clone the repository:

git clone <repository-url>
cd tetris

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

4. Open your browser and navigate to http://localhost:5173

Building for Production

npm run build

The built files will be in the dist directory.

🛠️ Technical Details

Technologies Used

• Phaser 3 - Game framework
• Vite - Build tool and dev server
• WebGL - Hardware-accelerated rendering and custom shaders
• Canvas API - Backdrop generation and color extraction

Architecture

• Scene-Based Structure - Modular game scenes (Preload, Mode Select, Game)
• Custom Shaders - GLSL fragment shaders for CRT effects
• Color Extraction System - Automatic palette generation from backdrop images
• Sprite Rendering Pipeline - Dynamic block colorization and rendering
• Procedural Sound Effects - Real-time sound effect generation

Performance

• 60 FPS target frame rate
• Optimized WebGL rendering
• Efficient sprite batching
• Minimal memory footprint

🎨 Customization

Adding New Levels

1. Create a new backdrop image (256x224 pixels)
2. Place it in public/assets/backdrops/level-X/backdrop.png
3. Add corresponding music track in public/assets/music/level-X/track.mp3
4. Update MAX_LEVEL in src/constants.js

See BACKDROP-GUIDE.md for detailed instructions on creating backdrops.

Adjusting CRT Effects

Edit src/shaderOverlay.js to customize:

• Curvature intensity
• Scanline density
• Static grain size and intensity
• Flicker frequency and amplitude
• Vignette strength

📁 Project Structure

tetris/
├── public/
│   └── assets/
│       ├── backdrops/      # Level backdrop images
│       ├── fonts/          # Bitmap fonts
│       ├── music/          # Level music tracks
│       ├── blocks-sprite.png
│       ├── game-over.png
│       ├── title.png
│       └── tv.png
├── src/
│   ├── scenes/
│   │   ├── PreloadScene.js
│   │   ├── ModeSelectScene.js
│   │   └── GameScene.js
│   ├── utils/
│   │   ├── ColorExtractor.js
│   │   ├── SpriteBlockRenderer.js
│   │   └── SoundGenerator.js
│   ├── constants.js
│   ├── main.js
│   └── shaderOverlay.js
├── index.html
└── package.json

🎯 Game Mechanics

Piece Movement

• Pieces fall automatically based on level speed
• Wall kicks allow rotation near edges
• Floor kicks prevent unfair lockouts
• Smooth movement with keyboard repeat

Level Progression

• Levels 1-10 with exponentially increasing speed
• New backdrop and music for each level
• Visual transition effects between levels
• Speed ranges from 1000ms (Level 1) to 100ms (Level 10)

Line Clearing

• Standard Tetris line clear mechanics
• Animated crush effect for cleared lines
• Combo system rewards consecutive clears
• Perfect clear detection and bonus

🐛 Troubleshooting

See TROUBLESHOOTING.md for common issues and solutions.

📝 License

This project is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

You are free to:

• Share — copy and redistribute the material in any medium or format
• Adapt — remix, transform, and build upon the material for any purpose, even commercially

Under the following terms:

• Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made.

👨‍💻 Credits

Created by Marco van Hylckama Vlieg

• Website: ai-created.com
• Twitter/X: @AIandDesign

Tools & Technologies

• Code: Written with Augment Code (Claude 4.5 Sonnet / Opus)
• Music: AI-generated with Suno AI
• Graphics: Created on Freepik and post-processed in Adobe Photoshop
• Game Framework: Phaser 3

🙏 Acknowledgments

• Phaser 3 framework and community
• Suno AI for music generation capabilities
• Freepik for graphic design tools
• Augment Code for AI-assisted development
• Retro gaming aesthetics and CRT shader techniques
• Classic Tetris gameplay mechanics