tweak docstrings, update changelog

CHANGELOG.md

@@ -7,7 +7,7 @@
 * Arche supports full world serialization and deserialization, in conjunction with [arche-serde](https://github.com/mlange-42/arche-serde) (#319)
 * Supports 256 instead of 128 component types as well as resource types and engine locks (#313)
 * Generic API supports up to 12 instead of 8 component types (#324)
-* Reworked event system with independent subscription for different event types (#333, #334)
+* Reworked event system with independent subscription for different event types and components (#333, #334, #335)
 
 ### Breaking changes
 
@@ -26,6 +26,7 @@ This change was necessary to get the same performance as before, despite the mor
 * Entities support JSON marshalling and unmarshalling (#319)
 * The world's entity state can be extracted and re-established via `World.DumpEntities()` and `World.LoadEntities()` (#319, #326)
 * Adds functions `ComponentIDs(*World)` and `ResourceIDs(*World)` to get all registered IDs (#329)
+* Adds methods `Mask.And`, `Mask.Or` and `Mask.Xor` (#335)
 
 ### Performance
 

ecs/event.go

@@ -25,11 +25,11 @@ import "github.com/mlange-42/arche/ecs/event"
 // This allows the [World] to be in an unlocked state, and notifies after potential entity initialization.
 type EntityEvent struct {
 	Entity                   Entity             // The entity that was changed.
-	Changed                  Mask               // Mask indicating changed components.
+	Changed                  Mask               // Mask indicating changed components (additions and removals).
 	Added, Removed           []ID               // Components added and removed. DO NOT MODIFY! Get the current components with [World.Ids].
 	OldRelation, NewRelation *ID                // Old and new relation component ID. No relation is indicated by nil.
 	OldTarget                Entity             // Old relation target entity. Get the new target with [World.Relations] and [Relations.Get].
-	EventTypes               event.Subscription // Bit mask of event types. See [Subscription].
+	EventTypes               event.Subscription // Bit mask of event types. See [event.Subscription].
 }
 
 // Contains returns whether the event's types contain the given type/subscription bit.
@@ -62,17 +62,18 @@ func newTestListener(callback func(e EntityEvent)) testListener {
 	}
 }
 
-// Notify the listener
+// Notify the listener.
 func (l *testListener) Notify(e EntityEvent) {
 	l.Callback(e)
 }
 
-// Subscriptions of the listener
+// Subscriptions of the listener in terms of event types.
 func (l *testListener) Subscriptions() event.Subscription {
 	return l.Subscribe
 }
 
 // Components the listener subscribes to.
+// Will be notified about changes on any (not all!) of the components in the mask.
 func (l *testListener) Components() *Mask {
 	return nil
 }

ecs/util.go

@@ -65,6 +65,7 @@ func subscription(entityCreated, entityRemoved, componentAdded, componentRemoved
 	return bits
 }
 
+// Returns whether a listener that subscribes to an event is also interested in terms of component subscription.
 func subscribes(evtType event.Subscription, changed *Mask, subs *Mask, oldRel *ID, newRel *ID) bool {
 	if event.Relations.Contains(evtType) {
 		return subs == nil || (oldRel != nil && subs.Get(*oldRel)) || (newRel != nil && subs.Get(*newRel))

listener/dispatch.go

@@ -8,8 +8,9 @@ import (
 // Dispatch event listener.
 //
 // Dispatches events to sub-listeners and manages subscription automatically.
-//
 // Sub-listeners should not alter their subscriptions or components after adding them.
+//
+// To make it possible for systems to add listeners, Dispatch should be added to the [ecs.World] as a resource.
 type Dispatch struct {
 	listeners     []ecs.Listener
 	events        event.Subscription