ecs

type BaseSystemState ¶

type BaseSystemState struct {
	// contains filtered or unexported fields
}

BaseSystemState is a barebones system state field that can be embedded in your custom system state types to allow your systems to access the world state. It provides a raw event emitter that can be used to emit custom events.

Example:

// Define your system state by embedding BaseState.
type DebugSystemState struct {
    ecs.BaseSystemState
    // Other fields...
}

// Your system function receives a pointer to your system state.
func DebugSystem(state *DebugSystemState) error {
    state.EmitRawEvent(EventKindCustom, "my custom event")
    return nil
}

func (b *BaseSystemState) EmitRawEvent(kind EventKind, payload any)

func (b *BaseSystemState) UnsafeWorldState() *worldState

type Command ¶

type Command interface {
	micro.ShardCommand
}

Command is the interface that all commands must implement. Commands are predefined user actions that are handled by systems.

type CommandContext ¶

type CommandContext[T Command] struct {
	// contains filtered or unexported fields
}

CommandContext wraps a micro.Command and provides typed access to command data and metadata.

func (c CommandContext[T]) Payload() T

func (c CommandContext[T]) Persona() string

type CommandID ¶

type CommandID uint32

CommandID is a unique identifier for a command type.

type Component ¶

type Component interface {
	// Name returns a unique string identifier for the component type.
	// This should be consistent across program executions.
	Name() string
}

Component is the interface that all components must implement. Components are pure data containers that can be attached to entities.

type Contains ¶

type Contains[T any] struct {
	// contains filtered or unexported fields
}

Contains provides a search that matches archetypes containing all specified component types, potentially along with additional components.

Example:

type MovementSystemState struct {
    Movers ecs.Contains[struct {
        Position ecs.Ref[Position]
        Velocity ecs.Ref[Velocity]
    }]
    // Other fields...
}

// Your system function receives a pointer to your system state.
func MovementSystem(state *MovementSystemState) error {
    for entity, mover := range state.Movers.Iter() {
        // Process entity and compnents.
    }
    return nil
}

func (s *Contains) Create() (EntityID, T)

entity, err := state.Mob.Create(Health{Value: 100}, Position{X: 0, Y: 0})
if err != nil {
    state.Logger().Error().Err(err).Msg("Failed to create entity")
}
// Use entity...

func (s *Contains) Destroy(eid EntityID) bool

func (c *Contains[T]) Iter() iter.Seq2[EntityID, T]

for _, mover := range state.Movers.Iter() {
    pos := mover.Position.Get()
    vel := mover.Velocity.Get()
    mover.Position.Set(Position{X: pos.X + vel.X, Y: pos.Y + vel.Y})
}

type EntityID ¶

type EntityID uint32

EntityID is a unique identifier for an entity.

func Create(ws *worldState) EntityID

type Event ¶

type Event = Command

Event is an interface that all events must implement. Events are packets of information that are sent from systems to the outside world.

type EventKind ¶

type EventKind uint8

EventKind is a type that represents the kind of event.

const (
	// EventKindDefault is the default event kind.
	EventKindDefault EventKind = 1
)

type Exact ¶

type Exact[T any] struct {
	// contains filtered or unexported fields
}

Exact provides a search that matches archetypes containing exactly the specified component types, without any additional components.

Example:

type PlayerSystemState struct {
    Players ecs.Exact[struct {
        Tag    ecs.Ref[PlayerTag]
        Health ecs.Ref[Health]
    }]
    // Other fields...
}

// Your system function receives a pointer to your system state.
func PlayerSystem(state *PlayerSystemState) error {
    for entity, player := range state.Players.Iter() {
        // Process entity and compnents.
    }
    return nil
}

func (s *Exact) Create() (EntityID, T)

entity, err := state.Mob.Create(Health{Value: 100}, Position{X: 0, Y: 0})
if err != nil {
    state.Logger().Error().Err(err).Msg("Failed to create entity")
}
// Use entity...

func (s *Exact) Destroy(eid EntityID) bool

func (c *Exact[T]) Iter() iter.Seq2[EntityID, T]

for _, player := range state.Players.Iter() {
    health := player.Health.Get()
    player.Health.Set(Health{HP: health.HP + 100})
}

type RawEvent ¶

type RawEvent struct {
	Kind    EventKind // The kind of event
	Payload any       // The payload of the event
}

RawEvent is the format of ECS output. It has a kind and a payload. The kind determines the type of event contained in the payload. Users of ECS can define custom event kinds and handle them in their own event handlers.

type Ref ¶

type Ref[T Component] struct {
	// contains filtered or unexported fields
}

Ref provides a type-safe handle to a component on an entity.

func (r *Ref[T]) Get() T

for _, player := range state.Players.Iter() {
    health := player.Health.Get()
}

func (r *Ref[T]) Set(component T)

for _, player := range state.Players.Iter() {
    player.Health.Set(Health{HP: 100})
}

type SearchMatch ¶

type SearchMatch string

SearchMatch is the type of match to use for the search.

const (
	// MatchExact matches entities that have exactly the specified components.
	MatchExact SearchMatch = "exact"
	// MatchContains matches entities that contains the specified components, but may have other
	// components as well.
	MatchContains SearchMatch = "contains"
)

type SearchParam ¶

type SearchParam struct {
	Find  []string    // List of component names to search for
	Match SearchMatch // A match type to use for the search
	Where string      // Optional expr language string to filter the results.
}

