ecs-design

ECS Design Principles

Design guidance for jecs in Roblox.

Core Mental Model

Think of ECS as a columnar database:

Database	ECS
Table	Archetype (unique component combination)
Column	Component type
Row	Entity
Query	System iteration

Design question: "Would I create a separate database column for this?"

Core References

Topic	Description	Reference
Database Model	ECS as columnar database, normalization, fragmentation	core-database-model
Query Design	Multi-entity queries, constraint decomposition, traversal	core-query-design

Best Practices

Topic	Description	Reference
Component Design	Granularity decisions, when to split/combine, tags vs data	best-practices-components
System Design	Single responsibility, avoiding work, ordering, data flow	best-practices-systems
Entity Design	When to create entities, lazy creation, scaling patterns	best-practices-entities

Quick Decision Guide

Question	Answer
Should this be an entity?	Only if it needs per-instance state that changes over time
Split or combine?	"Is there a system that needs A but not B?"
Tag or data component?	Tags for stable classification (free to add/remove), data for state
Relationship or entity ref?	Relationship if reverse lookup needed, entity member otherwise
Is fragmentation bad?	Only if thousands of archetypes AND you query broadly
When does DOD matter?	Thousands of entities, per-frame, CPU-bound

Common Mistakes

Mistake	Why it's bad	Fix
Monolithic components	Cache waste, tight coupling	Split by access pattern
Over-atomic components	Query complexity, invalid states	Combine semantic units
Frequent add/remove on large entities	Copies all component data	Mutate data component instead
Relationships for every link	Fragmentation without benefit	Use entity members for forward-only
Cached query inside system	Creates new cache every frame	Create cached queries at module scope

Key Principles

1. Components by access pattern — Group data that systems need together
2. Archetype transitions copy data — Adding/removing components copies all data to new archetype; cheap on small entities, expensive on large ones
3. Entity members vs relationships — Use entity members for forward lookup, relationships for reverse lookup or grouping
4. Cache queries at module scope — Never call .cached() inside a system
5. Filter in query — Use with/without, not code conditionals
6. Fragmentation can help — Relationships enable efficient grouped queries