Skip to content

getGameState ​

Get the current game state ​

getGameState is used to query in real time the lifecycle stage the mini game engine is currently in. Based on the enum value returned by this method, the host app can determine whether the game is initialized, running, or playing, and thereby decide whether to execute instructions such as start, play, or pause.


Method Declaration ​

objectivec
/**
 * Get the current game runtime state.
 * @return A SUDRTGameState enum value.
 */
- (NSInteger)getGameState;

Parameters ​

ParameterTypeRequiredDescription
None--This method takes no parameters.

Return Value (SUDRTGameState) ​

Enum ValueConstantDescription
0SUD_RT_GAME_STATE_UNAVAILABLEUnavailable: The engine is not created or has been destroyed; call create first.
1SUD_RT_GAME_STATE_WAITINGWaiting: The environment is ready; you can now mount the View or prepare to call start.
2SUD_RT_GAME_STATE_RUNNINGRunning: The script has started and is executing in the background, but the user may not be able to interact yet.
3SUD_RT_GAME_STATE_PLAYINGPlaying: Game logic and rendering are fully enabled; the user can interact normally.

Runtime Behavior ​

  1. Immediate sync: This method is a synchronous call and immediately returns the current value of the engine's internal state machine.
  2. State protection: Before executing key instructions (such as start), the SDK internally usually calls getGameState first to check whether it is in a valid starting state.
  3. Passive trigger: In addition to actively querying, it is recommended to use setGameStateListener: to observe automatic state transitions.

Example ​

objectivec
// Check the state before executing specific logic
SUDRTGameState currentState = [self.gameHandle getGameState];

if (currentState == SUD_RT_GAME_STATE_PLAYING) {
    // The game is being played; you can present the app's native settings menu and pause the game
    [self.gameHandle pause];
} else if (currentState == SUD_RT_GAME_STATE_WAITING) {
    // The environment is ready but the script has not run yet; trigger start
    [self.gameHandle start:@"{}"];
}

Notes ​

  • State dependency: Do not attempt to call getGameView or runScript in the UNAVAILABLE state; these operations will fail because the environment is not ready.
  • Multithreading considerations: Although you can query from any thread, for logic involving UI switching it is recommended to rely on the state obtained on the main thread.
  • Prefer listeners: For complex business logic, prefer using setGameStateListener: to observe state changes asynchronously, rather than continuously polling getGameState with a timer.