Scene

namespace Griff.Scenes;

public sealed class Scene

A tree of entities. All hierarchy changes go through the scene so its id index stays consistent.

The scene also keeps its components by type (All, Active) and which entities are active, so a game asking every frame doesn’t go through the whole hierarchy to find them.

Properties

Count

public int Count { get; }

Entities

public IReadOnlyList<Entity> Entities { get; }

Every entity in the scene, depth first, as it is now: adding or removing entities while going through it is safe, and it doesn’t change, however long it’s kept.

EntitiesNow

public Entity[] EntitiesNow { get; }

Every entity, for a system to go through in the step it asked in without keeping the array: once replaced (an entity added or destroyed), it’s filled again later, unless it was also handed out to be kept, so going through it each step makes no garbage.

PausedGroups

public IReadOnlyList<Entity> PausedGroups { get; }

The entities the game holds still with everything inside them, while it runs (see IsPaused).

Roots

public IReadOnlyList<Entity> Roots { get; }

Step

public long Step { get; }

The step the game is taking on this scene, or took last (the game’s Time.Frame then).

Version

public long Version { get; }

Changes whenever entities are added, removed or moved. Cheap to poll for structural changes.

Methods

Active

public ComponentList<T> Active<T>()

Like All, only those on active entities (see IsActive): what the game runs and draws.

ActiveNow

public ComponentList<T> ActiveNow<T>()

As Active, for a system to go through in the step it asked in without keeping the list (see AllNow).

Add

public void Add(Entity entity, Entity? parent = null, int? index = default)

Adds entity (and its descendants) under parent, or as a root if parent is null, at index or the end.

All

public ComponentList<T> All<T>()

Every component of type T in the scene, in hierarchy order. A base type or interface finds every kind of it (All<Collider>() finds box and circle colliders). Kept as the scene changes, so asking every frame is cheap; see ComponentList. It doesn’t change, however long it’s kept.

AllNow

public ComponentList<T> AllNow<T>()

As All, for a system to go through in the step it asked in without keeping the list: once replaced, it’s filled again two steps later, so enabling, disabling and destroying make no garbage.

Find

public Entity? Find(Guid id)

FindNamed

public Entity? FindNamed(string name, bool activeOnly = false, Entity? near = null)

The entity called name, found the one way names find entities (see EntityNames): one inside near first, then the scene, in near’s part of it (a minigame played in the scene, or outside them; without near, the minigame that has the screen) before another, and in a network game this machine’s player’s own first, so a camera or health bar follows your own.

IndexOf

public int IndexOf(Entity entity)

Position of entity among its siblings.

Move

public void Move(Entity entity, Entity? newParent, int? index = default)

Moves entity under a new parent (or to the root) at index.

Remove

public void Remove(Entity entity)

Removes entity and its descendants. They keep their own hierarchy.

Running

public ComponentList<T> Running<T>()

Like Active, less those on paused entities (see IsPaused): what the game moves on each step. The same list as Active while nothing is paused.

RunningNow

public ComponentList<T> RunningNow<T>()

As Running, for a system to go through in the step it asked in without keeping the list (see AllNow).

SamePart

public static bool SamePart(Entity entity, Entity? near)

True if entity is in the same part of the scene as near: the same minigame being played in it (see MinigameRoot), or both outside them. Always true while no minigame is.