Interface IWorld

Namespace: MicroEngine.Scenes
Assembly: MicroEngine.Scene.dll
Guide: Scenes

The objects of a scene: entities with an id, a transform (with an optional parent) and typed attachments. The world runs no game logic: it stores, identifies, orders, interpolates and destroys. Game code programs against this interface; the scene that owns the world drives its step and draw hooks (SceneWorld).

C#

public interface IWorld

Remarks

The rules of the contract:

1. Ids are generation-checked; a released slot is reused with a new generation. For a stale id [IsAlive](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_IsAlive_MicroEngine_Scenes_EntityId_) and [TryGet``1](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_TryGet__1_MicroEngine_Scenes_EntityId___0__) are false; [Local](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_Local_MicroEngine_Scenes_EntityId_), [Get``1](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_Get__1_MicroEngine_Scenes_EntityId_) and [ParentOf](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_ParentOf_MicroEngine_Scenes_EntityId_) throw `InvalidOperationException` naming the id and why.
2. Destroy takes effect at once for queries ([IsAlive](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_IsAlive_MicroEngine_Scenes_EntityId_) false, [Count](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_Count) drops, every iteration skips it and its subtree). Its transform and attachments stay readable through its id until the world ends the step; then [IDestroyedCallback](/docs/api/microengine.scenes.idestroyedcallback/) attachments are told in destroy order and the slot is released, never during an iteration. Destroying a destroyed, stale or [None](/docs/api/microengine.scenes.entityid/#MicroEngine_Scenes_EntityId_None) id does nothing.
3. Creation takes effect at once: the id is valid and its transform writable. An iteration already running does not visit it; every later one does. There is no spawn queue.
4. Iteration: [All``1](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_All__1) walks the attachments of one type of live entities in attach order, stable under removal. Attachments are keyed by the type argument, not the runtime type. foreach allocates nothing.
5. Interpolation: drawing reads [WorldMatrix](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_WorldMatrix_MicroEngine_Scenes_EntityId_) or [DrawPosition2D](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_DrawPosition2D_MicroEngine_Scenes_EntityId_) at the world's [Blend](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_Blend), from each entity's transform at the start of the step to its current one; at blend 1, or when nothing moved, the result is exactly the simulated transform. A child's matrix is its interpolated local matrix times its parent's.
6. Teleport: a new, teleported or re-parented entity is drawn at its current transform until the next step starts; a teleported parent carries its children.
7. Step tracking: [Blend](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_Blend) is the engine's blend when this world stepped in the engine's latest fixed step, otherwise 1 (paused, under an overlay, in a transition), so a frozen world is drawn as its last step.
8. Clock: [Clock](/docs/api/microengine.scenes.iworld/#MicroEngine_Scenes_IWorld_Clock) advances once per step of this world; at scale 1 the scaled step is the engine's step bit for bit.

Properties

Blend

The blend drawing uses this frame: the engine’s, or 1 when this world did not step in the latest engine step.

C#

float Blend { get; }

Property Value

float

Clock

The world’s clock: scaled time, time scale and freezes (hitstop).

C#

WorldClock Clock { get; }

Property Value

WorldClock

Count

Live entities (destroyed ones not counted).

C#

int Count { get; }

Property Value

int

Methods

All<T>()

The attachments of type T of live entities, in attach order; foreach allocates nothing.

C#

Attachments<T> All<T>() where T : class

Returns

Attachments<T>

Type Parameters

T

Attach<T>(EntityId, T)

Attaches attachment under the type T; replaces one already there, in its place.

C#

T Attach<T>(EntityId entity, T attachment) where T : class

Parameters

entity EntityId

attachment T

Returns

T

Type Parameters

T

Exceptions

InvalidOperationException

The entity is stale or destroyed.

Children(EntityId)

The live direct children of parent, in the order they were given that parent; foreach allocates nothing. A child created during the walk is visited by the next one; re-parenting during it throws.

C#

EntityChildren Children(EntityId parent)

Parameters

parent EntityId

Returns

EntityChildren

Create(EntityId)

Creates an entity at Identity, under parent when given.

C#

EntityId Create(EntityId parent = default)

Parameters

parent EntityId

Returns

EntityId

Exceptions

InvalidOperationException

parent is stale or destroyed.

Destroy(EntityId)

Destroys the entity and its subtree (see the rules); nothing for a destroyed, stale or none id.

C#

void Destroy(EntityId entity)

Parameters

entity EntityId

Detach<T>(EntityId)

Removes the attachment of type T; false when there was none.

C#

bool Detach<T>(EntityId entity) where T : class

Parameters

entity EntityId

Returns

bool

Type Parameters

T

DrawPosition2D(EntityId)

The world X/Y drawn this frame (at Blend); no matrix work for a root or under translation-only parents.

C#

Vector2 DrawPosition2D(EntityId entity)

Parameters

entity EntityId

Returns

Vector2

Get<T>(EntityId)

The attachment of type T.

C#

T Get<T>(EntityId entity) where T : class

Parameters

entity EntityId

Returns

T

Type Parameters

T

Exceptions

InvalidOperationException

There is none, or the id is stale.

IsAlive(EntityId)

Whether entity exists and was not destroyed.

C#

bool IsAlive(EntityId entity)

Parameters

entity EntityId

Returns

bool

Local(EntityId)

The transform relative to the parent, by reference (write through it).

C#

ref Transform Local(EntityId entity)

Parameters

entity EntityId

Returns

Transform

ParentOf(EntityId)

The parent, or None for a root.

C#

EntityId ParentOf(EntityId entity)

Parameters

entity EntityId

Returns

EntityId

SetParent(EntityId, EntityId)

Moves the entity under parent (None: to the root), keeping its local transform; it is drawn at its current transform until the next step starts.

C#

void SetParent(EntityId entity, EntityId parent)

Parameters

entity EntityId

parent EntityId

Exceptions

InvalidOperationException

The move would make the entity its own ancestor, or an id is stale or destroyed.

Teleport(EntityId)

Draws the entity (and so its children) at its current transform until the next step starts.

C#

void Teleport(EntityId entity)

Parameters

entity EntityId

TryGet<T>(EntityId, out T?)

The attachment of type T, if any (also of an entity destroyed this step).

C#

bool TryGet<T>(EntityId entity, out T? attachment) where T : class

Parameters

entity EntityId

attachment T?

Returns

bool

Type Parameters

T

WorldMatrix(EntityId)

The world matrix drawn this frame (at Blend).

C#

Matrix4x4 WorldMatrix(EntityId entity)

Parameters

entity EntityId

Returns

Matrix4x4