Jogo

O módulo de jogo oferece várias funcionalidades relacionadas ao jogo. Após ler a parte relacionada ao seu motor de jogo na página Introdução ao JOGOS_SDK, você pode usar as funcionalidades relevantes da seguinte maneira:

window.JOGOS_SDK.game;

Se precisar de concluir operações de configuração como adaptação de idioma de localização, adaptação de dispositivo e calibração de tempo durante a fase de inicialização, pode saltar para a página relacionada Inicialização (SysInfo) para visualizar definições de parâmetros detalhadas e métodos de configuração.

Pausar/Continuar jogo

Quando o jogo for interrompido (fim de nível, pausa do jogo, etc.), é obrigatório chamar o método de pausa do jogo para informar que o jogo foi pausado. Não se esqueça de chamar o método de continuação do jogo para informar que o jogo foi retomado quando ele for restaurado ou continuado (recuperação, ressurreição, entrada no próximo nível, etc.). O SDK trata automaticamente a pausa e continuação durante a reprodução de anúncios, não sendo necessário chamá-los repetidamente.

// Informe-nos que o jogo foi pausado
await window.JOGOS_SDK.game.pause();
// Informe-nos que o jogo pausado foi retomado
await window.JOGOS_SDK.game.continuePlay();

Iniciar/Encerrar carregamento do jogo

Quando o seu jogo começar a carregar, é obrigatório chamar o método de início de carregamento para informar que o jogo começou a carregar. Após o término do carregamento, certifique-se de chamar o método de encerramento de carregamento para informar que o jogo terminou de carregar.

// Informe-nos que o jogo começou a carregar
await window.JOGOS_SDK.game.loadingStart();
// Informe-nos que o carregamento do jogo terminou
await window.JOGOS_SDK.game.loadingEnd();

Quando o jogo começar a carregar, é obrigatório chamar o método de início de carregamento para informar que o jogo começou a carregar. Após o término do carregamento, é obrigatório chamar o método de encerramento de carregamento para informar que o jogo terminou de carregar.

// Informe-nos que o jogo foi pausado
await window.JOGOS_SDK.game.pause();
// Informe-nos que o jogo foi retomado
await window.JOGOS_SDK.game.continuePlay();

Momento feliz

Este método pode ser chamado quando o jogador alcançar um feito (derrotar um Chefão, alcançar uma pontuação alta, etc.). Uma chamada bem-sucedida a este método irá disparar ações de celebração no site (por exemplo, lançar confetes). Não é necessário chamar este método ao completar um nível ou receber uma recompensa.

// Ativar o momento feliz do jogo
await window.JOGOS_SDK.game.happytime();

Funcionalidades de Amigos e Chat

Integramos um módulo padronizado de funcionalidades sociais, abrangendo gerenciamento de relacionamentos de amizade e serviço de chat em tempo real. Se o seu jogo suportar jogabilidade interativa multijogador, você pode se conectar rapidamente através de uma API leve para implementar: sincronização na nuvem da lista de amigos, convite para formar equipe com um clique, diálogos privados e outros cenários sociais centrais. Ajuda os desenvolvedores a construir um ecossistema social imersivo dentro do jogo de forma eficiente e com custos de desenvolvimento extremamente baixos.

• Ao usar, o desenvolvedor precisa passar o UserId correspondente do jogador no lado da plataforma como parâmetro.

Verificação de Relacionamento de Amigos

Verifica se um jogador específico é amigo do usuário atual.

/**
 * Verifica se o jogador especificado é meu amigo
 * @param {Array<number>} userIds Conjunto de IDs de jogadores
 * @returns {Promise<Object>} { [userId: number]: boolean } Objeto de pares chave-valor
 */
window.JOGOS_SDK.game.isMyFriends = async function(userIds) {
    // Implementação interna
}

Explicação da Lógica de Interação com Amigos

Os desenvolvedores precisam implementar a lógica de exibição do botão com base no relacionamento de amizade:

1. Determinação do estado do botão: Use a interface isMyFriends para verificar se o jogador especificado é um amigo.
2. Lógica de exibição do botão:
   • Se for amigo: Exiba o botão "Conversation"; ao clicar, chame openChatDialog para iniciar um chat.
   • Se não for amigo: Exiba o botão "Add Friend"; ao clicar, chame sendFriendRequest para enviar um pedido de amizade.
3. Implementação do botão: O estilo da UI, a posição e os efeitos de interação do botão são implementados pelo próprio desenvolvedor do jogo.

Código de Exemplo

