宿主回调

在 PC 平台，宿主回调使用 JavaScript 回调函数（Callback）模式实现。

1. SDK 初始化回调

SDK 初始化完成时的回调函数。

函数签名

(hostHandle, error) => void

参数说明

参数	数据类型	说明
hostHandle	TJHostHandle	初始化成功时返回的宿主句柄，失败时为 null
error	HostRuntimeError	初始化失败时的错误对象，成功时为 null

使用示例

TJHostHandle.initialize('sdk-key', 'sdk-secret', (hostHandle, error) => {
  if (error) {
    console.error('Initialization failed:', error);
    return;
  }
  
  console.log('Initialization successful');
  // Use hostHandle...
});

2. 首帧渲染回调

游戏首帧渲染完成时的回调函数。

函数签名

() => void

使用示例

gameHandle.setOnFirstFrameRenderedListener(() => {
  console.log('First frame rendered');
  // Hide loading screen, etc.
});

3. 游戏包下载回调

游戏包下载过程中的回调函数集合。

onStart - 开始下载

函数签名

() => void

onProgress - 下载进度

函数签名

(progress, totalBytesWritten, totalBytesExpected) => void

参数说明

参数	数据类型	说明
progress	Number	下载进度 (0-1)
totalBytesWritten	Number	已下载字节数
totalBytesExpected	Number	总字节数

onSuccess - 下载成功

函数签名

() => void

onFailure - 下载失败

函数签名

(error) => void

参数说明

参数	数据类型	说明
error	Error	错误对象

使用示例

gameHandle.setOnGamePackageDownloadListener({
  onStart: () => {
    console.log('Download started');
  },
  
  onProgress: (progress, totalBytesWritten, totalBytesExpected) => {
    const percent = (progress * 100).toFixed(2);
    console.log(`Download progress: ${percent}%`);
  },
  
  onSuccess: () => {
    console.log('Download completed');
  },
  
  onFailure: (error) => {
    console.error('Download failed:', error);
  }
});

4. 游戏失败回调

游戏运行失败时的回调函数。

函数签名

(error) => void

参数说明

参数	数据类型	说明
error	HostRuntimeError	错误对象

使用示例

gameHandle.setOnHostFailureListener((error) => {
  console.error('Game host failure:', error.code, error.message);
  // Handle failure: show error UI, restart game, etc.
});

5. 菜单按钮点击回调

右上角菜单按钮被点击时的回调函数。

函数签名

() => void

使用示例

gameHandle.setOnTJMenuListener(() => {
  console.log('Menu button clicked');
  // Show menu UI
});

6. 关闭按钮点击回调

右上角关闭按钮被点击时的回调函数。

函数签名

() => void

使用示例

gameHandle.setOnTJCloseListener(() => {
  console.log('Close button clicked');
  // Show confirmation dialog, close game, etc.
});

7. 自定义命令回调

处理游戏中自定义命令的回调函数。

函数签名

(request, handle) => void

参数说明

参数	数据类型	说明
request	Object	请求参数对象
handle	Object	命令处理句柄，包含 success() 和 fail()

handle 对象方法

• handle.success(result) - 返回成功结果
• handle.fail(errorCode, errorMsg) - 返回失败结果

使用示例

gameHandle.setCustomCommandListener('login', (request, handle) => {
  // Validate parameters
  if (!request.username) {
    handle.fail(20001, 'Username is required');
    return;
  }

  // Process login
  performLogin(request.username, request.password)
    .then(result => {
      handle.success({
        userId: result.userId,
        token: result.token
      });
    })
    .catch(error => {
      handle.fail(20002, error.message);
    });
});

8. 自定义脚本执行回调

执行自定义脚本后的回调函数。

函数签名

(result, error) => void

参数说明

参数	数据类型	说明
result	Any	脚本执行结果，失败时为 null
error	Error	执行错误对象，成功时为 null

使用示例

const script = `
  console.log('Custom script running');
  return { success: true, data: 'Hello' };
`;

gameHandle.runCustomScript(script, (result, error) => {
  if (error) {
    console.error('Script execution failed:', error);
    return;
  }
  
  console.log('Script result:', result);
});

9. 隐私权限检查回调

检查系统权限时的回调函数。

函数签名

(methodName, callback) => void

参数说明

参数	数据类型	说明
methodName	String	需要检查权限的方法名
callback	Function	权限检查结果回调 (result) => {}

result 对象

{
  passed: Boolean,      // 是否通过权限检查
  errorNo: Number,      // 错误码
  errorMessage: String  // 错误消息
}

使用示例

const privacyChecker = {
  requirePrivacy: (methodName, callback) => {
    console.log(`Checking privacy for: ${methodName}`);
    
    // Perform permission check
    checkSystemPermission(methodName)
      .then(() => {
        callback({
          passed: true,
          errorNo: 0,
          errorMessage: ''
        });
      })
      .catch(error => {
        callback({
          passed: false,
          errorNo: 1,
          errorMessage: error.message
        });
      });
  }
};

gameHandle.setPrivacyChecker(privacyChecker);

完整回调示例

const { TJHostHandle } = require('webglhost-runtime-pc');

class GameCallbackManager {
  constructor() {
    this.gameHandle = null;
  }

  setupAllCallbacks(gameHandle) {
    this.gameHandle = gameHandle;

    // First frame rendered
    gameHandle.setOnFirstFrameRenderedListener(() => {
      this.onFirstFrameRendered();
    });

    // Download callbacks
    gameHandle.setOnGamePackageDownloadListener({
      onStart: () => this.onDownloadStart(),
      onProgress: (p, w, t) => this.onDownloadProgress(p, w, t),
      onSuccess: () => this.onDownloadSuccess(),
      onFailure: (e) => this.onDownloadFailure(e)
    });

    // Game failure
    gameHandle.setOnHostFailureListener((error) => {
      this.onGameFailure(error);
    });

    // UI callbacks
    gameHandle.setOnTJMenuListener(() => {
      this.onMenuClicked();
    });

    gameHandle.setOnTJCloseListener(() => {
      this.onCloseClicked();
    });

    // Custom command
    gameHandle.setCustomCommandListener('myCommand', (request, handle) => {
      this.handleCustomCommand(request, handle);
    });

    // Privacy checker
    gameHandle.setPrivacyChecker({
      requirePrivacy: (methodName, callback) => {
        this.checkPrivacy(methodName, callback);
      }
    });
  }

  onFirstFrameRendered() {
    console.log('First frame rendered');
  }

  onDownloadStart() {
    console.log('Download started');
  }

  onDownloadProgress(progress, written, total) {
    console.log(`Progress: ${(progress * 100).toFixed(2)}%`);
  }

  onDownloadSuccess() {
    console.log('Download completed');
  }

  onDownloadFailure(error) {
    console.error('Download failed:', error);
  }

  onGameFailure(error) {
    console.error('Game failure:', error);
  }

  onMenuClicked() {
    console.log('Menu clicked');
  }

  onCloseClicked() {
    console.log('Close clicked');
  }

  handleCustomCommand(request, handle) {
    // Process command
    handle.success({ result: 'ok' });
  }

  checkPrivacy(methodName, callback) {
    // Check permission
    callback({ passed: true, errorNo: 0, errorMessage: '' });
  }
}

// Usage
const callbackManager = new GameCallbackManager();
callbackManager.setupAllCallbacks(gameHandle);