Ark

<div align="center" width="100%"> <a href="https://github.com/mlange-42/ark"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mlange-42/ark/refs/heads/main/docs/static/images/ark-logo-text-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/mlange-42/ark/refs/heads/main/docs/static/images/ark-logo-text-light.svg"> <img alt="Ark Logo" src="https://raw.githubusercontent.com/mlange-42/ark/refs/heads/main/docs/static/images/ark-logo-text-light.svg"> </picture> </a>

Ark is an archetype-based Entity Component System (ECS) for Go.

——

Features   •   Installation   •   Usage   •   Tools

</div>

Features

• Designed for performance and highly optimized. See the Benchmarks.
• Well-documented, type-safe API, and a comprehensive User guide.
• Entity relationships as a first-class feature.
• Extensible event system with filtering and custom event types.
• Fast batch operations for mass manipulation.
• No systems. Just queries. Use your own structure (or the Tools).
• World serialization and deserialization with ark-serde.
• Zero dependencies, 100% test coverage.

Installation

To use Ark in a Go project, run:

go get github.com/mlange-42/ark

Usage

Below is the classical Position/Velocity example that every ECS shows in the docs.

See the User Guide, API docs and examples for details.

package main

import (
	"math/rand/v2"
	"github.com/mlange-42/ark/ecs"
)

// Position component
type Position struct {
	X, Y float64
}

// Velocity component
type Velocity struct {
	DX, DY float64
}

func main() {
	// Create a new World
	world := ecs.NewWorld()

	// Create a component mapper
	// Save mappers permanently and re-use them for best performance
	mapper := ecs.NewMap2[Position, Velocity](world)

	// Create entities with components
	for range 1000 {
		_ = mapper.NewEntity(
			&Position{X: rand.Float64() * 100, Y: rand.Float64() * 100},
			&Velocity{DX: rand.NormFloat64(), DY: rand.NormFloat64()},
		)
	}

	// Create a filter
	// Save filters permanently and re-use them for best performance
	filter := ecs.NewFilter2[Position, Velocity](world)

	// Time loop
	for range 5000 {
		// Get a fresh query and iterate it
		query := filter.Query()
		for query.Next() {
			// Component access through the Query
			pos, vel := query.Get()
			// Update component fields
			pos.X += vel.DX
			pos.Y += vel.DY
		}
	}
}

Tools

• ark-serde provides JSON serialization and deserialization for Ark's World.
• ark-tools provides systems, a scheduler, and other useful stuff for Ark.
• ark-pixel provides OpenGL graphics and live plots via the Pixel game engine.

Cite as

Lange, M. & contributors (2025): Ark – An archetype-based Entity Component System for Go. DOI: 10.5281/zenodo.14994239, GitHub repository: https://github.com/mlange-42/ark

License

Ark and all its sources and documentation are distributed under the MIT license and the Apache 2.0 license, as your options.