Skip to content

game-template.md

Latest commit

 

History

History
280 lines (204 loc) · 6.06 KB

game-template.md

File metadata and controls

280 lines (204 loc) · 6.06 KB

GameTemplate

This document defines the structure, expectations, and workflow for creating a new VectorRen game.
Every game in the repository should follow this template. The goal isn’t uniformity — it’s clarity.
A contributor should be able to open any game folder, understand its architecture in minutes, and build confidently without guessing.

VectorRen games are intentionally small, self‑contained, and explainable.
This template keeps them that way.

1. Folder Structure

Every game lives in its own folder under games/ and follows this structure:

game-name/
├── index.html
├── game.js          ← public API re-exports (entry point for test harness)
├── game.css
├── assets/
│   └── (optional SVG defs, patterns, or reusable shapes)
├── docs/
│   ├── architecture/
│   ├── design/
│   └── specs/
├── src/
│   ├── core/        ← state, update pipeline, entity logic
│   ├── svg/         ← renderer and DOM helpers
│   ├── input/       ← input capture
│   └── utils/       ← collision, wrapping, math helpers
├── tests/
│   └── behavior.spec.js
└── README.md

Each file has a clear purpose and should remain small and focused.
As a game grows, logic naturally separates into the src/ subdirectories above.
Small games may start with a single game.js and refactor into src/ as complexity warrants.

2. index.html

The HTML file is minimal and declarative. It should:

  • load the SVG root
  • load game.css
  • load game.js as a module
  • define the initial SVG scene graph
  • include any <defs> needed for instancing

Example skeleton (HTML tags escaped to avoid breaking the snippet):

&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
  &lt;meta charset="UTF-8" /&gt;
  &lt;title&gt;Game Name — VectorRen&lt;/title&gt;
  &lt;link rel="stylesheet" href="game.css" /&gt;
&lt;/head&gt;
&lt;body&gt;
  &lt;svg id="game" viewBox="-100 -100 200 200"&gt;
    &lt;defs&gt;
      &lt;!-- reusable shapes --&gt;
    &lt;/defs&gt;
    &lt;g id="world"&gt;&lt;/g&gt;
  &lt;/svg&gt;
  &lt;script type="module" src="game.js"&gt;&lt;/script&gt;
&lt;/body&gt;
&lt;/html&gt;

Keep it simple.
The browser is the engine.

3. game.js

For small games this file may contain all logic directly.
For larger games it becomes a thin public re-export facade:

export { create, createInitialState, update } from "./src/core/game.js";
export { createShip } from "./src/core/ship.js";
// ...

This keeps the public API stable for the test harness while allowing internal modules to evolve freely.

When written as a single file it defines:

  • initial state
  • update loop
  • render loop
  • input handling
  • collision logic
  • game lifecycle

Recommended structure (JS escaped):

const state = {
  // positions, velocities, timers, flags
};

let last = 0;

function update(dt) {
  // update state based on dt
}

function render() {
  // apply transforms to SVG nodes
}

function loop(timestamp) {
  const dt = timestamp - last;
  update(dt);
  render();
  last = timestamp;
  requestAnimationFrame(loop);
}

requestAnimationFrame(loop);

The game loop is sacred.
Keep it clean, predictable, and readable.

4. game.css

CSS defines the visual language:

  • strokes
  • fills
  • glow effects
  • UI elements
  • reusable classes

Use CSS for style.
Use transforms for motion.
Use inline attributes only when necessary.

5. assets/

Optional folder for:

  • reusable SVG shapes
  • patterns
  • filters
  • icons
  • ship/asteroid/star definitions

Use <defs> + <use> for instancing.
If you’re copying shapes manually, stop and rethink.

6. tests/behavior.spec.js

VectorRen uses Specification‑Driven Development with Given / When / Then behavior tests.

Tests should:

  • describe behavior, not implementation
  • read like a story
  • clarify intent
  • support refactoring
  • help Coding Assistants generate correct code

If a test is hard to write, the behavior is unclear.
If a test is hard to read, the naming is unclear.

7. README.md (per‑game)

Each game folder includes a README with:

  • game description
  • controls
  • architecture notes
  • SVG structure overview
  • high‑level behavior specs
  • known limitations
  • future ideas

This is the onboarding document for contributors.

8. Coding Assistant Workflow

VectorRen embraces assistants as collaborators, not authors.

When building a new game:

  1. Write the behavior first

    • Given / When / Then
    • plain language
    • no code yet

  2. Write the tests second

    • encode the behavior
    • clarify edge cases

  3. Let the assistant generate scaffolding

    • game loop
    • SVG setup
    • boilerplate

  4. Refine manually

    • architecture
    • naming
    • clarity

  5. Use the assistant for variations

    • alternate movement patterns
    • different shapes
    • UI ideas

  6. Keep the code explainable

    • if the assistant produces magic, rewrite it
    • if the assistant produces noise, simplify it

Assistants accelerate craft.
They don’t replace it.

9. Design Principles (Quick Reference)

Every game must follow the VectorRen principles:

  • SVG is the renderer
  • no build step
  • no dependencies unless absolutely necessary
  • shallow DOM
  • transforms over coordinates
  • readable in one sitting
  • fun comes first

See docs/Principles.md for the full list.

10. Starting a New Game

To create a new game:

  1. Copy this template folder
  2. Rename it
  3. Define the behavior in plain language
  4. Write the Given / When / Then tests
  5. Build the minimal SVG scene
  6. Implement the loop
  7. Add polish
  8. Document the game

If you’re not having fun, something is wrong.

Final Note

This template isn’t here to enforce sameness.
It’s here to enforce clarity.

VectorRen games are small on purpose.
Sharp on purpose.
Joyful on purpose.

Follow the template and you’ll build something worth sharing.