APIs and Events

1. Find the Right Class for Your Task

Content Development Task	Primary Entry Point
Advance to the next Plot, jump to a specific Act / Plot, or switch the narrative scene	YomovActManager
Close or open the visual mask, publish synchronous/asynchronous events, or send an in-project request	YomovEventBus
Respond to playback start, pause, resume, seek, or player-height notifications	YomovClientManager; use ContentEventManager for no-code Inspector bindings
Configure Act entrances/exits, Plot boundaries, boundary events, and Plot-advance triggers	YomovActDescriptor, YomovPlotBoundary, LoadNextPlotTrigger
Configure multiple vehicles, observe local binding state, and start content animation	YomovMultiVehicleController, RelatedVehicleInfo, YomovPlotBoundary
Read package type, single-player/multiplayer mode, venue, room, player, and language	YomovConfig, CommandLineArgs
Play 360 video, select a playback backend, or synchronize replay video with the recording timeline	YomovVideoPlaybackAutoBackend, IYomovVideoPlaybackBackend, YomovReplayVideoRecordSync
Record a Vgen camera shot	YomovVgenCamera

2. API Conventions

Convention	Guidance
Instance	Access manager singletons after SDK initialization. If a scene object's Awake or Start runs first, fix initialization order instead of repeatedly scanning the scene at runtime.
Act.name / Plot.name	LoadPlot, LoadStageScene, and seek targets use names from the narrative configuration. These are not Unity scene names or IDs.
Act.id / Plot.id	OnLoadAct, OnUnloadAct, and OnLoadPlot pass IDs. Do not mix names and IDs.
Time units	Unless stated otherwise, transition, video, and recording times are in seconds. Video seek positions use double seconds. Replay recording time uses the scene replay time supplied by the recording flow.
IAsyncTask / Task	Narrative navigation returns IAsyncTask; advanced event-bus and video APIs return .NET Task. Use await whenever later logic depends on completion.
Subscription lifecycle	Keep the same delegate instance and unsubscribe in OnDestroy or the matching lifecycle callback. Do not overwrite, clear, or invoke SDK callback fields yourself.
Public does not automatically mean supported	Only members documented on this page form the content-development contract. Other public members may be runtime infrastructure or testing hooks.

3. YomovActManager

Purpose. YomovActManager owns narrative state and advances Acts and Plots, including related Unity scene loads. Use it when content completion, a Timeline Signal, UI interaction, or single-player debugging needs to move the story forward.

Methods

Method	Description
LoadNextPlot(bool waitOtherPlayers = false, bool isFindAllScene = false, bool isChangeScene = true)	Advances to the next Plot in the narrative configuration and loads the target scene when crossing an Act. For multiplayer content that crosses scenes and requires server coordination, pass waitOtherPlayers: true. Returns IAsyncTask.
LoadPlot(string stageName, string areaName, bool isFindAllScene = false, bool isChangeScene = true)	Loads the target Plot by Act.name and Plot.name. By default, it switches scenes when the target is not in the active scene.
LoadStageScene(string stage)	The parameter is Act.name, not a Unity scene name. Loads the scene that contains the Act and enters its first narrative position. Use LoadPlot when a specific Plot is required.
TryGetCurrentPlotNames(out string actName, out string plotName)	Returns the current Act and Plot names. Returns false with empty strings when the narrative indices are invalid.
IsCurrentStageScene(string stage)	Checks whether the specified Act belongs to the active Unity scene. Use it before navigation when you need to determine whether a scene change is required.

Runtime State and Narrative Callbacks

Member	Description
CurrentAct	Current Act data. Access only after route initialization and with valid indices; the getter does not return null safely for every invalid state.
CurrentPlot	Current Plot Boundary. It can be temporarily null during scene transitions or Plot Boundary initialization.
CurrentActIndex	Current Act index. Treat it as diagnostic/read-only state.
CurrentPlotIndex	Current Plot index. The property has a public setter for runtime infrastructure; content code must treat it as read-only and navigate through the methods above.
RouteComplete, OnCreatedRealBoundary	Indicate route initialization completion and physical-boundary creation. Content that depends on runtime boundaries should wait for these states and must not take ownership of RealBoundary.
OnLoadAct, OnLoadPlot, OnUnloadAct	C# callbacks whose arguments are Act or Plot IDs. OnLoadPlot means the SDK selected a Plot; it does not mean every project-specific asynchronous asset has finished loading.
OnBeforeLoadScene	Raised after the transition effect and optional multiplayer wait complete, immediately before Unity starts loading the scene.
OnLoadLastPlot	Raised when another advance is requested but no later Act or Plot exists. This marks the end of the content sequence.
OnSwitchActAndPlot	Raised with target actName and plotName after a valid seek is accepted and before the target scene is loaded.
OnChangePlotEvent	Raised with the confirmed current Act and Plot names. Suitable for UI, logs, and position synchronization.

