The World

A World is the central data store for any application that uses Ark.jl. It manages Entities, Components and Resources, and all these are always tied to a World.

Most applications will have exactly one world, but multiple worlds can exist at the same time.

World creation

When creating a new world, all Component types that can exist in it must be specified.

using Ark

struct Position
    x::Float64
    y::Float64
end

struct Velocity
    dx::Float64
    dy::Float64
end

world = World(Position, Velocity)

This may seem unusual, but it allows Ark to leverage Julia's compile-time programming features for the best performance.

The World constructor takes an option keyword argument initial_capacity to allocate memory for the given number of entities in each archetype. This is useful to speed up entity creations by avoiding repeated allocations.

world = World(Position, Velocity; initial_capacity=1024)

World modes

The keyword argument boxed selects how much code Ark generates per component type.

Queries and iteration are statically typed in both modes.

Boxed storage

By default Ark resolves the component of a structural operation by generating one branch per component type, each holding a copy of the operation specialized for that component, and holds the component storages in a tuple. That is what makes structural operations fast, but both grow with the number of component types a world declares, and so does the time spent compiling them.

Setting boxed=true removes both. Structural operations are routed through type-erased calls, each compiled only when it is first used, and the storages are kept in an untyped container whose types are carried as values rather than as static arguments. No generated code is left that depends on the number of component types in the operations. The effect grows with the number of component types.

Stay on boxed=false unless compile time is a problem, and measure before committing to boxed=true.

World reset

Ark's primary goal is to empower high-performance simulation models. In this domain, it is common to run large numbers of simulations, whether to explore model stochasticity, perform calibration, or for optimization purposes.

To maximize efficiency, Ark provides a reset! function that resets a simulation world for subsequent reuse. This significantly accelerates model initialization by reusing already allocated memory and avoiding costly reallocation.

reset!(world)

World functionality

You will see that almost all methods in Ark's API take a World as their first argument. These methods are explained in the following chapters.