From 75097eb6151a8faa4eb7f55c5e5b86502c222602 Mon Sep 17 00:00:00 2001 From: Lars M Date: Tue, 10 Sep 2024 09:01:47 +0000 Subject: [PATCH] GITBOOK-32: No subject --- README.md | 2 +- SUMMARY.md | 4 +- documentation/concepts.md | 16 ++--- documentation/entity.md | 4 +- documentation/world.md | 4 +- extensions/page-3.md | 2 - extensions/page-3/README.md | 11 ++++ extensions/page-3/arch.system.md | 58 +++++++++++++++++++ .../page-3/arch.system.sourcegenerator.md | 8 +++ 9 files changed, 93 insertions(+), 16 deletions(-) delete mode 100644 extensions/page-3.md create mode 100644 extensions/page-3/README.md create mode 100644 extensions/page-3/arch.system.md create mode 100644 extensions/page-3/arch.system.sourcegenerator.md diff --git a/README.md b/README.md index 95f94c0..e912c34 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ Supports .NetStandard 2.1, .Net Core 6 and 7, and therefore you may use it with Put on your boots and give it a try, it's easier than you thought... ```sh -dotnet add PROJECT package Arch --version 1.2.8.1-alpha +dotnet add PROJECT package Arch --version 1.3.0-alpha ``` Don't miss your luggage and briefly import Arch... diff --git a/SUMMARY.md b/SUMMARY.md index 15e1ddf..81db7a1 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -24,7 +24,9 @@ ## 🧩 Extensions -* [WIP](extensions/page-3.md) +* [Arch.Extended](extensions/page-3/README.md) + * [Arch.System](extensions/page-3/arch.system.md) + * [Arch.System.SourceGenerator](extensions/page-3/arch.system.sourcegenerator.md) ## 💡 Examples diff --git a/documentation/concepts.md b/documentation/concepts.md index da231db..398d706 100644 --- a/documentation/concepts.md +++ b/documentation/concepts.md @@ -84,7 +84,7 @@ Arch is from the community for the community. You can participate, create forks,
-Archetypes & Chunks +Archetypes & Chunks Arch not only has archetypes but also chunks. This sets it apart from many other ECSs. Each archetype has several chunks. Chunks themselves are 64KB memory blocks and contain the entities and their components directly. The big advantage of this is that it is more efficient to iterate and allocate. Fast, efficient and memory friendly. @@ -92,7 +92,7 @@ Arch not only has archetypes but also chunks. This sets it apart from many other
-Small entities and `PURE_ECS` +Small entities and `PURE_ECS` Arch's entities are as small as possible, no unnecessary data is stored. If you want to make your entities even smaller, Arch supports the concept of “Pure ECS”. This makes entities even smaller and more memory-friendly. @@ -100,7 +100,7 @@ Arch's entities are as small as possible, no unnecessary data is stored. If you
-Versatile and fast queries +Versatile and fast queries You don't feel like writing delegates to edit entities? Don't worry, arch has you covered! We support a variety of different query types, from delegates to interfaces to manual enumeration and even source generation! @@ -108,7 +108,7 @@ You don't feel like writing delegates to edit entities? Don't worry, arch has yo
-Bulk & Batch +Bulk & Batch It is also possible to create, change and delete entities in bulk. This is even more efficient than doing this for each entity individually, Arch is incredibly efficient. @@ -116,7 +116,7 @@ It is also possible to create, change and delete entities in bulk. This is even
-Multithreading & Jobs +Multithreading & Jobs For even more efficiency and large amounts of data and entities, there is multithreading and jobs. The best thing about it, without creating garbage. Arch has its own JobScheduler that was written just for this purpose. This allows you to bring your huge worlds to life even better! @@ -124,7 +124,7 @@ For even more efficiency and large amounts of data and entities, there is multit
-CommandBuffer +CommandBuffer You don't want to make changes to entities immediately but only later? No problem! Arch has even taken this into consideration: with the CommandBuffer you can postpone these changes and execute them at a later time. @@ -132,7 +132,7 @@ You don't want to make changes to entities immediately but only later? No proble
-Events +Events Entity events are one of the things that are not included by default in the nugget, but you can easily enable them through the source code using a flag! You only pay for what you use! @@ -140,7 +140,7 @@ Entity events are one of the things that are not included by default in the nugg
-Generic & Non-Generic API +Generic & Non-Generic API Of course, you can also use the API with simple types. Nobody is forcing you to use generics. This is often very helpful, especially when it comes to persistence and reflection. diff --git a/documentation/entity.md b/documentation/entity.md index 2f7ad57..acb53f0 100644 --- a/documentation/entity.md +++ b/documentation/entity.md @@ -10,7 +10,7 @@ coverY: 55 In an [entity component system (ECS)](concepts.md), an entity is simply a **unique ID** tag. It represents **an object** in the game or application, but has no logic or data itself. The data and behavior come from **components** that are attached to this entity. -An `Entity` is nothing more than a simple `record struct Entity{ int ID, ... }`. Either you work directly on this entity and its methods, or you simply use `PURE_ECS`. More on this later. +An `Entity` is nothing more than a simple `record struct Entity{ int ID, int WorldId }`. Either you work directly on this entity and its methods, or you simply use [`PURE_ECS`](optimizations/pure\_ecs.md). More on this later. {% hint style="info" %} Its components can be **anything**, **primitive data types**, **structs** and even **classes**! YOU determine which components and attributes an entity receives, there are **no restrictions** here! @@ -28,7 +28,7 @@ I'm not a dark mage, but I can tell you a little about how to create life. It's {% hint style="info" %} -Components may vary and this example uses generics, if you don't feel like using generics, there are still plenty of APIs without them. +Components may vary and this example uses generics, if you don't feel like using generics, there are still [plenty of APIs without them](utilities/non-generic-api.md). {% endhint %} It can be that simple. How does it feel to be a god? diff --git a/documentation/world.md b/documentation/world.md index 08d95af..af3ae09 100644 --- a/documentation/world.md +++ b/documentation/world.md @@ -34,9 +34,9 @@ Now we have a world. A world with all the prerequisites for creating life, chang The world has the rudimentary methods on which everything in Arch is based. If you only want to work with them, this is possible and offers one less level of abstraction. {% hint style="info" %} -As an alternative, you can also work ONLY with the world. Without abstraction of entities and co. This principle is called `PURE_ECS` and will be looked at later. The following documentation refers further to the abstracted entity API. +As an alternative, you can also work ONLY with the world. Without abstraction of entities and co. This principle is called [`PURE_ECS`](optimizations/pure\_ecs.md) and will be looked at later. The following documentation refers further to the abstracted entity API. {% endhint %} -
Lifecycle ManagementCreating and destroying Entities. entity.md
Structural ChangesAdding/Removing components on Entitiesentity.md
Modification Accessing and modifying components on Entities.entity.md
EnumerationEnumerating/Filtering/Matching Entities.query.md
Bulk/Batch OperationsExecuting operations on Entities in Bulk/Batches.
LowlevelWorking with Archetypes, Chunks and Entities directly without any wrappers.
MultithreadingAcessing the JobScheduler to run querys or your own Jobs in parallel.
And much more...Working with Events, the CommandBuffer or several other features directly!
+
Lifecycle ManagementCreating and destroying Entities. entity.md
Structural ChangesAdding/Removing components on Entitiesentity.md
Modification Accessing and modifying components on Entities.entity.md
EnumerationEnumerating/Filtering/Matching Entities.query.md
Bulk/Batch OperationsExecuting operations on Entities in Bulk/Batches.batch-and-bulk.md
LowlevelWorking with Archetypes, Chunks and Entities directly without any wrappers. archetypes-and-chunks.md
MultithreadingAcessing the JobScheduler to run querys or your own Jobs in parallel. multithreading.md
And much more...Working with Events, the CommandBuffer or several other features directly!
We'll go into more detail later. But now enough talk, go on. Something is lurking behind the next bush. diff --git a/extensions/page-3.md b/extensions/page-3.md deleted file mode 100644 index 40b4ed4..0000000 --- a/extensions/page-3.md +++ /dev/null @@ -1,2 +0,0 @@ -# Page 3 - diff --git a/extensions/page-3/README.md b/extensions/page-3/README.md new file mode 100644 index 0000000..13cdf00 --- /dev/null +++ b/extensions/page-3/README.md @@ -0,0 +1,11 @@ +--- +description: >- + Arch is not enough for you and you think that features are missing? No way, + there's even more power here! +--- + +# Arch.Extended + +Arch itself remains **bare minimum**, but that does not mean that it is not expandable. [`Arch.Extended`](https://github.com/genaray/Arch.Extended) has many useful **utilities** and **additional frameworks** **to** **complement** Arch and make it what you've always wanted it to be! + +
Arch.SystemsFramework to easy organize, reuse and arrange queries.arch.system.md
Arch.System.SourceGeneratorDeclarative syntax using attributes and source generator, let your queries write themselves!arch.system.sourcegenerator.md
Arch.EventBusA source generated EventBus, send Events with high-performance!
Arch.LowLevelLow-level utils and data structures to get rid of GC pressure!
Arch.RelationshipsAdds simple relationships between entities to arch!
Arch.PersistenceJSON and Binary (de)serialization to persist your Worlds!
Arch.AOT.SourceGeneratorHelps with AOT compatibility and reduces boilerplate code!
diff --git a/extensions/page-3/arch.system.md b/extensions/page-3/arch.system.md new file mode 100644 index 0000000..38043a0 --- /dev/null +++ b/extensions/page-3/arch.system.md @@ -0,0 +1,58 @@ +--- +description: If only there was a way to organize your queries... wait... there is! +--- + +# Arch.System + +You write query after query all the time to order your subordinates around... it's a pure mess, isn't it? Then just use `Arch.System`? It's quite simple... With `Arch.System` you can organize your queries in `Systems` and call and reuse them at will. + +
public class MovementSystem : BaseSystem<World, float>
+{
+    private QueryDescription _desc = new QueryDescription().WithAll<Position, Velocity>();
+    public MovementSystem(World world) : base(world) {}
+    
+    // Can be called once per frame
+    public override void Update(in float deltaTime)
+    {
+        // Run query, can also run multiple queries inside the update method
+        World.Query(in _desc, (ref Position pos, ref Velocity vel) => {
+            pos.X += vel.X;
+            pos.Y += vel.Y;
+        });  
+    }
+}
+
+ +{% hint style="info" %} +The example above is of course kept simple. You can simply put anything you want to group into such a `System`, e.g. a `System` for everything that moves your creatures... another `System` that contains everything that causes your creatures to suffer damage and heals them etc. There is no limit to your imagination! +{% endhint %} + +Now we already have a `MovementSystem`, a `System` that groups everything that makes our [`Entities`](../../documentation/entity.md) move. But how do we integrate this now? + +```csharp +// Create a world and a group of systems which will be controlled +var world = World.Create(); +var _systems = new Group( + new MovementSystem(world), + new PhysicsSystem(world), + new DamageSystem(world), + new WorldGenerationSystem(world), + new OtherGroup(world) +); + +_systems.Initialize(); // Inits all registered systems +_systems.BeforeUpdate(in deltaTime); // Calls .BeforeUpdate on all systems ( can be overriden ) +_systems.Update(in deltaTime); // Calls .Update on all systems ( can be overriden ) +_systems.AfterUpdate(in deltaTime); // Calls .AfterUpdate on all System ( can be overriden ) +_systems.Dispose(); // Calls .Dispose on all systems ( can be overriden ) +``` + +{% hint style="info" %} +A `Group` can also contain other `Group`. `BeforeUpdate`, `Update` and `AfterUpdate` should be called at will to update the systems and queries. +{% endhint %} + +And we have already divided our `Systems` into `Group`s to bring order into it. What more could you want? + +[^1]: `BaseSystem` provides several usefull methods for interacting and structuring systems. `float` is the value that is transmitted to the system. This can be any type. + +[^2]: Can be any type based on the generics of this instance. diff --git a/extensions/page-3/arch.system.sourcegenerator.md b/extensions/page-3/arch.system.sourcegenerator.md new file mode 100644 index 0000000..7a31cae --- /dev/null +++ b/extensions/page-3/arch.system.sourcegenerator.md @@ -0,0 +1,8 @@ +--- +description: >- + What's the point of organized queries if it's sooo much work to write them? We + have a solution! +--- + +# Arch.System.SourceGenerator +