Skip to content

Class World

Namespace: Apogee.Ecs
Assembly: Apogee.Ecs.dll

A Flecs world: entities, components, queries and systems. Components are the unmanaged structs marked [Component] (reflected, so Flecs knows their fields too) or ones a script defined at run time. Not thread safe: use it from one thread.

public sealed class World : EngineObject, IDisposable

Inheritance

object ← EngineObject ← World

Implements

IDisposable

Inherited Members

EngineObject.IsAdopted, EngineObject.Handle, EngineObject.IsDestroyed, EngineObject.Class, EngineObject.Adopt(), EngineObject.TryGet(SlotHandle, out EngineObject), EngineObject.Destroy(), object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()

Constructors

World()

public World()

Properties

Assets

Which file a uid:// names ( accepts one in place of a path). Null: only paths are understood.

public AssetDatabase? Assets { get; set; }

Property Value

AssetDatabase?

Class

What the registry knows about this object's class.

public override ClassInfo Class { get; }

Property Value

ClassInfo

Components

The components this world has registered (the structs of the registry that were used, and the ones scripts defined), in name order.

public IReadOnlyList<ComponentInfo> Components { get; }

Property Value

IReadOnlyList<ComponentInfo>

DeltaTime

The time step of the current ; what systems read for their delta time.

public float DeltaTime { get; }

Property Value

float

Files

The files scene files are read from and written to (, ); set by whatever hosts the world. Null in a bare world, which has no files.

public VirtualFileSystem? Files { get; set; }

Property Value

VirtualFileSystem?

Frame

The number of frames has run.

public long Frame { get; }

Property Value

long

Prefabs

The prefab files this world knows, and the handles that and hold. Made from and when first asked for, so set those first; a host that shares one library between worlds (so that their handles agree) sets it. The prefab asset type ([Property(Asset = "prefab")]) is saved through it.

public PrefabLibrary Prefabs { get; set; }

Property Value

PrefabLibrary

Exceptions

InvalidOperationException

The world has no to make a library from.

Methods

Add(Entity, Entity)

public void Add(Entity entity, Entity id)

Parameters

entity Entity

id Entity

Add<T>(Entity)

public void Add<T>(Entity entity) where T : unmanaged

Parameters

entity Entity

Type Parameters

T

AddObserver(string, ReadOnlySpan<QueryTerm>, ObserverEvent, TableAction)

Adds an observer: action runs when a matching entity gets the event (a component added, set or removed), at once, not in a phase. Destroy the returned entity to remove it.

public Entity AddObserver(string name, ReadOnlySpan<QueryTerm> terms, ObserverEvent trigger, TableAction action)

Parameters

name string

terms ReadOnlySpan<QueryTerm>

trigger ObserverEvent

action TableAction

Returns

Entity

AddObserver<T1>(string, ObserverEvent, EachAction<T1>)

public Entity AddObserver<T1>(string name, ObserverEvent trigger, EachAction<T1> action) where T1 : unmanaged

Parameters

name string

trigger ObserverEvent

action EachAction<T1>

Returns

Entity

Type Parameters

T1

AddSystem(string, ReadOnlySpan<QueryTerm>, Phase, TableAction)

Adds a system: action runs once per matching table in every , in its phase. An exception it throws is held until the frame is done (see ). Destroy the returned entity to remove the system.

public Entity AddSystem(string name, ReadOnlySpan<QueryTerm> terms, Phase phase, TableAction action)

Parameters

name string

terms ReadOnlySpan<QueryTerm>

phase Phase

action TableAction

Returns

Entity

AddSystem<T1>(string, Phase, EachAction<T1>)

public Entity AddSystem<T1>(string name, Phase phase, EachAction<T1> action) where T1 : unmanaged

Parameters

name string

phase Phase

action EachAction<T1>

Returns

Entity

Type Parameters

T1

AddSystem<T1, T2>(string, Phase, EachAction<T1, T2>)

public Entity AddSystem<T1, T2>(string name, Phase phase, EachAction<T1, T2> action) where T1 : unmanaged where T2 : unmanaged

Parameters

name string

phase Phase

action EachAction<T1, T2>

Returns

Entity

Type Parameters

T1

T2

AddSystem<T1, T2, T3>(string, Phase, EachAction<T1, T2, T3>)

