> 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/entities-and-composition/assemblages.md).

# Assemblages

Named entity factories

An `Assemblage` is **a named factory bound to a fixed component composition**. 

It is a declaration of intent, not just a convenience wrapper around entity creation. `dwarf.Create(...)` means *"I am creating a dwarf"*, not *"I am creating an entity that happens to have these components."* The assemblage is where **a composition acquires meaning**.

The **performance benefits** follow from the design; because the archetype is known upfront, **entity creation skips the structural-change cost** and **lands directly into the bound, cached, archetype** with its components populated in one pass.

{% hint style="info" %}
The concept was inspired from this [article](https://prdeving.wordpress.com/2023/12/14/deep-diving-into-entity-component-system-ecs-architecture-and-data-oriented-programming/) that was stumbled during development.
{% endhint %}

#### Creating an Assemblage

Assemblages are created by the world via `CreateAssemblage<T1...T16>()`. The world **finds or creates the archetype for the given composition** and returns a factory bound to it. Assemblage registration is itself a structural change and is **highly recommended** to create it once, before the simulation starts.

```csharp
Assemblage<Transform, Health, Axe> dwarf = 
    world.CreateAssemblage<Transform, Health, Axe>();
```

**One assemblage per archetype.** Each archetype admits exactly one assemblage. Attempting to register a second for the same composition throws. With no possibility of two factories producing entities into the same archetype **under conflicting identities**.

#### Creating Entities

Once an Assemblage is created, call `Create(...)` with the component values directly. It returns the new entity's handle immediately.

```csharp
Entity balin = dwarf.Create(
    new Transform(),
    new Health() { Current = 100, Max = 100 },
    new Axe() { Damage = 12 }
);
```

`Create` is a structural change, **it throws if a query is currently iterating**. To create entities safely during system or query execution, use `DeferredCreate` instead. See [Deferred Commands](/theia-ecs/entities-and-composition/deferred-commands.md) for the full deferred creation API.

#### Per-Assemblage Events

Each assemblage owns its own event hub, `EntityEvents`. Handlers attached here fire in addition to the world-level handlers on `World.EntitiesEvents`. This lets **wire factory-specific behavior without filtering at the world-level bus**. See [Events](/theia-ecs/events.md) for the full event API, including the exact firing order and which lifecycle events each hub receives.