Web Game Template for Coding Agent-Assisted Development

A project template for building browser games with the help of a coding agent. Use any agent-enabled editor or CLI that can read and edit files in a local project folder. You describe the game — the agent writes the design doc, plans the tasks, implements the code, and tests it, all within strict architecture and design rules baked into the repo.

New to Coding Agents?

If you have little or no technical background, start with the Workshop Console — an interactive page that builds every prompt for you and tracks your progress with a checklist — or read AGENTS_WORKSHOP_GUIDE.md, a beginner-friendly step-by-step walkthrough from a first idea to a playable browser game link.

The guide is written for people who are just getting comfortable with AI agents and want to understand the workflow without needing to read code first.

How It Works

1. Get the template: download the ZIP and extract it, clone the repo, or click Use this template on GitHub
2. Open the folder in an agent-enabled editor or CLI
3. Build your first prompt in the Workshop Console (New game prompt tab) — or open FIRST_PROMPT.md and write your game concept in the placeholder
4. Copy the prompt into the agent chat
5. The coding agent reads the rules and follows a 4-phase workflow:

Phase	What happens	Output
1. Design	Agent writes a game design document	DESIGN.md
2. Planning	Agent creates an ordered task list	TODO.md
3. Implementation	Agent builds the game task by task	src/
4. Testing	Agent writes tests, fixes failures until all pass	tests/

The coding agent checks every change against the architecture and design rules. If your request would violate a rule, it warns you and proposes alternatives before writing any code.

For subsequent changes (new features, balance tweaks, mechanic removals), use the console's Change prompt tab or NEXT_ITERATION_PROMPT.md — it ensures the agent updates DESIGN.md first, then plans and implements, rather than jumping straight to code.

What's Inside

├── AGENTS.md                # Coding agent rules: workflow, guard behavior, coding standards
├── AGENTS_WORKSHOP_GUIDE.md # Beginner-friendly workshop guide for learning the agent workflow
├── ARCHITECTURE.md          # Code architecture: store API, patterns, file structure
├── DESIGN_RULES.md          # Game design principles: balance, UX, progression, etc.
├── FIRST_PROMPT.md          # Template: first message to the agent (new game)
├── NEXT_ITERATION_PROMPT.md # Template: subsequent messages (changes, new features)
├── src/
│   ├── index.html       # Entry point — open in browser (works via file:///)
│   ├── main.js          # Game loop skeleton
│   └── store/
│       └── store.js     # State management engine (don't modify)
└── tests/
    ├── index.html       # Test runner — open in browser
    ├── helpers.js        # Minimal test framework (assert, assertEqual)
    └── test-store.js     # Store engine tests (28 tests)

Rules (permanent, define standards):

• AGENTS.md — how the coding agent should work: 4-phase workflow, guard behavior that blocks rule-violating changes, coding conventions
• ARCHITECTURE.md — Mutable UDF + Deterministic Lockstep: one mutable state object, dispatched events logged for replay, continuous simulation on every tick
• DESIGN_RULES.md — 9 game design principles: intuitive affordances, emergent gameplay, wave-like difficulty, player agency, PEGI 7 compliance, etc.

Generated per game (created by the agent):

• DESIGN.md — game design document for your specific game
• TODO.md — implementation task list

Key Constraints

• No server required. The game runs by opening src/index.html directly via file:/// in any modern browser. No build tools, no npm, no bundlers.
• No ES modules. Files use IIFEs and window globals instead of import/export (ES modules require an HTTP server due to CORS).
• Deterministic replay. All randomness goes through a seeded PRNG (store.prng.next()). Math.random() is forbidden. Game sessions can be saved and replayed identically.
• Pure state. store.state contains only plain serializable data (numbers, strings, booleans, objects, arrays). No DOM refs, no class instances.

Architecture at a Glance

User Input → store.dispatch(type, payload)
           → logged in store.history
           → handler mutates store.state
           → subscribers notified → UI updates

Two kinds of state changes, kept strictly separate:

Kind	How	Logged?	Use for
Discrete events	store.dispatch()	Yes	inputs, spawns, deaths
Continuous simulation	system.update(state, dt)	No	movement, physics, AI

Running Tests

Open tests/index.html in a browser (works via file:///). All results display on the page.

Or run via Node.js:

node -e "
globalThis.window = globalThis;
globalThis.document = { getElementById: function() { return null }, title: '' };
require('./src/store/store.js');
require('./tests/helpers.js');
require('./tests/test-store.js');
var r = TestRunner.results, p = 0, f = 0;
r.forEach(function(t) { t.pass ? p++ : (f++, console.log('FAIL:', t.message)); });
console.log(p + ' passed, ' + f + ' failed');
process.exit(f);
"

License

MIT