Overview of methods for ECS manipulations

CHANGELOG.md

@@ -41,6 +41,10 @@ This change was necessary to get the same performance as before, despite the mor
 * Reduces archetype memory footprint by using a dynamically sized slice for storage lookup (#327)
 * Reduces event listener overhead through granular subscriptions and elimination of a heap allocation (#333, #334, #335, #337, #340)
 
+### Documentation
+
+* Adds an overview to packages `ecs` and `generic` on how to achieve ECS manipulation operations (#345)
+
 ### Other
 
 * Entity generation data type changed from `uint16` to `uint32` (#317)

ecs/doc.go

@@ -22,4 +22,36 @@
 // # Sub-packages
 //   - [github.com/mlange-42/arche/ecs/event] provides event subscription masks.
 //   - [github.com/mlange-42/arche/ecs/stats] provides world statistics for monitoring purposes.
+//
+// # Manipulation
+//
+// This section gives an overview over how to achieve typical ECS manipulation operations with Arche.
+//
+// Simple manipulations of a single entity:
+//   - Create an entity: [World.NewEntity], [World.NewEntityWith]
+//   - Remove an entity: [World.RemoveEntity]
+//   - Add components: [World.Add]
+//   - Remove components: [World.Remove]
+//   - Exchange components: [World.Exchange]
+//   - Change entity relation target: [Relations.Set]
+//
+// Manipulations of a single entity, with a relation target:
+//   - Create an entity: [Builder.New]
+//   - Add components: [Builder.Add], [Relations.Exchange]
+//   - Remove components: [Relations.Exchange]
+//   - Exchange components: [Relations.Exchange]
+//
+// Batch-manipulations of many entities:
+//   - Create entities: [Builder.NewBatch], [Builder.NewBatchQ]
+//   - Remove entities: [Batch.RemoveEntities]
+//   - Add components: [Batch.Add], [Batch.AddQ]
+//   - Remove components: [Batch.Remove], [Batch.RemoveQ]
+//   - Exchange components: [Batch.Exchange]
+//   - Change entity relation target: [Batch.SetRelation], [Batch.SetRelationQ]
+//
+// Batch-manipulations of many entities, with a relation target:
+//   - Create an entity: [Builder.NewBatch], [Builder.NewBatchQ]
+//   - Add components: [Relations.ExchangeBatch], [Relations.ExchangeBatchQ]
+//   - Remove components: [Relations.ExchangeBatch], [Relations.ExchangeBatchQ]
+//   - Exchange components: [Relations.ExchangeBatch], [Relations.ExchangeBatchQ]
 package ecs

generic/doc.go

@@ -12,4 +12,25 @@
 //     like [Map1.Get], [Map1.Add], [Map1.Remove], etc.
 //   - [Exchange] allows to add, remove and exchange components, incl. as batch operations.
 //   - [Resource] provides generic access to a resource from [ecs.Resources].
+//
+// # Manipulation
+//
+// This section gives an overview over how to achieve typical ECS manipulation operations using Arche's generic API.
+// MapX and QueryX variants are shown as [Map2] and [Query2] here.
+//
+// Manipulations of a single entity, with or without a relation target:
+//   - Create an entity: [Map2.New], [Map2.NewWith]
+//   - Remove an entity: use ecs.World.RemoveEntity
+//   - Add components: [Map2.Add], [Exchange.Add]
+//   - Remove components: [Map2.Remove], [Exchange.Add]
+//   - Exchange components: [Exchange.Exchange]
+//   - Change entity relation target: [Map.SetRelation]
+//
+// Batch-manipulations of many entities, with or without a relation target:
+//   - Create entities: [Map2.NewBatch], [Map2.NewBatchQ]
+//   - Remove entities: [Map2.RemoveEntities]
+//   - Add components: [Map2.AddBatch], [Map2.AddBatchQ]
+//   - Remove components: [Map2.RemoveBatch], [Map2.RemoveBatchQ]
+//   - Exchange components: [Exchange.ExchangeBatch]
+//   - Change entity relation target: [Map.SetRelationBatch], [Map.SetRelationBatchQ]
 package generic