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_RUNNINGorGAME_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
onHidecallback. 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
WAITINGstate,stopemphasizes "stopping logic" and carries theonHideMsgparameter, whereaspauseleans 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 toWAITINGviaGameStateChangeListener.
