README.md# 2D Game Base[](https://2d-game-base.gallop.software)A best-in-class TypeScript boilerplate for shipping high-quality 2D HTML5 games — built on PixiJS, Rapier physics, Howler audio, and tween.js — so you can build at the speed of thought with AI, ship a polished game, and rank #1 on Google.**⚡ Demo:** [2d-game-base.gallop.software](https://2d-game-base.gallop.software)**🎨 Template:** [gallop.software/templates](https://gallop.software/templates)**📦 Repository:** [github.com/gallop-software/2d-game-base-pro](https://github.com/gallop-software/2d-game-base-pro)**🏷️ Category:** 2D Game Boilerplate---## Why Use Gallop Templates?Just chat with AI inside your code editor using our Gallop templates, and you will never want to wrestle with a 3D engine, a heavyweight game framework, or a bloated visual editor again. Simply describe the game you want, and AI writes the code. No Unity, no GameMaker, no level editors, and no design limitations. Just type and watch. Build fun and crisp gameplay, add smooth physics-driven animations, configure your SEO and AI discoverability instantly, expand endlessly, and get prompting tips from our [Gallop community](https://gallop-software.slack.com/). Go live in minutes.[](https://gallop.software/#learn-more)---## Features- 🚀 **PixiJS 8** — industry-standard WebGL/WebGPU 2D renderer with native high-DPI support- ⚛️ **Rapier 2D** physics — Rust → WASM, deterministic, blazing fast- 🔊 **Howler.js** audio with Web Audio + HTML5 fallback- 🌀 **tween.js** for smooth animations- 🎯 **Responsive scene system** that adapts to any viewport, including live window resize- 🧩 **Modular architecture** — `core/`, `scenes/`, `systems/`, `objects/`, `ui/` separation- 📱 **PWA-ready** with service worker, manifest, and offline support- 🔍 **SEO and AI optimized** with meta tags, Open Graph, Twitter cards, and JSON-LD `VideoGame` schema- 🤖 **AI-friendly** codebase structure with TypeScript strict mode- ⚡ **Vite** for instant hot reload and lightning-fast production builds- 🛡️ **Type-safe** end-to-end with `strict: true`- 🎮 **Placeholder mini-game** included so the project runs out of the box---## Getting StartedNew to this? No problem. You'll have AI guiding you the entire way. Choose your editor below and follow the steps.### Choose Your EditorWe recommend the **Gallop AI Editor** for the best experience with Gallop templates — whether you're a beginner or an advanced game developer who wants AI-assisted iteration. It was purpose-built for this workflow and requires zero configuration. VS Code is also a fine choice if you prefer to work without AI assistance.| | Gallop AI Editor | VS Code || ------------------------ | --------------------------------------------------------- | ---------------------------------- || **Best for** | Non-programmers, junior programmers, advanced programmers | Advanced programmers || **AI built in** | Yes — Claude AI ready to go | No (optional extensions available) || **AI setup requirement** | Enter Claude API keys | Install extensions manually || **Template browser** | Built-in marketplace | Download ZIP from GitHub || **Media manager** | Built-in Studio with CDN sync | Manual file management || **Font manager** | Built-in Studio with WOFF2 font generation | No support || **SEO Audit** | Analyze SEO & Structured Data | No support || **Git** | Better Git UI with modal diff viewer | Default Git UI || **Node.js** | Built-in installer and version manager | Install Node.js separately |---### Option A: Gallop AI Editor (Recommended)The Gallop AI Editor is a desktop app built specifically for AI-powered web development. It includes everything you need — code editor, AI assistant, Git, terminal, media manager, font manager, SEO & structured data scanner, and a template marketplace — all in one window with nothing to configure.[](https://gallop.software/)Available for Mac and Windows.#### Step 1: Install Gallop AI Editor1. Go to [gallop.software](https://gallop.software/) and download the installer for your platform2. Open the installer and follow the prompts3. Launch the Gallop AI Editor4. If prompted, the editor will walk you through installing Node.js automatically — just follow the on-screen steps#### Step 2: Open This Template**From the built-in template marketplace:**1. Click the **Templates** tab in the sidebar2. Find **2D Game Base** and click **Clone**3. Choose a folder on your computer (like your Desktop)4. The editor will download and set up the project for you**Or from a ZIP download:**1. Click the green **Code** button at the top of this GitHub page, then click **Download ZIP**2. Unzip the folder somewhere easy to find (like your Desktop)3. In the Gallop AI Editor, click **Open Project** and select the unzipped `2d-game-base` folder#### Step 3: Start the Dev Server1. Click the **Terminal** tab at the bottom of the editor2. Click **Install** to install dependencies, then click **Start** to run the dev server3. Open [http://localhost:5173](http://localhost:5173) in your browser to see your game#### Step 4: Chat with AIClick the **AI Chat** panel (or press `Cmd+E` on Mac / `Ctrl+E` on Windows) to open the AI assistant. Now just ask:```I'm new to this. Help me turn this template into my own 2D game.```The AI assistant can read and edit your project files, run commands, and explain anything you're confused about. Just describe what you want in plain English:```Replace the placeholder with a side-scrolling platformer``````Add jump physics with a double-jump unlock``````Make the player sprite a pixel-art knight``````Wire up a game-over screen with a high-score table```**Tip:** Press `Cmd+Ctrl+3` (Mac) to take a screenshot of your running game and attach it to the chat. The AI can see exactly what you see and suggest changes visually.---### Option B: VS CodeVS Code is a good choice if you prefer to work without AI assistance. You'll need to install a few things manually.[](https://code.visualstudio.com)#### Step 1: Install Prerequisites1. Install [VS Code](https://code.visualstudio.com)2. Install [Node.js](https://nodejs.org) (version 20 or higher)3. Install [Git](https://git-scm.com)#### Step 2: Download This TemplateClick the green **Code** button at the top of this GitHub page, then click **Download ZIP**. Unzip the folder somewhere easy to find (like your Desktop).#### Step 3: Open in VS Code1. Open VS Code2. Click **File → Open Folder**3. Select the unzipped `2d-game-base` folder4. Click **Open**#### Step 4: Install and RunOpen the terminal in VS Code (`` Ctrl+` `` on Mac/Windows) and run:```bashnpm installnpm run dev```Open [http://localhost:5173](http://localhost:5173) to see your game. Press `Ctrl+C` to stop the server.#### Step 5: Start BuildingEdit files directly in VS Code. Refer to the [Project Structure](#project-structure) and [Available Scripts](#available-scripts) sections below for guidance.---### Join the CommunityConnect with other Gallop users on Slack. Share your progress, swap AI prompting tips, and see what indie devs are shipping with the help of AI.[](https://gallop-software.slack.com/)---## Put Your Game OnlineWhen you're ready to share your game with the world, you'll need a free [GitHub](https://github.com) account to store your code and a free [Vercel](https://vercel.com) account to host your build.### The Easy WayJust ask your AI assistant:```Help me create a GitHub account, push this project to GitHub, and deploy to Vercel```The AI will walk you through every step. When you're done, your game will be live with a URL you can share.### For Technical UsersIf you're comfortable with Git:#### Step 1: Create Your Repository[](https://github.com/gallop-software/2d-game-base/generate)#### Step 2: Clone Your RepositoryAsk your AI assistant:```Help me clone my new GitHub repository and run it locally```Or run these commands in your terminal:```bashgit clone https://github.com/YOUR-USERNAME/YOUR-REPO-NAME.gitcd YOUR-REPO-NAMEnpm installnpm run dev```Open [http://localhost:5173](http://localhost:5173) to view your game. Press `Ctrl+C` to stop the server. When ready to test the production build, run `npm run build` then `npm run preview`.#### Step 3: Deploy to Vercel[](https://vercel.com/new/clone?demo-title=2D%20Game%20Base&demo-description=A%20best-in-class%20TypeScript%20boilerplate%20for%20shipping%20high-quality%202D%20HTML5%20games%20built%20on%20PixiJS%2C%20Rapier%2C%20Howler%2C%20and%20tween.js.&demo-url=https%3A%2F%2F2d-game-base.gallop.software&demo-image=https%3A%2F%2F2d-game-base.gallop.software%2Fscreenshot.jpg&from=templates&project-name=2d-game-base&repository-name=2d-game-base&repository-url=https%3A%2F%2Fgithub.com%2Fgallop-software%2F2d-game-base)Select your repository, and Vercel will automatically deploy whenever you push changes.Congratulations! Your game is now live to the world. Share your new URL and start growing your audience. Ready for a custom domain? See [Vercel's domain setup guide](https://vercel.com/docs/projects/domains).---## About Gallop Templates2D Game Base is part of the [Gallop](https://gallop.software) template ecosystem. Gallop templates are designed to be built with AI — just describe what you want in plain English and watch your project come to life.### Gallop AI EditorThe [Gallop AI Editor](https://gallop.software/) is a desktop code editor built specifically for AI-powered development. It combines a full code editor, Claude AI assistant, visual Git interface, integrated terminal, media manager, and template marketplace into one app. Everything is preconfigured to work with Gallop templates out of the box — no extensions, no plugins, no setup.**Key highlights:**- **Claude AI built in** — Chat with Claude to write gameplay, debug physics, and learn engine APIs as you go. Supports Opus 4.7, Sonnet 4.6, and Haiku 4.5 models- **Agent and Plan modes** — Agent mode lets AI apply changes automatically. Plan mode shows you what AI wants to do before it does it, so you stay in control- **Screenshot capture** — Press `Cmd+Ctrl+3` to screenshot your running game and share it with AI for visual feedback- **Built-in template marketplace** — Browse and clone Gallop templates without leaving the editor- **Visual Git** — Stage, commit, and merge with a 3-column visual interface. No command line required- **Studio media manager** — Manage sprites, audio, and assets with thumbnail previews and CDN sync- **Node.js manager** — Install and switch Node.js versions without touching the terminal- **Auto-updates** — The editor keeps itself up to date automatically### Built for SEO and AI DiscoverabilityThis template was crafted from the ground up to get your game ranked #1 on Google and recommended by AI assistants like ChatGPT and Google's Gemini. Canvas-rendered games are invisible to crawlers by default, so the HTML shell ships with semantic landmarks, complete metadata, Open Graph, Twitter cards, and a JSON-LD `VideoGame` schema block that search engines and AI models actually parse.AI mentions are becoming more important than traditional SEO. When someone asks an AI assistant for "fun browser games like X," you want yours in that answer. Gallop templates are built with the structured data and semantic markup that AI models rely on to understand and recommend your work. Games using this template are already ranking on Google and getting discovered by AI assistants.### What You Can Build- **Build games with AI** — Let AI do the technical heavy lifting while you provide creative direction- **Skip the boring work** — Let AI scaffold scenes, wire up input, generate placeholder art, and handle physics setup- **Pixel-perfect rendering** — PixiJS v8 with native high-DPI support so text and sprites stay crisp on Retina and 4K displays- **Real physics from day one** — Rapier 2D ships with the boilerplate; deterministic, fast, and ready for replays or networking- **Get found online** — Battle-tested SEO foundation with structured data for search engines and AI assistants- **Deploy instantly** — Static-build output that drops onto Vercel, Netlify, Cloudflare Pages, or any static host### Built by Industry VeteransThe [team](https://webplant.media) behind Gallop has decades of combined experience building websites, apps, and web applications for top global brands. We've helped projects achieve #1 Google rankings in competitive markets and understand what it takes to ship something polished. That expertise is baked into every template, every component and every line of code.---## Project Structure```2d-game-base/├── src/│ ├── main.ts # Async bootstrap: creates Game, switches to PreloadScene│ ├── constants.ts # COLORS, ASSETS, gameplay tunables│ ├── types.ts # Shared scene-data interfaces│ ├── core/ # Engine glue│ │ ├── Game.ts # PIXI app + systems + scene manager + frame loop│ │ ├── Scene.ts # Abstract base extending PIXI.Container│ │ └── SceneManager.ts # Active-scene management with safe transitions│ ├── systems/ # Reusable subsystems│ │ ├── InputManager.ts # Keyboard + pointer + onPress() helpers│ │ ├── AudioManager.ts # Howler wrapper│ │ ├── PhysicsWorld.ts # Rapier wrapper: bodies, sensors, collision events│ │ └── AssetManager.ts # PIXI.Assets wrapper│ ├── scenes/ # Game flow│ │ ├── PreloadScene.ts # Loads assets, shows progress, hands off to Menu│ │ ├── MenuScene.ts # Title + Start button│ │ ├── GameScene.ts # Placeholder mini-game (REPLACE THIS)│ │ └── GameOverScene.ts # End screen + restart│ ├── objects/ # Per-entity classes (Pixi display + Rapier body)│ │ ├── Player.ts│ │ └── Coin.ts│ ├── ui/ # Persistent UI overlays│ │ └── HUD.ts│ └── utils/ # Shared helpers│ └── math.ts # clamp, lerp, randRange, randInt├── public/│ ├── screenshot.jpg # Featured image for OG / template marketplaces│ ├── favicon.svg # Vector favicon│ ├── manifest.webmanifest # PWA manifest│ ├── robots.txt # Crawler directives│ ├── sitemap.xml # Sitemap (single URL by default)│ └── assets/ # Game assets│ ├── sprites/ # Drop sprite sheets here│ ├── audio/ # Audio files (e.g. pickup.wav)│ └── tilemaps/ # Tilemap JSON / images├── _data/│ └── _studio.json # Studio/image metadata├── index.html # SEO-rich HTML shell + JSON-LD VideoGame schema├── vite.config.ts # Vite + vite-plugin-pwa configuration├── tsconfig.json # TypeScript config (strict: true)├── eslint.config / .eslintrc.cjs├── .prettierrc.json├── package.json└── README.md```---## Available Scripts### Development- **`npm run dev`** — Start development server at http://localhost:5173 with hot reload- **`npm run build`** — Type-check, then bundle to `dist/` for production- **`npm run preview`** — Serve the production build locally for testing- **`npm run typecheck`** — TypeScript type checking without emitting- **`npm run lint`** — Run ESLint on all source files- **`npm run format`** — Format all source files with Prettier---## Technologies### Frontend (Runtime)Every dependency is battle-tested in production and chosen for stability, performance, and long-term maintainability.- **PixiJS** `8.5.1` — WebGL/WebGPU 2D renderer with native high-DPI support- **Rapier 2D** `0.14.0` — Rust → WASM physics engine (`@dimforge/rapier2d-compat`)- **Howler.js** `2.2.4` — Web Audio with HTML5 fallback, sprite slicing, master volume/mute- **tween.js** `25.0.0` — Lightweight animation library (`@tweenjs/tween.js`)### Build & ToolingTools for building and developing the game:- **Vite** `5.4` — Dev server and bundler with instant HMR- **vite-plugin-pwa** `0.20.1` — Service worker + manifest generation- **TypeScript** `5.5` — Type safety and IntelliSense (`strict: true`)- **ESLint** `8.57` — Code linting (with `@typescript-eslint`)- **Prettier** `3.3` — Code formatting- **@types/howler** `2.2.11` — TypeScript types for Howler---## Support & Community- **Documentation:** [gallop.software](https://gallop.software)- **Issues:** [GitHub Issues](https://github.com/gallop-software/2d-game-base/issues)- **Slack:** [Join Community](https://join.slack.com/t/gallop-software/shared_invite/zt-358q3rdrp-H6kKvKzpR2qgB5xJviAOcw)- **Professional Services:** [Web Plant Media, LLC](https://webplant.media)---## LicenseMIT License — see [LICENSE](./LICENSE) for details---## Credits**Contributors:**- [Chris Baldelomar](https://github.com/webplantmedia)Built with ❤️ by the team at [Gallop](https://gallop.software)---## Learn More- [Gallop AI Editor](https://gallop.software/)- [Gallop Templates](https://gallop.software/templates)- [PixiJS Documentation](https://pixijs.com/8.x/guides)- [Rapier 2D Documentation](https://rapier.rs/docs/user_guides/javascript/getting_started_js)- [Howler.js Documentation](https://howlerjs.com/)- [tween.js Documentation](https://github.com/tweenjs/tween.js)- [Vite Documentation](https://vitejs.dev/guide/)