Scene Services

Overview

A scene service is a scene related system which solves a specific problem / feature requirement in the scene. Scene services are designed to be completely optional - though some may rely on other services-, thus allowing scenes to have their own unique scene services setup. A scene has, at most, one active instance of each service. Scene services live as long as the scene to which their are attached.

A SceneService is prepared to hold a reference to a single SimulationContext instance and implements these members:

• Scene: reference to SceneDirector
• Context: reference to currently registered SimulationContext
• SetContext(): caches the SimulationContext locally and invokes OnSetContext()
• ClearContext(): invokes OnClearContext() and clears locally cached SimulationContext
• OnInitialize(): virtual function, invoked after scene load at the scene services initialization phase
• OnDeinitialize(): virtual function, invoked before scene unload at the scene deinitialization phase
• OnSetContext(): virtual function, invoked after from SetContext(), usually after Quantum simulation start. Context can be switched multiple times in single scene
• OnClearContext(): virtual function, invoked from ClearContext(), usually when Quantum simulation is done or before scene unload

Following code shows example usage:

C#

public unsafe sealed partial class SceneAudio : SceneService
{
    protected override void OnInitialize()
    {
        // One-time initialization

        _musicAudioSource = GetComponent<AudioSource>();
        _musicAudioSource.enabled = true;
    }

    protected override void OnDeinitialize()
    {
        // Clean-up
        
        StopAllCoroutines();

        _currentPlayingSetup = null;
        _playMusicRoutine    = null;
        _stopMusicRoutine    = null;

        _musicAudioSource.enabled = false;
    }

    protected override void OnSetContext()
    {
        // Subscribe events, refresh the service based on current gameplay state - to correctly synchronize game => replay => game switches

        Context.Events.GameplayStateChanged += OnGameplayStateChanged;

        OnGameplayStateSet(Context.VerifiedFrame.Gameplay->CurrentState);
    }

    protected override void OnClearContext()
    {
        // Unsubscribe events

        Context.Events.GameplayStateChanged -= OnGameplayStateChanged;
    }
}

See the SimulationContext page in the Game Architecture section of the FPS Template manual for more details.

UI

SceneUI is responsible for UI management. It is an interconnected collection of UIViews and UIWidgets. In the case of SimulationContext switching, the active SimulationContext is forwarded to these types and each UIView instance is responsible for correctly synchronizing its internal state based on the simulation state it is given.

The concrete implementations deriving from SceneUI are saved in a separate scene which is loaded additively into the active scene. SceneUI in the active scene contains a list of UIViews required for that specific scene; each view is a provided as prefab for a team friendly workflow. It is also possible to define which UIViews should be visible for a specific gameplay state or platform (Mobile / VR / ...); for instance, GameplayUI polls the gameplay state from the simulation it is fed.

The following diagram shows the UI composition for the default ones included in the FPS Template.

Input

SceneInput is responsible for active platform input management, registering input actions, execution of desired actions and providing input values to the Quantum simulation.

The following diagram illustrates how input handling works for various scenes and input devices.

MatchMaking

SceneMatchmaking is responsible for running the matchmaking process from game design perspective (e.g. how long the player keeps trying to join a match before creating new one). The service offers basic matchmaking functions to join or create random match.

The FPS Template supports two service variants. These are derived from SceneMatchmaking and are supposed to be overridden for custom implementations:

• MenuMatchmaking: the matchmaking happens in menu, before a specific scene is loaded.
• GameplayMatchmaking: the matchmaking happens in an already loaded gameplay scene. This is reflected in the matchmaking rules.

The following diagram presents a simple example of the matchmaking process in the menu scene.

The following diagram shows a more complex example of matchmaking process taking place in a gameplay scene:

Camera

SceneCamera is responsible for active management and switching of the camera. Every camera is defined by a type which is the result of a specific CameraBehavior implementation. Only a single CameraBehavior can be active at one time. By default, the FPS Template uses a shared CameraBehavior implementation with various CinemachineVirtualCamera setups and simple transitions.

The following diagram shows the camera types / behaviours included in the FPS Template.

Cache

SceneCache is responsible for runtime prefab pooling. It supports a static configuration (drag & drop prefabs and set count in editor), runtime warmup, instances limit and deferred return in case the instance has still visual behaviours running.

C#

GameObject impactInstance = Context.Scene.Cache.Get(_impact);
if (impactInstance != null)
{
    Context.Scene.Cache.ReturnDeferred(impactInstance, 1.0f);
}

Audio

SceneAudio is responsible for playing music and sound effects. It is also possible to define different audio clips for specific gameplay states.