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 }
}, '*');