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:
- Initialize the SDK
- Complete user authentication
- Prepare the local game resource directory
- Construct
SUDOPGamePackageParams - Call
startGameByDirectoryPath
Full Example
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
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
| Parameter | Type | Description |
|---|---|---|
directoryPath | String | Required. 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. |
params | SUDOPGamePackageParams | Required. Game package parameter information, used to identify the version, validation information, and additional business-side information. |
listener | SUDOPStartGameListener | Required. 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:
| Field | Type | Description |
|---|---|---|
version | String | Game resource version number. |
fid | String | Game resource identifier, generally used for file validation. |
fidType | FIDType | File identifier type, e.g. MD5. |
appGameID | String | Business-side custom game ID. |
appCPID | String | Game developer ID. |
appGroupID | String | Game 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:
| Parameter | Type | Description |
|---|---|---|
handle | GamePkgDecryptHandle | Decryption result callback handle. |
filePath | String | Path 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:
| Parameter | Type | Description |
|---|---|---|
gameHandle | SUDRTGameHandle | Game 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:
| Parameter | Type | Description |
|---|---|---|
gameId | String | The ID of the game that started successfully. |
gameHandle | SUDRTGameHandle | Game instance handle. |
Example:
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:
| Parameter | Type | Description |
|---|---|---|
retCode | int | Error code. |
retMsg | String | Error 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:
| Parameter | Type | Description |
|---|---|---|
decryptedFilePath | String | Path of the decrypted file. |
isDeleteFile | boolean | Whether to delete the decrypted file after the game finishes loading. |
void fail(int retCode, String retMsg)
Notifies the SDK that decryption failed.
Parameters:
| Parameter | Type | Description |
|---|---|---|
retCode | int | Error code. |
retMsg | String | Error description. |
Runtime Behavior
After startGameByDirectoryPath is called, the SDK executes the following process:
- Validate whether the resource structure in the specified directory is valid
- Read the game resources directly from that directory
- Initialize the runtime environment
- Create the game instance
- 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:
FrameLayout container;After obtaining gameView in the onSuccess callback, add it to the container:
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:
SUDOPGameTask gameTask = SUDOP.startGameByDirectoryPath(directoryPath, params, listener);When the page is destroyed or the business ends:
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.
4. Using the Application's Private Directory Is Recommended
If the resource directory is placed under the application's private directory, e.g.:
context.getFilesDir() + "/game_res/my_tetris_folder"Additional storage permissions are usually not required, and path access is more stable.
5. Running a Single Game Instance at a Time Is Recommended
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:
- Call
SUDOP.initSDKto initialize the SDK - Call
SUDOP.authto complete authentication - Prepare the local game resource directory and
SUDOPGamePackageParams - Call
SUDOP.startGameByDirectoryPath - Obtain the
gameViewinonSuccess - Add the
gameViewto the page container - Call
gameTask.destroy()to release resources when the business ends