// Exemplo de implementação de botão de interação com amigo
async function setupFriendButton(userId, buttonElement) {
    try {
        // 1. Verificar relacionamento de amizade
        const friendStatus = await window.JOGOS_SDK.game.isMyFriends([userId]);
        const isFriend = friendStatus[userId];
        
        // 2. Configurar botão com base no relacionamento de amizade
        if (isFriend) {
            // Exibir botão de chat
            buttonElement.textContent = "Conversation";
            buttonElement.onclick = async () => {
                const success = await window.JOGOS_SDK.game.openChatDialog(userId);
                if (!success) {
                    alert("Não foi possível abrir a janela de chat, certifique-se de estar no ambiente da plataforma oficial");
                }
            };
        } else {
            // Exibir botão de adicionar amigo
            buttonElement.textContent = "Add Friend";
            buttonElement.onclick = async () => {
                const success = await window.JOGOS_SDK.game.sendFriendRequest(userId);
                if (success) {
                    alert("Pedido de amizade enviado");
                } else {
                    alert("Falha ao enviar pedido de amizade");
                }
            };
        }
        
        // 3. Adicionar lógica de prevenção de clique frequente
        let lastClickTime = 0;
        const originalClick = buttonElement.onclick;
        buttonElement.onclick = function() {
            const now = Date.now();
            if (now - lastClickTime < 3000) {
                console.log("Cliques muito frequentes, tente novamente mais tarde");
                return;
            }
            lastClickTime = now;
            originalClick.call(this);
        };
        
    } catch (error) {
        console.error("Falha ao configurar botão de amigo:", error);
    }
}

Adicionar Amigo

Envia um pedido de amizade para um jogador específico.

/**
 * Envia um pedido de amizade para um jogador específico
 * @param {number} userId ID do jogador alvo
 * @returns {Promise<boolean>} Se foi enviado com sucesso
 */
window.JOGOS_SDK.game.sendFriendRequest = async function(userId) {
    // Implementação interna
}

Iniciar Chat

Abre a janela de chat com um amigo específico.

/**
 * Abre a janela de chat com um jogador específico
 * @param {number} userId ID do jogador alvo
 * @returns {Promise<boolean>} Se foi aberto com sucesso
 */
window.JOGOS_SDK.game.openChatDialog = async function(userId) {
    // Implementação interna
}

Tratamento de Limites:

• Ao ser incorporado em uma plataforma não oficial, retorna falha e exibe a mensagem: "A funcionalidade de chat com amigos está disponível apenas na plataforma oficial".
• O botão não pode ser clicado novamente dentro de 3 segundos após o clique.

Aviso Importante

Funcionalidade de chat própria do jogo do desenvolvedor: Se este jogo (jogo online) tiver sua própria funcionalidade de chat, exigimos que o desenvolvedor adicione um filtro de palavrões e desative o chat conforme as configurações do jogo. Se houver reclamações, solicitaremos que você desative o chat.

A Interface de Inicialização Retornará Parâmetros de Campo de Convite

• A interface de inicialização do jogo adicionou parâmetros personalizados para convidar a ingressar no jogo, como ID da sala, código de convite, etc. Os desenvolvedores podem transmitir esses parâmetros ao compartilhar o link de convite. Quando o jogador convidado entra no jogo através do link, o SDK passará os parâmetros para o desenvolvedor para colocar o jogador na sala correspondente.

// Passar parâmetros da sala ao inicializar o jogo (exemplo)
const gameConfig = {
    inviteArgs: 'ABC123',       // Campo personalizado (ex: código de convite/ID da sala)
    // Outras configurações do jogo...
};

// Passar parâmetros ao inicializar o SDK
window.JOGOS_SDK.init({
    gameId: 'your_game_id',
    customParams: JSON.stringify(gameConfig)
});

Abrir Janela de Convite de Amigos

• Quando o usuário está em uma posição no jogo onde pode ingressar em um novo jogo, esta funcionalidade permite que você coloque um botão "Compartilhar Convite" na cena do jogo:
• Clicar no botão abre um pop-up contendo o link de convite, permitindo selecionar amigos para enviar o convite.
• O link de convite conterá parâmetros personalizados (como ID da sala/código de convite, etc.). Quando o jogador convidado clica no link para entrar no jogo, o desenvolvedor pode analisar os parâmetros e colocar o jogador na sala correspondente.
• Clicar no botão "Invite friend" na cena do jogo abre a barra lateral da lista de amigos, envia uma mensagem de convite para amigos, permitindo ingressar no jogo através do link ou por convite direto.

/**
 * Abre a janela de convite
 * @param {Object} inviteArgs Objeto de parâmetros de convite
 * @param {string} inviteArgs.inviteArgs Parâmetros de convite personalizados (obrigatório, ex: ID da sala ou código de convite)
 * @param {string} [inviteArgs.customData] Dados personalizados (serão repassados ao convidado)
 * @param {number} [inviteArgs.expireTime] Timestamp de expiração do link de convite (milissegundos)
 */
window.JOGOS_SDK.game.openInviteDialog = function(inviteArgs) {
    // Validação de parâmetros
    if (!inviteArgs || !inviteArgs.inviteArgs) {
        throw new Error('Missing required parameter: inviteArgs');
    }
    
    // Implementação interna:
    // 1. Gerar link de convite com parâmetros
    // 2. Abrir pop-up de convite (contém lista de amigos e opções de compartilhamento)
    // 3. Processar callback do resultado do convite
};

---