Gioco

Il modulo di gioco offre varie funzionalità relative al gioco. Dopo aver letto la parte relativa al tuo motore di gioco nella pagina Introduzione a JOGOS_SDK, puoi utilizzare le funzionalità correlate come segue:

window.JOGOS_SDK.game;

Se hai bisogno di completare operazioni di configurazione come l'adattamento della lingua di localizzazione, l'adattamento del dispositivo e la calibrazione del tempo durante la fase di inizializzazione, puoi saltare alla pagina relativa Inizializzazione (SysInfo) per visualizzare definizioni dettagliate dei parametri e metodi di configurazione.

Sospensione/Ripresa del gioco

Quando il gioco viene interrotto (fine del livello, pausa del gioco, ecc.), è obbligatorio chiamare il metodo di sospensione del gioco per informarci che il gioco è stato sospeso. Non dimenticare di chiamare il metodo di ripresa del gioco per informarci che il gioco è stato ripreso quando questo viene ripristinato o continuato (ripristino, risurrezione, accesso al prossimo livello, ecc.). L'SDK gestirà automaticamente la sospensione e la ripresa durante la riproduzione degli annunci, quindi non è necessario chiamarli ripetutamente.

// Informaci che il gioco è stato sospeso
await window.JOGOS_SDK.game.pause();
// Informaci che il gioco sospeso è stato ripreso
await window.JOGOS_SDK.game.continuePlay();

Inizio/Fine caricamento del gioco

Quando il tuo gioco inizia a caricare, è obbligatorio chiamare il metodo di inizio caricamento per informarci che il gioco ha iniziato a caricare. Dopo il termine del caricamento, assicurati di chiamare il metodo di fine caricamento per informarci che il gioco ha completato il caricamento.

// Informaci che il gioco ha iniziato a caricare
await window.JOGOS_SDK.game.loadingStart();
// Informaci che il caricamento del gioco è stato completato
await window.JOGOS_SDK.game.loadingEnd();

Quando il gioco inizia a caricare, è obbligatorio chiamare il metodo di inizio caricamento per informarci che il gioco ha iniziato a caricare; dopo il termine del caricamento, è obbligatorio chiamare il metodo di fine caricamento per informarci che il gioco ha completato il caricamento.

// Informaci che il gioco è stato sospeso
await window.JOGOS_SDK.game.pause();
// Informaci che il gioco è stato ripreso
await window.JOGOS_SDK.game.continuePlay();

Momento felice

Questo metodo può essere chiamato quando il giocatore raggiunge un determinato traguardo (sconfiggere un Boss, raggiungere un punteggio alto, ecc.). Una chiamata riuscita a questo metodo attiverà azioni di celebrazione sul sito web (ad esempio, lanciare dei coriandoli). Non è necessario chiamare questo metodo quando si completa un livello o si riceve un premio.

// Attivare il momento felice del gioco
await window.JOGOS_SDK.game.happytime();

Funzionalità Amici e Chat

Abbiamo integrato moduli di funzionalità social standardizzati, che coprono la gestione delle relazioni di amicizia e i servizi di chat in tempo reale. Se il tuo gioco supporta meccaniche di interazione multiplayer, puoi integrarli rapidamente tramite API leggere per implementare: sincronizzazione cloud della lista amici, invito a squadra con un clic, conversazioni private e altri scenari sociali fondamentali. Aiutiamo gli sviluppatori a costruire in modo efficiente un ecosistema sociale immersivo all'interno del gioco con costi di sviluppo estremamente bassi.

• Gli sviluppatori, durante l'utilizzo, devono passare l'UserId corrispondente del giocatore sul lato piattaforma come parametro.

Controllo Relazione Amici

Controlla se un giocatore specificato è un amico dell'utente corrente.

/**
 * Controlla se i giocatori specificati sono miei amici
 * @param {Array<number>} userIds Insieme degli ID giocatore
 * @returns {Promise<Object>} { [userId: number]: boolean } Oggetto coppia chiave-valore
 */
window.JOGOS_SDK.game.isMyFriends = async function(userIds) {
    // Implementazione interna
}

Spiegazione Logica Interazione Amici

Gli sviluppatori devono implementare autonomamente la logica di visualizzazione del pulsante in base alla relazione di amicizia:

1. Determinazione Stato Pulsante: Utilizza l'interfaccia isMyFriends per verificare se un giocatore specificato è un amico.
2. Logica Visualizzazione Pulsante:
   • Se è un amico: Visualizza un pulsante "Conversazione". Al clic, chiama openChatDialog per avviare una chat.
   • Se non è un amico: Visualizza un pulsante "Aggiungi Amico". Al clic, chiama sendFriendRequest per inviare una richiesta di amicizia.
3. Implementazione Pulsante: Lo stile UI del pulsante, la posizione e gli effetti di interazione devono essere implementati dallo sviluppatore del gioco.

Codice Esempio

