How mlange-42/ark works
Project type and purpose
• Project Type: An open-source Go library implementing an archetype-based Entity Component System (ECS).
• Purpose: Provide a high-performance, zero-dependency ECS framework for Go programs, with facilities for queries, events, relationships, batching, serialization, and code-generation helpers.
File structure
• Top-level directories:
• ecs – Core library code (world, entities, components, archetypes, queries, events, resources, relations, storage)
• ecs/internal/generate – Code-generation tool to emit optimized query/exchange/filter code from templates
• examples – Usage samples demonstrating integration with game engines (e.g., Pixel), custom events, parallel queries, relations
• benchmark – Performance benchmarks and profiling code
• docs – Hugo-based user guide and API docs
• Config/build/deploy files: .github workflows for tests, benchmarks, publish; .golangci.yml for linting; go.mod/go.sum
README for additional insights
• Highlights:
• Zero dependencies, 100% test coverage, benchmarks
• Features: archetype storage, entity relationships, event system, batch operations, serialization (via ark-serde)
• Tools: ark-serde, ark-tools, ark-pixel
a. Main components (logical layers)
• API Layer: ecs.NewWorld(), entity mappers, filters, queries, event emitters
• Core ECS Engine:
– World (registry of archetypes & tables)
– Archetype Manager (grouping of component sets)
– Tables & Pools (contiguous storage of component data)
– Component Columns (typed arrays)
– ID Map & Entity Index
• Query & Filter System (generates iterators over tables)
• Event & Observer Subsystem
• Resource & Relation Manager
• Code-Generation Tool (ecs/internal/generate)
• Benchmark Suite (benchmark/)
• Documentation Site (docs/)
b. Relationships and interactions
• World holds ArchetypeManager, TableStore, EntityRegistry
• Entity creation → World → Archetype → Table → Pools → Columns
• Query/Filter → World → matching Archetype Tables → returns typed component views
• Events → EventBus in World → Observers subscribe and receive callbacks
• Relations and Resources extend World’s storage and indexing
• Code-Gen tool reads templates + API definitions → emits optimized query & exchange code → built into ecs package
• Examples import ecs API; benchmarks import ecs to gauge performance
c. Architectural patterns & design principles
• Archetype-based storage for cache-friendly data locality
• Separation of concerns: storage vs query vs events vs relations
• Code-generation to avoid reflection and maximize performance
• Zero dependencies: minimal external integration
• Highly modular: each feature (batch, events, relations) is a distinct package area
d. Key technologies & frameworks
• Go modules (go.mod)
• Hugo for documentation site
• Go’s testing & benchmarking (testing package)
• GitHub Actions for CI/CD
• Code generation via Go templates
Detail
• Code-generation as part of the build pipeline, showing templates feeding into generated .go files
• CI workflows that run tests and benchmarks—optional but useful for a comprehensive view