listener

Documentation

Overview

Package listener provides ecs.Listener implementations (see github.com/mlange-42/arche/ecs.Listener).

See the top level module github.com/mlange-42/arche for an overview.

🕮 Also read Arche's User Guide!

Index

• type Callback
  • func NewCallback(callback func(*ecs.World, ecs.EntityEvent), events event.Subscription, ...) Callback
  • func (l *Callback) Components() *ecs.Mask
  • func (l *Callback) Notify(w *ecs.World, e ecs.EntityEvent)
  • func (l *Callback) Subscriptions() event.Subscription
• type Dispatch
  • func NewDispatch(listeners ...ecs.Listener) Dispatch
  • func (l *Dispatch) AddListener(ls ecs.Listener)
  • func (l *Dispatch) Components() *ecs.Mask
  • func (l *Dispatch) Notify(world *ecs.World, evt ecs.EntityEvent)
  • func (l *Dispatch) Subscriptions() event.Subscription

Examples

• Callback
• Dispatch

Types

type Callback

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

Callback listener for ecs.EntityEvent.

Calls a function on events that are contained in the subscription mask.

Example

world := ecs.NewWorld()

posID := ecs.ComponentID[Position](&world)

ls := listener.NewCallback(
	func(w *ecs.World, e ecs.EntityEvent) {
		// Print the EventType bits of the event.
		fmt.Printf("   EventType: %08b\n", e.EventTypes)
	},
	// Subscribe to all events.
	event.All,
)
world.SetListener(&ls)

fmt.Println("Create entity")
e := world.NewEntity()

fmt.Println("Add component")
world.Add(e, posID)

fmt.Println("Remove component")
world.Remove(e, posID)

fmt.Println("Remove entity")
world.RemoveEntity(e)

fmt.Println("Create entity with component(s)")
e = world.NewEntity(posID)

fmt.Println("Remove entity with component(s)")
world.RemoveEntity(e)

Output:

Create entity
   EventType: 00000001
Add component
   EventType: 00000100
Remove component
   EventType: 00001000
Remove entity
   EventType: 00000010
Create entity with component(s)
   EventType: 00000101
Remove entity with component(s)
   EventType: 00001010

func NewCallback

func NewCallback(callback func(*ecs.World, ecs.EntityEvent), events event.Subscription, components ...ecs.ID) Callback

NewCallback creates a new Callback listener for the given events.

Subscribes to the specified events with changes on the specified components. If no component IDs are given, it subscribes to all components.

Note that this listener is slower than a custom ecs.Listener implementation that does not use the indirection of a callback function.

func (*Callback) Components

func (l *Callback) Components() *ecs.Mask

Components the listener subscribes to.

func (*Callback) Notify

func (l *Callback) Notify(w *ecs.World, e ecs.EntityEvent)

Notify the listener.

func (*Callback) Subscriptions

func (l *Callback) Subscriptions() event.Subscription

Subscriptions of the listener.

type Dispatch

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

Dispatch event listener.

Dispatches events to sub-listeners and manages subscription automatically, based on their settings. Sub-listeners should not alter their subscriptions or components after being added.

To make it possible for systems to add listeners, Dispatch can be added to the ecs.World as a resource.

Example

package main

import (
	"fmt"

	"github.com/mlange-42/arche/ecs"
	"github.com/mlange-42/arche/ecs/event"
	"github.com/mlange-42/arche/listener"
)

type Position struct {
	X float64
	Y float64
}

type Velocity struct {
	X float64
	Y float64
}

func main() {
	world := ecs.NewWorld()
	posID := ecs.ComponentID[Position](&world)
	velID := ecs.ComponentID[Velocity](&world)

	entityListener := listener.NewCallback(
		func(w *ecs.World, ee ecs.EntityEvent) { fmt.Println("Entity event") },
		event.EntityCreated|event.EntityRemoved,
	)
	componentListener := listener.NewCallback(
		func(w *ecs.World, ee ecs.EntityEvent) { fmt.Println("Component event on Position") },
		event.ComponentAdded|event.ComponentRemoved,
		posID, // optional restriction of subscribed components
	)

	mainListener := listener.NewDispatch(
		&entityListener,
		&componentListener,
	)

	world.SetListener(&mainListener)

	// Triggers entityListener
	e := world.NewEntity()
	// Triggers componentListener
	world.Add(e, posID)

	// Triggers entityListener and componentListener
	_ = world.NewEntity(posID)

	// Triggers entityListener but not componentListener, as it is restricted to posID
	_ = world.NewEntity(velID)
}

Output:

Entity event
Component event on Position
Entity event
Component event on Position
Entity event

func NewDispatch

func NewDispatch(listeners ...ecs.Listener) Dispatch

NewDispatch returns a new Dispatch listener with the given sub-listeners.

func (*Dispatch) AddListener

func (l *Dispatch) AddListener(ls ecs.Listener)

AddListener adds a sub-listener to this listener.

func (*Dispatch) Components

func (l *Dispatch) Components() *ecs.Mask

Components the listener subscribes to.

func (*Dispatch) Notify

func (l *Dispatch) Notify(world *ecs.World, evt ecs.EntityEvent)

Notify the listener.

func (*Dispatch) Subscriptions

func (l *Dispatch) Subscriptions() event.Subscription

Subscriptions of the listener.