2D Game Base Readme

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
☁️ Cloudflare Demo: 2d-game-base-cloudflare.gallop.software
🎨 Template: gallop.software/templates
📦 Repository: github.com/gallop-software/2d-game-base
🏷️ Category: 2D Game Boilerplate

Why Use Gallop Templates?

Just chat with AI inside our Gallop AI Editor using 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. Go live in minutes.

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
• ☁️ Deploy anywhere — Cloudflare Workers or Vercel, both ready out of the box
• 🛡️ Type-safe end-to-end with strict: true
• 🎮 Placeholder mini-game included so the project runs out of the box

Getting Started

New to this? No problem. You'll have AI guiding you the entire way.

The Gallop AI Editor

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 gallery of open-source templates — all in one window with nothing to configure.

It was purpose-built for this workflow, whether you're a complete beginner or an advanced game developer who wants AI-assisted iteration:

Available for Mac and Windows.

Step 1: Install Gallop AI Editor

1. Go to gallop.software and download the installer for your platform
2. Open the installer and follow the prompts
3. Launch the Gallop AI Editor
4. If prompted, the editor will walk you through installing Node.js automatically — just follow the on-screen steps

Step 2: Create Your Project

Open the New Project modal. It has three tabs — Gallop Templates, Git Repositories, and Local — and you want the first one.

1. On the Gallop Templates tab, select 2D Game Base from the gallery
2. Name your new repository, and pick which GitHub account or organization owns it
3. Choose whether it's public or private
4. Pick the folder on your computer where it should live
5. Click create

The editor then does everything else in one pass:

• Creates your own repository on GitHub from the template — a clean repo that belongs to you, with no shared history tying it back to the original
• Clones it to your machine in the folder you picked, with a progress bar
• Opens it as a project, ready to run

Because the repository is created here, your GitHub repo already exists by the time you reach Put Your Game Online — there's nothing to set up on GitHub when it's time to deploy.

Why this is one click: you're already signed in to GitHub inside the editor, so it can create the repository on your behalf without asking you for anything.

Step 3: Start Your Game

Click the play icon in the left rail (or press Cmd+1) to open the Start Website view. It's a terminal with a toolbar across the top — two clicks and your game is running locally.

1. Click Install and wait for it to finish. This downloads everything the project needs, and takes a minute or two the first time.
2. Click Start Website. Your game is now running at http://localhost:5173.
3. Click the globe icon in the top-right title bar to open it in a browser. Hover it and it tells you the port it's running on.

Here's the full toolbar, and the command each button saves you from typing:

The play icon in the left rail turns green with a dot while your game is running, so you can tell at a glance from any view.

Leave the server running while you work. You only need Start Website once per session — the page refreshes on its own every time you or the AI saves a file.

If something looks stuck — a change won't appear, or the canvas won't load — try Refresh Cache first, and Stop then Start Website if that doesn't do it.

Step 4: Chat with AI

Press Cmd+J to show the AI panel on the right. Click the + in its header and you'll get a picker with three cards:

Both AI options are Claude Code. Gallop's AI Chat runs Claude Code under the hood and puts a friendlier interface on top of it; the Claude Code card gives you the same engine as its normal terminal interface. Same capabilities, same access to your project — pick whichever you find easier to read.

• New to this? Use AI Chat. Answers render as formatted text, file changes are easier to follow, and screenshots insert straight into the conversation.
• Already use Claude Code? Use the Claude Code card. Everything works the way you're used to, including slash commands and your existing habits.

You can run both at once in separate tabs — they're independent sessions.

Pick AI Chat, then 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+Shift+S 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.

Working in the Editor

Everything below is how you actually build your game day to day. The left rail switches between views; each has a keyboard shortcut.

Cmd+K cycles forward through views if you'd rather not remember numbers.

The AI Panel

The AI panel lives on the right and is where most of your work happens.

• Cmd+J shows and hides it. Hiding does not stop what's running — a long AI task keeps going while the panel is closed.
• Cmd+I expands it to fill the window, for when you're reading a long answer.
• Cmd+T opens a new tab; Cmd+Shift+[ and Cmd+Shift+] cycle between them. You can drag tabs to reorder them.
• Every tab has a ×. Close the last one and you're back at the AI Chat / Claude Code / Terminal picker.

