Skip to content

start ​

Start the Mini-Game Runtime Environment ​

start() is the key command that makes the mini-game truly "come alive." Before executing this method, the game environment must have already been created via create().

After calling start(), the Runtime loads the game's main entry script (usually game.js), initializes the game logic, and begins executing the game loop. At this point, the mini-game enters the RUNNING state.


Method Declaration ​

java
/**
 * Starts the mini-game runtime environment.
 * On success, the mini-game instance enters the `RUNNING` state, where the mini-game script executes normally.
 * This interface should be executed when starting the mini-game or switching from the background to the foreground.
 *
 * @param onShowMsg The argument passed to the js api `onShow` callback after the program moves to the foreground.
 * Usually a JSON string is passed in to convey the launch scene or parameters to the game.
 */
void start(String onShowMsg);

Runtime Behavior and State Transitions ​

1. Preconditions ​

  • The state must be GAME_STATE_WAITING.
  • The game resource package must have been decompressed and located.

2. Execution Process ​

  • The engine loads and parses the JS script.
  • Triggers the game's internal lifecycle functions (such as App.onLaunch and App.onShow).
  • Starts the render loop and the logic loop.

3. Result ​

  • On success, the state changes to GAME_STATE_RUNNING.
  • At this point, the game screen begins to render, but since play() has not yet been called, the game may not respond to any touch input.

Example Code ​

java
// Assume the state has been observed to change to WAITING in setGameStateListener
@Override
public void onStateChanged(int fromState, int toState) {
    if (toState == SUDRTGameHandle.GAME_STATE_WAITING) {
        // Prepare the launch parameters to pass to the game, e.g., the entry scene value, sharer ID, etc.
        String onShowMsg = "{\"scene\": 1001, \"query\": {\"inviter\": \"user_99\"}}";
        
        // Officially run the script
        gameHandle.start(onShowMsg);
    }
}

Key Parameter: onShowMsg ​

The onShowMsg parameter is the primary channel for the native layer to pass business context to the game layer:

  • First launch: Corresponds to the arguments of the mini-game JS layer's onLaunch and onShow.
  • Hot start (switching back to the foreground): When you switch away from the Activity hosting the mini-game to another page and then come back, calling start again with onShowMsg triggers the JS layer's onShow.

Notes ​

  • Do not start repeatedly: If the state is already RUNNING, calling start again may cause the JS logic to reinitialize repeatedly.
  • Use together with play(): Usually, after observing the entry into RUNNING, you should immediately call gameHandle.play(), otherwise the player will see the screen but be unable to interact.
  • JSON format: It is recommended to pass in a standard JSON string so the game can parse it easily.