Stage

namespace Griff.Modules.VisualNovels;

public sealed class Stage : Component, IDrawable

A visual novel’s stage: a background filling its Size, and the characters inside it (each a Character) standing at its named Positions. The lines of a Dialogue direct it with tags, done as each line is said: “[background Park fade]” changes the background, “[show Ava left happy]” brings Ava on at the left looking happy (or, when she’s on already, moves her there and changes her face), “[move Ava right]” walks her over, “[hide Ava]” takes her off and “[hide all]” clears the stage; a tag can end with how it happens, cut, fade or slide. “Ava (happy): …” says a line with that expression. Whoever speaks is lit and the others on stage dimmed. Its AdvanceAction (Space, the gamepad’s A) moves the talk on as Interact and a click or tap do (finishing the line being typed first).

A dialogue directs the stage it’s inside, or else the scene’s first. Its Background, Show, Hide, Hide All and Direct actions are there for a trigger, a wire or a script, and its Background and Speaking outputs for a text. What it shows (the background, who’s on, where and how they look, and transitions under way) is saved with the scene, so a rewind goes back to it. In a network game each machine keeps its own stage, for its own player’s reading.

This is a component: its saved properties are on its component page.

Properties

AdvanceAction

public string? AdvanceAction { get; set; }

An input action that moves the talk on as well as Interact and a click: Jump is Space and the gamepad’s A.

AutoAction

public string? AutoAction { get; set; }

An input action that turns reading on by itself on and off (see the player’s Auto Speed setting): Auto is A and the gamepad’s X.

Background

public string? Background { get; set; }

The background showing, one of Backgrounds: set it here for the one the game starts with.

BackgroundTransition

public StageTransition BackgroundTransition { get; set; }

How backgrounds change when a tag doesn’t say: “[background Park]”.

Backgrounds

public IReadOnlyList<string> Backgrounds { get; set; }

The backgrounds it can show, one per row: a name and a picture (“Park: Backgrounds/park.png”), a color (“Night: #10183A”), or a color at the top running to another at the bottom (“Dusk: #F2A65A #3A2F5B”). Tags name them: “[background Park fade]”.

Cast

public IReadOnlyList<Character> Cast { get; }

Its characters: those inside it, and, for the scene’s first stage, any that aren’t inside a stage at all.

ChangeLeft

public float ChangeLeft { get; set; }

Seconds left of the background’s change.

Changing

public StageTransition Changing { get; set; }

How the background is changing.

CharacterTransition

public StageTransition CharacterTransition { get; set; }

How characters come on and go off when a tag doesn’t say: “[show Ava]”.

Controllable

public bool Controllable { get; set; }

Takes the player’s input: off, its Advance Action doesn’t move the talk on (Interact and clicks still do).

DefaultPositions

public static IReadOnlyList<string> DefaultPositions { get; }

The positions a new stage starts with.

DimOthers

public float DimOthers { get; set; }

How much darker the others on stage go while someone on it speaks, from 0 (not at all) to 1 (black). When nobody on stage speaks (a narrator), nobody is dimmed.

LeavingBackground

public string? LeavingBackground { get; set; }

The background being changed from, while a fade or slide is under way.

MoveTime

public float MoveTime { get; set; }

Seconds a character takes to walk to another position.

OnStage

public int OnStage { get; }

How many characters are on it now.

Order

public int Order { get; set; }

Where the background draws among the rest: under the characters (0) and the dialogue box.

Positions

public IReadOnlyList<string> Positions { get; set; }

Where characters stand, one per row: a one-word name and how far across from the stage’s middle (and, after a comma, how far up), e.g. “Left: -4.5” or “FarLeft: -7, -0.5”. Tags name them: “[show Ava left]”.

Size

public Vector2 Size { get; set; }

How big the background is, in world units (as much as the camera shows, for a whole screen).

SkipAction

public string? SkipAction { get; set; }

An input action that skips while it’s held: lines read before go by in a moment, stopping at choices and at a line not read yet (unless the player’s Skip Unread setting is on). Skip is Ctrl and the gamepad’s right trigger.

SlideDistance

public float SlideDistance { get; set; }

How far a character slides in from (or out to), past their position, toward the side of the stage they’re on.

Speaking

public string Speaking { get; }

The name of whoever on the stage is speaking now, or empty.

TransitionTime

public float TransitionTime { get; set; }

Seconds a fade or slide takes.

Methods

ChangeBackground

public void ChangeBackground(string name)

Changes the background to name, one of Backgrounds, as “[background Park]” does, with its BackgroundTransition.

CharacterNamed

public Character? CharacterNamed(string? name)

The character called name (their speaker’s name, or their entity’s), or null.

Direct

public void Direct(string direction)

Does a direction written as a dialogue tag says it, without the brackets: “show Ava left happy”, “background Night fade”.

Hide

public void Hide(string character)

Takes the character called that off, as “[hide Ava]” does.

HideAll

public void HideAll()

Takes everyone off, as “[hide all]” does.

PositionOf

public Vector2? PositionOf(string? name)

Where position name is from the stage’s middle, or null when it has none called that.

Show

public void Show(string character)

Brings the character called that on, as “[show Ava]” does: where they were last, or in the middle.

StageOf

public static Stage? StageOf(Entity entity)

The stage entity is inside (or is), or null.