Class CutsceneBuilder

Namespace

S1API.Cutscenes

Assembly

S1API.dll

Builds a local, camera-driven cutscene with a managed cross-runtime API.

public sealed class CutsceneBuilder

Inheritance

object

CutsceneBuilder

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Extension Methods

ReflectionUtils.GetValueTupleItems(object)

ReflectionUtils.IsValueTuple(object)

Constructors

CutsceneBuilder(string)

Creates a builder for a uniquely identified local cutscene.

public CutsceneBuilder(string id)

Parameters

id string

A stable, mod-namespaced identifier such as my-mod:crew-arrival.

Methods

Build()

Builds a reusable managed handle for the configured cutscene.

public CutsceneHandle Build()

Returns

CutsceneHandle

A cutscene handle that can start and control local playback.

Exceptions

InvalidOperationException

Thrown when duration or the initial camera pose has not been configured.

OnEnded(Action<CutsceneEndReason>)

Sets the callback invoked exactly once when a playback attempt ends.

public CutsceneBuilder OnEnded(Action<CutsceneEndReason> callback)

Parameters

callback Action<CutsceneEndReason>

The callback that receives the reason playback ended.

Returns

CutsceneBuilder

This builder for method chaining.

OnStarted(Action)

Sets the callback invoked after native playback starts successfully.

public CutsceneBuilder OnStarted(Action callback)

Parameters

callback Action

The playback-started callback.

Returns

CutsceneBuilder

This builder for method chaining.

WithCameraUpdate(Action<CutsceneFrame>)

Sets the callback that updates the managed camera transform each frame.

public CutsceneBuilder WithCameraUpdate(Action<CutsceneFrame> update)

Parameters

update Action<CutsceneFrame>

The per-frame camera callback.

Returns

CutsceneBuilder

This builder for method chaining.

WithDuration(float)

Sets the cutscene playback duration.

public CutsceneBuilder WithDuration(float seconds)

Parameters

seconds float

A finite duration greater than zero, in seconds.

Returns

CutsceneBuilder

This builder for method chaining.

WithFadeIn(float)

Fades from black when playback begins.

public CutsceneBuilder WithFadeIn(float seconds)

Parameters

seconds float

A finite fade duration greater than or equal to zero.

Returns

CutsceneBuilder

This builder for method chaining.

Remarks

The helper does not alter a black overlay that was already shown by another game system. A duration of zero disables the helper.

WithFadeIn(float, float)

Holds on black, then fades in after a delay.

public CutsceneBuilder WithFadeIn(float seconds, float delaySeconds)

Parameters

seconds float

A finite fade duration greater than or equal to zero.

delaySeconds float

A finite delay greater than or equal to zero before the fade begins.

Returns

CutsceneBuilder

This builder for method chaining.

Remarks

The helper does not alter a black overlay that was already shown by another game system. A fade duration of zero disables the helper.

WithFadeOut(float)

Fades to black near the end of normal playback, then releases the overlay.

public CutsceneBuilder WithFadeOut(float seconds)

Parameters

seconds float

A finite fade duration greater than or equal to zero.

Returns

CutsceneBuilder

This builder for method chaining.

Remarks

The helper does not close a black overlay that was already owned by another game system. A duration of zero disables the helper.

WithFov(float)

Overrides the player camera's field of view while the cutscene is active.

public CutsceneBuilder WithFov(float fov)

Parameters

fov float

A finite field of view greater than zero and less than 180 degrees.

Returns

CutsceneBuilder

This builder for method chaining.

WithHoldToSkip(float)

Allows the local player to hold primary click to skip playback.

public CutsceneBuilder WithHoldToSkip(float seconds = 0.5)

Parameters

seconds float

The finite hold duration required to skip.

Returns

CutsceneBuilder

This builder for method chaining.

WithInitialCamera(Vector3, Quaternion)

Sets the initial world-space camera position and rotation.

public CutsceneBuilder WithInitialCamera(Vector3 position, Quaternion rotation)

Parameters

position Vector3

The initial world-space position.

rotation Quaternion

The initial world-space rotation.

Returns

CutsceneBuilder

This builder for method chaining.

WithName(string)

Sets the descriptive name used by the native cutscene state.

public CutsceneBuilder WithName(string name)

Parameters

name string

A non-empty descriptive name.

Returns

CutsceneBuilder

This builder for method chaining.

WithTitleCard(string, float)

Displays a simple centered title card during the start of playback.

public CutsceneBuilder WithTitleCard(string text, float duration = 2)

Parameters

text string

The non-empty title text.

duration float

The finite title duration greater than zero.

Returns

CutsceneBuilder

This builder for method chaining.