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¶
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 (
public AssetDatabase? Assets { get; set; }
Property Value¶
Class¶
What the registry knows about this object's class.
public override ClassInfo Class { get; }
Property Value¶
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¶
DeltaTime¶
The time step of the current
public float DeltaTime { get; }
Property Value¶
Files¶
The files scene files are read from and written to (
public VirtualFileSystem? Files { get; set; }
Property Value¶
Frame¶
The number of frames
public long Frame { get; }
Property Value¶
Prefabs¶
The prefab files this world knows, and the handles that prefab asset type ([Property(Asset = "prefab")]) is saved
through it.
public PrefabLibrary Prefabs { get; set; }
Property Value¶
Exceptions¶
The world has no
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¶
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¶
Type Parameters¶
T1
AddSystem(string, ReadOnlySpan<QueryTerm>, Phase, TableAction)¶
Adds a system: action runs once per matching table in every
public Entity AddSystem(string name, ReadOnlySpan<QueryTerm> terms, Phase phase, TableAction action)
Parameters¶
name string
terms ReadOnlySpan<QueryTerm>
phase Phase
action TableAction
Returns¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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
public Trs ComputeWorldTransform(Entity entity)
Parameters¶
entity Entity
Returns¶
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¶
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¶
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 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¶
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
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
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¶
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¶
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¶
GetParent(Entity)¶
public Entity GetParent(Entity entity)
Parameters¶
entity Entity
Returns¶
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¶
Has<T>(Entity)¶
public bool Has<T>(Entity entity) where T : unmanaged
Parameters¶
entity Entity
Returns¶
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¶
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 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¶
Exceptions¶
The world has no
The reference is a uid:// that no file has.
There is no such file.
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
public Entity Instantiate(uint prefab, Entity parent = default)
Parameters¶
prefab uint
parent Entity
Returns¶
Exceptions¶
The handle is not one of the library's.
IsAlive(Entity)¶
public bool IsAlive(Entity entity)
Parameters¶
entity Entity
Returns¶
IsPrefabInstance(Entity)¶
Whether the entity is the root of a prefab instance (
public bool IsPrefabInstance(Entity entity)
Parameters¶
entity Entity
Returns¶
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
public bool IsUserEntity(Entity entity)
Parameters¶
entity Entity
Returns¶
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
public List<Entity> LoadScene(string text, Entity parent = default)
Parameters¶
text string
parent Entity
Returns¶
LoadScene(XmlNode, Entity)¶
Creates the entities of a Scene element (parent when given.
See
public List<Entity> LoadScene(XmlNode root, Entity parent = default)
Parameters¶
root XmlNode
parent Entity
Returns¶
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 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¶
Exceptions¶
The world has no
The path is a uid:// that no file has.
There is no such file.
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¶
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¶
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¶
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 (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
public void RegisterAssetType(string type, Func<uint, AssetRef?> toRef, Func<AssetRef, uint> fromRef)
Parameters¶
type string
The asset type, as [Property(Asset = "…")] spells it.
The reference a handle names, or null when it names nothing that can be saved (a model made in code has no path).
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¶
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¶
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 (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¶
The world has no
The path is not in a writable source.
The path does not end in .aprefab, or the entity is not a user entity.
SaveScene()¶
The user entities (uid: text is a copy, and a copy must not carry the identity of a file.
public string SaveScene()
Returns¶
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¶
SaveSceneDocument(IReadOnlyList<Entity>)¶
The entities in roots, each with everything below it, as a Scene element: what uid to, to patch with DefDatabase.Merge, to cook).
public XmlNode SaveSceneDocument(IReadOnlyList<Entity> roots)
Parameters¶
roots IReadOnlyList<Entity>
Returns¶
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 (
public void SaveSceneFile(string path)
Parameters¶
path string
Exceptions¶
The world has no
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
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 (
public WorldSnapshot Snapshot()
Returns¶
SnapshotTree(Entity)¶
Takes one entity and everything below it, parents first.
public WorldSnapshot SnapshotTree(Entity root)
Parameters¶
root Entity
Returns¶
Subtree(Entity)¶
The entity and everything below it, parents before children.
public List<Entity> Subtree(Entity root)
Parameters¶
root Entity
Returns¶
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¶
ToJson<T>(in T)¶
public string ToJson<T>(in T value) where T : unmanaged
Parameters¶
value T
Returns¶
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¶
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()