Skip to content

Game.IScreenState

Assembly:
Namespace: Game.SceneFlow

Type: interface

Base:

Summary:
Interface representing a screen state used by the game's scene/flow system. IScreenState exposes a single instance method Execute that screen implementations must implement, and it also defines several static helper asynchronous methods used by screen states to wait for various user/input events (waiting input phase, performed input, device pairing, and user sign-in changes). These helpers are designed to integrate with the game's input and platform/event systems and to be cancellable via CancellationToken.

Fields

  • (none)
    No instance fields are defined on this interface. Implementations may maintain their own state.

Properties

  • (none)
    This interface does not declare properties.

Constructors

  • (none)
    Interfaces do not declare constructors. Implementing types provide construction.

Methods

  • static Task WaitForWaitingState(InputAction inputAction)
    Waits until the given InputAction has its phase equal to InputActionPhase.Waiting. If the action is already in Waiting, it returns a completed Task. Otherwise it polls the action.phase using a System.Timers.Timer with an interval of ~33.333ms and completes when the action enters the Waiting phase. Note: uses a timer-based poll rather than Unity update callbacks.

  • static async Task<(bool ok, InputDevice device)> WaitForInput(InputAction inputContinue, InputAction inputCancel, Action cancel, CancellationToken token)
    Waits for either a continue or cancel input action to be performed, or for an external cancel, or for the CancellationToken to be cancelled. Returns a tuple:

  • ok: true when inputContinue triggered, false when inputCancel triggered.
  • device: the InputDevice that performed the action (derived from c.action.activeControl?.device). If an input hint proxy triggers the continue action, the returned device will be Mouse.current. Behavior and notes:
  • Subscribes to inputContinue.performed and inputCancel.performed (if provided).
  • Subscribes to GameManager.instance.userInterface.inputHintBindings.onInputHintPerformed to respect input hints.
  • If a cancel Action is provided the helper adds a CancelHandler to it (and removes it on completion).
  • On completion it unsubscribes all handlers and calls Reset() on the input actions used.

  • Honors the provided CancellationToken; registering it will TrySetCanceled the awaiting TaskCompletionSource.

  • static async Task<object> WaitForDevice(Action cancel, CancellationToken token)
    Waits for a device pairing event. Subscribes to Game.Input.InputManager.instance.EventDevicePaired and completes when that event is fired. If a cancel Action is provided it attaches a CancelHandler that will TrySetCanceled the Task. Returns an object (the code sets a TaskCompletionSource and completes with null); the caller typically only cares that pairing occurred.

  • static async Task<UserChangedFlags> WaitForUser(Action cancel, CancellationToken token)
    Waits for a user update event indicating the principal user signed in again. Subscribes to PlatformManager.instance.onUserUpdated and, when the event is invoked for the principal user and the flags include UserChangedFlags.UserSignedInAgain, completes and returns the UserChangedFlags. If a cancel Action is provided a CancelHandler is added to cancel the wait. Honors CancellationToken as well.

  • Task Execute(GameManager manager, CancellationToken token)
    Instance method to be implemented by concrete screen states. Called by the scene/flow system to execute the state's logic. Implementations should use the static helper methods above as needed to await user/input events and should respect the provided CancellationToken so the state can be cancelled/aborted cleanly.

    • Usage Example

    // Example implementation of a simple screen state that waits for a continue input
public class ConfirmExitScreenState : IScreenState
{
    private InputAction _continueAction;
    private InputAction _cancelAction;

    public ConfirmExitScreenState(InputAction continueAction, InputAction cancelAction)
    {
        _continueAction = continueAction;
        _cancelAction = cancelAction;
    }

    public async Task Execute(GameManager manager, CancellationToken token)
    {
        // Ensure the input action is in Waiting phase before listening
        await IScreenState.WaitForWaitingState(_continueAction);

        try
        {
            var (ok, device) = await IScreenState.WaitForInput(_continueAction, _cancelAction, cancel: null, token);
            if (ok)
            {
                // user confirmed; proceed with exit
                manager.RequestExit();
            }
            else
            {
                // user cancelled; return to previous screen
            }
        }
        catch (OperationCanceledException)
        {
            // Handle cancellation (state aborted)
        }
    }
}

    Notes and caveats: - All helper methods use TaskCompletionSource and event subscriptions; implementations should avoid double-subscribing and should manage cancellation tokens properly. - The static helpers interact with game singletons and input systems (GameManager, Game.Input.InputManager, PlatformManager, GameManager.instance.userInterface.inputHintBindings). When modding, ensure correct access to these game objects and run code on appropriate threads/context expected by those APIs. - WaitForWaitingState uses a System.Timers.Timer for polling — this is not frame-locked and will fire on a thread-pool thread; use care if interacting with Unity objects from its callbacks.