Gurjot's Games

---

🕹️ The arcade

Every thumbnail below is a live link. Click one and you are playing in about a second.

---

✨ Why it feels good to use

⚡ Instant	Canvas games with no build step and no bundle to download. Click and play.
📴 Offline	A service worker caches the shell and assets, so the arcade keeps working on a plane or a dead connection.
🎮 Your controls	Keyboard, mouse, touch and on-screen controls, with rebindable keys on the games that support them.
♿ Reachable	Semantic markup, ARIA labels, visible focus, and pause-on-hidden so nothing runs away while you are in another tab.
🧪 Actually tested	250+ unit tests, plus a smoke test that boots all 15 games in a real browser on every pull request.
🔓 Yours	MIT licensed. Fork it, reskin it, add your own game.

---

🚀 Run it locally

git clone https://github.com/koonergurjot/Gurjots-Games.git
cd Gurjots-Games
npm install
npx serve .

Then open http://localhost:3000.

Serve it over HTTP rather than opening index.html from disk — the games load assets from absolute paths like /assets/..., which the file:// protocol cannot resolve.

Useful scripts

Command	What it does
npm test	Health check plus the full unit suite
npm run test:unit	Unit tests only (Vitest)
node tools/dev/boot-check.mjs	Boots every game in a headless browser and reports anything broken
npm run health	Verifies every catalogued game resolves
npm run doctor	Game Doctor — assets, manifests, shells
npm run sync:games	Regenerates the offline catalog from games.json
npm run sitemap	Rebuilds sitemap.xml

---

🎨 Add your own game

1. Fork the repository and create a branch.
2. Drop your game into games/your-slug/ with an index.html entry point.
3. Signal readiness. Copy the auto-signal bootstrap from any existing game's index.html. It posts GAME_READY to the parent shell so the loading overlay clears — without it your game looks broken even when it works.
4. Draw a thumbnail at games/your-slug/thumb.svg, using the same 160×90 viewBox as the others.
5. Add a catalog entry to games.json, then run npm run sync:games.
6. Check your work:

   node tools/dev/boot-check.mjs your-slug   # must print PASS
   npm run health && npm run doctor
   

7. Open a pull request. CI boots your game in a real browser and will tell you if anything is wrong.

Full detail lives in CONTRIBUTING.md and docs/submit-game.md.

---

🧩 How a game boots

flowchart LR
    A["🏠 index.html<br/>catalog"] -->|pick a game| B["🎛️ game.html<br/>shell"]
    B --> Cmodern wrapper<br/>exists?
    C -->|yes| D["gameshells/slug/"]
    C -->|no| E["games/slug/"]
    D --> F["🎮 your game"]
    E --> F
    F -->|postMessage GAME_READY| B
    B -->|hides the loading overlay| G["▶️ playing"]
    F -.->|postMessage GAME_ERROR| H["⚠️ error screen"]

    style A fill:#1e2951,stroke:#8ec8ff,color:#e8ecf6
    style B fill:#1e2951,stroke:#8ec8ff,color:#e8ecf6
    style F fill:#10321f,stroke:#5fcf9f,color:#e8ecf6
    style G fill:#10321f,stroke:#5fcf9f,color:#e8ecf6
    style H fill:#3a1a22,stroke:#ff8b99,color:#e8ecf6

The catalog in games.json is the single source of truth. It drives the landing page, the sitemap, the offline fallback and the service worker precache — so a game that is not listed there is invisible, however finished it is.

---

🛡️ Quality gates

Every pull request runs four independent checks before anything reaches main:

Check	What it protects
Unit Tests	145 tests across 44 files, on Node 20 and 22
Game Smoke Test	Boots all 15 games over HTTP in headless Chromium and fails on a console error, a failed request, a GAME_ERROR, or a stuck loading overlay
Game Doctor	Every catalogued game has its shell, thumbnail, assets and manifest entries
Code Doctor	Syntax, unresolved imports, circular dependencies, dead code

---

📚 Documentation

Getting started

• Beginner tutorials
• Submit a game
• Contributing guide

Reference

• Project overview
• API reference
• Configuration
• Deployment

Internals

• Game Doctor
• Loader diagnostics
• Game inventory
• Custom thumbnails

Project

• Roadmap
• Creator program
• Achievements
• Launcher guide

The health check looks for extra assets declared in tools/reporters/game-doctor-manifest.json. Each slug can list required files (paths) and patterns (globs), resolved relative to the folder holding the playable shell.

{
  "requirements": {
    "pong": {
      "paths": ["manifest.json", "pong.css"],
      "globs": ["*.js"]
    }
  }
}

Add a slug's entry, keep every value in arrays of strings, then run npm run doctor to confirm it passes.

---

❓ FAQ

---

🤝 Contributing

Pull requests are welcome, from a one-word typo fix to a whole new game. Start with CONTRIBUTING.md and the Code of Conduct. Found a security issue? See SECURITY.md.

---