Class TextModeEffectPlayer

Runs text effects against a grid, advancing every active effect once per frame and handing out the pooled scratch storage they need.

Inheritance
object
TextModeEffectPlayer
Implements
Inherited Members
Namespace: Scylla.TextMode
Assembly: ScyllaTextMode.dll
Syntax
public sealed class TextModeEffectPlayer : ITextEffectContext, IDisposable
Remarks

Each view lazily creates a player the first time something plays an effect on it, and ticks it from LateUpdate immediately before uploading the grid to the GPU. That ordering matters: an effect that wrote its cells after the upload would not appear until the following frame. A view with no effects holds no player at all, so it pays a single null check per frame and nothing else.

A player can also be constructed directly against a bare grid and ticked by hand, which is how effects work in a headless context or on a console with no view attached.

The registry is a fixed-size array rather than a list, so running effects allocates nothing per frame. Playing more than Capacity effects at once logs a warning and refuses the newest, rather than growing without bound.

Constructors

TextModeEffectPlayer(CellGrid, GlyphAtlasCache, int)

Creates a player targeting a grid directly.

Declaration
public TextModeEffectPlayer(CellGrid grid, GlyphAtlasCache glyphCache, int capacity = 0)
Parameters
Type Name Description
CellGrid grid

The grid effects write into.
GlyphAtlasCache glyphCache

Glyph cache used to stamp codepoints. May be null for effects that only move or recolor existing cells.
int capacity

Maximum number of effects that can run at once, clamped to the supported range. Zero takes the limit from the TextMode configuration.

TextModeEffectPlayer(ITextModeGridProvider, int)

Creates a player targeting the grid of an existing view.

Declaration
public TextModeEffectPlayer(ITextModeGridProvider provider, int capacity = 0)
Parameters
Type Name Description
ITextModeGridProvider provider

The view supplying the grid and glyph cache.
int capacity

Maximum number of effects that can run at once, clamped to the supported range. Zero takes the limit from the TextMode configuration.

Properties

ActiveCount

Gets the number of effects currently being advanced.

Declaration
public int ActiveCount { get; }
Property Value
Type Description
int

Capacity

Gets the maximum number of effects that can run at once.

Declaration
public int Capacity { get; }
Property Value
Type Description
int

CellAspect

Gets the width of a cell divided by its height, which effects use to keep radial and diagonal shapes from coming out stretched. Cells are typically about twice as tall as they are wide, so this is usually around 0.5.

Declaration
public float CellAspect { get; set; }
Property Value
Type Description
float

Console

Gets the high-level writer over Grid, for effects that print text rather than stamping individual cells.

Declaration
public TextModeConsole Console { get; }
Property Value
Type Description
TextModeConsole

GlyphCache

Gets the glyph cache used to stamp codepoints an effect introduces itself. Effects that only move or recolor existing cells do not need it.

Declaration
public GlyphAtlasCache GlyphCache { get; }
Property Value
Type Description
GlyphAtlasCache

Grid

Gets the grid effects write into. Never null while an effect is bound.

Declaration
public CellGrid Grid { get; }
Property Value
Type Description
CellGrid

HasActiveEffects

Gets whether any effect is currently being advanced.

Declaration
public bool HasActiveEffects { get; }
Property Value
Type Description
bool

IsEnabled

Gets or sets whether the player advances effects. Setting this false freezes every active effect in place without stopping it, and costs one branch per frame.

Declaration
public bool IsEnabled { get; set; }
Property Value
Type Description
bool

ReduceMotion

Gets or sets whether effects resolve instantly instead of animating.

Declaration
public bool ReduceMotion { get; set; }
Property Value
Type Description
bool
Remarks

This is an accessibility setting, adopted from the TextMode configuration. An effect played while this is set jumps straight to its finished state, so the content appears at once. Completion callbacks still fire, which means game logic sequenced off the end of an effect keeps working unchanged.

TimeScale

Gets or sets a speed multiplier applied to every effect this player runs, on top of each effect's own speed.

Declaration
public float TimeScale { get; set; }
Property Value
Type Description
float

Methods

AdoptConfiguration()

Re-reads the effect settings from the active TextMode configuration.

Declaration
public void AdoptConfiguration()
Remarks

Views call this when the configuration changes, so edits made in the Inspector during play mode take effect without restarting the scene. The concurrency limit is not re-read, because the registry is allocated once when the player is created.

Dispose()

Declaration
public void Dispose()

IsPlaying(ITextEffect)

Checks whether a given effect is currently owned and being advanced by this player.

Declaration
public bool IsPlaying(ITextEffect effect)
Parameters
Type Name Description
ITextEffect effect

The effect to look for.
Returns
Type Description
bool

True if the player is running it.

IsRegionBusy(in CellRect)

Checks whether any active effect currently owns cells overlapping the given block.

Declaration
public bool IsRegionBusy(in CellRect region)
Parameters
Type Name Description
CellRect region

The block of cells to test.
Returns
Type Description
bool

True if an active effect overlaps the region.
Remarks

Drawing into a region while an effect is playing there will fight with the effect, because the effect keeps rewriting those cells from its own captured state. Ask this first when game code might redraw over an animating area.

