Documentation tweaks (#336)

* add zenodo DOI badge
* fix unitoftime/ecs link in benchmarks
* rename example `change_listener` to `events`
* extend standalone events example

.github/workflows/tests.yml

@@ -108,7 +108,7 @@ jobs:
         run: |
           go run ./examples/base
           go run ./examples/batch_ops
-          go run ./examples/change_listener
+          go run ./examples/events
           go run ./examples/filter
           go run ./examples/generic
           go run ./examples/locked_world

README.md

@@ -5,6 +5,7 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/mlange-42/arche)](https://goreportcard.com/report/github.com/mlange-42/arche)
 [![Go Reference](https://pkg.go.dev/badge/github.com/mlange-42/arche.svg)](https://pkg.go.dev/github.com/mlange-42/arche)
 [![GitHub](https://img.shields.io/badge/github-repo-blue?logo=github)](https://github.com/mlange-42/arche)
+[![DOI:10.5281/zenodo.7656484](https://zenodo.org/badge/DOI/10.5281/zenodo.7656484.svg)](https://doi.org/10.5281/zenodo.7656484)
 [![MIT license](https://img.shields.io/github/license/mlange-42/arche)](https://github.com/mlange-42/arche/blob/main/LICENSE)
 
 *Arche* is an [archetype](https://github.com/mlange-42/arche/blob/main/ARCHITECTURE.md)-based [Entity Component System](https://en.wikipedia.org/wiki/Entity_component_system) for [Go](https://go.dev/).
@@ -167,7 +168,7 @@ To the best of the author's knowledge, there are only a handful of ECS implement
 * [go-gameengine-ecs](https://github.com/marioolofo/go-gameengine-ecs)
 * [Donburi](https://github.com/yohamta/donburi)
 * [Ento](https://github.com/wwfranczyk/ento)
-* [unitoftime/ecs](github.com/unitoftime/ecs)
+* [unitoftime/ecs](https://github.com/unitoftime/ecs)
 
 Here, *Arche* is benchmarked against these implementations.
 Feel free to open an issue if you have suggestions for improvements on the benchmarking code or other engines to include.

examples/events/main.go

@@ -0,0 +1,90 @@
+// Demonstrates the use of a EntityEvent through listeners.
+package main
+
+import (
+	"fmt"
+
+	"github.com/mlange-42/arche/ecs"
+	"github.com/mlange-42/arche/ecs/event"
+	"github.com/mlange-42/arche/listener"
+)
+
+// Position component
+type Position struct {
+	X float64
+	Y float64
+}
+
+// Velocity component
+type Velocity struct {
+	X float64
+	Y float64
+}
+
+// ChildOf relation component
+type ChildOf struct {
+	ecs.Relation
+}
+
+// EventHandler that prints information about received events.
+type EventHandler struct{}
+
+// Notify is called with all subscribed events.
+func (h *EventHandler) Notify(world *ecs.World, evt ecs.EntityEvent) {
+	fmt.Printf("    Type mask:     %06b\n", evt.EventTypes)
+	fmt.Printf("    Entity:        %+v\n", evt.Entity)
+	fmt.Printf("    Added/Removed: %+v / %+v\n", evt.Added, evt.Removed)
+	fmt.Printf("    Relation:      %+v -> %+v\n", evt.OldRelation, evt.NewRelation)
+
+	var target ecs.Entity
+	if evt.NewRelation != nil {
+		target = world.Relations().Get(evt.Entity, *evt.NewRelation)
+	}
+	fmt.Printf("    Target:        %+v -> %+v\n", evt.OldTarget, target)
+}
+
+func main() {
+	// Create a World.
+	world := ecs.NewWorld()
+
+	// Get component IDs
+	posID := ecs.ComponentID[Position](&world)
+	velID := ecs.ComponentID[Velocity](&world)
+	childID := ecs.ComponentID[ChildOf](&world)
+
+	// Create the event handler.
+	handler := EventHandler{}
+
+	// Create the listener.
+	listener := listener.NewCallback(
+		// Function to handle events.
+		handler.Notify,
+		// Subscribe to event types; could also use `event.All` here.
+		event.EntityCreated|event.EntityRemoved|
+			event.ComponentAdded|event.ComponentRemoved|
+			event.RelationChanged|event.TargetChanged,
+		// Optionally, restrict subscription to a list of component types / IDs.
+		//posID, childID,
+	)
+
+	// Register a listener function.
+	world.SetListener(&listener)
+
+	fmt.Println("=== Create entity ===")
+	child := world.NewEntity()
+
+	fmt.Println("=== Create entity with normal components ===")
+	parent := world.NewEntity(posID, velID)
+
+	fmt.Println("=== Create entity with relation component ===")
+	world.NewEntity(childID)
+
+	fmt.Println("=== Add normal component to entity ===")
+	world.Add(child, posID)
+
+	fmt.Println("=== Add relation component to entity ===")
+	world.Add(child, childID)
+
+	fmt.Println("=== Change relation target ===")
+	world.Relations().Set(child, childID, parent)
+}