Class UnityCutscenePlayerService

Unity cutscene player service providing cutscene-specific playback API.
Executes timed stages directly using ITimedSequenceStage.DurationSeconds.

CutscenePlayer is a first-class vertical aggregate, NOT legacy. It provides cutscene authoring, tooling, and UX on top of the generic SequencePlayer orchestration foundation.

NOTE: This service does NOT delegate to UnitySequencePlayerService. It executes stages directly because CutscenePlayer owns timed orchestration. RigPrefab is owned by CutscenePlayer, NOT by generic SequencePlayer.

Bounded-wait contract (Slice W): every wait path in this service has a hard upper bound enforced via either Delay(TimeSpan, CancellationToken) against a sanitized duration, or a wall-clock-driven loop against UnityEngine.Time.realtimeSinceStartup. No code path waits for a Unity callback (UnityEngine.Playables.PlayableDirector.stopped, UnityEngine.Time.unscaledDeltaTime tick) without also racing it against a finite timeout. This is required for WebGL where PlayableDirector.stopped may not fire reliably for some timeline shapes, AudioContext suspension can stall the main update loop, and a hung cutscene would otherwise block the entire initialization pipeline indefinitely.

Inheritance
object
UnityCutscenePlayerService
Implements
Namespace: Serenity.CutscenePlayer.Infrastructure.Services
Assembly: Serenity.UnityCutscenePlayer.Infrastructure.dll
Syntax
public class UnityCutscenePlayerService : MonoBehaviour, ICutscenePlayerService, ISequencePlayerService, IService, IFoundationSettings

Constructors

UnityCutscenePlayerService()

Declaration
public UnityCutscenePlayerService()

Fields

_activeRig

Declaration
protected GameObject _activeRig
Field Value
Type Description
GameObject

_director

Declaration
protected PlayableDirector _director
Field Value
Type Description
PlayableDirector

_guid

Declaration
protected string _guid
Field Value
Type Description
string

_id

Declaration
protected string _id
Field Value
Type Description
string

_logService

Declaration
protected ILogService _logService
Field Value
Type Description
ILogService

_loopingRigs

Declaration
protected readonly Dictionary<string, GameObject> _loopingRigs
Field Value
Type Description
Dictionary<string, GameObject>

_overlayCanvas

Declaration
protected Canvas _overlayCanvas
Field Value
Type Description
Canvas

_overlayImage

Declaration
protected Image _overlayImage
Field Value
Type Description
Image

cutsceneDefinitions

Declaration
protected UnityCutsceneDefinition[] cutsceneDefinitions
Field Value
Type Description
UnityCutsceneDefinition[]

Properties

Guid

Declaration
public string Guid { get; set; }
Property Value
Type Description
string

Id

Declaration
public string Id { get; set; }
Property Value
Type Description
string

LogService

Declaration
public ILogService LogService { get; set; }
Property Value
Type Description
ILogService

Methods

Initialize(ILogService)

Initializes the cutscene player service with logging dependency.

Declaration
public virtual void Initialize(ILogService logService)
Parameters
Type Name Description
ILogService logService

IsPlaying(string)

True while a looping cutscene for cutsceneKey is alive. See IsPlaying(string).

Declaration
public virtual bool IsPlaying(string cutsceneKey)
Parameters
Type Name Description
string cutsceneKey
Returns
Type Description
bool

PlayAsync(ISequenceDefinition, CancellationToken)

Plays a cutscene asynchronously using a cutscene definition.

Declaration
public virtual Task PlayAsync(ISequenceDefinition definition, CancellationToken cancellationToken = default)
Parameters
Type Name Description
ISequenceDefinition definition
CancellationToken cancellationToken
Returns
Type Description
Task

PlayAsync(string, CancellationToken)

Plays a cutscene asynchronously by key identifier.

Declaration
public virtual Task PlayAsync(string cutsceneKey, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string cutsceneKey
CancellationToken cancellationToken
Returns
Type Description
Task

PlayLoopingAsync(string, CancellationToken)

Plays a cutscene as a persistent looping rig, idempotently. See PlayLoopingAsync(string, CancellationToken).

Declaration
public virtual Task PlayLoopingAsync(string cutsceneKey, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string cutsceneKey
CancellationToken cancellationToken
Returns
Type Description
Task

SetDefinitions(UnityCutsceneDefinition[])

Sets cutscene definitions array.

Declaration
public void SetDefinitions(UnityCutsceneDefinition[] defs)
Parameters
Type Name Description
UnityCutsceneDefinition[] defs

Stop(string)

Stops and destroys a looping cutscene. Idempotent. See Stop(string).

Declaration
public virtual void Stop(string cutsceneKey)
Parameters
Type Name Description
string cutsceneKey

Implements