← All decisions

#0004 · 2026-08-07 · accepted · architecture

Model game entities as a plain immutable List(Entity) in pe, not an ECS

data-modelpeecs

Context

Needed a representation for game entities/state in the physics engine (pe). ECS (entity-component-system) is the standard pattern in mutable-OOP engines, optimizing for cache-friendly bulk iteration.

Options considered

ECS (entity-component-system) — rejected
Buys cache-friendly bulk access at the cost of real complexity (entity IDs, component storage indirection) -- but the bulk-layout problem this project actually has is already solved differently, at the cs FFI boundary (List(Vector2) -> Float32Array), not in pe's own data model.
Plain immutable record (Entity) in a List(Entity) — chosen
Simplest thing that composes with the already-built cs.vector2_batch API shape, and matches Gleam/Elm idiom for small-to-medium state.

Decision

Entity is a plain Gleam record (position, velocity, radius); pe.Model holds entities: List(Entity).

Verification

N/A at decision time (a design choice, not something to test in isolation) -- validated indirectly by every physics module built on top of it working and testing cleanly.

Consequences

Revisit only if entity *type* diversity (many different component combinations), not just entity count, becomes a real pain point -- count is already cs's problem to solve, not pe's.

References