Agent mode vs Plan mode — on an AI Chat tab, press Cmd+. to switch between them. (Claude Code tabs have their own mode controls, so Cmd+. doesn't apply there.)

Two AI Chat slash commands are worth knowing: /new starts a fresh conversation, and /compact summarizes a long one so you can keep going without losing the thread.

How you pay for AI is set in the panel's settings gear. There are three options, and none of them require you to have an API key:

Sessions pick up this setting when they start, so change it before opening a chat tab.

Showing AI What You See

Describing a visual bug in a game is hard — a sprite that jitters, a hitbox that feels off, a camera that lags behind. Show it instead.

• Cmd+Shift+S — drag a box around any part of your running game. The capture opens in an annotator where you can draw arrows and boxes, then Insert it straight into a chat tab.
• Cmd+Shift+L — drops the file you're editing into the chat as a reference, so you can say "the jump feels floaty here" without explaining where "here" is.

Studio: Sprites, Audio, and Fonts

Cmd+4 opens Studio, which manages everything in your public/ folder — including public/assets/sprites/, public/assets/audio/, and public/assets/tilemaps/.

• Drop in images and it generates thumbnails and blur placeholders automatically
• Crop and edit without leaving the editor
• Push assets to a CDN so they load fast worldwide
• Drop in a font and it converts to WOFF2, the format browsers load fastest

Studio keeps its records in _data/_studio.json. That file is generated — let Studio manage it.

SEO

Canvas games are invisible to crawlers by default, so the HTML shell around your game does all the SEO work. Cmd+5 opens the SEO view to check it. You run a report yourself — the AI can't trigger one for you:

1. Type or paste the URL you want to check (your local game works: http://localhost:5173)
2. Pick a report from the dropdown
3. Click Analyze

Each report opens in its own tab, so you can check several pages side by side.

Once you have the results, hand them to AI: screenshot the report with Cmd+Shift+S and insert it into a chat, or paste the details in. Then ask for what you want:

Here's the SEO report for my game page. Fix everything it flags.

Source Control

Cmd+2 gives you Git without the command line — stage individual lines, review diffs side by side, and browse history. If you'd rather not think about Git at all, don't: ask AI to "commit my changes and push them."

Keyboard Shortcuts

On Windows, use Ctrl wherever this says Cmd.

Join the Community

Connect with other Gallop users on Discord or Slack. Share your progress, swap AI prompting tips, and see what indie devs are shipping with the help of AI.

Put Your Game Online

Your code is already on GitHub — you're signed in inside the editor, and your repository was created when you started the project. All that's left is a hosting account: either Cloudflare or Vercel. Check their current plans before you pick — pricing and what each tier allows change over time.

Either way you're shipping a static build. npm run build produces a dist/ folder of HTML, JavaScript, and assets with no server behind it, which is why deployment here is simpler than for a server-rendered site: there are no environment variables to push and no secrets to manage.

The Easy Way: Let AI Deploy It

Press Cmd+6 (the rocket icon) to open the Publish view. It has a tab for each service you might need:

Each tab links straight to the page where you generate the token, with the right permissions preselected — you paste it in, click Connect to verify it, then Save.

From then on the editor injects those credentials into your terminal and AI chat automatically, so the assistant can deploy on your behalf and you never paste a token into a project file.

Important: credentials are handed to a session when it starts. After saving a new token, open a new chat or terminal tab — an existing one won't see it.

Then just ask:

Push my latest changes to GitHub and deploy this game

The AI will walk you through every step. When you're done, your game will be live with a URL you can share.

Already know which host you want? Use the ready-made prompt for Cloudflare or Vercel.

Deploy to Cloudflare Workers

2D Game Base ships Cloudflare-ready — the build output is served as static assets straight from Cloudflare's edge.

Step 1 — Connect Cloudflare in the Publish view (Cmd+6). Once saved, the editor puts your Cloudflare credentials (CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID) into the terminal environment and makes them available to the AI chat. Wrangler reads those variables automatically, which means nobody has to run npx wrangler login, and no token is ever pasted into a file.

Step 2 — Paste this prompt into the AI chat:

Deploy this game to Cloudflare Workers. My Cloudflare account is already
connected, so CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are in the
terminal environment — do not run `wrangler login`.

Please:
1. Push my latest changes to GitHub
2. Run `npm run cf:deploy` to build and create the Worker
3. Tell me the live URL when it's done

That's the entire first deploy — there's nothing to fill in, because a static game has no secrets. It takes a couple of minutes.

Step 3 — Follow-up prompts for anything after the first deploy:

Deploy my latest changes to Cloudflare

Rename my Cloudflare Worker to my-game and redeploy

My game loads on Cloudflare but the audio 404s — check the asset paths

If a prompt fails, paste the error back into the chat. The most common cause is a Cloudflare account that isn't connected yet, so wrangler has no credentials — the AI can diagnose that from the error text.

Reference: How the Cloudflare Deployment Works

Everything below is reference material for your AI assistant — what files Cloudflare needs, which ones get generated, and what has to change when you rename things. You don't need to read or run any of it yourself; the prompts above cover the whole process. It's here so the AI has accurate ground truth, and so you have something to point at if a deploy goes wrong.

The Two Kinds of Cloudflare Files

If you forked or generated this repo, every config file already exists — you do not create any of them.

1. Config files — already in the repo, keep them

2. Build output — generated, never committed

Both are already gitignored. dist/ does not exist until you build, which is why cf:deploy and cf:preview always run the build first.

The Deployment Sequence

This is what the AI runs on your behalf:

npm run cf:deploy    # build + deploy — creates the Worker on first run

No wrangler login step is needed: connecting Cloudflare in the editor already put CLOUDFLARE_API_TOKEN in the environment, and wrangler picks it up automatically. If your account can't be inferred from the token, also set CLOUDFLARE_ACCOUNT_ID. Wrangler ships as a dev dependency, so npx runs the local copy — no global install needed.

Names must match. The name in wrangler.jsonc must equal the Worker's actual name in your Cloudflare dashboard. If a Git-connected deploy created it under a different name, update wrangler.jsonc to match.

Renaming the Worker

wrangler.jsonc ships with the Worker named 2d-game-base. Change the single name field to rename it — nothing else in the repo references it:

{
  "name": "your-game-name" // ← the Worker name
}

Git-Connected Builds

If you connect the repo in the Cloudflare dashboard instead of deploying from your machine:

• Build command: npm run build
• Deploy command: npx wrangler deploy

Custom domains live under the Worker's Settings → Domains & Routes.

Single-Page Routing

not_found_handling is set to single-page-application, so any URL that doesn't match a file returns index.html instead of a 404. That's what you want for a canvas game with client-side screens, but it does mean a mistyped path loads the game rather than erroring.

Quick Reference

Deploy to Vercel

Connect your Vercel account in the Gallop AI Editor, then paste this into the AI chat:

Deploy this game to Vercel. My Vercel account is already connected.

Please:
1. Push my latest changes to GitHub
2. Link this project to Vercel and deploy it to production
3. Tell me the live URL when it's done

Vercel detects Vite automatically — build command npm run build, output directory dist. It redeploys every time you push, so from here on your changes go live by asking the AI to push them.

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.

About Gallop Templates

2D Game Base is part of the Gallop 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 Editor

The Gallop AI Editor 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 gallery into one app. Everything is preconfigured to work with Gallop templates out of the box — no extensions, no plugins, no setup.

Key highlights:

• Claude built in — Chat with Claude to write gameplay, debug physics, and learn engine APIs as you go. Use Gallop AI with no setup, your Claude Max or Pro plan, or your own API key
• 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+Shift+S to screenshot your running game and share it with AI for visual feedback
• Built-in template gallery — Browse and clone Gallop templates without leaving the editor, all free and open source
• Visual Git — Stage, commit, and merge with a visual interface. No command line required
• Studio media manager — Manage sprites, audio, and tilemaps with thumbnail previews and CDN sync
• Node.js manager — Install and switch Node.js versions without touching the terminal
• One-click deployment — Connect Cloudflare or Vercel and let AI ship your game
• Auto-updates — The editor keeps itself up to date automatically

Built for SEO and AI Discoverability

This 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.

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 Cloudflare Workers, Vercel, Netlify, or any static host

Built by Industry Veterans

The team 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 gallery
│   ├── images/                # Responsive screenshot variants
│   ├── favicon.svg            # Vector favicon
│   ├── manifest.webmanifest   # PWA manifest
│   ├── robots.txt             # Crawler directives
│   ├── sitemap.xml            # Sitemap (single URL by default)
│   ├── _headers               # Cloudflare cache-control rules
│   └── assets/                # Game assets
│       ├── sprites/           # Drop sprite sheets here
│       ├── audio/             # Audio files (e.g. pickup.wav)
│       └── tilemaps/          # Tilemap JSON / images
├── _data/
│   └── _studio.json           # Studio media metadata
├── index.html                 # SEO-rich HTML shell + JSON-LD VideoGame schema
├── vite.config.ts             # Vite + vite-plugin-pwa configuration
├── wrangler.jsonc             # Cloudflare Workers config (assets-only)
├── tsconfig.json              # TypeScript config (strict: true)
├── .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

Cloudflare Deployment

• npm run cf:build — Type-check and build the static site into dist/
• npm run cf:preview — Build, then serve it with the real Workers runtime locally
• npm run cf:deploy — Build and deploy to Cloudflare Workers
• npm run cf:upload — Build and upload a new version without making it live

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 & Tooling

Tools for building, developing, and shipping 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
• Wrangler 4.x — Cloudflare Workers CLI for local preview and deployment
• @types/howler 2.2.11 — TypeScript types for Howler

Support & Community

• Documentation: gallop.software
• Issues: GitHub Issues
• Discord: Join Community
• Slack: Join Community
• Professional Services: Web Plant Media, LLC

License

MIT License — see LICENSE for details

Credits

Contributors:

• Chris Baldelomar

Built with ❤️ by the team at Gallop

Learn More

• Gallop AI Editor
• Gallop Templates
• PixiJS Documentation
• Rapier 2D Documentation
• Howler.js Documentation
• tween.js Documentation
• Vite Documentation
• Cloudflare Workers Static Assets