跳到正文

XMPlay SDK v2

XMPlay 集成文档

快速开始

在你的游戏 HTML 文件中监听 xmp_inject 消息来接收宿主注入的参数:

window.addEventListener('message', (e) => {
  if (e.data?.type === 'xmp_inject') {
    const { params, gameId } = e.data;
    // Apply params to your game
    initGame(params);
  }
});

// Signal ready to the host
window.parent.postMessage({
  type:    'xmp_ack',
  gameId:  window.__XMP_GAME_ID ?? 'unknown',
  payload: { lifecycle: 'ready' },
}, '*');

消息类型

消息类型方向说明
xmp_inject宿主 → 游戏注入初始参数(游戏就绪后触发)
xmp_control宿主 → 游戏发送控制命令(restart/mute/pause等)
xmp_ack游戏 → 宿主游戏确认消息(lifecycle/score/log等)

沙盒属性

所有 XMP 游戏运行在受控 iframe 中,使用以下沙盒属性:

<!-- Standard XMP formats -->
sandbox="allow-scripts allow-same-origin allow-pointer-lock
         allow-storage-access-by-user-activation"
allow="autoplay; fullscreen; picture-in-picture"

<!-- xmp-cc format (adds form/popup/download capabilities) -->
sandbox="allow-scripts allow-same-origin allow-pointer-lock
         allow-storage-access-by-user-activation
         allow-forms allow-popups allow-downloads"

生命周期

推荐的游戏生命周期事件序列:

// 1. DOM ready → signal ready
window.parent.postMessage({ type: 'xmp_ack', payload: { lifecycle: 'ready' } }, '*');

// 2. Host fires xmp_inject with params
// → Your game initialises with injected params

// 3. Game loop starts → optional: report score
window.parent.postMessage({
  type: 'xmp_ack',
  payload: { lifecycle: 'score', value: 1234 }
}, '*');

// 4. Game ends → signal complete
window.parent.postMessage({
  type: 'xmp_ack',
  payload: { lifecycle: 'complete', score: 9999 }
}, '*');
XMPlay SDK — FairyChest Studio | FairyChest