Skip to content

stop ​

Stop Mini-Game Script Execution ​

stop() is used to stop the currently running mini-game script. After calling this method, the game rolls back from the PLAYING or RUNNING state to the WAITING state.

Unlike pause(), stop() usually comes with an explicit business intent (such as the player actively tapping exit). It triggers the mini-game's internal onHide lifecycle function and lets you pass specific exit or stop parameters to the JS layer.


Method Declaration ​

java
/**
 * Stops mini-game execution.
 * On success, the mini-game instance enters the `WAITING` state.
 *
 * @param onHideMsg The argument passed to the js api `onHide` callback before the program moves to the background or stops.
 * Usually a JSON string is passed in to inform the game of the reason for stopping or to save the current state.
 */
void stop(String onHideMsg);

Runtime Behavior and State Transitions ​

1. Preconditions ​

  • The current state must be GAME_STATE_RUNNING or GAME_STATE_PLAYING.
  • The game environment must exist and not yet have been destroyed (UNAVAILABLE).

2. Execution Process ​

  • Trigger callback: The SDK sends a command to the JS engine, triggering App.onHide(onHideMsg) in the game code.
  • Logic termination: Stops game logic updates, physics simulation, and render submission.
  • Resource suspension: Audio and input listening are completely cut off.

3. Result ​

  • On success, the state changes to GAME_STATE_WAITING.
  • At this point, the script is inactive, but the JS virtual machine memory is not released, so it can be quickly restarted by calling start() again.

Example Code ​

java
// When the user taps the native "Back" or "Close Game" button
public void handleUserExit() {
    // Construct the stop parameters to inform the game layer
    String onHideMsg = "{\"reason\": \"user_exit\", \"timestamp\": " + System.currentTimeMillis() + "}";
    
    // Stop execution
    gameHandle.stop(onHideMsg);
    
    // If you confirm the game instance is no longer needed, destroy it immediately afterward
    // gameHandle.destroy();
}

Notes ​

  • Importance of onHideMsg: The mini-game can perform operations such as saving, reporting analytics events, or cleaning up local temporary data in the onHide callback. Make sure the JSON string you pass in conforms to the protocol agreed upon between you and the game developer.
  • Difference from pause: Although both ultimately enter the WAITING state, stop emphasizes "stopping logic" and carries the onHideMsg parameter, whereas pause leans more toward a system-level temporary suspension.
  • Asynchronous confirmation: If the game performs complex IO operations in onHide, the state transition may incur a slight delay. It is recommended to observe whether the state successfully switches back to WAITING via GameStateChangeListener.