SearchParam contains paramters for a search query. We use expr lang for the where clause to filter the entities, please refer to its documentation for more details: https://expr-lang.org/docs/getting-started.

type System ¶

type System[T any] func(state *T) error

System is a function that contains game logic.

type SystemEvent ¶

type SystemEvent = Command

SystemEvent is an interface that all system events must implement. SystemEvents are events emitted by a system to be handled by another system.

type SystemHook ¶

type SystemHook uint8

SystemHook defines when a system should be executed in the update cycle.

const (
	// PreUpdate runs before the main update.
	PreUpdate SystemHook = 0
	// Update runs during the main update phase.
	Update SystemHook = 1
	// PostUpdate runs after the main update.
	PostUpdate SystemHook = 2
	// Init runs once during world initialization.
	Init SystemHook = 3
)

type SystemOption ¶

type SystemOption func(*systemConfig)

SystemOption is a function that configures a SystemConfig.

func WithHook(hook SystemHook) SystemOption

func WithModifier(fieldType systemStateFieldType, fn func(any) error) SystemOption

type WithCommand ¶

type WithCommand[T Command] struct {
	// contains filtered or unexported fields
}

WithCommand is a generic system state field that allows systems to receive commands of type T. The commands are automatically registered when the system is registered.

Example:

// Define a command type for spawning players.
type SpawnPlayer struct{ Nickname string }

func (SpawnPlayer) Name() string { return "spawn-player" }

// Define your system state.
type SpawnSystemState struct {
    SpawnPlayerCommands ecs.WithCommand[SpawnPlayer]
    // Other fields...
}

// Your system function receives a pointer to your system state.
func SpawnSystem(state *SpawnSystemState) error {
    for cmd := range state.SpawnPlayerCommands.Iter() {
        persona := cmd.Persona()
        spawnData := cmd.Payload()
        // Process spawn commands based on persona and payload.
    }
    return nil
}

func (m *WithCommand[T]) Iter() iter.Seq[CommandContext[T]]

for cmd := range state.SpawnPlayerCommands.Iter() {
    persona := cmd.Persona()
    payload := cmd.Payload()
    // Process each command
}

type WithEvent ¶

type WithEvent[T Event] struct {
	// contains filtered or unexported fields
}

WithEvent is a generic system state field that allows systems to emit events of type T.

Example:

// Define an event type for level ups.
type LevelUp struct{ Nickname string }

func (LevelUp) Name() string { return "level-up" }

type LevelUpSystemState struct {
    LevelUpEvents ecs.WithEvent[LevelUp]
    // Other fields...
}

// Your system function receives a pointer to your system state.
func LevelUpSystem(state *LevelUpSystemState) error {
    // Emit a level up event.
    state.LevelUpEvents.Emit(LevelUp{Nickname: "Player1"})
    return nil
}

func (e *WithEvent[T]) Emit(event T)

state.LevelUpEvents.Emit(LevelUp{Nickname: "Player1"})

type WithSystemEventEmitter ¶

type WithSystemEventEmitter[T SystemEvent] struct {
	// contains filtered or unexported fields
}

WithSystemEventEmitter is a generic system state field that allows systems to emit system events of type T. System events are automatically registered when the system is registered.

Example:

// Define a system event for player deaths.
type PlayerDeath struct{ Nickname string }

func (PlayerDeath) Name() string { return "player-death" }

type CombatSystemState struct {
    PlayerDeathSystemEvents ecs.WithSystemEventEmitter[PlayerDeath]
    // Other fields...
}

// Your system function receives a pointer to your system state.
func CombatSystem(state *CombatSystemState) error {
    // Emit a player death event to be handled in another system.
    state.PlayerDeathEvents.Emit(PlayerDeath{Nickname: "Player1"})
    return nil
}

func (s *WithSystemEventEmitter[T]) Emit(systemEvent T)

state.PlayerDeathEvents.Emit(PlayerDeath{Nickname: "Player1"})

type WithSystemEventReceiver ¶

type WithSystemEventReceiver[T SystemEvent] struct {
	// contains filtered or unexported fields
}

WithSystemEventReceiver is a generic system state field that allows systems to receive system events of type T. System events are automatically registered when the system is registered.

Example:

// Define a system event for player deaths.
type PlayerDeath struct{ Nickname string }

func (PlayerDeath) Name() string { return "player-death" }

type GraveyardSystemState struct {
    PlayerDeathSystemEvents ecs.WithSystemEventReceiver[PlayerDeath]
    // Other fields...
}

// Your system function receives a pointer to your system state.
func GraveyardSystem(state *GraveyardSystemState) error {
    // Receive system events emitted from another system.
    for systemEvent := range state.PlayerDeathSystemEvents.Iter() {
        // Process the system event.
    }
    return nil
}

func (s *WithSystemEventReceiver[T]) Iter() iter.Seq[T]

for systemEvent := range state.PlayerDeathEvents.Iter() {
    // Process each system event
}

type World ¶

type World struct {
	// contains filtered or unexported fields
}

World represents the root ECS state with double buffering support.

func NewWorld() *World

func (w *World) CustomTick(fn func(*worldState))

func (w *World) Deserialize(data []byte) error

func (w *World) InitSchedulers()

func (w *World) InitSystems() error

func (w *World) NewSearch(params SearchParam) ([]map[string]any, error)

func (w *World) Serialize() ([]byte, error)

func (w *World) Tick(commands []micro.Command) ([]RawEvent, error)