Skip to content
kjkrol edited this page Sep 23, 2026 · 7 revisions

Welcome to the GOKe Wiki

GOKe Logo

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/v3

GOKe requires Go 1.27+.

Why GOKe?

  • 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 place reflect is 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, from github.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: CmdBuf queues add/remove component and entity removal during a tick; changes apply at explicit Sync() points, so parallel systems never race.
  • Batch or single-entity structural edits: Editor/ValueEditor/Remover migrate a whole Query-matched chunk in one pass; CmdBuf.AddOne/RemoveOne/RemoveCompOne handle one entity reached without a query — see Bulk Operations and When to Use Them.
  • World persistence: Pause/Save/Load round-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 Plan wires systems into sequential/parallel execution with synchronization points.

Strategic Use Cases

🎮 Game Development

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.

🧬 High-Mass Simulations

Crowd simulations, particle systems, agent-based models — the linear SoA layout keeps memory tightly packed, minimizing cache misses as entity counts grow.

⚡ Latency-Critical Systems

Zero allocations in the hot path means no GC-induced latency spikes — relevant for real-time telemetry or other deterministic-latency workloads.

🤖 Digital Twins & IoT

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.

Core Concepts at a Glance

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

Documentation Index

Where to Look Next


Keywords: Go ECS, Golang Entity Component System, Data-Oriented Design Go, Archetype ECS, GOKe Engine.

Clone this wiki locally