Example

using UnityEngine;
using Yomov;

public class StoryNavigationExample : MonoBehaviour
{
    public async void ContinueStory()
    {
        // For multiplayer scene changes, wait for server coordination.
        await YomovActManager.Instance.LoadNextPlot(waitOtherPlayers: true);
    }

    public async void JumpToPlot()
    {
        await YomovActManager.Instance.LoadPlot("Act02", "Plot03");
    }
}

4. YomovEventBus

Purpose. YomovEventBus is the SDK's strongly typed event bus. Content commonly uses it for close-eye/open-eye transitions and project-defined events. Asynchronous events are useful when a flow must wait for multiple handlers. Request/response is intended for an in-project query with a single handler.

Methods

Method	Description
Publish<T>(T eventData)	Synchronously publishes an event that implements IYomovEvent. Handlers run on the current call stack.
Subscribe<T>(Action<T> handler) / Unsubscribe<T>(...)	Subscribes to or unsubscribes from a synchronous event. Pass the same delegate instance when unsubscribing.
PublishAsync<T>(T eventData)	Invokes all handlers for an IYomovAsyncEvent in parallel and waits for Task.WhenAll.
SubscribeAsync<T>(Func<T, Task> handler) / UnsubscribeAsync<T>(...)	Subscribes to or unsubscribes from an asynchronous event. Handlers must not access destroyed Unity objects.
SubscribeRequest<TRequest, TResponse>(...)	Registers the single handler for a request type. A later registration replaces the previous handler. Request and response types implement IYomovRequest<TResponse> and IYomovResponse.
SendRequestAsync<TRequest, TResponse>(request)	Dispatches an in-project request and returns the handler response. In SDK 1.3.6, the request timeout does not guarantee that this call returns if the handler never completes. Ensure the handler completes or enforce a caller-side timeout.
UnsubscribeRequest<TRequest, TResponse>()	Removes the registered handler for the request type.

Common Content Event Types

Type	Description
FadeOutEvent	Closes the visual mask or fades it to the target color. time is in seconds; content code should set color explicitly.
FaddInEvent	Opens the visual mask. time is in seconds. Fadd is the exact spelling of the current API type.
EndGameEvent	Notifies recording/replay infrastructure that the current content has ended. Standard Release packages normally do not need to publish it directly.
Project-defined event	Implement IYomovEvent for a synchronous event or IYomovAsyncEvent for an asynchronous event. Do not reuse SDK protocol types for internal content events.

Example: Close and Open the Visual Mask

using UnityEngine;
using Yomov;

public class FadeTransitionExample : MonoBehaviour
{
    public void CloseEyes()
    {
        YomovEventBus.Publish(new FadeOutEvent
        {
            time = 0.5f,
            color = Color.black
        });
    }

    public void OpenEyes()
    {
        YomovEventBus.Publish(new FaddInEvent { time = 0.5f });
    }
}

5. YomovClientManager

Purpose. YomovClientManager forwards playback-control notifications such as start, pause, resume, seek, and player-height changes to content. Content consumes these notifications and does not participate in SDK authorization.

Member	Description
SubscribeStartGame(Action handler, bool replayIfStarted = true)	Subscribes to playback start. If the start signal already arrived and replay is enabled, the handler is called synchronously during subscription. The handler must be idempotent.
UnsubscribeStartGame(Action handler)	Removes the playback-start subscription. Pass the original handler.
OnPause, OnResume	Pause or resume the content's own Timeline, video, or state machine.
OnSeek	Raised after the target scene for a valid seek finishes loading. Subscribe to YomovActManager.OnSwitchActAndPlot when the target must be known earlier.
OnSetPlayerHeight	Raised when a player-height command is received. The SDK also consumes this notification for Avatar height adaptation.
HasStartGameSignal, LastStartGameUnscaledTime	Read-only start state and Time.unscaledTime captured when the first start signal arrived. Use them to align late-created content and recording timelines.

