ecs

ExampleCommands demonstrates using command buffers to defer entity mutations. Commands are essential when modifying entities during iteration, as directly spawning or deleting entities while iterating can invalidate iterators and cause crashes. The Scheduler automatically flushes commands at the end of each frame, applying all deferred operations safely.

registry := ecs.NewComponentRegistry()
ecs.RegisterComponent[Position](registry)
ecs.RegisterComponent[Velocity](registry)
ecs.RegisterComponent[Health](registry)
storage := ecs.NewStorage(registry)

storage.Spawn(Position{X: 0, Y: 0}, Health{Current: 0, Max: 100})
storage.Spawn(Position{X: 10, Y: 10}, Health{Current: 50, Max: 100})
storage.Spawn(Position{X: 20, Y: 20}, Health{Current: 100, Max: 100})

scheduler := ecs.NewScheduler(storage)
scheduler.Register(&CleanupSystem{})

scheduler.Once(1.0)

view := ecs.NewView[struct{ *Position }](storage)
remaining := 0
for range view.Iter() {
	remaining++
}
fmt.Printf("Remaining entities: %d\n", remaining)

Output:

Queued 1 dead entities for deletion
Remaining entities: 2

ExampleCommands_spawning shows using commands to spawn entities during iteration. This is common for systems that need to create projectiles, particles, or other entities based on existing entity state. Commands ensure spawning happens after iteration completes, preventing iterator invalidation.

registry := ecs.NewComponentRegistry()
ecs.RegisterComponent[Position](registry)
ecs.RegisterComponent[Velocity](registry)
ecs.RegisterComponent[ShootTimer](registry)
storage := ecs.NewStorage(registry)

storage.Spawn(
	Position{X: 10, Y: 10},
	Velocity{DX: 1, DY: 0},
	ShootTimer{TimeUntilShot: 0},
)
storage.Spawn(
	Position{X: 20, Y: 20},
	Velocity{DX: 0, DY: 1},
	ShootTimer{TimeUntilShot: 5},
)

scheduler := ecs.NewScheduler(storage)
scheduler.Register(&ShootingSystem{})

scheduler.Once(1.0)

view := ecs.NewView[struct {
	*Position
	*Velocity
}](storage)
count := 0
for range view.Iter() {
	count++
}
fmt.Printf("Total entities with velocity: %d\n", count)

Output:

Spawned projectile at (10, 10)
Total entities with velocity: 3

ExampleEntityRef demonstrates using EntityRefs to maintain stable references to entities. Unlike EntityIds which can become invalid when entities move between archetypes or are deleted, EntityRefs remain valid and automatically track entities as they move. This makes them ideal for storing relationships between entities in components.

registry := ecs.NewComponentRegistry()
ecs.RegisterComponent[Position](registry)
ecs.RegisterComponent[Velocity](registry)
storage := ecs.NewStorage(registry)

target := storage.Spawn(Position{X: 100, Y: 100})
targetRef := storage.CreateEntityRef(target)

targetId, ok := storage.ResolveEntityRef(targetRef)
if ok {
	targetPos := ecs.ReadComponent[Position](storage, targetId)
	fmt.Printf("Target at (%.0f, %.0f)\n", targetPos.X, targetPos.Y)
}

target = storage.AddComponent(target, Velocity{DX: 0, DY: 0})

targetId, ok = storage.ResolveEntityRef(targetRef)
if ok {
	targetPos := ecs.ReadComponent[Position](storage, targetId)
	fmt.Printf("Target moved archetypes, still at (%.0f, %.0f)\n", targetPos.X, targetPos.Y)
}

storage.Delete(target)
_, ok = storage.ResolveEntityRef(targetRef)
fmt.Printf("Target deleted, ref valid: %v\n", ok)

Output:

Target at (100, 100)
Target moved archetypes, still at (100, 100)
Target deleted, ref valid: false

ExampleEntityRef_relationshipComponent shows using EntityRefs within components to create relationships between entities. This pattern is common for AI targets, parent-child hierarchies, or any other entity-to-entity relationships that need to survive archetype changes and entity deletions.

registry := ecs.NewComponentRegistry()
ecs.RegisterComponent[Position](registry)
ecs.RegisterComponent[FollowerAI](registry)
storage := ecs.NewStorage(registry)

leader := storage.Spawn(Position{X: 50, Y: 50})
leaderRef := storage.CreateEntityRef(leader)

storage.Spawn(
	Position{X: 40, Y: 40},
	FollowerAI{Target: leaderRef},
)
storage.Spawn(
	Position{X: 60, Y: 40},
	FollowerAI{Target: leaderRef},
)

fmt.Println("Followers tracking leader:")
view := ecs.NewView[struct {
	*Position
	*FollowerAI
}](storage)

