Class Scene

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

A screen of the game (title, level, battle, pause menu…). Scenes live on a stack: an overlay scene (dialogue, pause) draws on top of the scene below and can freeze it. Each scene owns its coroutines and tweens, which stop when it leaves the stack.

C#

public abstract class Scene : IStateHashed

Inheritance

object ← Scene

Derived

Scene<TResult>

Implements

IStateHashed

Examples

C#

public sealed class TitleScene : Scene
{
    public override void Update(float dt)
    {
        if (Input.Pressed("confirm")) Game.Scenes.Replace(new LevelScene(), Transition.Fade());
    }

    public override void Draw(IRenderer renderer) =>
        Font.DrawCentered(renderer, "PRESS START", new Vector2(Game.Width / 2f, Game.Height / 2f), Color.White);
}

Constructors

Scene()

C#

protected Scene()

Properties

Age

Seconds this scene has been updated.

C#

public float Age { get; }

Property Value

float

Assets

The game’s content files (Assets).

C#

public AssetCache Assets { get; }

Property Value

AssetCache

Audio

The game’s audio mixer (Audio).

C#

public AudioMixer Audio { get; }

Property Value

AudioMixer

BlocksUpdateBelow

When true (default), scenes below an overlay are not updated.

C#

public virtual bool BlocksUpdateBelow { get; }

Property Value

bool

Coroutines

Coroutines owned by this scene. They advance before Update while the scene is updated and stop when it leaves the stack.

C#

public CoroutineRunner Coroutines { get; }

Property Value

CoroutineRunner

EngineStep

The engine’s step in seconds (1 / UpdateRate): the step of the current update before the world’s clock scales or freezes it. Age, Coroutines and Tweens advance by it, and it is what Update receives when the scene has no Objects. Use it for what keeps moving through a hitstop or slow motion (play time, camera shake, particles, a pause button) while the rules advance by Update’s step. Known from Enter on.

C#

public float EngineStep { get; }

Property Value

float

Exceptions

InvalidOperationException

Read before the scene is on a running game’s stack and was updated.

Font

The game’s built-in font (Font).

C#

public BitmapFont Font { get; }

Property Value

BitmapFont

Game

The game this scene belongs to. Set when the scene is pushed; throws InvalidOperationException before that (for example in the scene’s constructor).

C#

public Game Game { get; }

Property Value

Game

Input

The game’s input actions (Input).

C#

public InputMap Input { get; }

Property Value

InputMap

IsOverlay

When true, the scene below is drawn first.

C#

public virtual bool IsOverlay { get; }

Property Value

bool

Objects

The scene’s objects (IWorld), created the first time it is read. While the scene is updated the engine steps it with the scene: each step starts before the scene’s coroutines, tweens and Update (which then receives the step on the world’s Clock) and ends after them, releasing what was destroyed. Before Draw the engine sets its Blend: the frame’s blend when the scene was updated in the latest step, 1 when it was not (frozen under an overlay, in a transition), so drawing through DrawPosition2D and WorldMatrix is smooth while it plays and still while it is frozen. Its state is part of the scene’s state hash.

C#

public IWorld Objects { get; }

Property Value

IWorld

Remarks

Create it outside drawing: read it first from Enter, Update or the scene’s constructor. A world created by drawing would be stepped and hashed only in runs that drew a frame, so the state hash would depend on the display; the first read from Draw or DrawUi is refused instead.

Exceptions

InvalidOperationException

Read for the first time while the game draws.

TouchActions

The actions this scene needs from the on-screen touch controls while it is on top, or null for all of them (the default). A dialogue returns [“confirm”, “cancel”]: the movement control disappears from over its text and the buttons that confirm and cancel stay. Read every frame, so a scene may change it with its own state.

C#

public virtual IReadOnlyCollection<string>? TouchActions { get; }

Property Value

IReadOnlyCollection<string>?

Tweens

Tweens owned by this scene. They advance before Update while the scene is updated and are cleared when it leaves the stack.

C#

public Tweener Tweens { get; }

Property Value

Tweener

Widgets

The scene’s widgets (UiRoot), created the first time it is read (from Enter on; the scene must be on the stack). Set its Content and the engine does the rest: it lays the widgets out in UI units in the UI view and draws them after DrawUi, updates them before Update (so the actions they act on are consumed before the scene reads them), and, while the scene is on top, routes input to them as the highest input layer: a press on a widget, and the keyboard while a text field has the focus, never reach gameplay, and the pointer over them is on the UI (PointerOnUi). The widgets use the game’s font and the map’s action names until the game sets others. A scene that never reads it has no UI and pays nothing.

C#

public UiRoot Widgets { get; }

Property Value

UiRoot

Exceptions

InvalidOperationException

The scene is not attached to a game yet (read from its constructor).

WorldCamera

The camera of the scene’s world view: when set, the engine pushes it before Draw and pops it after, so Draw draws in world coordinates. Null (the default) draws in canvas pixels.

C#

public Camera2D? WorldCamera { get; set; }

Property Value

Camera2D?

Methods

Describe()

A short description of the scene’s state for development probes and tests (the web host’s trace, for example “x=120 y=88 grounded”); null by default. Never shown to players.

C#

public virtual string? Describe()

Returns

string?

Draw(IRenderer)

Draws the scene’s world once per frame into the canvas (the world view). Scenes below an overlay are drawn first. With a WorldCamera, the engine pushes it around this call.

C#

public abstract void Draw(IRenderer renderer)

Parameters

renderer IRenderer

The renderer of the current frame.

DrawUi(IRenderer)

Draws the scene’s interface once per frame in the UI view, after every scene’s world: in UI units at the window’s resolution (UiSize), composited over the world, so text and shapes stay sharp whatever the canvas’s resolution. On a platform without a UI view it is drawn in the canvas instead. Does nothing by default.

C#

public virtual void DrawUi(IRenderer ui)

Parameters

ui IRenderer

The UI view’s renderer: ui.Width and ui.Height are its size in UI units.

Enter()

Called when the scene is pushed onto the stack, after Game is set and input was reset.

C#

public virtual void Enter()

Exit()

Called when the scene leaves the stack (popped, replaced or cleared), after its coroutines and tweens stopped.

C#

public virtual void Exit()

HashState(StateHasher)

Adds the scene’s simulation state to the per-step state hash (ComputeStateHash): the fields that decide what happens next (positions, velocities, timers, health, the state of its own generators), in a fixed order. Leave out what Draw writes (text and layout caches, positions held for blending, particles that are only drawn): the hash must be the same whether or not a frame was drawn. The engine adds the scene’s type, Age, coroutines and tweens itself, in the scene’s section (scene[index]:Type). The default adds nothing.

C#

public virtual void HashState(StateHasher hash)

Parameters

hash StateHasher

The hasher of the step; a section started here lasts until the engine starts the next one.

Resume()

Called when a scene pushed above this one is popped.

C#

public virtual void Resume()

UiContains(Vector2)

Whether uiPoint (UI units) lies on this scene’s interface, so the pointer belongs to the UI view there and not to the world (PointerOnUi). False by default.

C#

public virtual bool UiContains(Vector2 uiPoint)

Parameters

uiPoint Vector2

Returns

bool

Update(float)

Advances the scene by one fixed step. Not called while a blocking overlay is above, nor during the covering half of a transition.

C#

public abstract void Update(float dt)

Parameters

dt float

Step length in seconds: 1 / UpdateRate, or, once the scene has Objects, the step on the world’s clock (the same at scale 1; scaled by Scale; 0 while it is frozen).