6. YomovActDescriptor

Purpose. YomovActDescriptor is the scene authoring component shown as Act Unit. It describes the Act name, entrance/exit geometry, and transition settings. Configure it in the Inspector; content scripts normally read its state or bind events.

Member	Description
actName, id	Narrative name and stable ID. Navigation APIs use actName; load callbacks normally pass id.
EntrancePosition, arrivalAreaPoints, exitPoint	Act entrance position, Entrance Area polygon, and exit point. The Act authoring tools interpret these values in the configured scene space.
transitionEffect, closeEyeDuration	Transition type and close-eye duration in seconds when entering or leaving the Act.
OnSwitchAct : UnityEvent<YomovActDescriptor>	Raised when this Act becomes active. Suitable for starting Act-root content.

7. YomovPlotBoundary

Purpose. YomovPlotBoundary is the Plot Boundary authoring component. It connects narrative nodes with the physical experience area by defining Plot geometry, Plot type, trigger behavior, and boundary callbacks.

Member	Description
plotName, id	Plot name and stable ID. LoadPlot uses the name; narrative load callbacks normally pass the ID.
plotType, triggerType	Walking/vehicle mode and Plot trigger mode.
relatedVehicle	Vehicle GameObject used by the legacy single-vehicle Plot flow.
multiVehicle, multiVehicleController, autoStartMultiVehicle	Enable multi-vehicle mode, assign its controller, and decide whether the local multi-vehicle session starts automatically after Plot activation.
OnSwitchPlot : UnityEvent<string>	Raised when this Plot becomes active. The argument is plotName, not the Plot ID.
OnBoundaryEnter, OnBoundaryExit	Raised when the player enters or leaves the Plot boundary. The argument is the boundary-related position.
OnLocalPlayerVehicleSessionStarted : UnityEvent<int>	Raised after the local player's multi-vehicle follow session is fully established. The argument is the vehicle index. Start the local vehicle animation here so it does not run before runtime boundary handoff.

8. LoadNextPlotTrigger

Purpose. LoadNextPlotTrigger dispatches an advance to the next Plot after the component's trigger is entered or its timeout is reached. Use it for endpoint gates, transition trigger zones, and single-player fallback progression.

Member / Setting	Description
SetCollider(Collider collider)	Replaces the Collider used by this component. The trigger disables that component Collider before dispatching the Plot advance. It does not register a separate allow-list Collider.
onPlotLoaded : Action	Invoked immediately after LoadNextPlot(true) is dispatched as a fire-and-forget operation. It does not wait for Plot loading to complete.
Inspector settings	The Inspector exposes the component Collider, Delay Time, and Trigger Timeout. The entering GameObject must use the hard-coded SinglePlayer Tag; there is no configurable allowed-tag field. Avoid multiple triggers dispatching an advance for the same Plot.

9. YomovMultiVehicleController and RelatedVehicleInfo

Purpose. YomovMultiVehicleController manages binding, follow, and unbinding for multiple vehicles in one Plot. RelatedVehicleInfo describes each vehicle, capacity, and local experience area. Configure vehicles and content callbacks in the Inspector. YomovPlotBoundary and the SDK own activation, start, stop, and deactivation; content scripts must not duplicate those lifecycle calls.

Configuration or Event	Description
relatedVehicleList	List of RelatedVehicleInfo entries, normally configured in the Inspector.
RelatedVehicleInfo.vehicle, capacity, vehicleArea	Vehicle GameObject, maximum player capacity, and the vehicle experience area in controller-local space.
YomovPlotBoundary.multiVehicle, multiVehicleController, autoStartMultiVehicle	Enable multi-vehicle mode on the Plot, assign the controller, and decide whether the follow state starts automatically after Plot activation.
OnPlayerBindVehicle, OnPlayerUnbindVehicle	UnityEvent<int> callbacks for the local player's bind/unbind state. The argument is the vehicle index. Use them for lightweight feedback.
YomovPlotBoundary.OnLocalPlayerVehicleSessionStarted	Raised after the local player's vehicle session is fully established. Prefer this callback when starting vehicle animation or content flow.

