Juego

El módulo de juego ofrece diversas funciones relacionadas con el juego. Después de leer la parte relacionada con tu motor de juego en la página Introducción a JOGOS_SDK, puedes usar las funciones correspondientes de la siguiente manera:

window.JOGOS_SDK.game;

Si necesitas completar operaciones de configuración como la adaptación del idioma de localización, adaptación del dispositivo y calibración del tiempo durante la fase de inicialización, puedes saltar a la página relacionada Inicialización (SysInfo) para ver definiciones de parámetros detalladas y métodos de configuración.

Pausa/Reanudación del juego

Cuando el juego se interrumpa (finalizar un nivel, pausar el juego, etc.), debes llamar al método de pausa del juego para informarnos que el juego ha sido pausado. No olvides llamar al método de reanudación del juego para informarnos que el juego ha continuado cuando se restablezca o continúe (restauración, resurrección, entrada al siguiente nivel, etc.). El SDK maneja automáticamente la pausa y reanudación durante la reproducción de anuncios, por lo que no es necesario llamarlos repetidamente.

// Informarnos que el juego ha sido pausado
await window.JOGOS_SDK.game.pause();
// Informarnos que el juego pausado ha continuado
await window.JOGOS_SDK.game.continuePlay();

Inicio/Fin de carga del juego

Cuando tu juego comience a cargar, debes llamar al método de inicio de carga para informarnos que el juego ha empezado a cargar. Una vez finalizada la carga, asegúrate de llamar al método de fin de carga para informarnos que el juego ha terminado de cargar.

// Informarnos que el juego ha comenzado a cargar
await window.JOGOS_SDK.game.loadingStart();
// Informarnos que la carga del juego ha terminado
await window.JOGOS_SDK.game.loadingEnd();

Cuando el juego comience a cargar, debes llamar al método de inicio de carga para informarnos que el juego ha empezado a cargar. Una vez finalizada la carga, debes llamar al método de fin de carga para informarnos que el juego ha terminado de cargar.

// Informarnos que el juego ha sido pausado
await window.JOGOS_SDK.game.pause();
// Informarnos que el juego ha continuado
await window.JOGOS_SDK.game.continuePlay();

Momento feliz

Este método puede llamarse cuando el jugador logre algún logro (derrotar a un Jefe, alcanzar una puntuación alta, etc.). Una llamada exitosa a este método activará acciones de celebración en el sitio web (por ejemplo, lanzar confeti). No es necesario llamar a este método al completar un nivel o obtener una recompensa.

// Activar el momento feliz del juego
await window.JOGOS_SDK.game.happytime();

Funciones de Amigos y Chat

Hemos integrado módulos de funciones sociales estandarizados, que cubren la gestión de relaciones de amistad y servicios de chat en tiempo real. Si tu juego soporta mecánicas de interacción multijugador, puedes integrarlos rápidamente a través de API ligeras para implementar: sincronización en la nube de la lista de amigos, invitación a equipo con un clic, conversaciones privadas y otros escenarios sociales fundamentales. Ayudamos a los desarrolladores a construir de manera eficiente un ecosistema social inmersivo dentro del juego con costos de desarrollo extremadamente bajos.

• Los desarrolladores, al utilizar estas funciones, deben pasar el UserId correspondiente del jugador en el lado de la plataforma como parámetro.

Verificación de Relación de Amistad

Verifica si un jugador especificado es amigo del usuario actual.

/**
 * Verifica si los jugadores especificados son mis amigos
 * @param {Array<number>} userIds Conjunto de IDs de jugador
 * @returns {Promise<Object>} { [userId: number]: boolean } Objeto par clave-valor
 */
window.JOGOS_SDK.game.isMyFriends = async function(userIds) {
    // Implementación interna
}

Explicación de la Lógica de Interacción de Amigos

Los desarrolladores deben implementar por sí mismos la lógica de visualización del botón según la relación de amistad:

1. Determinación del Estado del Botón: Utiliza la interfaz isMyFriends para verificar si un jugador especificado es amigo.
2. Lógica de Visualización del Botón:
   • Si es amigo: Muestra un botón "Conversación". Al hacer clic, llama a openChatDialog para iniciar un chat.
   • Si no es amigo: Muestra un botón "Añadir Amigo". Al hacer clic, llama a sendFriendRequest para enviar una solicitud de amistad.
3. Implementación del Botón: El estilo UI del botón, la posición y los efectos de interacción deben ser implementados por el desarrollador del juego.

Código de Ejemplo