for item := range view.Iter() {
	if targetId, ok := storage.ResolveEntityRef(item.FollowerAI.Target); ok {
		targetPos := ecs.ReadComponent[Position](storage, targetId)
		fmt.Printf("Follower at (%.0f, %.0f) following target at (%.0f, %.0f)\n",
			item.Position.X, item.Position.Y, targetPos.X, targetPos.Y)
	}
}

storage.Delete(leader)

fmt.Println("\nAfter leader deleted:")
for item := range view.Iter() {
	if _, ok := storage.ResolveEntityRef(item.FollowerAI.Target); !ok {
		fmt.Printf("Follower at (%.0f, %.0f) lost its target\n",
			item.Position.X, item.Position.Y)
	}
}

Output:

Followers tracking leader:
Follower at (40, 40) following target at (50, 50)
Follower at (60, 40) following target at (50, 50)

After leader deleted:
Follower at (40, 40) lost its target
Follower at (60, 40) lost its target

ExampleQuery demonstrates using queries for high-performance iteration. Unlike Views, Queries cache the list of matching archetypes, which provides a significant performance boost for repeated iteration, as the set of matching archetypes doesn't need to be re-calculated each time.

registry := ecs.NewComponentRegistry()
ecs.RegisterComponent[Position](registry)
ecs.RegisterComponent[Velocity](registry)
ecs.RegisterComponent[Health](registry)
storage := ecs.NewStorage(registry)

storage.Spawn(Position{X: 0, Y: 0}, Velocity{DX: 1, DY: 0})
storage.Spawn(Position{X: 10, Y: 10}, Velocity{DX: 0, DY: 1}, Health{Current: 100, Max: 100})
storage.Spawn(Position{X: 20, Y: 20}, Velocity{DX: -1, DY: -1})

query := ecs.NewQuery[struct {
	*Position
	*Velocity
}](storage)

type result struct {
	x, y, newX, newY float32
}
results := make([]result, 0)
for item := range query.Iter() {
	newX := item.Position.X + item.Velocity.DX
	newY := item.Position.Y + item.Velocity.DY
	results = append(results, result{item.Position.X, item.Position.Y, newX, newY})
}

for i := 0; i < len(results); i++ {
	for j := i + 1; j < len(results); j++ {
		if results[i].x > results[j].x {
			results[i], results[j] = results[j], results[i]
		}
	}
}

fmt.Println("Moving entities:")
for _, r := range results {
	fmt.Printf("Position (%.0f, %.0f) -> (%.0f, %.0f)\n", r.x, r.y, r.newX, r.newY)
}

Output:

Moving entities:
Position (0, 0) -> (1, 0)
Position (10, 10) -> (10, 11)
Position (20, 20) -> (19, 19)

ExampleScheduler demonstrates building a game loop with multiple systems. The Scheduler manages system execution order, automatically initializes Query fields, executes queries each frame, and flushes command buffers. Systems are executed in registration order, and all queries are synchronized before any system runs.

package main

import (
	"fmt"

	"github.com/plus3/ooftn/ecs"
)

type Transform struct {
	X, Y float32
}

type Speed struct {
	DX, DY float32
}

type Hitpoints struct {
	Current, Max int
}

type PhysicsSystem struct {
	Entities ecs.Query[struct {
		*Transform
		*Speed
	}]
}

func (s *PhysicsSystem) Execute(frame *ecs.UpdateFrame) {
	for entity := range s.Entities.Iter() {
		entity.Transform.X += entity.Speed.DX * float32(frame.DeltaTime)
		entity.Transform.Y += entity.Speed.DY * float32(frame.DeltaTime)
	}
}

type HealingSystem struct {
	Entities  ecs.Query[struct{ *Hitpoints }]
	RegenRate float32
}

func (s *HealingSystem) Execute(frame *ecs.UpdateFrame) {
	for entity := range s.Entities.Iter() {
		if entity.Hitpoints.Current < entity.Hitpoints.Max {
			entity.Hitpoints.Current += int(s.RegenRate * float32(frame.DeltaTime))
			if entity.Hitpoints.Current > entity.Hitpoints.Max {
				entity.Hitpoints.Current = entity.Hitpoints.Max
			}
		}
	}
}