10. YomovConfig and CommandLineArgs

YomovConfig

Purpose. YomovConfig exposes the current package type and runtime-mode configuration. Content reads this data and must not modify it at runtime.

Member	Description
YomovConfig.Instance.ConfigData	Loads the current configuration from Resources. Access it after SDK initialization and guard against missing data.
ConfigData.buildType	Package type: OpenPackage, Test, Release, TrailerPackage, or Vgen.
ConfigData.multiplayerMode	SinglePlayer or MultiPlayer.
ConfigData.isRecord, ConfigData.isReplay	Read-only calculated states indicating recording mode and a Vgen replay package.

CommandLineArgs

Purpose. CommandLineArgs contains identity and business parameters supplied by the launcher for the current run. Content may read stable business fields, but must never log or expose credentials.

Member	Description
venueID, roomID, contentID	Venue, room, and content IDs for analytics, save-data isolation, or business display.
teamOriginID, teamName, teamCount	Current team identity and player count.
playerOriginID, playerNick	Current player business ID and nickname. Apply the content project's privacy rules before displaying the nickname.
languageType	Language selected by the launcher. Use it as the initial localization choice.
JsonData	Parsed extended parameters such as stageName, origin offset, area dimensions, and replay speed. Fields may be absent in some runtime modes; always provide defaults.
secretKey	Credential field and not a content API. Never write it to logs, documentation, analytics, or UI.

11. ContentEventManager

Purpose. ContentEventManager is an optional Inspector bridge for no-code callbacks from Timeline, PlayableDirector, Animator, or scene objects. Do not create a duplicate Inspector binding when code already handles the same business action.

Field	Description
OnStartGame, OnPauseGame, OnResumeGame, OnSeek, OnSetPlayerHeight	Parameterless UnityEvent callbacks for playback-control notifications. Start has replay semantics, so a component created late can invoke OnStartGame immediately from Start.
OnLoadAct, OnLoadPlot, OnUnloadAct	UnityEvent<string> callbacks whose arguments are Act or Plot IDs.
OnBeforeLoadScene, OnLoadLastPlot	Parameterless callbacks raised before scene loading and at the end of the content sequence.
OnSwitchActAndPlot, OnChangePlotEvent	UnityEvent<string, string> callbacks whose arguments are Act and Plot names. The first reports the seek target; the second reports the confirmed current position.

12. Video Playback and Replay Synchronization

Purpose. This feature plays external video in a Linux runtime and uses YomovReplayVideoRecordSync to align video frames with scene replay recording time. Content projects normally configure components and the video path in the Inspector without calling the playback interface directly.

Recommended Component Setup:

On the GameObject that displays the video, configure a Renderer and add these four components:

1. YomovVideoPlaybackAutoBackend: selects the playback backend, preferring Linux Native GPU playback and falling back automatically.

2. YomovNativeGpuVideoPlayer: Linux NVIDIA low-copy Native playback.

3. YomovFFmpegPipeVideoPlayer: FFmpeg Pipe fallback when Native playback is unavailable.

4. YomovReplayVideoRecordSync: connects the player to the scene replay recording timeline.

After you add YomovVideoPlaybackAutoBackend, it finds or adds the Native and Pipe components on the same GameObject. For replay recording, set YomovReplayVideoRecordSync.Player Component to YomovVideoPlaybackAutoBackend.

YomovVideoPlaybackAutoBackend

Inspector purpose. Manages both concrete player components and selects an available backend. On Linux, it prefers Native GPU when the Native plugin, graphics API, FFmpeg, ffprobe, and NVDEC requirements are met. It falls back to FFmpeg Pipe when Native is unavailable, opening fails, or the first frame is not ready.

Inspector Field	Configuration
Native Backend	Assign YomovNativeGpuVideoPlayer, normally the component on the same GameObject.
Pipe Fallback	Assign YomovFFmpegPipeVideoPlayer as the fallback path.
Prefer Native Backend	Recommended: enabled. Tries low-copy Native GPU playback first. When disabled, uses Pipe directly.
Log Fallback	Logs backend selection, fallback reasons, and errors. Enable during development.

YomovNativeGpuVideoPlayer

