This document defines the shared vocabulary and structure for writing behavior specifications across all VectorRen games.
Behavior specifications are the backbone of Specification‑Driven Development.
They describe how the game should behave in plain language before any code is written.
Behavior specs are not tests.
They are the source of truth that tests encode and code implements.
Behavior specifications exist to:
- clarify intent
- eliminate ambiguity
- guide implementation
- support refactoring
- help Coding Assistants generate correct code
- keep the project explainable
If a behavior is not written down, it does not exist.
Every behavior specification follows the same structure:
- Given an initial state
- When an action or event occurs
- Then the outcome should be clear
This format forces clarity and prevents hidden assumptions.
Examples (escaped to avoid breaking the snippet):
Given a ship with zero velocity
When thrust is applied
Then its velocity increases in the direction it is facing
Given an asteroid with a known velocity
When one second of game time passes
Then its position changes by that velocity
Given a bullet and an asteroid on a collision path
When their bounding circles overlap
Then both are removed and the score increases
A good behavior specification is:
- short
- clear
- unambiguous
- implementation‑agnostic
- testable
- assistant‑friendly
A behavior spec describes what happens, not how it happens.
Avoid:
- references to DOM structure
- references to SVG attributes
- references to specific functions
- references to code organization
Behavior is conceptual.
Implementation is mechanical.
VectorRen games typically fall into a few recurring behavior categories.
Movement behaviors describe how entities change position over time.
Examples:
Given an entity with velocity
When time advances
Then its position changes by velocity multiplied by elapsed time
Wrapping behaviors describe how entities reappear when leaving world bounds.
Given an entity beyond the right boundary
When wrapping is applied
Then it appears on the left boundary
Collision behaviors describe interactions between entities.
Given two entities with overlapping collision radii
When a collision check occurs
Then both entities are marked for removal
Spawning behaviors describe how new entities enter the world.
Given a destroyed asteroid
When it splits
Then two smaller asteroids appear with new velocities
Input behaviors describe how player actions affect state.
Given the player presses the thrust key
When input is processed
Then the ship accelerates forward
Timing behaviors describe delays and intervals.
Given a weapon with a cooldown
When the player fires
Then the weapon cannot fire again until the cooldown expires
When adding a new feature:
- Write the behavior in plain language.
- Use the Given / When / Then structure.
- Keep it short and unambiguous.
- Avoid implementation details.
- Ensure it is testable.
- Ensure it is assistant‑friendly.
If a behavior is hard to express, the design is unclear.
Avoid these common pitfalls:
- describing implementation instead of behavior
- using vague terms like “sometimes” or “usually”
- combining multiple behaviors into one specification
- relying on hidden assumptions
- using synonyms for the same concept
- describing visual appearance instead of logic
Behavior specs should be crisp and atomic.
Behavior specifications serve as:
- design documentation
- onboarding material
- test scaffolding
- assistant prompts
- refactoring safety nets
They are the most important documents in each game folder.
These patterns can be copied into new games as needed.
Given an entity with position and velocity
When time advances
Then its position changes by velocity multiplied by elapsed time
Given an entity with angular velocity
When time advances
Then its rotation changes accordingly
Given an entity outside world bounds
When wrapping is applied
Then it reappears on the opposite side
Given two entities with overlapping collision radii
When a collision check occurs
Then both are marked for removal
Given the player presses the fire control
When input is processed
Then a new projectile appears at the ship’s position
Given a weapon with a cooldown
When the player fires
Then the weapon cannot fire again until the cooldown expires
Behavior specifications are the backbone of VectorRen.
They keep the project honest, explainable, and joyful.
Write behaviors clearly.
Test them faithfully.
Let the code follow.