Quickstart

Ark

Quickstart

This page shows how to install Ark, and gives a minimal usage example.

Finally, it points into possible directions to continue.

Installation

To use Ark in a Go project, run:

go get github.com/mlange-42/ark

Usage example

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

package main

import (
	"math/rand/v2"

	"github.com/mlange-42/ark/ecs"
)

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

// Velocity component
type Velocity struct {
	X float64
	Y 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
	for range 1000 {
		// Create a new Entity with components
		_ = mapper.NewEntity(
			&Position{X: rand.Float64() * 100, Y: rand.Float64() * 100},
			&Velocity{X: rand.NormFloat64(), Y: 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
		query := filter.Query()
		// Iterate it
		for query.Next() {
			// Component access through the Query
			pos, vel := query.Get()
			// Update component fields
			pos.X += vel.X
			pos.Y += vel.Y
		}
	}
}

What’s next?

If you ask “What is ECS?”, take a look at the great ECS FAQ by Sander Mertens, the author of the Flecs ECS.

To learn how to use Ark, read the following chapters, browse the API documentation, or take a look at the examples in the GitHub repository.

Ark Concepts