Inspector purpose. NVIDIA low-copy Native playback for Linux Player or Linux Editor. Windows Editor cannot load the Linux Native plugin, so YomovVideoPlaybackAutoBackend uses the Pipe fallback.

Inspector Field	Configuration
Allow Linux Editor	Allows playback validation in Linux Editor. Does not affect a Linux Player build.
Require Supported Graphics Api	Requires a graphics API supported by the Native low-copy path. Keep enabled.
Loop	Loops the video at end of playback. Configure according to content needs; replay recording usually follows the recording interval.
Source Path	Standalone player path. Leave empty when using replay synchronization; YomovReplayVideoRecordSync.Video Path supplies the path.
Target Renderer	Renderer that receives the video textures. Normally use the Renderer on the same GameObject.
Luma Texture Property	Material property for the luma texture. Default: _YTex.
Chroma Texture Property	Material property for the chroma texture. Default: _UVTex.
Use Yuv Property	Material property that enables the YUV branch. Default: _UseYuv.
Yuv Full Range Property	Material property for the YUV full-range flag. Default: _YuvFullRange.
Yuv Color Matrix Property	Material property for the YUV color matrix. Default: _YuvColorMatrix.
Yuv Flip Y Property	Material property for vertical YUV flipping. Default: _YuvFlipY.
Flip Native Texture Vertically	Vertically flips the Native output texture. Enabled by default to match Unity material coordinates.
First Frame Timeout Ms	First-frame timeout. Default: 5000 ms. Increase for large files or slower storage.
Enable Audio	Allows embedded video audio. During replay recording, Play Audio on the Sync component has final control.
Audio Volume	Embedded video audio volume. Default: 1.
Audio Prebuffer Seconds	Audio prebuffer duration. Default: 0.25 seconds. Increase if audio startup is unstable.
Log Environment Report	Logs runtime, FFmpeg, NVDEC, Native plugin, and graphics API checks. Enable when diagnosing Linux playback.
Log Audio Playback	Logs the audio playback flow. Enable only when diagnosing audio.

YomovFFmpegPipeVideoPlayer

Inspector purpose. Decodes with FFmpeg and uploads CPU-buffered frames into a Unity Texture2D. It uses more resources than Native GPU playback but offers broader compatibility. Let YomovVideoPlaybackAutoBackend manage it as the fallback.

Inspector Field	Configuration
Allow Linux Editor	Allows Pipe playback validation in Linux Editor.
Require Supported Graphics Api	Requires the graphics API to pass environment validation. Keep enabled.
Prefer Nvdec	Requests NVDEC hardware decoding when supported. Automatic fallback from Native selects the stable CPU path when required.
Loop	Loops the video at end of playback.
Playback Speed	Playback multiplier. Default: 1. Keep at 1 for replay recording synchronization.
Ffmpeg Extra Input Args	Advanced FFmpeg input arguments. Leave empty unless you understand the FFmpeg options being added.
Source Path	Standalone player path. Leave empty when the Sync component supplies the path.
Target Renderer	Renderer that receives the video texture, normally on the same GameObject as AutoBackend and Sync.
Target Texture Property	Material property that receives the RGB texture. Default: _MainTex.
Use Yuv Property	Material YUV-branch switch. Default: _UseYuv. Pipe disables this branch for RGB output.
Flip Frame Vertically	Vertically flips FFmpeg output frames. Enabled by default to match Unity texture orientation.
First Frame Timeout Ms	First-frame timeout. Default: 5000 ms.
Enable Audio	Allows embedded video audio. During replay recording, Play Audio on the Sync component has final control.
Audio Volume	Embedded video audio volume. Default: 1.
Audio Prebuffer Seconds	Audio prebuffer duration. Default: 0.25 seconds.
Log Environment Report	Logs playback environment checks. Enable when diagnosing FFmpeg or graphics issues.
Log Process Output	Logs FFmpeg process output. It is verbose; enable only when diagnosing decode failures.
Log Audio Playback	Logs the audio playback flow. Enable only when diagnosing audio.

YomovReplayVideoRecordSync

Inspector purpose. Before replay recording starts, seeks the video to the current replay time and waits for the first frame. It resumes playback when recording starts and stops/releases resources according to its configuration after recording. Video is not played while browsing replay at 10x speed.

