Batch and Bulk

Batch and Bulk, executing batched commands on all your entities.

So... you don't want to edit all your entities individually, but all at once? How good that I know what makes you tick! In some cases, it is more efficient to carry out operations not on each entity individually, but on all of them together. This is what this chapter is about.

Reserve

Arch offers you the possibility to reserve memory for your entities in advance. This speeds up the creation of entities, as the memory already exists and does not have to be allocated later.

world.EnsureCapacity<Dwarf, Position, Velocity>(1_000_000);

The world.EnsureCapacity method reserves memory for entities of a specific component structure. The archetype that contains entities of this specific structure is therefore enlarged so that there is enough space for them.

However, these have not yet been created, the space has only been reserved. This still has to happen, the moment does not matter, the reserved memory does not expire. All in all, it looks like this:

world.EnsureCapacity<Dwarf, Position, Velocity>(1_000_000);
for(var index = 0; index < 1_000_000; index++){
    var dwarf = world.Create(signature);
}

So space is created for around one million dwarves and this space is then filled by creating the entities through world.create. This is fast and efficient, it only needs to allocate memory once. Of course theres also an Non-Generic APIwhich accepts an Signature instead.

The world.EnsureCapacity method works like an array or list. This means that it does not allocate memory for n additional elements, but ensures that there is space for a total of n elements.

Create

If you not only want to reserve memory, but also create many entities at the same time. Then the world.Create overload is a good choice.

world.Create(1_000_000, new Dwarf(), RandomPosition(), RandomVelocity());

Each entity created will have exactly the same components (and exactly the same values). There is of course a Non-Generic API that takes a Signature instead and even returns a list of Entity!

Change

But what if you want to change all entities at once? That works too, of course, and has the same advantages.

// Giving our dwarfs equipment
var allDwarfs = new QueryDescription().WithAll<Dwarf>().WithNone<Axe, Armor, Boots>();
world.Add(in allDwarfs, new Axe(state = State.Broken), new Armor(), new Boots());

// Repairing the axe of all ours dwarfs 
var dwarfsWithAxe = new QueryDescription().WithAll<Dwarf, Axe>();
world.Set(in dwarfsWithAxe, new Axe(state = State.Repaired));

// Deciding that our dwarfs are too heavy and they dont need any armor
var dwarfsWithArmor = new QueryDescription().WithAll<Armor>();
world.Remove<Armor>(in dwarfsWithArmor);

// Destroying all dwarfs
world.Destroy(in dwarfsWithAxe);

Each of these operations uses generics and is available in many variations and overloads. Up to 25 parameters are accepted, but do not have to be passed, in which case the default values are used.

These perform their operations on all entities that match the query. The entities are not processed individually but as a set, making this incredibly fast and efficient.