NotifyGridChanged(CellGrid)

Tells the player its grid changed shape or identity, so it can drop effects that are now working from stale coordinates.

Declaration
public void NotifyGridChanged(CellGrid grid)
Parameters
Type Name Description
CellGrid grid

The grid as it is now.

PauseAll()

Suspends every active effect, keeping its progress.

Declaration
public void PauseAll()

Play(TextEffectSequencer)

Starts a sequence, running its effects on this player one after another.

Declaration
public TextEffectSequencer Play(TextEffectSequencer sequence)
Parameters
Type Name Description
TextEffectSequencer sequence

The sequence to start.
Returns
Type Description
TextEffectSequencer

The sequence, so it can be stopped or listened to.
Remarks

The sequence is not itself an effect and owns no cells. It hands each of its effects to this player in turn, so each one behaves exactly as it would played on its own.

Play<T>(T)

Starts an effect and takes ownership of it, so the player advances and disposes it.

Declaration
public T Play<T>(T effect) where T : TextEffectBase
Parameters
Type Name Description
T effect

The effect to start.
Returns
Type Description
T

The effect, whether or not it could be started.
Type Parameters
Name Description
T

The concrete effect type.
Remarks

Returns the effect it was given, so a configured effect can be played and kept in one expression when game code wants to stop or skip it later.

RentBuffer()

Rents a cell buffer for the duration of an effect.

Declaration
public CellBuffer RentBuffer()
Returns
Type Description
CellBuffer

A buffer holding nothing, ready to be resized and captured into.

RentThresholds(int)

Rents a float array of at least the requested length, for per-cell threshold values.

Declaration
public float[] RentThresholds(int minimumLength)
Parameters
Type Name Description
int minimumLength

Smallest acceptable array length.
Returns
Type Description
float[]

An array of at least minimumLength entries.
Remarks

The array may be longer than requested and its contents are undefined, so fill every entry that will be read before reading any of them.

ResumeAll()

Resumes every suspended effect.

Declaration
public void ResumeAll()

ReturnBuffer(CellBuffer)

Returns a previously rented cell buffer.

Declaration
public void ReturnBuffer(CellBuffer buffer)
Parameters
Type Name Description
CellBuffer buffer

The buffer to return. Null is ignored.

ReturnThresholds(float[])

Returns a previously rented threshold array.

Declaration
public void ReturnThresholds(float[] thresholds)
Parameters
Type Name Description
float[] thresholds

The array to return. Null is ignored.

SetTarget(CellGrid, GlyphAtlasCache)

Points the player at a different grid, stopping every active effect first.

Declaration
public void SetTarget(CellGrid grid, GlyphAtlasCache glyphCache)
Parameters
Type Name Description
CellGrid grid

The new grid, which may be the same instance after a resize.
GlyphAtlasCache glyphCache

The glyph cache that goes with it.
Remarks

Effects hold snapshots and coordinates that belong to the grid they started on, so a resize or a grid swap invalidates them. Stopping is the honest response: an effect cannot meaningfully continue against a grid of a different shape.

Stop(ITextEffect, bool)

Stops an effect this player owns and releases it.

Declaration
public bool Stop(ITextEffect effect, bool applyFinalState = false)
Parameters
Type Name Description
ITextEffect effect

The effect to stop.
bool applyFinalState

True to leave the region looking as though the effect had finished, false to leave it mid-flight.
Returns
Type Description
bool

True if the effect was found and stopped.

StopAll(bool)

Stops every effect this player owns.

Declaration
public void StopAll(bool applyFinalState = false)
Parameters
Type Name Description
bool applyFinalState

True to leave each region looking as though its effect had finished.

Tick()

Advances every active effect, choosing a delta time per effect from its TimeMode.

Declaration
public void Tick()
Remarks

This is what the views call. Effects set to scaled time honor framework pause and time scale; effects set to unscaled time keep running through both. When the framework has not been initialized, Unity's own delta times are used instead.

Tick(float)

Advances every active effect by an explicit delta time, ignoring each effect's time mode.

Declaration
public void Tick(float deltaTime)
Parameters
Type Name Description
float deltaTime

Seconds elapsed since the previous tick.

TryRenderScratch(Action<TextModeConsole>, in CellRect, CellBuffer)

Draws something onto a scratch grid and captures a region of the result, without disturbing what is currently on screen.

Declaration
public bool TryRenderScratch(Action<TextModeConsole> draw, in CellRect region, CellBuffer destination)
Parameters
Type Name Description
Action<TextModeConsole> draw

Callback that draws the target state.
CellRect region

The block of cells to capture from the result.
CellBuffer destination

Buffer to capture into.
Returns
Type Description
bool

True if the target was drawn and captured.
Remarks

This is how a transition gets hold of the screen it is transitioning to. The callback is handed a console over a spare grid the same size as the live one and writes to it exactly as it would to the real thing, in full-grid coordinates, so game code that draws a screen needs no special version for transitions.

The scratch grid is cleared before the callback runs and is reused between calls, so nothing survives from one transition to the next.

Implements