游戏

游戏模块提供游戏相关的各种功能，阅读JOGOS_SDK 简介页面与您的游戏引擎相关的部分后，可以按如下方式使用相关的功能：：

window.JOGOS_SDK.game;

若你需要在初始化阶段完成本地化语言适配、设备适配、时间校准等配置操作，可跳转至初始化（SysInfo）相关页面，查看详细的参数定义与配置方法。

游戏暂停/继续

游戏中断时（结束关卡、暂停游戏等），必须调用游戏暂停方法告知我们游戏已经暂停，不要忘记在游戏恢复或继续时（恢复、复活、进入下一关等），调用继续游戏方法告诉我们游戏已经继续。SDK 内部会自动处理播放广告时的暂停与继续，无需重复调用。

// 告知我们游戏已暂停
await window.JOGOS_SDK.game.pause();
// 告知我们暂停的游戏已继续
await window.JOGOS_SDK.game.continuePlay();

游戏开始/结束加载

当您的游戏开始加载时，必须调用开始加载方法告知我们游戏开始加载，加载结束后，务必调用加载结束方法告知我们游戏已经加载结束。

// 告知我们游戏开始加载
await window.JOGOS_SDK.game.loadingStart();
// 告知我们游戏加载已经结束
await window.JOGOS_SDK.game.loadingEnd();

当游戏开始加载时，必须调用开始加载方法告知我们游戏开始加载，加载结束后，必须调用加载结束方法告知我们游戏已经加载结束。

// 告知我们游戏已经暂停
await window.JOGOS_SDK.game.pause();
// 告知我们游戏已经继续
await window.JOGOS_SDK.game.continuePlay();

欢乐时光

可以在玩家达到某种成就（击败 Boss、达到高分等）时调用此方法，成功调用此方法后进触发网站的庆祝动作（例如发射一些五彩纸屑）。完成关卡或获得奖励时，无需调用此方法。

// 激活游戏欢乐时光
await window.JOGOS_SDK.game.happytime();

好友和聊天功能

我们已集成标准化社交功能模块，涵盖好友关系管理与实时聊天服务。若您的游戏支持多人互动玩法，可通过轻量级API快速接入，实现：好友列表云端同步、一键邀请组队、私密对话等核心社交场景。助力开发者以极低开发成本，高效构建游戏内沉浸式社交生态体系。

• 开发者在使用时，需要传对应玩家在平台侧 UserId 作为传递参数。

好友关系检查

检查指定玩家是否为当前用户的好友。

/**
 * 检查指定玩家是否我的好友
 * @param {Array<number>} userIds 玩家ID集合
 * @returns {Promise<Object>} { [userId: number]: boolean } 键值对对象
 */
window.JOGOS_SDK.game.isMyFriends = async function(userIds) {
    // 内部实现
}

好友交互逻辑说明

开发者需要根据好友关系自行实现按钮显示逻辑：

1. 按钮状态判断：使用 isMyFriends 接口检查指定玩家是否为好友
2. 按钮显示逻辑：
   • 如果是好友：显示“Conversation”按钮，点击后调用 openChatDialog 发起聊天
   • 如果不是好友：显示“Add Friend”按钮，点击后调用 sendFriendRequest 发送好友申请
3. 按钮实现：按钮的UI样式、位置、交互效果均由游戏开发者自行实现

示例代码

