Skip to content

pause ​

Pause Mini-Game Execution ​

pause() is used to switch the mini-game from its current active state (PLAYING or RUNNING) to the paused state. After calling this method, the game enters the WAITING state.

While paused, the engine stops the render loop, pauses audio playback, and cuts off all user input dispatch (such as touch events and sensor data). This is essential for saving system resources and battery power.


Method Declaration ​

java
/**
 * Pauses mini-game execution.
 * On success, the mini-game instance enters the `WAITING` state.
 * Usually called when the app moves to the background or a native global dialog pops up.
 */
void pause();

Runtime Behavior and State Transitions ​

1. Preconditions ​

  • The current state should usually be GAME_STATE_PLAYING or GAME_STATE_RUNNING.
  • The pause command is only effective when the environment has been created and is running.

2. Execution Process ​

  • Logic suspension: The script engine's timers (such as requestAnimationFrame) are suspended.
  • Resource silencing: Audio output is muted or stopped, and the rendering pipeline stops submitting new frames.
  • Interaction cutoff: No longer responds to any screen touch operations.

3. Result ​

  • On success, the state rolls back to GAME_STATE_WAITING.
  • At this point, the game screen stays on the last frame before pausing (depending on the specific Surface recycling strategy).

Example Code ​

java
@Override
protected void onPause() {
    super.onPause();
    // When the Activity loses focus or moves to the background, actively pause the game
    if (gameHandle != null) {
        gameHandle.pause();
    }
}

// Or when an important native UI module pops up
public void showNativePayDialog() {
    gameHandle.pause();
    // Execute native payment logic...
}

Notes ​

  • Must be used in pairs: After calling pause(), when the user returns to the game, you must wake the game via start() or play() (depending on which stage you want to resume to).
  • Lifecycle alignment: It is strongly recommended to place pause() in the Activity's onPause() and start() in onResume() to keep the mini-game strictly aligned with the app's lifecycle.
  • Audio handling: Although the SDK attempts to handle this automatically, on some extreme device models it is recommended to explicitly check for any unclosed system-level audio streams after pause() to prevent "the person leaves but the sound stays."