> For the complete documentation index, see [llms.txt](https://wise-shepherd-games.gitbook.io/theia-ecs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wise-shepherd-games.gitbook.io/theia-ecs/start-forging.md).

# Start Forging

Your entry point into Theia ECS. Start here.

<figure><picture><source srcset="/files/IgCdGce03TWg8lj0ifvk" media="(prefers-color-scheme: dark)"><img src="https://3072820196-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQaOAK3yykMTlFNjIwV4z%2Fuploads%2FKKs1eiRkYpmqjM7rlaYL%2FTheiaECSReforgedLight.png?alt=media&amp;token=dc1ca70f-4d86-4ae4-88e2-97bf45cb75fc" alt=""></picture><figcaption></figcaption></figure>

**Theia ECS Reforged** is the second *incarnation* of Theia. Every layer has been **redesigned** around a unified set of **priorities**: high performance, O(1) structural changes, zero-to-minimum allocations, cache-coherent memory layouts, and a framework philosophy that is opinionated, loud, and refuses to be vague. **Theia means what it says**.

Theia is for developers who want:

* **Strict validation that catches misuse early** (blittable component enforcement at registration, throw-on-stale-handle, throw-on-structural-change-during-query-iteration, and so on);
* **Predictable memory allocation** (zero allocations on query iteration, structural changes, event invocation);
* **Query models the JIT can specialize and inline** (struct-based callbacks);
* **Explicit code intent at the surface level** (separate APIs for tag vs data relations, immediate vs deferred structural changes, value-update vs structural-change on components);
* **A powerful relation system** (bilateral O(1) lookups, tag and data variants, thread safety);
* **Out-of-the-box ergonomics for the boring stuff** (one-call `world.Serialize(path)` and `world.Deserialize(path)`, assemblage factories that bind compositions to events).

Theia is an archetype-based high-performance ECS written in **fully managed C#**: no unsafe pointer arithmetic, no platform-specific intrinsics. It aims to be one of the right tools: **safe**, **expressive**, and **faster**  than, or competitive with, established alternatives.

<details>

<summary><strong>Requirements</strong></summary>

* C# 14;
* .NET 10.

</details>

#### **Features:**

* **Entities with** **slot recycling** and **O(1) state access**;
* **Components** with **strict blittable enforcement**;
* **Archetypes** with **lazy initialized** **chunked storage**;
* **Assemblages** as **composition-bound entity factories** with their own event hubs;
* **Queries** in two categories: **assemblage-bound** (`Settler`) and **composition-based** (`Nomad`), sequential or parallel;
* **Relations** with **bilateral O(1) lookups**, tag and data variants, and **thread safety;**
* **Events** at world and assemblage scope, with **zero allocation** **ref-struct payloads;**
* **Systems** with **parameterized variants** up to T16 and **parallel execution support**;
* **Jobs** with type-pooled instances and chunk-level scheduling;
* **Resources** as ***enum-keyed*****&#x20;tables with immutable post-construction state**;
* **Uniques** for world-singleton component-shaped state;
* **Deferred Commands** for safe structural changes during query iteration;
* **Serialization** via one-call `Serialize(path)` / `Deserialize(path)`, sync and async (built with [MessagePack](https://github.com/MessagePack-CSharp/MessagePack-CSharp)).

#### **Why Theia exists?**

Theia is built to power a specific game project and is **heavily battle-tested through that project**. Open-sourcing it makes the framework available to other developers; **development priorities are driven by that project's needs**. Features, optimizations, and updates land when they serve the main project.

Future updates are planned, SIMD support, for example. The framework will evolve as the main project evolves, which means the **roadmap is honest rather than ambitious**: what ships, ships when it's needed.

{% hint style="info" %}
Theia is a standalone ECS library designed to be used alongside game frameworks like [MonoGame](https://monogame.net):heart\_exclamation: Bindings or integrations for game engines such as Unity or Godot **are not part of the core project** and will not be developed by the maintainer, but contributions from the community are **welcome** and **encouraged**.
{% endhint %}