Skip to content

Load Game by Directory Path ​

This document describes how to launch a game from a local game package directory and load the game view into an application page.

Overview ​

Through the SUDOP.startGameByDirectoryPath interface, you can directly launch a game based on a local game resource directory on the device.

This interface is suitable for the following scenarios:

  • The business side has already completed downloading and extracting the game resources
  • The game resources have been pre-placed in the application's private directory
  • You need to skip the download and extraction process to speed up startup
  • The business side needs to manage the game resource directory on its own

After being called, the SDK directly completes the following process based on the specified directory:

  • Validate the game directory structure
  • Initialize the runtime environment
  • Create the game instance
  • Return the game view via callback

Developers only need to obtain the gameView in the success callback and add it to the page container.

Prerequisites ​

Before launching a game from a local directory, you must first complete the following steps:

  1. Initialize the SDK
  2. Complete user authentication
  3. Prepare the local game resource directory
  4. Construct SUDOPGamePackageParams
  5. Call startGameByDirectoryPath

Full Example ​

java
SUDOP.initSDK(context, "Your appId", "Your appKey", new SUDOPInitSDKListener() {
    @Override
    public void onSuccess() {
        SUDOP.auth("Your user signature", new SUDOPAuthListener() {
            @Override
            public void onSuccess() {
                String directoryPath = context.getFilesDir() + "/game_res/my_tetris_folder";

                SUDOPGamePackageParams params = new SUDOPGamePackageParams();
                params.version = "gamePkgVersion";
                params.fid = "2e7ca170f33629c7baf4dc430c541c43";
                params.fidType = FIDType.MD5;
                params.appGameID = "appGameID";
                params.appCPID = "Game Developer id";
                params.appGroupID = "Game developer group id";

                SUDOPGameTask gameTask = SUDOP.startGameByDirectoryPath(directoryPath, params, new SUDOPStartGameListener() {
                    @Override
                    public void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) {
                        // By default this callback does not need to be implemented
                    }

                    @Override
                    public void onCreated(SUDRTGameHandle gameHandle) {
                        // Callback when SUDRTGameHandle is created; you can typically set custom startup parameters or inject Java objects for game interaction here
                    }

                    @Override
                    public void onSuccess(String gameId, SUDRTGameHandle gameHandle) {
                        // When this callback is received, the game has loaded successfully; the app just needs to add the game View to the page it wants to display
                        View gameView = gameHandle.getGameView();
                    }

                    @Override
                    public void onFailure(int retCode, String retMsg) {
                        // Failed to load the game; usually check whether the parameters are correct and check network issues
                    }
                });

                // When the business needs to destroy the game, call this method to destroy it
//              gameTask.destroy();
            }

            @Override
            public void onFailure(int retCode, String retMsg) {
                // auth interface failed; usually check whether the user signature is correct and check network issues
            }
        });
    }

    @Override
    public void onFailure(int retCode, String retMsg) {
        // SDK initialization failed; when appId and appKey are correct, this is usually caused by network issues
    }
});

Core Interface ​

startGameByDirectoryPath ​

java
public static SUDOPGameTask startGameByDirectoryPath(
    String directoryPath,
    SUDOPGamePackageParams params,
    SUDOPStartGameListener listener
);

This interface launches a game based on a local game resource directory and returns a SUDOPGameTask handle used for subsequent game lifecycle management.

Parameters ​

ParameterTypeDescription
directoryPathStringRequired. The absolute path of the local game resource directory. The root of the directory must contain the entry file required for the game to run, e.g. app.json.
paramsSUDOPGamePackageParamsRequired. Game package parameter information, used to identify the version, validation information, and additional business-side information.
listenerSUDOPStartGameListenerRequired. The game startup process listener, used to receive state callbacks during startup.

SUDOPGamePackageParams ​

SUDOPGamePackageParams describes the metadata corresponding to the current game resource directory.

The meaning of the parameters in the example is as follows:

FieldTypeDescription
versionStringGame resource version number.
fidStringGame resource identifier, generally used for file validation.
fidTypeFIDTypeFile identifier type, e.g. MD5.
appGameIDStringBusiness-side custom game ID.
appCPIDStringGame developer ID.
appGroupIDStringGame developer group ID.

Startup Callbacks ​

SUDOPStartGameListener ​

void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) ​

Game package decryption callback.

For the directory-based launch scenario, this callback is usually not part of the main flow, but the interface remains consistent. If the business side still has additional decryption logic during the directory resource preparation stage, it can handle it in this callback.

