Architecture

VectorRen games are intentionally small, transparent, and easy to understand. This document defines the architectural model shared by all VectorRen games. It is not a framework, not an engine, and not a shared runtime — it is a set of expectations that keep every game explainable for humans and Coding Assistants.

VectorRen architecture is shaped by four core beliefs:

• Each game stands alone — No shared engine, utilities, physics, or runtime.
• SVG is the renderer — The DOM is the scene graph. Transforms drive motion.
• Behavior defines architecture — Specification‑Driven Development (Given / When / Then) shapes the code.
• Clarity beats cleverness — If the architecture becomes hard to explain, it’s wrong.

The architecture exists to support readability, testability, and assistant‑friendly development.

Every VectorRen game follows three conceptual layers:

• State Layer — Pure data describing the world.
• Logic Layer — Functions that update state based on time, input, and rules.
• Rendering Layer — Functions that reflect state into the SVG scene.

These layers are conventions, not enforced abstractions — but they are followed consistently.

The state layer contains positions, velocities, rotations, timers, flags, and lists of entities.

State is explicit, minimal, serializable, deterministic, and easy to inspect and test.

State never depends on the DOM. State is the truth; the DOM is the view.

The logic layer updates state based on elapsed time, input state, collisions, timers, and world rules.

Logic is deterministic, testable, behavior‑driven, and independent of rendering.

Logic should not mutate the DOM, rely on SVG structure, or embed rendering concerns. It implements the behavior defined in Given / When / Then specs.

The rendering layer reflects state into the SVG scene using transforms for movement, classes for style, <defs> + <use> for instancing, and shallow groups for structure.

Rendering is declarative, predictable, stable, and easy to debug in DevTools. It should not contain game logic or modify state.

Every VectorRen game uses the same conceptual loop:

• Compute elapsed time
• Update state
• Render state
• Request the next frame

The loop is intentionally simple and should be readable in one sitting.

Input is handled separately from logic and rendering. It is captured once per frame, stored in state, and consumed by logic during the update step.

Input should not directly manipulate the DOM or mutate state outside the update cycle.

Entities are plain objects containing identity, position, velocity, rotation, radius, and flags.

Entities do not contain methods, DOM references, or embedded behavior. Behavior lives in the logic layer. Rendering lives in the rendering layer.

SVG is the scene graph. The architecture uses a single root <svg>, a single world <g>, one <g> per entity, transforms for motion, and classes for style.

The DOM should remain shallow, semantic, and easy to inspect.

As a game grows beyond a single file, logic naturally separates into focused modules:

src/
├── core/      ← state shape, update pipeline, entity logic
├── svg/       ← renderer, DOM helpers
├── input/     ← input capture and key mapping
└── utils/     ← collision detection, wrapping, vector math

Each module is small, single‑purpose, independently testable, and free of DOM or rendering concerns (except svg/). This layout is a convention, not a requirement. Small games may start in a single file and refactor naturally.

Behavior specifications shape the architecture. A behavior spec defines rules, expected outcomes, interactions, timing, and edge cases.

Architecture exists to satisfy behavior, not the other way around.

VectorRen is designed for human + assistant collaboration. To support this: keep files small, keep naming consistent, keep behavior explicit, avoid clever abstractions, avoid deep call stacks, and avoid hidden state.

Assistants thrive on clarity. So does VectorRen.

Avoid these architectural mistakes:

• mixing logic and rendering
• mutating DOM attributes every frame
• deep SVG nesting
• global state scattered across files
• clever abstractions that hide behavior
• random behavior without bounds
• implicit side effects

If the architecture becomes hard to explain, simplify it.

VectorRen's architecture is intentionally minimal. It exists to support clarity, behavior, and joy.

If a design choice makes the game easier to understand, it belongs here. If it makes the game harder to understand, it doesn't.

Build small.
Build sharp.
Build with intention.