Skip to content

Game Lifecycle Maintenance ​

This document describes how to manage the lifecycle of a minigame through SUDRTGameHandle, including state listening and state transition control.

Game lifecycle maintenance consists of two core parts:

  1. Game state listening (GameStateChangeListener)
  2. Game state control (state transition interfaces)

Overview ​

SUDRTGameHandle is the core control object for the game runtime. Through this object, developers can:

  • Listen for game state changes
  • Control the game's running state
  • Manage the game resource lifecycle

All game lifecycle control revolves around this object.


Game State Definitions ​

The game internally defines the following state constants:

java
// Defined in SUDRTGameHandle
int GAME_STATE_UNAVAILABLE = 0;
int GAME_STATE_WAITING = 1;
int GAME_STATE_RUNNING = 2;
int GAME_STATE_PLAYING = 3;

State descriptions:

State ValueState NameDescription
0UNAVAILABLEThe game runtime environment is not ready. The GameHandle is in this state right after creation; startup parameters should be set in this state.
1WAITINGThe game environment is ready but not running. Usually used for the game-invisible state.
2RUNNINGThe game is running but the user cannot interact. Usually used when the UI is visible but does not have focus.
3PLAYINGThe game is running and the user can interact. The normal gameplay state.

Game State Listening ​

Registering the Listener ​

java
gameHandle.setGameStateListener(listener);

Method description:

java
/**
 * Sets the minigame state change listener.
 * If the current minigame state equals the target minigame state when a minigame operation interface is called, the callback will not be triggered.
 */
void setGameStateListener(SUDRTGameHandle.GameStateChangeListener listener);

GameStateChangeListener Definition ​

java
public interface GameStateChangeListener {
    /**
     * Callback right before a state is about to change
     * @param fromState previous state
     * @param state     current state
     */
    void preStateChange(int fromState, int state);

    /**
     * Callback after a state change succeeds
     * @param fromState previous state
     * @param state     current state
     */
    void onStateChanged(int fromState, int state);

    /**
     * Callback after a state change fails
     * @param fromState previous state
     * @param toState   the minigame's next state
     * @param error     error information
     */
    void onFailure(int fromState, int toState, Throwable error);
}

Game State Control ​

State Transition Relationships ​

text
UNAVAILABLE → WAITING → RUNNING → PLAYING
                           ↑       ↓
                        WAITING ← RUNNING

State Control Interfaces ​

1. Set Startup Parameters ​

java
gameHandle.setGameStartOptions(gameId, bundle);

Description:

  • Should be called in the GAME_STATE_UNAVAILABLE state
  • Used to set the game startup parameters

2. Create Game Instance ​

java
gameHandle.create();

State change:

text
UNAVAILABLE → WAITING

Description:

  • Initializes the game runtime environment
  • Creates the game instance but does not start running

3. Start Game Running ​

java
gameHandle.start(null);

State change:

text
WAITING → RUNNING

Description:

  • The game starts running
  • The user cannot interact yet

4. Enter Interactive State ​

java
gameHandle.play();

State change:

text
RUNNING → PLAYING

Description:

  • The game enters the normal interactive state
  • The user can perform operations

5. Pause Game Interaction ​

java
gameHandle.pause();

State change:

text
PLAYING → RUNNING

Description:

  • The game keeps running, but user interaction is paused

6. Stop Game Running ​

java
gameHandle.stop(null);

State change:

text
RUNNING → WAITING

Description:

  • The game stops running
  • The runtime environment is retained

7. Destroy Game ​

java
gameHandle.destroy();

State change:

text
ANY → UNAVAILABLE

Description:

  • Releases all resources occupied by the game
  • Destroys the runtime environment

About SUDOPGameTask.destroy ​

When starting a game through interfaces such as SUDOP.startGame, a SUDOPGameTask is returned.

java
gameTask.destroy();

Description:

  • Internally, this actually calls:
java
gameHandle.destroy();
  • Used for unified lifecycle management
  • It is recommended to prefer gameTask.destroy()

Standard Lifecycle Flow ​

text
UNAVAILABLE
    ↓ create()
WAITING
    ↓ start()
RUNNING
    ↓ play()
PLAYING

Exit flow:

text
PLAYING
    ↓ pause()
RUNNING
    ↓ stop()
WAITING
    ↓ destroy()
UNAVAILABLE

Example Code ​

java
gameHandle.setGameStateListener(new SUDRTGameHandle.GameStateChangeListener() {
    @Override
    public void preStateChange(int fromState, int state) {
    }

    @Override
    public void onStateChanged(int fromState, int state) {
    }

    @Override
    public void onFailure(int fromState, int toState, Throwable error) {
    }
});

// Initialize parameters
gameHandle.setGameStartOptions(gameId, bundle);

// Create
gameHandle.create();

// Start
gameHandle.start(null);

// Interactive
gameHandle.play();

// Pause
gameHandle.pause();

// Stop
gameHandle.stop(null);

// Destroy
gameHandle.destroy();

Notes ​

1. Duplicate States Do Not Trigger Callbacks ​

If the current state is the same as the target state:

text
GameStateChangeListener will not be triggered

2. destroy Must Be Called ​

It must be called in the following scenarios:

  • Activity destruction
  • Page exit
  • Game switching

Otherwise it may cause:

  • Memory leaks
  • Unreleased resources
  • Continued running in the background

3. UI Lifecycle Recommendations ​

ScenarioRecommended Operation
Page shownstart()
Page gains focusplay()
Page loses focuspause()
Page hiddenstop()
Page destroyeddestroy()

Summary ​

The core points of game lifecycle maintenance are as follows:

  1. Use SUDRTGameHandle as the single control entry point
  2. Listen for state changes through setGameStateListener
  3. Call the lifecycle interfaces in order to control the game state
  4. Call destroy at the appropriate time to release resources

Full flow:

text
setGameStartOptions → create → start → play → pause → stop → destroy