func main() {
	registry := ecs.NewComponentRegistry()
	ecs.RegisterComponent[Transform](registry)
	ecs.RegisterComponent[Speed](registry)
	ecs.RegisterComponent[Hitpoints](registry)
	storage := ecs.NewStorage(registry)

	storage.Spawn(
		Transform{X: 0, Y: 0},
		Speed{DX: 10, DY: 5},
		Hitpoints{Current: 80, Max: 100},
	)
	storage.Spawn(
		Transform{X: 100, Y: 100},
		Speed{DX: -5, DY: -5},
		Hitpoints{Current: 50, Max: 100},
	)

	scheduler := ecs.NewScheduler(storage)
	scheduler.Register(&PhysicsSystem{})
	scheduler.Register(&HealingSystem{RegenRate: 10})

	scheduler.Once(1.0)

	view := ecs.NewView[struct {
		*Transform
		*Hitpoints
	}](storage)

	fmt.Println("After one frame:")
	for item := range view.Iter() {
		fmt.Printf("Position: (%.0f, %.0f), Health: %d/%d\n",
			item.Transform.X, item.Transform.Y,
			item.Hitpoints.Current, item.Hitpoints.Max)
	}

}

Output:

After one frame:
Position: (10, 5), Health: 90/100
Position: (95, 95), Health: 60/100

ExampleScheduler_withSingletons demonstrates using singleton components in systems. Singleton fields are automatically initialized by the Scheduler, just like Query fields. This provides efficient access to global state without the iteration overhead of queries.

package main

import (
	"fmt"

	"github.com/plus3/ooftn/ecs"
)

type Transform struct {
	X, Y float32
}

type GameTime struct {
	TotalFrames int
	TotalTime   float64
}

type TimeTracker struct {
	Entities ecs.Query[struct{ *Transform }]
	GameTime ecs.Singleton[GameTime]
}

func (s *TimeTracker) Execute(frame *ecs.UpdateFrame) {
	gameTime := s.GameTime.Get()
	gameTime.TotalFrames++
	gameTime.TotalTime += frame.DeltaTime
}

type ScoreTracker struct {
	Points int
}

type ScoreSystem struct {
	Entities ecs.Query[struct{ *Transform }]
	Score    ecs.Singleton[ScoreTracker]
}

func (s *ScoreSystem) Execute(frame *ecs.UpdateFrame) {
	count := 0
	for range s.Entities.Iter() {
		count++
	}
	s.Score.Get().Points += count * 10
}

func main() {
	registry := ecs.NewComponentRegistry()
	ecs.RegisterComponent[Transform](registry)
	storage := ecs.NewStorage(registry)

	// Initialize singletons
	ecs.NewSingleton[GameTime](storage, GameTime{TotalFrames: 0, TotalTime: 0})
	ecs.NewSingleton[ScoreTracker](storage, ScoreTracker{Points: 0})

	// Spawn entities
	storage.Spawn(Transform{X: 0, Y: 0})
	storage.Spawn(Transform{X: 10, Y: 10})
	storage.Spawn(Transform{X: 20, Y: 20})

	// Create scheduler with systems that use singletons
	scheduler := ecs.NewScheduler(storage)
	scheduler.Register(&TimeTracker{})
	scheduler.Register(&ScoreSystem{})

	// Run for 3 frames
	scheduler.Once(0.016)
	scheduler.Once(0.016)
	scheduler.Once(0.016)

	// Check singleton values
	var gameTime *GameTime
	storage.ReadSingleton(&gameTime)
	fmt.Printf("Frames: %d, Time: %.3f\n", gameTime.TotalFrames, gameTime.TotalTime)

	var score *ScoreTracker
	storage.ReadSingleton(&score)
	fmt.Printf("Score: %d points\n", score.Points)

}

Output:

Frames: 3, Time: 0.048
Score: 90 points

ExampleSingleton_multipleReferences shows that multiple Singleton instances reference the same underlying data.

package main

import (
	"fmt"

	"github.com/plus3/ooftn/ecs"
)

type GameScore struct {
	Points int
	Level  int
}

func main() {
	registry := ecs.NewComponentRegistry()
	storage := ecs.NewStorage(registry)

	// Create first singleton reference
	score1 := ecs.NewSingleton[GameScore](storage, GameScore{Points: 0, Level: 1})
	fmt.Printf("Score1: %d points, Level %d\n", score1.Get().Points, score1.Get().Level)

	// Modify via first reference
	score1.Get().Points = 100
	score1.Get().Level = 2

	// Create second reference to same singleton
	score2 := ecs.NewSingleton[GameScore](storage)
	fmt.Printf("Score2: %d points, Level %d\n", score2.Get().Points, score2.Get().Level)

	// Both references point to the same data
	score2.Get().Points = 250
	fmt.Printf("Score1 after Score2 update: %d points\n", score1.Get().Points)

}

Output:

Score1: 0 points, Level 1
Score2: 100 points, Level 2
Score1 after Score2 update: 250 points

ExampleStorage demonstrates the basic API for managing entities and components. Storage is the core container for all entities and their component data. Components are organized by archetype - entities with the same component types share the same archetype for efficient memory layout and iteration.

registry := ecs.NewComponentRegistry()
ecs.RegisterComponent[Position](registry)
ecs.RegisterComponent[Velocity](registry)
ecs.RegisterComponent[Health](registry)
storage := ecs.NewStorage(registry)

