Skip to content

Commit

Permalink
GITBOOK-32: No subject
Browse files Browse the repository at this point in the history
  • Loading branch information
genaray authored and gitbook-bot committed Sep 10, 2024
1 parent 8f92753 commit 75097eb
Show file tree
Hide file tree
Showing 9 changed files with 93 additions and 16 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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...
Expand Down
4 changes: 3 additions & 1 deletion SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
16 changes: 8 additions & 8 deletions documentation/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,63 +84,63 @@ Arch is from the community for the community. You can participate, create forks,

<details>

<summary>Archetypes &#x26; Chunks</summary>
<summary><a href="concepts.md#archetypes-and-chunks">Archetypes &#x26; Chunks</a></summary>

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.

</details>

<details>

<summary>Small entities and `PURE_ECS`</summary>
<summary><a href="optimizations/pure_ecs.md">Small entities and `PURE_ECS`</a></summary>

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.

</details>

<details>

<summary>Versatile and fast queries</summary>
<summary><a href="optimizations/query-techniques.md">Versatile and fast queries</a></summary>

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!

</details>

<details>

<summary>Bulk &#x26; Batch</summary>
<summary><a href="concepts.md#bulk-and-batch">Bulk &#x26; Batch</a></summary>

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.

</details>

<details>

<summary>Multithreading &#x26; Jobs</summary>
<summary><a href="optimizations/multithreading.md">Multithreading &#x26; Jobs</a></summary>

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!

</details>

<details>

<summary>CommandBuffer</summary>
<summary><a href="concepts.md#commandbuffer">CommandBuffer</a></summary>

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.

</details>

<details>

<summary>Events</summary>
<summary><a href="concepts.md#events">Events</a></summary>

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!

</details>

<details>

<summary>Generic &#x26; Non-Generic API</summary>
<summary><a href="utilities/non-generic-api.md">Generic &#x26; Non-Generic API</a></summary>

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.

Expand Down
4 changes: 2 additions & 2 deletions documentation/entity.md
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand All @@ -28,7 +28,7 @@ I'm not a dark mage, but I can tell you a little about how to create life. It's
</strong></code></pre>

{% 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?
Expand Down
4 changes: 2 additions & 2 deletions documentation/world.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.&#x20;

{% 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 %}

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Lifecycle Management</strong></td><td>Creating and destroying Entities. </td><td><a href="entity.md">entity.md</a></td></tr><tr><td><strong>Structural Changes</strong></td><td>Adding/Removing components on Entities</td><td><a href="entity.md">entity.md</a></td></tr><tr><td><strong>Modification</strong> </td><td>Accessing and modifying components on Entities.</td><td><a href="entity.md">entity.md</a></td></tr><tr><td><strong>Enumeration</strong></td><td>Enumerating/Filtering/Matching Entities.</td><td><a href="query.md">query.md</a></td></tr><tr><td><strong>Bulk/Batch Operations</strong></td><td>Executing operations on Entities in Bulk/Batches.</td><td></td></tr><tr><td><strong>Lowlevel</strong></td><td>Working with Archetypes, Chunks and Entities directly without any wrappers. </td><td></td></tr><tr><td><strong>Multithreading</strong></td><td>Acessing the JobScheduler to run querys or your own Jobs in parallel. </td><td></td></tr><tr><td><strong>And much more...</strong></td><td>Working with Events, the CommandBuffer or several other features directly!</td><td></td></tr></tbody></table>
<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Lifecycle Management</strong></td><td>Creating and destroying Entities. </td><td><a href="entity.md">entity.md</a></td></tr><tr><td><strong>Structural Changes</strong></td><td>Adding/Removing components on Entities</td><td><a href="entity.md">entity.md</a></td></tr><tr><td><strong>Modification</strong> </td><td>Accessing and modifying components on Entities.</td><td><a href="entity.md">entity.md</a></td></tr><tr><td><strong>Enumeration</strong></td><td>Enumerating/Filtering/Matching Entities.</td><td><a href="query.md">query.md</a></td></tr><tr><td><strong>Bulk/Batch Operations</strong></td><td>Executing operations on Entities in Bulk/Batches.</td><td><a href="optimizations/batch-and-bulk.md">batch-and-bulk.md</a></td></tr><tr><td><strong>Lowlevel</strong></td><td>Working with Archetypes, Chunks and Entities directly without any wrappers. </td><td><a href="archetypes-and-chunks.md">archetypes-and-chunks.md</a></td></tr><tr><td><strong>Multithreading</strong></td><td>Acessing the JobScheduler to run querys or your own Jobs in parallel. </td><td><a href="optimizations/multithreading.md">multithreading.md</a></td></tr><tr><td><strong>And much more...</strong></td><td>Working with Events, the CommandBuffer or several other features directly!</td><td></td></tr></tbody></table>

We'll go into more detail later. But now enough talk, go on. Something is lurking behind the next bush.
2 changes: 0 additions & 2 deletions extensions/page-3.md

This file was deleted.

11 changes: 11 additions & 0 deletions extensions/page-3/README.md
Original file line number Diff line number Diff line change
@@ -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!

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Arch.Systems</strong></td><td>Framework to easy organize, reuse and arrange queries.</td><td><a href="arch.system.md">arch.system.md</a></td></tr><tr><td><strong>Arch.System.SourceGenerator</strong></td><td>Declarative syntax using attributes and source generator, let your queries write themselves!</td><td><a href="arch.system.sourcegenerator.md">arch.system.sourcegenerator.md</a></td></tr><tr><td><strong>Arch.EventBus</strong></td><td>A source generated EventBus, send Events with high-performance!</td><td></td></tr><tr><td><strong>Arch.LowLevel</strong></td><td>Low-level utils and data structures to get rid of GC pressure!</td><td></td></tr><tr><td><strong>Arch.Relationships</strong></td><td>Adds simple relationships between entities to arch!</td><td></td></tr><tr><td><strong>Arch.Persistence</strong></td><td>JSON and Binary (de)serialization to persist your Worlds!</td><td></td></tr><tr><td><strong>Arch.AOT.SourceGenerator</strong></td><td>Helps with AOT compatibility and reduces boilerplate code!</td><td></td></tr></tbody></table>
58 changes: 58 additions & 0 deletions extensions/page-3/arch.system.md
Original file line number Diff line number Diff line change
@@ -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.

<pre class="language-csharp"><code class="lang-csharp">public class MovementSystem : <a data-footnote-ref href="#user-content-fn-1">BaseSystem&#x3C;World, float></a>
{
private QueryDescription _desc = new QueryDescription().WithAll&#x3C;Position, Velocity>();
public MovementSystem(World world) : base(world) {}

// Can be called once per frame
public override void Update(in <a data-footnote-ref href="#user-content-fn-2">float deltaTime</a>)
{
// 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;
});
}
}
</code></pre>

{% 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?&#x20;

```csharp
// Create a world and a group of systems which will be controlled
var world = World.Create();
var _systems = new Group<float>(
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<T>` can also contain other `Group<T>`. `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<T>`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.
8 changes: 8 additions & 0 deletions extensions/page-3/arch.system.sourcegenerator.md
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 75097eb

Please sign in to comment.