// Esempio di implementazione di un pulsante di interazione amico
async function setupFriendButton(userId, buttonElement) {
    try {
        // 1. Controlla la relazione di amicizia
        const friendStatus = await window.JOGOS_SDK.game.isMyFriends([userId]);
        const isFriend = friendStatus[userId];
        
        // 2. Imposta il pulsante in base alla relazione di amicizia
        if (isFriend) {
            // Visualizza pulsante chat
            buttonElement.textContent = "Conversazione";
            buttonElement.onclick = async () => {
                const success = await window.JOGOS_SDK.game.openChatDialog(userId);
                if (!success) {
                    alert("Impossibile aprire la finestra di chat. Assicurati di essere nell'ambiente della piattaforma ufficiale.");
                }
            };
        } else {
            // Visualizza pulsante aggiungi amico
            buttonElement.textContent = "Aggiungi Amico";
            buttonElement.onclick = async () => {
                const success = await window.JOGOS_SDK.game.sendFriendRequest(userId);
                if (success) {
                    alert("Richiesta di amicizia inviata.");
                } else {
                    alert("Invio richiesta di amicizia fallito.");
                }
            };
        }
        
        // 3. Aggiungi logica per prevenire clic troppo frequenti
        let lastClickTime = 0;
        const originalClick = buttonElement.onclick;
        buttonElement.onclick = function() {
            const now = Date.now();
            if (now - lastClickTime < 3000) {
                console.log("Clic troppo frequenti. Riprova più tardi.");
                return;
            }
            lastClickTime = now;
            originalClick.call(this);
        };
        
    } catch (error) {
        console.error("Impostazione pulsante amico fallita:", error);
    }
}

Aggiungi Amico

Invia una richiesta di amicizia a un giocatore specificato.

/**
 * Invia una richiesta di amicizia a un giocatore specificato
 * @param {number} userId ID giocatore target
 * @returns {Promise<boolean>} Indica se la richiesta è stata inviata con successo
 */
window.JOGOS_SDK.game.sendFriendRequest = async function(userId) {
    // Implementazione interna
}

Avvia Chat

Apre la finestra di chat con un amico specificato.

/**
 * Apre la finestra di chat con un giocatore specificato
 * @param {number} userId ID giocatore target
 * @returns {Promise<boolean>} Indica se è stata aperta con successo
 */
window.JOGOS_SDK.game.openChatDialog = async function(userId) {
    // Implementazione interna
}

Gestione dei Casi Limite:

• Restituisce un fallimento e visualizza un avviso quando non integrato nella piattaforma ufficiale: "La funzionalità chat amici è disponibile solo sulla piattaforma ufficiale."
• Il pulsante non può essere cliccato nuovamente entro 3 secondi dall'ultimo clic.

Promemoria Importante

Funzionalità Chat Propria del Gioco: Se il gioco (gioco online) ha la sua propria funzionalità di chat, richiediamo agli sviluppatori di aggiungere un filtro per le parole volgari e di disabilitare la chat in base alle impostazioni del gioco. In caso di segnalazioni, richiederemo la disattivazione della chat.

L'Interfaccia di Inizializzazione Restituirà i Parametri del Campo Invito

• L'interfaccia di inizializzazione del gioco ora include parametri personalizzati per invitare altri a unirsi al gioco, come l'ID stanza, il codice invito, ecc. Gli sviluppatori possono includere questi parametri quando condividono i link di invito. Quando un giocatore invitato entra nel gioco tramite il link, l'SDK passerà i parametri allo sviluppatore per inserire il giocatore nella stanza corrispondente.

// Passaggio parametri stanza durante l'inizializzazione del gioco (Esempio)
const gameConfig = {
    inviteArgs: 'ABC123',       // Campo personalizzato (es. codice invito/ID stanza)
    // Altre configurazioni del gioco...
};

// Passa i parametri durante l'inizializzazione dell'SDK
window.JOGOS_SDK.init({
    gameId: 'your_game_id',
    customParams: JSON.stringify(gameConfig)
});

Apri Finestra Invita Amici

• Quando un utente si trova in una posizione all'interno del gioco in cui è possibile unirsi a una nuova partita, questa funzionalità ti consente di posizionare un pulsante "Invita & Condividi" nella scena del gioco.
• Cliccando il pulsante si apre un popup contenente un link di invito, supportando la selezione di amici a cui inviare l'invito.
• Il link di invito trasporta parametri personalizzati (come ID stanza/codice invito, ecc.). Quando il giocatore invitato clicca sul link ed entra nel gioco, lo sviluppatore può analizzare questi parametri per inserire il giocatore nella stanza corrispondente.
• Cliccando il pulsante "Invita amico" nella scena del gioco si apre una barra laterale con l'elenco amici per inviare messaggi di invito agli amici, supportando l'ingresso nel gioco tramite link o invito diretto.

/**
 * Apre la finestra di invito
 * @param {Object} inviteArgs Oggetto parametri invito
 * @param {string} inviteArgs.inviteArgs Parametro invito personalizzato (Obbligatorio, es. ID stanza o codice invito)
 * @param {string} [inviteArgs.customData] Dati personalizzati (saranno trasmessi all'invitato)
 * @param {number} [inviteArgs.expireTime] Timestamp di scadenza link invito (millisecondi)
 */
window.JOGOS_SDK.game.openInviteDialog = function(inviteArgs) {
    // Validazione parametri
    if (!inviteArgs || !inviteArgs.inviteArgs) {
        throw new Error('Parametro obbligatorio mancante: inviteArgs');
    }
    
    // Implementazione interna:
    // 1. Genera link invito con parametri
    // 2. Apri popup invito (include elenco amici e opzioni di condivisione)
    // 3. Gestisci callback risultati invito
};

---