// 实现好友交互按钮的示例
async function setupFriendButton(userId, buttonElement) {
    try {
        // 1. 检查好友关系
        const friendStatus = await window.JOGOS_SDK.game.isMyFriends([userId]);
        const isFriend = friendStatus[userId];
        
        // 2. 根据好友关系设置按钮
        if (isFriend) {
            // 显示聊天按钮
            buttonElement.textContent = "Conversation";
            buttonElement.onclick = async () => {
                const success = await window.JOGOS_SDK.game.openChatDialog(userId);
                if (!success) {
                    alert("无法打开聊天窗口，请确保在官方平台环境");
                }
            };
        } else {
            // 显示添加好友按钮
            buttonElement.textContent = "Add Friend";
            buttonElement.onclick = async () => {
                const success = await window.JOGOS_SDK.game.sendFriendRequest(userId);
                if (success) {
                    alert("好友申请已发送");
                } else {
                    alert("发送好友申请失败");
                }
            };
        }
        
        // 3. 添加防频繁点击逻辑
        let lastClickTime = 0;
        const originalClick = buttonElement.onclick;
        buttonElement.onclick = function() {
            const now = Date.now();
            if (now - lastClickTime < 3000) {
                console.log("点击过于频繁，请稍后再试");
                return;
            }
            lastClickTime = now;
            originalClick.call(this);
        };
        
    } catch (error) {
        console.error("设置好友按钮失败:", error);
    }
}

添加好友

向指定玩家发送好友申请。

/**
 * 向指定玩家发送好友申请
 * @param {number} userId 目标玩家ID
 * @returns {Promise<boolean>} 是否发送成功
 */
window.JOGOS_SDK.game.sendFriendRequest = async function(userId) {
    // 内部实现
}

发起聊天

打开与指定好友的聊天窗口。

/**
 * 打开与指定玩家的聊天窗口
 * @param {number} userId 目标玩家ID
 * @returns {Promise<boolean>} 是否成功打开
 */
window.JOGOS_SDK.game.openChatDialog = async function(userId) {
    // 内部实现
}

边界处理：

• 非官方平台嵌入时返回失败并显示提示：“好友聊天功能仅在官方平台提供”
• 按钮点击后3秒内不可重复点击

重要提醒

开发者的游戏自有聊天功能：如果该游戏（联网游戏）自己拥有聊天功能，我们要求开发者添加脏话过滤器并根据游戏设置禁用聊天。如有投诉，我们将要求您禁用聊天。

初始化接口会返回邀请字段参数

• 游戏初始化接口增加邀请加入游戏的自定义参数，如房间ID、邀请码等，开发者可在分享邀请链接时携带这些参数，被邀请玩家通过链接进入游戏时，SDK 会将参数传递给开发者，以便将玩家拉入对应房间。

// 游戏初始化时传递房间参数（示例）
const gameConfig = {
    inviteArgs: 'ABC123',       // 自定义字段（如邀请码/房间ID）
    // 其他游戏配置...
};

// 初始化SDK时传递参数
window.JOGOS_SDK.init({
    gameId: 'your_game_id',
    customParams: JSON.stringify(gameConfig)
});

打开邀请好友窗口

• 当用户处于游戏中可加入新游戏的位置时，此功能支持您在游戏场景中放置“邀请分享”按钮：
• 点击按钮可打开一个包含邀请链接的弹窗，支持选择好友发送邀请。
• 邀请链接会携带自定义参数（如房间ID/邀请码等），被邀请玩家点击链接进入游戏时，开发者可解析参数并将玩家拉入对应房间。
• 点击游戏场景中的“Invite friend”按钮，打开侧边好友列表栏，发送邀请消息给好友，支持通过链接或直接邀请方式加入游戏。

/**
 * 打开邀请窗口
 * @param {Object} inviteArgs 邀请参数对象
 * @param {string} inviteArgs.inviteArgs 自定义邀请参数（必填，如房间ID或邀请码）
 * @param {string} [inviteArgs.customData] 自定义数据（将透传给被邀请者）
 * @param {number} [inviteArgs.expireTime] 邀请链接过期时间戳（毫秒）
 */
window.JOGOS_SDK.game.openInviteDialog = function(inviteArgs) {
    // 参数校验
    if (!inviteArgs || !inviteArgs.inviteArgs) {
        throw new Error('Missing required parameter: inviteArgs');
    }
    
    // 内部实现：
    // 1. 生成带参邀请链接
    // 2. 打开邀请弹窗（含好友列表和分享选项）
    // 3. 处理邀请结果回调
};

---