public Entity AddSystem<T1, T2, T3>(string name, Phase phase, EachAction<T1, T2, T3> action) where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged

Parameters

name string

phase Phase

action EachAction<T1, T2, T3>

Returns

Entity

Type Parameters

T1

T2

T3

Children(Entity)

The children of an entity in creation order (the order of their ids), user entities only.

public List<Entity> Children(Entity parent)

Parameters

parent Entity

Returns

List<Entity>

Clone(Entity, Entity?)

A copy of the entity with all its components, and of everything below it, under parent (the original's parent by default). Names get " (copy)" added so they stay unique. Returns the copy of source.

public Entity Clone(Entity source, Entity? parent = null)

Parameters

source Entity

parent Entity?

Returns

Entity

Component<T>()

The id of the component T, registering it (and its fields, for Flecs' reflection) on first use.

public Entity Component<T>() where T : unmanaged

Returns

Entity

Type Parameters

T

ComponentId(ComponentInfo)

The component id of info in this world, when it has been registered.

public Entity ComponentId(ComponentInfo info)

Parameters

info ComponentInfo

Returns

Entity

ComponentsOf(Entity)

The components (and tags) the entity has that the registry describes, with their descriptions: what an inspector lists. Relationship pairs and Flecs' own are left out.

public List<(Entity Id, ComponentInfo Info)> ComponentsOf(Entity entity)

Parameters

entity Entity

Returns

List<(Entity Id, ComponentInfo Info)>

ComputeWorldTransform(Entity)

The world placement of entity computed now, from its and those of its parents. is only up to date after the last ; this is for code that changes transforms and needs the result before the next one (physics placing a body it was just given). An entity with no counts as the identity.

public Trs ComputeWorldTransform(Entity entity)

Parameters

entity Entity

Returns

Trs

CreateEntity(string?, Entity)

A new entity; with a name, the entity of that name (created when it does not exist). A parent makes the name relative to it.

public Entity CreateEntity(string? name = null, Entity parent = default)

Parameters

name string?

parent Entity

Returns

Entity

CreateQuery(ReadOnlySpan<QueryTerm>)

A query from terms, for callers that do not know the components at compile time (scripts).

public Query CreateQuery(ReadOnlySpan<QueryTerm> terms)

Parameters

terms ReadOnlySpan<QueryTerm>

Returns

Query

DefineComponent(string, IReadOnlyList<(string Name, FieldKind Kind)>, IReadOnlyDictionary<string, InspectorMeta>?, IReadOnlyDictionary<string, string>?)

Defines a component at run time (what a script does): the fields are laid out in name order, so a schema always gives the same layout. The same name and fields again return the same component; other fields under a known name fail.

public Entity DefineComponent(string name, IReadOnlyList<(string Name, FieldKind Kind)> fields, IReadOnlyDictionary<string, InspectorMeta>? meta = null, IReadOnlyDictionary<string, string>? assetTypes = null)

Parameters

name string

The component's name (not Entity, which a scene file uses for a child entity).

fields IReadOnlyList<(string Name, FieldKind Kind)>

The fields and their kinds.

meta IReadOnlyDictionary<string, InspectorMeta>?

Inspector hints per field name, or null.

assetTypes IReadOnlyDictionary<string, string>?

For the fields, the asset type each names (model), by field name, or null. It is not part of the layout: a component defined again keeps the types it was first given.

Returns

Entity

Destroy(Entity)

Deletes the entity with its components; its id is never alive again, even when Flecs reuses the number.

public void Destroy(Entity entity)

Parameters

entity Entity

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Ensure<T>(Entity)

A writable reference to the component, added (zeroed) when missing. Call after writing for observers to see it.

public ref T Ensure<T>(Entity entity) where T : unmanaged

Parameters

entity Entity

Returns

T

Type Parameters

T

EnsurePointer(Entity, Entity, int)

The component's memory on the entity, added (zeroed) when missing. Call after writing.

public byte* EnsurePointer(Entity entity, Entity component, int size)

Parameters

entity Entity

component Entity

size int

Returns

byte*

FindComponent(string)

The component of that name registered in this world, or null.

public Entity FindComponent(string name)

Parameters

name string

Returns

Entity

Get<T>(Entity)

The component's value; a reference into the world's memory, valid until the next structural change.

public ref readonly T Get<T>(Entity entity) where T : unmanaged

Parameters

entity Entity

Returns

T

Type Parameters

T

GetComponentInfo(Entity)

What the registry knows about a component of this world, or null for an id that is not one.

public ComponentInfo? GetComponentInfo(Entity component)

Parameters

component Entity

Returns

ComponentInfo?

GetName(Entity)

The entity's name, or null when it has none or is not alive (Flecs does not check, and a dead entity's memory is gone).

public string? GetName(Entity entity)

Parameters

entity Entity

Returns

string?

GetParent(Entity)

public Entity GetParent(Entity entity)

Parameters

entity Entity

Returns

Entity

GetPointer(Entity, Entity)

The component's memory on the entity, or null; valid until the next structural change.

public byte* GetPointer(Entity entity, Entity component)

Parameters

entity Entity

component Entity

Returns

byte*

Has(Entity, Entity)

public bool Has(Entity entity, Entity id)

Parameters

entity Entity

id Entity

Returns

bool

Has<T>(Entity)

public bool Has<T>(Entity entity) where T : unmanaged

Parameters

entity Entity

Returns

bool

Type Parameters

T

IgnoreInScenes(string)

Leaves a component out of scenes: what is derived (WorldTransform, which is always left out) or only means something in this run (physics bodies).

public void IgnoreInScenes(string component)

Parameters

component string

InstanceOf(Entity)

The instance an entity belongs to: the nearest entity above it (or itself) that is an instance root; null when it is not part of one.

public Entity InstanceOf(Entity member)

Parameters

member Entity

Returns

Entity

Instantiate(string, Entity)

Makes the entities of a prefab file under parent (the world's top level when none) and returns the root, which has ; every entity made has with its id in the file. The entities are plain: the file's components are copied, and changing the instance changes nothing in the file. From a script this reads without the per-mod confinement of fs.read_text, as load_scene_file does.

public Entity Instantiate(string reference, Entity parent = default)

Parameters

reference string

The prefab: a path, uid://… (for the file that has that UID, wherever it moved to) or path|uid://….

parent Entity

Where the root goes; none puts it at the top level.

Returns

Entity

Exceptions

InvalidOperationException

The world has no .

ContentException

The reference is a uid:// that no file has.

FileNotFoundException

There is no such file.

FormatException

The reference is not valid, or the file is not a prefab.

Instantiate(uint, Entity)

Makes the entities of the prefab with this handle of . See .

public Entity Instantiate(uint prefab, Entity parent = default)

Parameters

prefab uint

parent Entity

Returns

Entity

Exceptions

ArgumentException

The handle is not one of the library's.

IsAlive(Entity)

public bool IsAlive(Entity entity)

Parameters

entity Entity

Returns

bool

IsPrefabInstance(Entity)

Whether the entity is the root of a prefab instance ().

public bool IsPrefabInstance(Entity entity)

Parameters

entity Entity

Returns

bool

IsUserEntity(Entity)

Whether the entity is one the game or an editor made (see above): alive, not Flecs' own, not a component or the data that describes one, not a system or an observer, not marked , and not under such an entity.

public bool IsUserEntity(Entity entity)

Parameters

entity Entity

Returns

bool

LoadScene(string, Entity)

Creates the entities of scene text, under parent when given, and returns them in the order of the file (parents first). A component the file names that this world cannot find, and a field it does not have, are logged and skipped; components that scripts defined are defined again from the file. Throws when the text is not a scene.

public List<Entity> LoadScene(string text, Entity parent = default)

Parameters

text string

parent Entity

Returns

List<Entity>

LoadScene(XmlNode, Entity)

Creates the entities of a Scene element (, or a file read with , possibly patched), under parent when given. See .

public List<Entity> LoadScene(XmlNode root, Entity parent = default)

Parameters

root XmlNode

parent Entity

Returns

List<Entity>

LoadSceneFile(string, Entity)

Creates the entities of the scene file at path (a path, or uid://… for the file that has that UID, wherever it moved to), under parent when given. The file is read as reads it, so a scene cooked into a pack loads like the text one. From a script this reads without the per-mod confinement of fs.read_text, as models.load and ui:load_document do. See .

public List<Entity> LoadSceneFile(string path, Entity parent = default)

Parameters

path string

parent Entity

Returns

List<Entity>

Exceptions

InvalidOperationException

The world has no .

ContentException

The path is a uid:// that no file has.

FileNotFoundException

There is no such file.

FormatException

The file is not a scene.

Lookup(string)

Finds an entity by name or path ("parent.child"); the null entity (id 0, which scripts see as the number 0) when there is none.

public Entity Lookup(string path)

Parameters

path string

Returns

Entity

Modified(Entity, Entity)

public void Modified(Entity entity, Entity component)

Parameters

entity Entity

component Entity

Modified<T>(Entity)

public void Modified<T>(Entity entity) where T : unmanaged

Parameters

entity Entity

Type Parameters

T

OnDestroyed()

protected override void OnDestroyed()

Pair(Entity, Entity)

The id that says "first with second": a relationship such as (ChildOf, parent).

public static Entity Pair(Entity first, Entity second)

Parameters

first Entity

second Entity

Returns

Entity

PrefabOf(Entity)

The prefab an instance root was made from, as the text of its (res://prefabs/lamp.aprefab|uid://…); null for any other entity.

public string? PrefabOf(Entity entity)

Parameters

entity Entity

Returns

string?

Progress(float)

Runs the systems of one frame in their phases. A system or observer that throws does not stop the others: the exceptions are collected and thrown together when the frame is done (a single one as itself, several as an ).

public void Progress(float deltaTime)

Parameters

deltaTime float

Query<T1>()

A query for entities that have all of the components.

public Query<T1> Query<T1>() where T1 : unmanaged

Returns

Query<T1>

Type Parameters

T1

Query<T1, T2>()

public Query<T1, T2> Query<T1, T2>() where T1 : unmanaged where T2 : unmanaged

Returns

Query<T1, T2>

Type Parameters

T1

T2

Query<T1, T2, T3>()

public Query<T1, T2, T3> Query<T1, T2, T3>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged

Returns

Query<T1, T2, T3>

Type Parameters

T1

T2

T3

Query<T1, T2, T3, T4>()

public Query<T1, T2, T3, T4> Query<T1, T2, T3, T4>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanaged

Returns

Query<T1, T2, T3, T4>

Type Parameters

T1

T2

T3

T4

RegisterAssetType(string, Func<uint, AssetRef?>, Func<AssetRef, uint>)

Says how the fields of an asset type (, such as model for ModelRenderer.Model) are saved. Such a field is a number in memory, a handle that only means something in this run (a model's number in the library); a scene holds the it names, the path and the UID, which is what lets it load in another run, and after the file moved.

public void RegisterAssetType(string type, Func<uint, AssetRef?> toRef, Func<AssetRef, uint> fromRef)

Parameters

type string

The asset type, as [Property(Asset = "…")] spells it.

toRef Func<uint, AssetRef?>

The reference a handle names, or null when it names nothing that can be saved (a model made in code has no path).

fromRef Func<AssetRef, uint>

The handle of this run for a reference (loading what it names when needed), or 0 when there is none. When it throws, the failure is logged, the field stays 0 and the scene loads on.

RegisterComponent(ComponentInfo)

Registers a component: an entity with the component's name, its size and alignment, and its fields as Flecs reflection data. Registering the same name again returns the same entity when the layout is the same and fails when it is not.

public Entity RegisterComponent(ComponentInfo info)

Parameters

info ComponentInfo

Returns

Entity

Remove(Entity, Entity)

public void Remove(Entity entity, Entity id)

Parameters

entity Entity

id Entity

Remove<T>(Entity)

public void Remove<T>(Entity entity) where T : unmanaged

Parameters

entity Entity

Type Parameters

T

Restore(WorldSnapshot)

Puts the world back as the snapshot says: user entities that are not in it are destroyed, the ones that are come back under their ids (made alive again when they were destroyed) with their components, names and parents as they were.

public void Restore(WorldSnapshot snapshot)

Parameters

snapshot WorldSnapshot

RestoreEntities(WorldSnapshot)

Brings back the entities of the snapshot under their ids, overwriting what is there, and destroys nothing: what an undo of a deletion does. A snapshot of another world comes back with this world's handles for the assets it named.

public void RestoreEntities(WorldSnapshot snapshot)

Parameters

snapshot WorldSnapshot

Roots()

The user entities that have no parent, in creation order.

public List<Entity> Roots()

Returns

List<Entity>

SavePrefabFile(string, Entity)

Writes root and everything below it as the prefab file at path. The ids in the file stay the same from one save to the next: an entity that came from this file ( of it) keeps its id, and a new one takes the file's nextId and raises it, so an id that was deleted is never used again. The file keeps its UID (a new one gets a new UID). Every entity written is marked as a member of the file, with its id there, so that saving again keeps it. Entity fields that point outside what is saved are left out, and an instance of another prefab inside is written as plain entities.

public void SavePrefabFile(string path, Entity root)

Parameters

path string

A path ending in .aprefab, or uid://… for the file that has that UID.

root Entity

The one root entity of the file.

Exceptions

InvalidOperationException

The world has no .

UnauthorizedAccessException

The path is not in a writable source.

ArgumentException

The path does not end in .aprefab, or the entity is not a user entity.

SaveScene()

The user entities () as scene text (XML). It has no uid: text is a copy, and a copy must not carry the identity of a file.

public string SaveScene()

Returns

string

SaveScene(Entity)

One entity and everything below it as scene text: a prefab, a copy for the clipboard.

public string SaveScene(Entity root)

Parameters

root Entity

Returns

string

SaveSceneDocument(IReadOnlyList<Entity>)

The entities in roots, each with everything below it, as a Scene element: what writes as text, for code that wants the tree (to add a uid to, to patch with DefDatabase.Merge, to cook).

public XmlNode SaveSceneDocument(IReadOnlyList<Entity> roots)

Parameters

roots IReadOnlyList<Entity>

Returns

XmlNode

SaveSceneFile(string)

Writes every user entity as the scene file at path. The file keeps its UID: when one is already there its uid is written again, and a new file gets a new one, so saving over a scene never changes what references to it mean ( makes text with no UID, for copies).

public void SaveSceneFile(string path)

Parameters

path string

Exceptions

InvalidOperationException

The world has no .

UnauthorizedAccessException

The path is not in a writable source.

SaveSceneFile(string, Entity)

One entity and everything below it as the scene file at path. See .

public void SaveSceneFile(string path, Entity root)

Parameters

path string

root Entity

Set<T>(Entity, in T)

public void Set<T>(Entity entity, in T value) where T : unmanaged

Parameters

entity Entity

value T

Type Parameters

T

SetName(Entity, string)

public void SetName(Entity entity, string name)

Parameters

entity Entity

name string

SetParent(Entity, Entity)

Makes parent the parent of entity (its becomes local to it), or with no parent (0) a root. It does not change the transform: set it to keep the entity where it is.

public void SetParent(Entity entity, Entity parent)

Parameters

entity Entity

parent Entity

SetPointer(Entity, Entity, int, void*)

Sets the component from data (copied) and adds it when missing.

public void SetPointer(Entity entity, Entity component, int size, void* data)

Parameters

entity Entity

component Entity

size int

data void*

Snapshot()

Takes every user entity () as it is now.

public WorldSnapshot Snapshot()

Returns

WorldSnapshot

SnapshotTree(Entity)

Takes one entity and everything below it, parents first.

public WorldSnapshot SnapshotTree(Entity root)

Parameters

root Entity

Returns

WorldSnapshot

Subtree(Entity)

The entity and everything below it, parents before children.

public List<Entity> Subtree(Entity root)

Parameters

root Entity

Returns

List<Entity>

ToJson(Entity, void*)

A component value as the JSON Flecs' reflection writes ({"x":1,"y":2}); for tools and tests.

public string ToJson(Entity component, void* data)

Parameters

component Entity

data void*

Returns

string

ToJson<T>(in T)

public string ToJson<T>(in T value) where T : unmanaged

Parameters

value T

Returns

string

Type Parameters

T

TryGet<T>(Entity, out T)

public bool TryGet<T>(Entity entity, out T value) where T : unmanaged

Parameters

entity Entity

value T

Returns

bool

Type Parameters

T

UserEntities()

Every user entity, in creation order (the order of their ids): what an editor searches when it looks for the one under the pointer.

public List<Entity> UserEntities()

Returns

List<Entity>