VectorRen is an open invitation to build small, sharp, joyful SVG games.
This project is intentionally simple, intentionally transparent, and intentionally fun.
Contributions are welcome — as long as they follow the philosophy that makes VectorRen work.
This document explains how to contribute without breaking the spirit of the project.
| Folder | Purpose |
|---|---|
docs/ |
Project documentation (philosophy, principles, specs, guidelines) |
games/ |
Individual games — each self-contained in its own subfolder |
site/ |
Production site — to test it use the local dev server (localhost:3000) |
test-harness/ |
Shared test runner for all games (Vitest + jsdom) |
VectorRen is built on small, self‑contained games.
If your idea requires:
- a framework
- a build step
- a shared engine
- or a dependency tree
…it probably doesn’t belong here.
Start with something tiny.
If it sparks joy, grow it.
Before contributing, read:
These documents define the project’s identity.
If your contribution aligns with them, you’re on the right track.
Every contribution begins with behavior, not code.
Write the behavior in Given / When / Then form:
Given an initial state
When something happens
Then the outcome should be clear
If you can’t express the behavior clearly, the feature isn’t ready.
After writing the behavior, encode it in a test.
Tests should:
- read like a story
- avoid implementation details
- be deterministic
- be assistant‑friendly
Tests are documentation.
Write them for humans.
Each game lives in its own folder and shares no code with others.
Do not create:
- shared engines
- shared utilities
- shared physics
- shared rendering code
VectorRen shares ideas, not code.
Contributions should be:
- readable in one sitting
- predictable
- free of clever abstractions
- easy to debug in DevTools
- easy for Coding Assistants to understand
If a future contributor would struggle to understand your code, simplify it.
All rendering must use SVG.
No Canvas.
No WebGL.
No hybrid layers.
Use:
- groups for structure
- transforms for motion
- CSS for style
- defs + use for instancing
SVG is the engine.
Treat it with respect.
VectorRen runs in a browser tab.
That’s the whole point.
Avoid:
- bundlers
- compilers
- preprocessors
- dependency forests
If your contribution requires a build step, rethink it.
SVG scenes should be:
- shallow
- semantic
- easy to inspect
- easy to debug
If someone can’t understand the scene graph in DevTools, simplify it.
Follow the naming conventions:
- nouns for state
- verbs for behavior
- lower camel case for JS
- kebab case for files
- semantic IDs and classes in SVG
Consistency helps both humans and assistants.
Coding Assistants are collaborators.
To help them help you:
- write clear behavior specs
- use consistent naming
- avoid synonyms for the same concept
- avoid clever abstractions
- keep files small and focused
Assistants thrive on clarity.
So does VectorRen.
A good PR:
- includes behavior specs
- includes tests
- includes documentation
- includes readable code
- does not include unrelated changes
- does not introduce dependencies
- does not break the philosophy
Small, intentional PRs are easier to review and easier to merge.
PRs over ~200 lines will be reviewed more slowly. If your change is large, consider splitting it into smaller pieces with clear, independent purposes.
VectorRen games should feel like vector games:
- crisp lines
- geometric shapes
- neon glows
- minimalism
- wireframe vibes
Avoid raster textures, faux‑3D hacks, or anything that breaks the aesthetic.
VectorRen is a renaissance — a return to joyful building.
If your contribution feels heavy, complicated, or joyless, stop and rethink it.
If it sparks joy, you’re on the right path.
VectorRen uses NPM only as a lightweight host and test runner, not as a build system. There is no bundler, no transpiler, and no compile step.
The repository has three independent NPM projects — each in its own subfolder:
| Folder | Purpose |
|---|---|
site/ |
Local dev server (serves the site at localhost:3000) |
test-harness/ |
Shared test runner for all games (Vitest + jsdom) |
games/<name>/ |
Per-game test runner (Vitest, no DOM) |
To run the site locally:
cd site
npm start
Open your browser to http://localhost:3000. No install step required — npx serve is used directly.
To run the shared test harness:
cd test-harness
npm install
npm test
To run a game's own tests:
cd games/vectoroids
npm install
npm test
If your contribution requires more than this, it is probably too complex for VectorRen.
Tests live in two places:
test-harness/tests/— integration-style behavior specs that test game logic using jsdom (Vitest)games/<name>/tests/— game-level specs that test pure logic without the DOM (Vitest)
Tests are:
- deterministic
- behavior-driven
- written to be read by humans and assistants
Run the shared test harness:
cd test-harness
npm test
Run a specific game's tests:
cd games/vectoroids
npm test
Watch mode (re-runs on file save):
npm run test:watch
Tests always encode the behavior you wrote in Given / When / Then form. If the behavior changes, the tests change first.
If you find a bug, have an idea, or want to propose something:
- Open an Issue
- Keep it small
- Describe the behavior, not the implementation
- Include a minimal reproduction if it is a bug
- Link to any relevant docs (Philosophy, Principles, SVG Guidelines, etc.)
Issues that align with the project’s philosophy are easier to act on. Issues that do not will be closed quickly and kindly.
New games are welcome — as long as they follow the VectorRen ethos.
A good game proposal:
- starts tiny
- has a clear behavior spec
- uses SVG as the renderer
- avoids dependencies
- fits the aesthetic (crisp lines, geometric shapes, neon vibes)
- can be understood in one sitting
If your idea requires a shared engine, a physics library, or a build step, it is not a VectorRen game.
Propose something small. If it sparks joy, we will grow it.
Contributing to VectorRen isn’t about adding features.
It’s about adding clarity, craft, and delight.
Build small.
Build sharp.
Build with intention.
And above all — have fun.