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:
- Game state listening (GameStateChangeListener)
- 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:
// 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 Value | State Name | Description |
|---|---|---|
0 | UNAVAILABLE | The game runtime environment is not ready. The GameHandle is in this state right after creation; startup parameters should be set in this state. |
1 | WAITING | The game environment is ready but not running. Usually used for the game-invisible state. |
2 | RUNNING | The game is running but the user cannot interact. Usually used when the UI is visible but does not have focus. |
3 | PLAYING | The game is running and the user can interact. The normal gameplay state. |
Game State Listening
Registering the Listener
gameHandle.setGameStateListener(listener);Method description:
/**
* 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
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
UNAVAILABLE → WAITING → RUNNING → PLAYING
↑ ↓
WAITING ← RUNNINGState Control Interfaces
1. Set Startup Parameters
gameHandle.setGameStartOptions(gameId, bundle);Description:
- Should be called in the
GAME_STATE_UNAVAILABLEstate - Used to set the game startup parameters
2. Create Game Instance
gameHandle.create();State change:
UNAVAILABLE → WAITINGDescription:
- Initializes the game runtime environment
- Creates the game instance but does not start running
3. Start Game Running
gameHandle.start(null);State change:
WAITING → RUNNINGDescription:
- The game starts running
- The user cannot interact yet
4. Enter Interactive State
gameHandle.play();State change:
RUNNING → PLAYINGDescription:
- The game enters the normal interactive state
- The user can perform operations
5. Pause Game Interaction
gameHandle.pause();State change:
PLAYING → RUNNINGDescription:
- The game keeps running, but user interaction is paused
6. Stop Game Running
gameHandle.stop(null);State change:
RUNNING → WAITINGDescription:
- The game stops running
- The runtime environment is retained
7. Destroy Game
gameHandle.destroy();State change:
ANY → UNAVAILABLEDescription:
- 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.
gameTask.destroy();Description:
- Internally, this actually calls:
gameHandle.destroy();- Used for unified lifecycle management
- It is recommended to prefer
gameTask.destroy()
Recommended Workflow
Standard Lifecycle Flow
UNAVAILABLE
↓ create()
WAITING
↓ start()
RUNNING
↓ play()
PLAYINGExit flow:
PLAYING
↓ pause()
RUNNING
↓ stop()
WAITING
↓ destroy()
UNAVAILABLEExample Code
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:
GameStateChangeListener will not be triggered2. 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
| Scenario | Recommended Operation |
|---|---|
| Page shown | start() |
| Page gains focus | play() |
| Page loses focus | pause() |
| Page hidden | stop() |
| Page destroyed | destroy() |
Summary
The core points of game lifecycle maintenance are as follows:
- Use
SUDRTGameHandleas the single control entry point - Listen for state changes through
setGameStateListener - Call the lifecycle interfaces in order to control the game state
- Call
destroyat the appropriate time to release resources
Full flow:
setGameStartOptions → create → start → play → pause → stop → destroy