Inspector Field	Configuration
Player Component	Assign YomovVideoPlaybackAutoBackend on the same GameObject. Do not assign Native or Pipe directly, so automatic fallback remains available.
Target Renderer	Renderer that displays video during recording and can be hidden outside recording.
Video Path	External path relative to AssetBundle/. In Editor it is relative to the project root; in Linux Player it is relative to the executable root. For Movies/demo.mp4, place the file at AssetBundle/Movies/demo.mp4.
Video Time Offset Seconds	Offset relative to scene replay time. Target video time = scene replay time + offset, clamped to 0 or later.
Play Audio	Plays embedded video audio during recording. Disable when the scene already contains separate spatial audio.
Stop After Recording	Stops video after recording. Keep enabled.
Disable Renderer Outside Recording	Hides the Renderer outside recording to prevent stale frames during replay browsing or preparation. Keep enabled.
Release Playback Resources On Disable	Releases Native playback resources when the component is disabled. Keep enabled to avoid retaining GPU decode and external texture resources.
Log Sync	Logs backend selection, seek, first-frame preparation, recording start, and resource release. Enable during development.

Replay Recording Setup

1. Place the external video under AssetBundle/ in the project root or Linux executable root.

2. Configure a Renderer and a material that supports the required texture properties on the video display object.

3. Add YomovVideoPlaybackAutoBackend and verify that Native Backend and Pipe Fallback are assigned.

4. Add YomovReplayVideoRecordSync; point Player Component to AutoBackend and Target Renderer to the display Renderer.

5. Set Video Path relative to AssetBundle/, then configure Video Time Offset Seconds against scene replay time.

6. The recording system handles first-frame seeking, playback start, and post-recording cleanup. Content scripts do not need to control playback separately.

13. Special-Mode APIs

YomovVgenCamera

Purpose. Records a camera shot in a Vgen replay package. Calls from standard Test or Release packages do not start recording.

Method	Description
StartRecord()	Starts recording with the component's camera, duration, and ShotScope settings.
StartRecord(Action onRecordStarted)	Invokes the callback after recording actually starts.
StartRecord(float sceneReplayTimeSeconds)	Uses the specified scene replay time as the recording trigger point.
StartRecord(Action onRecordStarted, float? sceneReplayTimeSeconds)	Full overload with both a start callback and an optional replay trigger time.

14. Do Not Use as Content APIs

Member or Legacy Pattern	Required Handling
YomovClientManager.OnStartGame += handler	Legacy direct subscription. Use SubscribeStartGame / UnsubscribeStartGame so late subscribers do not miss an already-received start signal.
YomovManager.BeforeLoadScene	Legacy API. Migrate to YomovActManager.OnBeforeLoadScene.
YomovClientManager.Validate*, OnValidateFailed	SDK authorization, diagnostics, and exit policy. Content does not call or subscribe to these members.
TeleportSelfData	No stable runtime consumer exists in the current SDK. It is not a player teleport API. Move the player through the project's controller and use close-eye/open-eye events when needed.
CrossFadeScreen(...)	The current implementation only waits; it does not render a visual transition. It cannot replace FadeOutEvent / FaddInEvent.
LoadSceneTrigger	Its current scene-loading path is disabled; do not use it as a content entry point.
UpdateIndex(...), SwitchActAndPlot(...), BeforeLoadSceneTask	Internal index or network bridging. They do not form a complete navigation contract. Use LoadPlot / LoadStageScene.
YomovActConfig.Instance.RealBoundary, active-boundary static lists	SDK runtime boundary state. Content may wait for readiness but must not reparent the object, persist it independently, or own collection lifecycle.
YomovVehicleManager, FishNet messages, RecorderClient / Server	SDK infrastructure. Use the higher-level vehicle, video, and recording entry points instead of sending protocol messages or controlling server lifecycle.
YomovNativeGpuVideoPlayer, YomovFFmpegPipeVideoPlayer	Playback backend implementations and diagnostics. Standard content should use YomovVideoPlaybackAutoBackend.

15. Reference and Verification Scope

This reference is derived from the current Unity SDK 1.3.6 source and covers the content-development surface for narrative navigation, spatial boundaries, vehicles, runtime configuration, video playback, and recording. A C# member being public does not by itself make it a supported third-party API; only members documented on this page are part of the content contract. Preserve the exact spelling and capitalization of API, Inspector, Timeline, resource-path, and reflection identifiers.