docs(learn): add game-dev primer for programmers new to game dev - #11
Conversation
Six focused documents targeting the tech lead / backend engineer / web developer who has always wanted to build games but never had the time. - README.md: learning path + one-line summaries - 01-game-dev-for-programmers.md: game loop vs request/response, determinism, coordinate systems, what transfers from dayjob code - 02-core-concepts.md: sprites, tilemaps, AABB collision, scenes, audio, tweens, particles — every term with Phaser equivalent - 03-ai-asset-generation.md: the big one. Scenario, Retro Diffusion, PixelLab, Midjourney, ElevenLabs, Suno, sfxr, Tiled, Aseprite. Prompt templates, pipeline, Phaser integration, cost budget, licensing gotchas. - 04-game-design-primer.md: core loop, MDA, verbs, game feel, juice, difficulty curves, scope discipline, genre cheatsheet - 05-solo-dev-workflow.md: prototype → vertical slice → ship, weekly cadence, playtesting, itch.io checklist, common graveyards, a workable 3-month plan - 06-resources.md: curated books, YouTube, talks, communities, Phaser-specific links, asset stores, game jams Total ~1200 lines. Wired into README.md start-here table and BUILD_THE_GAME.md further-reading. The goal is that a programmer who finishes all six docs (≈2.5h) can go from 'I know I want to do this' to 'I know how to do this' without needing any other resource. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
agjs
changed the title
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive 'Learn Game Dev' documentation suite designed for experienced programmers transitioning into game development. The new content covers the fundamental shift to the game loop, core terminology, AI-driven asset generation, game design principles, and solo developer workflows. The review feedback correctly identifies technical inaccuracies regarding Phaser's default object origins and audio format compatibility for cross-browser support, alongside minor typographical corrections.
| - **Phaser**: `scene.anims.create({ key: 'walk', frames: scene.anims.generateFrameNames('hero', { prefix: 'walk_', start: 0, end: 7 }), frameRate: 12, repeat: -1 })`. | ||
|
|
||
| ### Origin / pivot | ||
| The reference point on a sprite used for positioning and rotation. Default is the top-left in Phaser's coordinate system for `Image`, but center `(0.5, 0.5)` for `Sprite`. Wrong origin = sprites that rotate around their corner. Set with `sprite.setOrigin(0.5, 0.5)`. |
There was a problem hiding this comment.
In Phaser, both Image and Sprite objects default to an origin of (0.5, 0.5). The statement that Image defaults to the top-left is incorrect.
| The reference point on a sprite used for positioning and rotation. Default is the top-left in Phaser's coordinate system for `Image`, but center `(0.5, 0.5)` for `Sprite`. Wrong origin = sprites that rotate around their corner. Set with `sprite.setOrigin(0.5, 0.5)`. | |
| The reference point on a sprite used for positioning and rotation. Default is the center (0.5, 0.5) for both Image and Sprite. Wrong origin = sprites that rotate around their corner. Set with sprite.setOrigin(0, 0) to align to the top-left. |
| 2. **For realistic/modern SFX, use ElevenLabs.** Prompt: "A soft wooden click with a metallic edge, short decay, for a UI button press." | ||
| 3. **Batch per category.** Generate 10 jump sounds in one session, pick 2, mark the favorite, reuse the prompt style. | ||
| 4. **Normalize volume.** All SFX should peak at roughly the same dB so the player doesn't get blown out by one sound. [Audacity](https://www.audacityteam.org/) (free) has a "Loudness Normalization" effect. | ||
| 5. **Export as OGG or MP3.** OGG is smaller and better for web; some older browsers preferred MP3. Phaser supports both. |
There was a problem hiding this comment.
While OGG is efficient, it lacks native support in some versions of Safari. It is generally recommended to provide both OGG and MP3 formats for maximum browser compatibility, as correctly shown in the code example on line 203.
| 5. **Export as OGG or MP3.** OGG is smaller and better for web; some older browsers preferred MP3. Phaser supports both. | |
| 5. **Export as OGG and MP3.** Provide both for maximum browser compatibility (Safari lacks OGG support in some contexts). Phaser allows passing an array of formats to load.audio. |
|
|
||
| ### Practical workflow | ||
| 1. **Generate 3–5 candidate tracks** per level/mood. | ||
| 2. **Pick favorites. Export at WAV.** |
There was a problem hiding this comment.
Minor typo: "Export at WAV" should be "Export as WAV".
| 2. **Pick favorites. Export at WAV.** | |
| 2. **Pick favorites. Export as WAV.** |
There was a problem hiding this comment.
Pull request overview
Adds a new docs/learn/ mini-curriculum intended to onboard experienced programmers (new to game dev) into this Phaser template, and links it from the main README and build guide.
Changes:
- Introduces six new learning docs under
docs/learn/plus a landingdocs/learn/README.mdwith a suggested reading order. - Adds entrypoints in
README.mdandBUILD_THE_GAME.mdto route first-time game devs to the new learning path. - Includes practical guidance on AI-assisted asset generation, game design fundamentals, and a solo-dev workflow.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/learn/README.md | New landing page + reading order + “one-line” summaries of each doc. |
| docs/learn/01-game-dev-for-programmers.md | Explains the game loop mental model and how it maps to the repo’s architecture. |
| docs/learn/02-core-concepts.md | Glossary/primer mapping common game-dev concepts to Phaser and repo locations. |
| docs/learn/03-ai-asset-generation.md | AI tooling/pipeline guidance + Phaser integration pointers. |
| docs/learn/04-game-design-primer.md | Condensed design fundamentals (core loop, MDA, difficulty, scope). |
| docs/learn/05-solo-dev-workflow.md | Suggested production phases, playtesting cadence, and publishing checklist. |
| docs/learn/06-resources.md | Curated resources for further learning (books, talks, communities, tools). |
| README.md | Adds “start here” pointer to docs/learn/ for programmers new to game dev. |
| BUILD_THE_GAME.md | Adds an upfront note directing first-timers to docs/learn/ first. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - [ ] A controls screen in-game (keyboard + gamepad) | ||
| - [ ] An in-game or README credits page (tools, assets, fonts, music, people) | ||
| - [ ] Price set ($0 / name your price / fixed) | ||
| - [ ] `game.html` works standalone when opened in a browser |
There was a problem hiding this comment.
game.html is referenced in the itch.io publishing checklist, but this repo/template doesn’t appear to contain a game.html entrypoint (it uses index.html). This is likely to confuse readers—consider changing this checklist item to index.html (or explicitly dist/index.html after pnpm build).
| - [ ] `game.html` works standalone when opened in a browser | |
| - [ ] `index.html` works standalone when opened in a browser |
| ├── music/ # loop-ready tracks | ||
| ├── fonts/ # ttf / woff / bitmap | ||
| └── LICENSES.md # attribution for anything CC-licensed | ||
| ``` | ||
|
|
||
| Keep `LICENSES.md` up to date as you add assets — it's painful to backfill two months before launch. |
There was a problem hiding this comment.
The suggested public/assets/ layout includes LICENSES.md, but the template currently ships with public/assets/README.md and no LICENSES.md. Either add a placeholder public/assets/LICENSES.md to the template or tweak this section to say to create/maintain it when you start adding third‑party assets.
Summary
Adds
docs/learn/— a six-document primer that reframes this template for a new (and much larger) audience: programmers who have always wanted to build games but never had the time.The architecture + spec-kit + CI we've built is great for the AI-first workflow, but it assumes you already know what a sprite, tilemap, and core loop are. That assumption rules out most potential users. This PR fixes it.
The audience
Tech leads, backend engineers, systems programmers, web developers. People who can ship production software but have never shipped a game. The pitch in the updated README header:
The six docs
Plus a
docs/learn/README.mdindex with a learning path, time estimates per doc, and a "one-line summary" section for readers who only have five minutes.Total: ~1200 lines, ~2.5 hours of focused reading. The goal is that someone who reads all six can go from "I know I want to do this" to "I know how to do this" without needing another resource.
Integration with the rest of the repo
README.md: added a new row in the "Start here" table for programmers-new-to-gamedev pointing atdocs/learn/, plus a one-line hook in the opening paragraph.BUILD_THE_GAME.md: a banner at the top that says "read docs/learn/ first if you're new," plus a new row in the Further Reading table.docs/learn/README.md: an index table that cross-links back to BUILD_THE_GAME.md anddocs/ai/*so readers know where each concern lives.The docs don't touch any code or workflows. Tests still pass (43/43).
Why it matters
This template was designed to help one archetype (the AI-first game dev) do their thing. This PR expands it to a second archetype (the programmer who never shipped a game) that is orders of magnitude larger and has been underserved by everything on the market — every Phaser tutorial assumes you're a game dev, every game-dev textbook assumes you're not a programmer.
If the repo achieves what it's aiming for, forkers will include both "I've shipped 5 games and want a clean starter" and "I've been a tech lead for 12 years and finally have a quiet weekend."
Test plan
pnpm checkgreen (no code changes, tests unaffected)