{"id":28549129,"url":"https://github.com/decker-dev/wizard-game-react","last_synced_at":"2026-04-29T22:41:01.650Z","repository":{"id":296712144,"uuid":"994228686","full_name":"decker-dev/wizard-game-react","owner":"decker-dev","description":"2D pixel art wizard survival shooter built with Next.js. Survive infinite waves, upgrade weapons, and compete on global leaderboards.","archived":false,"fork":false,"pushed_at":"2025-12-14T14:35:08.000Z","size":12913,"stargazers_count":6,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-16T21:35:52.379Z","etag":null,"topics":["arcade-game","browser-game","canvas","game-development","html5","nextjs","pixel-art","shooter","supabase","survival","typescript","vercel","waves","zombie-game","zombies"],"latest_commit_sha":null,"homepage":"https://mystic.lat","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/decker-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-01T13:54:54.000Z","updated_at":"2025-12-14T14:35:12.000Z","dependencies_parsed_at":"2025-06-01T23:19:36.916Z","dependency_job_id":"76b85506-7bdd-46a0-985f-cb8bd46ae041","html_url":"https://github.com/decker-dev/wizard-game-react","commit_stats":null,"previous_names":["decker-dev/zombie-game-react","decker-dev/wizard-game-react"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/decker-dev/wizard-game-react","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decker-dev%2Fwizard-game-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decker-dev%2Fwizard-game-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decker-dev%2Fwizard-game-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decker-dev%2Fwizard-game-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/decker-dev","download_url":"https://codeload.github.com/decker-dev/wizard-game-react/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decker-dev%2Fwizard-game-react/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32447299,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"ssl_error","status_checked_at":"2026-04-29T22:10:49.234Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arcade-game","browser-game","canvas","game-development","html5","nextjs","pixel-art","shooter","supabase","survival","typescript","vercel","waves","zombie-game","zombies"],"created_at":"2025-06-10T02:00:20.237Z","updated_at":"2026-04-29T22:41:01.631Z","avatar_url":"https://github.com/decker-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔮 MYSTIC REALM DEFENDER\n### *A 2D magical survival game with infinite waves of mythological creatures*\n\n[![Deployed on Vercel](https://img.shields.io/badge/Deployed%20on-Vercel-black?style=for-the-badge\u0026logo=vercel)](https://mystic.decker.sh)\n[![Built with Next.js](https://img.shields.io/badge/Built%20with-Next.js%2015-black?style=for-the-badge\u0026logo=next.js)](https://nextjs.org/)\n[![Powered by Supabase](https://img.shields.io/badge/Powered%20by-Supabase-green?style=for-the-badge\u0026logo=supabase)](https://supabase.com/)\n[![Built with TypeScript](https://img.shields.io/badge/Built%20with-TypeScript-blue?style=for-the-badge\u0026logo=typescript)](https://www.typescriptlang.org/)\n\n---\n\n## 🎮 **About the Game**\n\n**Mystic Realm Defender** is a 2D magical survival game developed during the **first Vibe Gaming Hackathon in LATAM** as part of Buenos Aires Tech Week. Control a powerful wizard and defend the mystical realm by surviving infinite waves of mythological creatures using powerful spells and magical abilities.\n\n### 🏆 **Developed by:**\n- **[Lauti](https://x.com/lautidev_)** - Vibe Developer\n- **[Alejo](https://x.com/alejorrojass)** - Vibe Developer\n- **[Decker](https://x.com/0xDecker)** - Vibe Developer\n\n---\n\n## ✨ **Game Features**\n\n### 🎯 **Core Gameplay**\n- **Infinite wave system** with exponential difficulty scaling every 10 waves\n- **6 distinct creature types** including normal, caster, tank, speed, explosive, and boss enemies\n- **Advanced AI pathfinding** with A* algorithm and collision avoidance\n- **Progressive spell upgrade system** with 6 levels (0-5) of magical power\n- **Health pack system** for survival strategy\n- **Mobile-responsive** with virtual controls for touch devices\n\n### 🪄 **Magic System**\n- **Spell Levels (0-5)**: Each level enhances casting abilities\n  - **Level 0**: Single projectile (250ms cooldown)\n  - **Level 1**: Faster casting (200ms cooldown)\n  - **Level 2**: Double projectile spread (180ms cooldown)\n  - **Level 3**: Larger projectiles (160ms cooldown, 150% size)\n  - **Level 4**: Triple projectile barrage (150ms cooldown)\n  - **Level 5**: Quadruple spell storm (120ms cooldown, 200% size)\n\n### 👹 **Enemy Variety**\n- **Normal Creatures**: Basic pursuers (30 HP base, 3 crystals reward)\n- **Caster Creatures**: Ranged spell attackers (50 HP base, 7 crystals reward)\n- **Tank Creatures**: High HP, slow movement (120 HP base, 10 crystals reward)\n- **Speed Creatures**: Fast but fragile (15 HP base, 5 crystals reward)\n- **Explosive Creatures**: Explode on death (25 HP base, 8 crystals reward)\n- **Boss Creatures**: Massive enemies every 5 waves (300 HP base, 50 crystals reward)\n\n### 🏅 **Leaderboard System**\n- **Top 3** highest scores from the greatest wizards\n- **Complete history** of magical battles\n- **Global statistics** with total realms defended\n- **Real-time persistence** with Supabase magic\n\n---\n\n## 🎮 **How to Play**\n\n### 🕹️ **Controls**\n```\nDesktop:\nWASD / Arrow Keys  →  Wizard movement\nSpacebar          →  Cast spells in movement direction\nESC               →  Exit fullscreen\nF                 →  Toggle fullscreen\n\nMobile:\nVirtual Joystick   →  Movement\nFire Button        →  Cast spells in movement direction\n```\n\n### 🎯 **Objectives**\n1. **Survive infinite waves** of increasingly difficult mythological creatures\n2. **Collect crystals** from defeated enemies to purchase upgrades\n3. **Use the Arcane Shop** between waves to enhance spells and health\n4. **Compete globally** for the highest score on the leaderboard\n5. **Master the spell system** to achieve maximum magical power\n\n---\n\n## 🚀 **Technologies Used**\n\n### **Frontend \u0026 Game Engine**\n- **Next.js 15** - React framework with App Router architecture\n- **TypeScript** - Full type safety across the entire codebase\n- **HTML5 Canvas** - Custom 2D game engine with 60 FPS rendering\n- **React 19** - Latest React with concurrent features\n- **Tailwind CSS** - Utility-first styling with custom magical theme\n\n### **Backend \u0026 Database**\n- **Supabase** - PostgreSQL database with real-time subscriptions\n- **Row Level Security (RLS)** - Secure data access controls\n- **Edge Functions** - Serverless API endpoints for game logic\n\n### **Development \u0026 Build Tools**\n- **Bun** - Ultra-fast JavaScript runtime and package manager\n- **Biome** - Fast linter and formatter (ESLint + Prettier alternative)\n- **PostCSS** - CSS processing with plugins\n- **Vercel Analytics** - Performance and usage tracking\n\n### **Game Assets \u0026 Graphics**\n- **Pixel art sprites** - Custom wizard, creature, and effect assets\n- **Press Start 2P font** - Retro gaming typography\n- **Custom particle systems** - Crystal collection and floating effects\n\n---\n\n## 📦 **Installation and Development**\n\n### **Prerequisites**\n- **Bun** (recommended) or **Node.js 18+**\n- **Git**\n- **Supabase** account for database functionality\n\n### **Local Development Setup**\n\n1. **Clone the repository**\n```bash\ngit clone https://github.com/decker-dev/wizard-game-react\ncd wizard-game-react\n```\n\n2. **Install dependencies**\n```bash\n# With Bun (recommended for speed)\nbun install\n\n# Or with npm\nnpm install\n```\n\n3. **Environment configuration**\n```bash\n# Create .env.local file\nNEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url\nNEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key\n```\n\n4. **Database setup**\n```sql\n-- Execute in Supabase SQL Editor:\n-- sql/create_tables.sql contains all necessary table schemas\n```\n\n5. **Start development server**\n```bash\nbun dev\n# Runs on http://localhost:3001\n```\n\n---\n\n## 🗄️ **Database Architecture**\n\n### **Leaderboard Table**\n```sql\nCREATE TABLE leaderboard (\n    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n    player_name VARCHAR(50) NOT NULL,\n    score INTEGER DEFAULT 0,\n    waves_survived INTEGER DEFAULT 0,\n    created_at TIMESTAMPTZ DEFAULT NOW()\n);\n```\n\n### **Game Statistics Table**\n```sql\nCREATE TABLE game_stats (\n    id SERIAL PRIMARY KEY,\n    stat_type VARCHAR(50) NOT NULL UNIQUE,\n    total_games_played INTEGER DEFAULT 0,\n    created_at TIMESTAMPTZ DEFAULT NOW(),\n    updated_at TIMESTAMPTZ DEFAULT NOW()\n);\n```\n\n---\n\n## 🎨 **Project Architecture**\n\n```\n📦 mystic-realm-defender/\n├── 📁 app/                    # Next.js App Router\n│   ├── 📁 game/              # Game page route (/game)\n│   ├── 📁 credits/           # Credits page (/credits)\n│   ├── 📁 settings/          # Settings page (/settings)\n│   ├── 📁 api/               # API routes\n│   │   └── validate-score/   # Score validation endpoint\n│   ├── layout.tsx            # Root layout with fonts and analytics\n│   ├── page.tsx              # Home page component\n│   ├── globals.css           # Global styles and Tailwind base\n│   ├── manifest.ts           # PWA manifest configuration\n│   └── sitemap.ts            # SEO sitemap generation\n├── 📁 components/            # React UI Components\n│   ├── GameScreen.tsx        # Main game orchestration component\n│   ├── GameCanvas.tsx        # Canvas rendering and game loop\n│   ├── GameUI.tsx            # In-game interface (health, score, wave)\n│   ├── Marketplace.tsx       # Upgrade shop between waves\n│   ├── Leaderboard.tsx       # Score rankings display\n│   ├── MobileControls.tsx    # Touch controls for mobile devices\n│   ├── GameOverlay.tsx       # Game state overlays (pause, game over)\n│   ├── ScoreSubmissionModal.tsx # Score submission and sharing\n│   ├── HomeScreen.tsx        # Main menu and navigation\n│   ├── LoadingScreen.tsx     # Asset loading screen\n│   ├── ShareModal.tsx        # Social sharing functionality\n│   ├── CoinParticles.tsx     # Crystal collection effects\n│   ├── FloatingParticles.tsx # Background ambient effects\n│   └── CoinIcon.tsx          # Crystal currency icon\n├── 📁 hooks/                 # Custom React Hooks\n│   ├── useGameController.ts  # Main game state orchestration\n│   ├── useGameState.ts       # Game entity state management\n│   ├── useAssetLoader.ts     # Sprite and texture loading\n│   ├── useInputHandlers.ts   # Keyboard and mouse input\n│   ├── useGameAudio.ts       # Sound effects and music system\n│   ├── useLeaderboard.ts     # Score persistence and retrieval\n│   └── useGameScreens.ts     # Screen state management\n├── 📁 game/                  # Core Game Logic\n│   ├── Player.ts             # Wizard character controller\n│   ├── Creatures.ts          # Enemy AI and behavior systems\n│   ├── Projectiles.ts        # Spell and magic bolt physics\n│   ├── Collisions.ts         # AABB collision detection\n│   └── Renderer.ts           # Canvas rendering engine\n├── 📁 utils/                 # Utility Functions\n│   ├── math.ts               # Vector mathematics and physics\n│   ├── marketplace.ts        # Upgrade cost calculations\n│   └── coinParticles.ts      # Particle effect systems\n├── 📁 types/                 # TypeScript Definitions\n│   └── game.ts               # Game entity interfaces and types\n├── 📁 constants/             # Game Configuration\n│   └── game.ts               # Balancing constants and settings\n├── 📁 data/                  # Static Game Data\n│   ├── obstacles.ts          # Map obstacle definitions\n│   └── mapLayouts/           # Level layout configurations\n├── 📁 lib/                   # External Integrations\n│   ├── supabase.ts           # Database client configuration\n│   └── metadata.ts           # SEO and PWA metadata\n├── 📁 public/                # Static Assets\n│   ├── 📁 wizard/            # Player character sprite sheets\n│   ├── 📁 creature/          # Normal enemy sprites\n│   ├── 📁 mage/              # Caster enemy sprites\n│   ├── 📁 health/            # Health pack sprites\n│   ├── 📁 explosive/         # Explosive creature sprites (WIP)\n│   ├── floor-texture.png     # Game background texture\n│   ├── og.png                # Social media preview image\n│   └── favicon.ico           # Site favicon\n├── 📁 sql/                   # Database Scripts\n│   └── create_tables.sql     # Supabase table schemas\n└── 📁 styles/                # Additional Stylesheets\n```\n\n---\n\n## 🚀 **Available Scripts**\n\n```bash\n# Development\nbun dev              # Start development server on port 3001\nbun build            # Build optimized production bundle\nbun start            # Start production server\n\n# Code Quality\nbun lint             # Run Next.js linting\n```\n\n---\n\n## 🌟 **Technical Highlights**\n\n### **🎮 Custom Game Engine**\n- **60 FPS rendering** with requestAnimationFrame optimization\n- **Object pooling** for projectiles to prevent memory leaks\n- **Spatial partitioning** for efficient collision detection\n- **Sprite animation system** with directional character movement\n- **Camera system** with smooth player following and map boundaries\n\n### **🧠 Advanced AI Systems**\n- **A* pathfinding** for intelligent navigation around obstacles\n- **Steering behaviors** including seek, flee, separation, and obstacle avoidance\n- **Line of sight** optimization for performance\n- **Behavioral patterns** unique to each creature type\n\n### **📱 Mobile-First Design**\n- **Responsive detection** with automatic mobile optimization\n- **Virtual controls** with customizable joystick and fire button\n- **Touch gesture** support for smooth mobile gameplay\n- **Fullscreen API** integration for immersive experience\n\n### **⚡ Performance Optimizations**\n- **Efficient rendering** with dirty rectangle updates\n- **Memory management** with proper cleanup cycles\n- **Asset preloading** for smooth gameplay experience\n- **Debounced input handling** for responsive controls\n\n---\n\n## 🏆 **Game Jam Achievement**\n\nThis project was developed during the **Vibe Gaming Hackathon LATAM**, part of Buenos Aires Tech Week 2024.\n\n### **🎯 Hackathon Accomplishments:**\n- ✅ **Complete game** with full gameplay loop\n- ✅ **6 enemy types** with unique behaviors and AI\n- ✅ **Progressive difficulty** system with infinite scaling\n- ✅ **Real-time leaderboard** with global competition\n- ✅ **Mobile compatibility** with touch controls\n- ✅ **Polish and effects** including particle systems\n- ✅ **Deployment** on production infrastructure\n\n---\n\n## 🤝 **Contributing**\n\nWe welcome contributions to enhance the mystical realm! Here's how to get involved:\n\n### **Development Workflow**\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/enhanced-spells`)\n3. **Implement** your changes with TypeScript\n4. **Test** thoroughly on both desktop and mobile\n5. **Add patch notes** for your changes (see Patch Notes Requirements below)\n6. **Submit** a pull request with detailed description\n\n### **📝 Patch Notes Requirements**\n**All pull requests MUST include patch notes** describing what was added, modified, or improved:\n\n1. **Update** `/data/patchNotes.ts` with your changes\n2. **Follow the existing format** with proper categorization:\n   - `NEW` ✨ - New features or content\n   - `IMPROVED` ⚡ - Enhancements to existing features\n   - `FIXED` 🔧 - Bug fixes and corrections\n   - `BALANCED` ⚖️ - Game balance adjustments\n3. **Include version number** following semantic versioning (e.g., v1.2.3)\n4. **Write clear descriptions** of what changed and why\n5. **Add your changes** to the top of the patch notes array\n\n**Example patch note entry:**\n```typescript\n{\n  version: \"v1.3.0\",\n  title: \"Enhanced Spell System\",\n  date: \"2025-06-XX\",\n  description: \"Major improvements to spell casting mechanics\",\n  changes: [\n    {\n      category: \"NEW\",\n      items: [\n        \"Added spell combo system for advanced players\",\n        \"New visual effects for level 5 spells\"\n      ]\n    },\n    {\n      category: \"IMPROVED\", \n      items: [\n        \"Spell casting now feels more responsive\",\n        \"Better projectile collision detection\"\n      ]\n    }\n  ]\n}\n```\n\n### **Contribution Areas**\n- 🎨 **New sprites** for explosive and speed creatures\n- 🎵 **Audio system** enhancements and sound effects\n- 🎮 **New creature types** with unique behaviors\n- 📊 **Game balance** improvements and testing\n- 🌐 **Accessibility** features and improvements\n\n---\n\n## 📄 **License**\n\nThis project is licensed under the **GNU General Public License v3.0** (GPL-3.0).\n\n**Mystic Realm Defender** - A 2D magical survival game with infinite waves of mythological creatures  \nCopyright (C) 2025 Lauti, Alejo, and Decker (Vibe Gaming Hackathon Team)\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program. If not, see [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).\n\nFor more details, see the [LICENSE](./LICENSE) file.\n\n---\n\n## 🔗 **Links \u0026 Resources**\n\n- **🎮 Play the Game**: [mystic.decker.sh](https://mystic.decker.sh)\n- **🏆 Hackathon Event**: [Paisanos.io Vibe Gaming](https://lu.ma/xqvznvg4?locale=es)\n- **🐦 Developers**: \n  - [Lauti (@lautidev_)](https://x.com/lautidev_)\n  - [Alejo (@alejorrojass)](https://x.com/alejorrojass)\n  - [Decker (@0xDecker)](https://x.com/0xDecker)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with 🔮 magical code and ❤️ during Buenos Aires Tech Week**\n\n*\"Defend the mystical realm with the power of TypeScript and creativity\"*\n\n![Game Preview](https://mystic.decker.sh/og.png)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecker-dev%2Fwizard-game-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdecker-dev%2Fwizard-game-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecker-dev%2Fwizard-game-react/lists"}