-
Notifications
You must be signed in to change notification settings - Fork 1
Home
GOKe is a type-safe, archetype-based Entity Component System (ECS) for Go. It uses a Structure of Arrays (SoA) storage model and Data-Oriented Design principles for cache-friendly iteration and zero-allocation hot paths.
go get github.com/kjkrol/goke/v2GOKe requires Go 1.26+.
- Archetype-Based Storage (SoA): entities are grouped by component composition; components of the same type live in contiguous memory columns.
- Zero-allocation hot paths: chunk-based storage with direct pointer arithmetic — no GC pressure during iteration or component access.
-
Type-safe generics, no reflection at runtime:
Comp[T]gives typed read/write access;RegComp[T]is the only placereflectis used, once per type at startup. - O(1) component lookup: entity-to-storage is a direct array index, not a hash map.
-
Safe entity recycling: 64-bit generational IDs (
uid.UID64) detect stale references after an entity is removed. -
Deferred structural changes:
CmdBufqueues add/remove component and entity removal during a tick; changes apply at explicitSync()points, so parallel systems never race. -
Built-in scheduler: a declarative
Planwires systems into sequential/parallel execution with synchronization points.
GOKe pairs naturally with rendering engines such as Ebitengine: GOKe owns world state, logic, and large numbers of entities (bullets, particles, enemies); the renderer reads it each frame. See examples/ebiten-demo for a collision simulation driving thousands of AABBs at 120 TPS.
Crowd simulations, particle systems, agent-based models — the linear SoA layout keeps memory tightly packed, minimizing cache misses as entity counts grow.
Zero allocations in the hot path means no GC-induced latency spikes — relevant for real-time telemetry or other deterministic-latency workloads.
Constant-time archetype masks make it cheap to filter and update large numbers of heterogeneous state objects (e.g. thousands of sensors) by their current composition.
| Concept | Type | Role |
|---|---|---|
| Entity | uid.UID64 |
A 64-bit generational ID — index + generation, recycled safely after removal |
| Component | plain Go struct | Pure data, registered once via RegComp[T]
|
Comp[T] |
generic struct | Typed handle to a component column; reused across Factory, Query, Editor
|
Factory |
ecs.NewFactory(...) |
Bulk entity creation for one archetype, chunk-based writes |
Query |
ecs.NewQueryBuilder(...).Build() |
Filters entities by component mask; iterate via All/Pick, or look up one via Seek
|
Editor |
ecs.NewEditorBuilder(...).Build() |
Adds/removes components on an existing entity in a single archetype migration |
System / SystemFn
|
interface / func | A unit of per-tick logic |
CmdBuf |
*goke.CmdBuf |
Buffers structural changes raised inside a system; flushed on ctx.Sync()
|
Plan |
ecs.SetPlan(...) |
Declares execution order: ctx.Run, ctx.RunParallel, ctx.Sync
|
- Getting Started with GOKe — installation, entities & components, queries, systems, command buffers, and a full runnable example
-
Core Concepts: Archetypes & Queries — why components live in columns, how archetypes and the archetype graph work, and what a
Queryactually matches -
Systems & Execution Planning — systems, the per-system
CmdBuf,Sync()semantics, and the parallelism rulesRunParalleldoes and doesn't enforce for you - Benchmark Results — measured cost of migrations, queries, and batch creation across population sizes, with a pointer to the full tables in BENCHMARKS.md
- README — github.com/kjkrol/goke covers performance numbers, architecture layering, and the project roadmap.
- API Reference — pkg.go.dev/github.com/kjkrol/goke/v2.
-
Runnable examples — examples/ in the repository (
simple-demo,mini-demo,parallel-demo,ebiten-demo).
Keywords: Go ECS, Golang Entity Component System, Data-Oriented Design Go, Archetype ECS, GOKe Engine.