// Ejemplo de implementación de un botón de interacción de amigo
async function setupFriendButton(userId, buttonElement) {
    try {
        // 1. Verifica la relación de amistad
        const friendStatus = await window.JOGOS_SDK.game.isMyFriends([userId]);
        const isFriend = friendStatus[userId];
        
        // 2. Configura el botón según la relación de amistad
        if (isFriend) {
            // Muestra botón de chat
            buttonElement.textContent = "Conversación";
            buttonElement.onclick = async () => {
                const success = await window.JOGOS_SDK.game.openChatDialog(userId);
                if (!success) {
                    alert("No se puede abrir la ventana de chat. Asegúrate de estar en el entorno de la plataforma oficial.");
                }
            };
        } else {
            // Muestra botón añadir amigo
            buttonElement.textContent = "Añadir Amigo";
            buttonElement.onclick = async () => {
                const success = await window.JOGOS_SDK.game.sendFriendRequest(userId);
                if (success) {
                    alert("Solicitud de amistad enviada.");
                } else {
                    alert("Error al enviar la solicitud de amistad.");
                }
            };
        }
        
        // 3. Agrega lógica para prevenir clics demasiado frecuentes
        let lastClickTime = 0;
        const originalClick = buttonElement.onclick;
        buttonElement.onclick = function() {
            const now = Date.now();
            if (now - lastClickTime < 3000) {
                console.log("Clics demasiado frecuentes. Inténtalo de nuevo más tarde.");
                return;
            }
            lastClickTime = now;
            originalClick.call(this);
        };
        
    } catch (error) {
        console.error("Error al configurar el botón de amigo:", error);
    }
}

Añadir Amigo

Envía una solicitud de amistad a un jugador especificado.

/**
 * Envía una solicitud de amistad a un jugador especificado
 * @param {number} userId ID del jugador objetivo
 * @returns {Promise<boolean>} Indica si la solicitud se envió con éxito
 */
window.JOGOS_SDK.game.sendFriendRequest = async function(userId) {
    // Implementación interna
}

Iniciar Chat

Abre la ventana de chat con un amigo especificado.

/**
 * Abre la ventana de chat con un jugador especificado
 * @param {number} userId ID del jugador objetivo
 * @returns {Promise<boolean>} Indica si se abrió con éxito
 */
window.JOGOS_SDK.game.openChatDialog = async function(userId) {
    // Implementación interna
}

Manejo de Casos Límite:

• Devuelve un fallo y muestra una alerta cuando no está integrado en la plataforma oficial: "La función de chat entre amigos solo está disponible en la plataforma oficial."
• El botón no se puede hacer clic nuevamente dentro de los 3 segundos posteriores a un clic.

Recordatorio Importante

Función de Chat Propia del Juego: Si el juego (juego en línea) tiene su propia función de chat, requerimos que los desarrolladores agreguen un filtro de palabras ofensivas y deshabiliten el chat según la configuración del juego. Si hay quejas, le pediremos que deshabilite el chat.

La Interfaz de Inicialización Devolverá Parámetros del Campo de Invitación

• La interfaz de inicialización del juego ahora incluye parámetros personalizados para invitar a otros a unirse al juego, como el ID de sala, el código de invitación, etc. Los desarrolladores pueden incluir estos parámetros al compartir enlaces de invitación. Cuando un jugador invitado ingresa al juego a través del enlace, el SDK pasará los parámetros al desarrollador para insertar al jugador en la sala correspondiente.

// Paso de parámetros de sala durante la inicialización del juego (Ejemplo)
const gameConfig = {
    inviteArgs: 'ABC123',       // Campo personalizado (ej. código de invitación/ID de sala)
    // Otras configuraciones del juego...
};

// Pasa los parámetros durante la inicialización del SDK
window.JOGOS_SDK.init({
    gameId: 'your_game_id',
    customParams: JSON.stringify(gameConfig)
});

Abrir Ventana de Invitar Amigos

• Cuando un usuario se encuentra en una posición dentro del juego donde es posible unirse a una nueva partida, esta función te permite colocar un botón "Invitar & Compartir" en la escena del juego.
• Al hacer clic en el botón se abre una ventana emergente que contiene un enlace de invitación, permitiendo seleccionar amigos a quienes enviar la invitación.
• El enlace de invitación transporta parámetros personalizados (como ID de sala/código de invitación, etc.). Cuando el jugador invitado hace clic en el enlace e ingresa al juego, el desarrollador puede analizar estos parámetros para insertar al jugador en la sala correspondiente.
• Al hacer clic en el botón "Invitar amigo" en la escena del juego, se abre una barra lateral con la lista de amigos para enviar mensajes de invitación a los amigos, admitiendo la entrada al juego mediante enlace o invitación directa.

/**
 * Abre la ventana de invitación
 * @param {Object} inviteArgs Objeto de parámetros de invitación
 * @param {string} inviteArgs.inviteArgs Parámetro de invitación personalizado (Obligatorio, ej. ID de sala o código de invitación)
 * @param {string} [inviteArgs.customData] Datos personalizados (se transmitirán al invitado)
 * @param {number} [inviteArgs.expireTime] Marca de tiempo de caducidad del enlace de invitación (milisegundos)
 */
window.JOGOS_SDK.game.openInviteDialog = function(inviteArgs) {
    // Validación de parámetros
    if (!inviteArgs || !inviteArgs.inviteArgs) {
        throw new Error('Falta el parámetro obligatorio: inviteArgs');
    }
    
    // Implementación interna:
    // 1. Genera enlace de invitación con parámetros
    // 2. Abre ventana emergente de invitación (incluye lista de amigos y opciones de compartir)
    // 3. Maneja devoluciones de llamada de resultado de invitación
};

---