player := storage.Spawn(
	Position{X: 10, Y: 20},
	Velocity{DX: 1, DY: 0},
	Health{Current: 100, Max: 100},
)

pos := ecs.ReadComponent[Position](storage, player)
fmt.Printf("Player spawned at (%.0f, %.0f)\n", pos.X, pos.Y)

pos.X = 15
pos.Y = 25
fmt.Printf("Player moved to (%.0f, %.0f)\n", pos.X, pos.Y)

storage.Delete(player)
fmt.Println("Player deleted")

Output:

Player spawned at (10, 20)
Player moved to (15, 25)
Player deleted

ExampleStorage_addRemoveComponents shows how entity archetypes change when components are added or removed. When an entity's components change, it moves to a different archetype that matches its new component set.

registry := ecs.NewComponentRegistry()
ecs.RegisterComponent[Position](registry)
ecs.RegisterComponent[Velocity](registry)
ecs.RegisterComponent[Health](registry)
storage := ecs.NewStorage(registry)

entity := storage.Spawn(Position{X: 0, Y: 0})

hasVel := storage.HasComponent(entity, reflect.TypeOf(Velocity{}))
fmt.Printf("Has velocity: %v\n", hasVel)

entity = storage.AddComponent(entity, Velocity{DX: 5, DY: 3})
vel := ecs.ReadComponent[Velocity](storage, entity)
fmt.Printf("Has velocity: %v (%.0f, %.0f)\n", vel != nil, vel.DX, vel.DY)

entity = storage.AddComponent(entity, Health{Current: 50, Max: 50})
health := ecs.ReadComponent[Health](storage, entity)
fmt.Printf("Has health: %v (%d/%d)\n", health != nil, health.Current, health.Max)

entity = storage.RemoveComponent(entity, reflect.TypeOf(Velocity{}))
hasVel = storage.HasComponent(entity, reflect.TypeOf(Velocity{}))
fmt.Printf("Has velocity: %v\n", hasVel)

Output:

Has velocity: false
Has velocity: true (5, 3)
Has health: true (50/50)
Has velocity: false

ExampleView demonstrates using Views for flexible entity queries and spawning. Views provide a way to query entities with specific component combinations and optionally spawn new entities. Unlike Queries, Views don't require a Scheduler and perform iteration on-demand, making them ideal for one-off queries, tools, or situations where you need to query entities outside of a system.

registry := ecs.NewComponentRegistry()
ecs.RegisterComponent[Position](registry)
ecs.RegisterComponent[Velocity](registry)
ecs.RegisterComponent[Health](registry)
storage := ecs.NewStorage(registry)

player := storage.Spawn(
	Position{X: 10, Y: 20},
	Velocity{DX: 1, DY: 0},
	Health{Current: 100, Max: 100},
)

view := ecs.NewView[struct {
	*Position
	*Velocity
}](storage)

if item := view.Get(player); item != nil {
	fmt.Printf("Player at (%.0f, %.0f) moving (%.0f, %.0f)\n",
		item.Position.X, item.Position.Y, item.Velocity.DX, item.Velocity.DY)
}

Output:

Player at (10, 20) moving (1, 0)

ExampleView_optional demonstrates using optional components in views. Optional components allow a single view to match entities that may or may not have certain components. This is useful for systems that need to handle both cases, like rendering entities with optional visual effects or processing entities with optional AI components.

registry := ecs.NewComponentRegistry()
ecs.RegisterComponent[Position](registry)
ecs.RegisterComponent[Velocity](registry)
ecs.RegisterComponent[Health](registry)
storage := ecs.NewStorage(registry)

storage.Spawn(Position{X: 10, Y: 10}, Velocity{DX: 1, DY: 0}, Health{Current: 50, Max: 100})
storage.Spawn(Position{X: 20, Y: 20}, Velocity{DX: 0, DY: 1}, Health{Current: 75, Max: 100})
storage.Spawn(Position{X: 30, Y: 30}, Velocity{DX: -1, DY: 0})

view := ecs.NewView[struct {
	Position *Position
	Velocity *Velocity
	Health   *Health `ecs:"optional"`
}](storage)

fmt.Println("All moving entities:")
for item := range view.Iter() {
	if item.Health != nil {
		fmt.Printf("Entity at (%.0f, %.0f) with health %d/%d\n",
			item.Position.X, item.Position.Y, item.Health.Current, item.Health.Max)
	} else {
		fmt.Printf("Invulnerable entity at (%.0f, %.0f)\n", item.Position.X, item.Position.Y)
	}
}

Output:

All moving entities:
Entity at (10, 10) with health 50/100
Entity at (20, 20) with health 75/100
Invulnerable entity at (30, 30)