Repository navigation
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/v3GOKe requires Go 1.27+.
- 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, fromgithub.com/kjkrol/uid— GOKe's only external engine dependency) detect stale references after an entity is removed, and reserve 8 bits a host library can repurpose as its own per-entity tag. See Architecture for both. -
Deferred structural changes:
CmdBufqueues add/remove component and entity removal during a tick; changes apply at explicitSync()points, so parallel systems never race. -
Batch or single-entity structural edits:
Editor/ValueEditor/Removermigrate a wholeQuery-matched chunk in one pass;CmdBuf.AddOne/RemoveOne/RemoveCompOnehandle one entity reached without a query — see Bulk Operations and When to Use Them. -
World persistence:
Pause/Save/Loadround-trip the whole world — components, archetypes, entity identity — to a file; components are matched by name on load, not registration order. See Persistence: Save and Load. -
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 gram (formerly gokebiten), a companion game engine over GOKe and Ebitengine — a world of moving boxes, collisions, sight, a board with pathfinding — with runnable demos, one of them driving thousands of colliding AABBs.
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 ecs.RegComp[T]()
|
| Component handle | Comp[T] |
Typed handle to a component column; reused across Factory, Query, Editor
|
| System construction context | *SysInit |
The only way to get NewFactory/NewQueryBuilder/RegComp — construction flows through systems, not *ECS directly |
| Bulk entity creation |
*Factory (via si.NewFactory(...)) |
Bulk entity creation for one archetype, chunk-based writes |
| Entity query |
*Query (via si.NewQueryBuilder(...).Build()) |
Filters entities by component mask; iterate via All/Pick, or look up one via Seek/SeekH
|
| Batch structural edit |
*Editor / *ValueEditor / *Remover (via query.NewEditorBuilder(...).Build(), etc.) |
Batch add/remove components or entities for a Query-matched chunk in one migration |
| Per-tick logic unit |
System (interface) / SystemFn (struct) |
A unit of per-tick logic; SystemFn{OnInit, OnUpdate} covers most cases without a named type |
| Structural change buffer | *goke.CmdBuf |
Buffers structural changes raised inside a system; flushed on ctx.Sync()
|
| Execution plan |
Plan (func, via ecs.SetPlan(...)) |
Declares execution order: ctx.Run, ctx.RunParallel, ctx.Sync
|
| System/component bundle |
Module (interface, via ecs.RegModule(...)) |
Bundles a set of systems and the components they own behind one value |
- Architecture — how GOKe's internal packages are layered, and what each one depends on
- 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 -
Bulk Operations and When to Use Them —
Editor/ValueEditor/RemovervsCmdBuf.AddOne/RemoveOne, and how to tell which one a given piece of code needs - Persistence: Save and Load — saving and restoring the whole world, and how components are matched back up by name
- 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/v3.
-
Runnable examples — examples/ in the repository (
simple-demo,mini-demo,parallel-demo,module-demo,single-entity-demo,bulk-edit-demo,persistence-demo). - gram — github.com/kjkrol/gram, the Ebitengine game engine built on GOKe, with a collision-simulation demo.
Keywords: Go ECS, Golang Entity Component System, Data-Oriented Design Go, Archetype ECS, GOKe Engine.