Parameters:

ParameterTypeDescription
handleGamePkgDecryptHandleDecryption result callback handle.
filePathStringPath of the file currently to be processed.

void onCreated(SUDRTGameHandle gameHandle) ​

Game instance created callback.

When this callback is received, the SUDRTGameHandle has been created. Here you can typically:

  • Set custom startup parameters
  • Inject Java objects for game interaction
  • Complete business preparation before startup

Parameters:

ParameterTypeDescription
gameHandleSUDRTGameHandleGame instance handle.

void onSuccess(String gameId, SUDRTGameHandle gameHandle) ​

Game startup success callback.

When this callback is received, the game has been loaded successfully. Developers can obtain the game view via gameHandle.getGameView() and add it to their own page container for display.

Parameters:

ParameterTypeDescription
gameIdStringThe ID of the game that started successfully.
gameHandleSUDRTGameHandleGame instance handle.

Example:

java
View gameView = gameHandle.getGameView();
// container.addView(gameView);

void onFailure(int retCode, String retMsg) ​

Game startup failure callback.

You can usually determine the failure reason from the error code and error message.

Parameters:

ParameterTypeDescription
retCodeintError code.
retMsgStringError description.

Common failure reasons include:

  • Incorrect directory path
  • Directory does not exist
  • Invalid directory structure
  • Missing required entry file
  • Incorrect parameters
  • Network exception
  • Runtime initialization failure

Decryption Handle ​

GamePkgDecryptHandle ​

void success(String decryptedFilePath, boolean isDeleteFile) ​

Notifies the SDK that decryption succeeded.

Parameters:

ParameterTypeDescription
decryptedFilePathStringPath of the decrypted file.
isDeleteFilebooleanWhether to delete the decrypted file after the game finishes loading.

void fail(int retCode, String retMsg) ​

Notifies the SDK that decryption failed.

Parameters:

ParameterTypeDescription
retCodeintError code.
retMsgStringError description.

Runtime Behavior ​

After startGameByDirectoryPath is called, the SDK executes the following process:

  1. Validate whether the resource structure in the specified directory is valid
  2. Read the game resources directly from that directory
  3. Initialize the runtime environment
  4. Create the game instance
  5. Return the game view via callback

Compared with launching a game via gameId or a local package, this interface does not trigger the download process and does not perform the package extraction process, but launches directly based on the existing directory.

Page Integration ​

It is recommended to prepare a container for hosting the game view in the page in advance, e.g. FrameLayout.

Example:

java
FrameLayout container;

After obtaining gameView in the onSuccess callback, add it to the container:

java
View gameView = gameHandle.getGameView();
container.addView(gameView);

Lifecycle Management ​

startGameByDirectoryPath returns a SUDOPGameTask object. The business side needs to hold this object and actively destroy it when the game is no longer needed.

Example:

java
SUDOPGameTask gameTask = SUDOP.startGameByDirectoryPath(directoryPath, params, listener);

When the page is destroyed or the business ends:

java
gameTask.destroy();

Notes ​

1. Must Pass a Directory Path, Not a File Path ​

directoryPath must point to an already existing game resource directory, not a package file path.

2. The Directory Structure Must Be Complete ​

Make sure the root of the directory contains the key files required for the game to run, e.g. app.json. If the directory structure is incomplete, the SDK will not be able to launch the game properly.

3. The Directory Lifecycle Is Managed by the Business Side ​

The SDK does not automatically delete or clean up the resource directory specified by this interface. Updating, replacing, and deleting the directory must be managed by the business side.

If the resource directory is placed under the application's private directory, e.g.:

java
context.getFilesDir() + "/game_res/my_tetris_folder"

Additional storage permissions are usually not required, and path access is more stable.

To avoid resource contention and increased page management complexity, it is recommended to maintain only one active game instance at a time.

6. Callbacks Can Directly Operate the UI ​

Startup-related callbacks are executed on the main thread, so developers can directly perform UI operations such as addView in onSuccess.

Summary ​

The core process of loading a game from a local game directory is as follows:

  1. Call SUDOP.initSDK to initialize the SDK
  2. Call SUDOP.auth to complete authentication
  3. Prepare the local game resource directory and SUDOPGamePackageParams
  4. Call SUDOP.startGameByDirectoryPath
  5. Obtain the gameView in onSuccess
  6. Add the gameView to the page container
  7. Call gameTask.destroy() to release resources when the business ends