I weak_map di Verse si puliscono automaticamente in UEFN quando un player abbandona?

Se vi fidate del vostro assistente di programmazione IA quando vi dice che Verse elimina automaticamente i dati del player da una weak_map nell'esatto millisecondo in cui si disconnette dalla vostra isola Fortnite, vi state preparando a un grave crash a runtime. L'affermazione sembra logica: trattandosi di un riferimento debole (weak reference), l'engine dovrebbe pulire la chiave una volta che l'oggetto player viene elaborato dal Garbage Collection. Ma in Unreal Editor for Fortnite (UEFN), la realtà è molto più complessa, e non comprendere come il memory manager di Verse gestisca il ciclo di vita dei player porta a leak di stato silenziosi e a eccezioni che compromettono il funzionamento del gioco.

Quando un player abbandona la sessione, fare riferimento al suo oggetto obsoleto (stale) in una mappa può scatenare il temuto ErrRuntime_WeakMapInvalidKey o causare crash dell'intera isola, richiedendo l'implementazione di un rigido UEFN server crash fix protocol per mantenere stabili i server. Per evitare questo, i developer devono comprendere come Verse gestisce internamente la memoria e come implementare routine di cleanup autorevoli.

L'equivoco: consigli generati dall'IA vs. la realtà di Verse

Molti developer chiedono ai propri assistenti IA come gestire i dati della mappa di un player quando questo abbandona un match. Un consiglio comune generato dall'IA è che l'engine tratti la chiave del player come un "weak reference" ed elimini automaticamente l'entry del player dalla mappa al momento della disconnessione. Questo è fondamentalmente errato.

Sebbene la weak_map(player, t) di Verse utilizzi sotto la scocca dei weak reference come chiavi per prevenire cicli di riferimenti forti (hard reference) che bloccherebbero il Garbage Collection, non esegue una pulizia automatica e immediata delle entry della mappa stesse. L'entry — che contiene sia lo slot della chiave sia i dati associati — rimane allocata all'interno del container della mappa.

Se il vostro codice tenta di accedere, valutare o mutare quella chiave dopo che il player ha abbandonato la sessione, il runtime di Verse proverà a dereferenziare un oggetto player nullo o non valido. Invece di gestire l'errore in modo controllato (failing gracefully), il runtime attiva un crash o solleva un'eccezione non intercettabile. Il sistema si aspetta che gestiate esplicitamente le transizioni del ciclo di vita dei player, piuttosto che affidarvi a una pulizia automatica.

Perché le weak map non eseguono la pulizia automatica delle entry dei player

Per capire perché questo accada, dobbiamo analizzare lo scopo di una weak_map in UEFN. A differenza dei normali ambienti di programmazione in cui le weak map fungono da cache di memoria transitorie, Verse utilizza weak_map(player, t) principalmente come custode per i dati persistenti dei player.

Persistenza tra le sessioni di gioco

Quando utilizzate una weak_map(player, t) dichiarata a livello di modulo (module scope), l'engine collega i valori al database cloud persistente di Epic. Se un player lascia la partita e ritorna tre giorni dopo, l'engine abbina il suo ID player con la chiave persistente della mappa per ripristinare i suoi progressi.

Se l'engine cancellasse automaticamente l'entry di un player dalla mappa nel momento in cui lascia il gioco, la mappa perderebbe tutti i dati persistenti. Livelli, valute personalizzate ed elementi sbloccati verrebbero azzerati ogni volta che un player si disconnette o subisce un timeout di rete. Pertanto, il database è architettato per mantenere intatte queste entry proprio perché sono destinate a sopravvivere alle disconnessioni.

Il ciclo di vita limitato degli oggetti player

Quando un player abbandona la partita, il suo oggetto sessione attivo nel playspace viene distrutto. Il riferimento fisico player mantenuto dal codice Verse diventa un handle inattivo (dead handle).

Dato che la chiave all'interno della mappa punta ora a un oggetto non valido e inattivo, interrogare la mappa con quel riferimento inattivo fallirà. L'engine non esegue una scansione attiva per ripulire le chiavi inattive in tempo reale. Al contrario, le lascia inerti, ed è per questo che la gestione manuale è obbligatoria per evitare l'accumulo di riferimenti obsoleti (stale).

Le conseguenze: memory leak, dati obsoleti e crash dei server

La mancata pulizia delle entry dei player comporta tre problemi distinti che degradano le prestazioni del gioco e la stabilità del server nel corso di partite lunghe.

• Leak di dati obsoleti (stale data): Se un player abbandona e un altro si unisce alla partita, il nuovo player potrebbe ereditare i dati di sessione del vecchio player se l'engine riutilizza gli slot interni dei player. Ciò porta a bug di stato, come nuovi player che effettuano lo spawn con l'inventario pieno o statistiche di gioco errate.
• Accumulo di memoria: Sebbene un singolo booleano o intero occupi uno spazio trascurabile, memorizzare strutture complesse per un massimo di 50 player in una lobby ad alta capacità può aumentare l'uso della memoria. Nel corso di una sessione server di 4 ore, questo accumulo può degradare i tick rate del server.
• Errori di look-up: Tentare di interrogare lo stato di un player inattivo o chiamare funzioni su un riferimento player inattivo scatena crash immediati a runtime.

Raggiungimento dei limiti di salvataggio cloud di Epic

UEFN impone limiti rigidi sui dati persistenti. Siete limitati a un massimo di 4 weak_map persistenti per isola, e la dimensione del record individuale di ciascun player non può superare i 256 KB di dati.

Se utilizzate una weak_map persistente per memorizzare stati di sessione temporanei, state sprecando questo prezioso spazio del database. Ogni aggiornamento scrive sul database di Epic, rischiando penalità di write-throttling o di superare il limite di 256 KB, cosa che attiva un errore a runtime quando si tenta di scrivere ulteriori dati.

Tutorial passo-passo: gestire in sicurezza gli stati di sessione dei player

Per gestire gli stati dei player senza rischiare memory leak o un sovraccarico del database, dovete separare i dati di sessione transitori dai dati cloud persistenti. I dati transitori dovrebbero essere memorizzati in mappe standard non persistenti, che dovrete pulire manualmente al momento della disconnessione dei player.

Step 1: Definire la struct dello stato della sessione

Iniziate definendo una struct non persistibile che contenga tutte le variabili di cui il vostro player ha bisogno durante un singolo round o match. Non contrassegnate questa classe o struct come <persistable>.

# Define the transient data structure for active gameplay tracking
player_session_state := struct:
    IsMoneyBagFull : logic = false
    CurrentGold : int = 0
    SpawnTime : float = 0.0

Step 2: Configurare il Manager Device

Create un creative device che funga da coordinatore. Conterrà una mappa mutabile e non persistente dei player attivi. Poiché le mappe standard in Verse sono immutabili, dichiariamo la variabile mappa come var in modo da poterla sovrascrivere quando i player si uniscono o abbandonano la sessione.

using { /Fortnite.com/Devices }
using { /Fortnite.com/Playspaces }
using { /Verse.org/Simulation }

# Device handling player lifecycle events and session state mapping
state_manager_device := class(creative_device):

    # Non-persistent map for tracking active player sessions
    var SessionStates : [player]player_session_state = map{}

Step 3: Sottoscrivere gli eventi del Playspace

Nella funzione OnBegin, effettuate la sottoscrizione agli eventi di connessione del playspace. Questo vi assicura di eseguire il codice di inizializzazione quando un player si unisce, e il codice di cleanup quando abbandona.

    OnBegin<override>()<suspends>:void=
        GetPlayspace().PlayerAddedEvent().Subscribe(OnPlayerAdded)
        GetPlayspace().PlayerRemovedEvent().Subscribe(OnPlayerRemoved)
        
        # Initialize any players already in the session (useful for UEFN hot-reloading)
        for (Player : GetPlayspace().GetPlayers()):
            OnPlayerAdded(Player)

Step 4: Implementare la logica di registrazione e di cleanup

Quando un player si unisce, popolate la mappa con il suo stato di sessione predefinito. Quando abbandona, dovete eliminare la sua entry dalla mappa. Poiché Verse non dispone di una funzione integrata Map.Remove(), dovete ricostruire la mappa, filtrando il player che sta uscendo. Questo impedisce ai riferimenti obsoleti (stale) di rimanere in memoria.

    # Triggered when a player connects to the server
    OnPlayerAdded(Player: player):void=
        if (not SessionStates[Player]):
            InitialState := player_session_state{IsMoneyBagFull := false, CurrentGold := 0, SpawnTime := GetEngineTime()}
            if (set SessionStates[Player] = InitialState):
                Print("Initialized gameplay state for joining player.")

    # Triggered when a player disconnects or leaves the game
    OnPlayerRemoved(Player: player):void=
        Print("Player disconnected. Initiating map cleanup.")
        RemovePlayerSession(Player)

    # Purges the player's entry by reconstructing the map
    RemovePlayerSession(PlayerToRemove: player):void=
        var CleanedStates : [player]player_session_state = map{}
        for (ActivePlayer -> State : SessionStates):
            # Copy all players except the one who left
            if (ActivePlayer <> PlayerToRemove):
                if (set CleanedStates[ActivePlayer] = State):
                    # Entry successfully migrated to the cleaned map
        
        set SessionStates = CleanedStates
        Print("Successfully removed player session entry from memory.")

Ricostruendo la mappa alla rimozione del player, eliminate completamente la chiave di riferimento. Il Garbage Collector potrà quindi reclamare le risorse del player senza lasciare entry obsolete (stale) nel vostro game loop.

Se desiderate tracciare telemetria personalizzata durante queste transizioni del ciclo di vita, dovrete tenere conto di limiti come il limite di 32 caratteri per i nomi degli eventi analitici in Verse quando inviate report sulla durata delle sessioni o statistiche sulle valute a dei backend esterni.

Best practice per la gestione dello stato in Verse

Per garantire che i vostri server UEFN rimangano stabili e performanti, seguite queste linee guida per la gestione dei dati dei player:

1. Distinguere tra dati di sessione e dati persistenti: Non memorizzate mai variabili a breve termine (come la salute nel match corrente, il punteggio del round o le posizioni temporanee) in una weak_map persistente. Mantenete gli stati transitori in una mappa mutabile standard racchiusa all'interno di una classe manager.
2. Verificare l'attività del player con IsActive: Prima di recuperare o modificare i dati di un player in qualsiasi mappa, verificate se sia ancora presente nel playspace utilizzando la query IsActive[]. Se IsActive[] restituisce false, annullate il look-up e attivate un evento di cleanup.
3. Monitorare le dimensioni dei dati con FitsInPlayerMap: Quando scrivete in una weak_map persistente, chiamate FitsInPlayerMap() per verificare che l'aggiornamento non superi il limite di 256 KB, evitando eccezioni a runtime.
4. Consolidare le mappe: Non create mappe separate per ciascuna variabile. Definite una singola classe contenente tutte le variabili del player e mappate il player a tale classe. Questo riduce al minimo il numero complessivo di mappe e rispetta il limite per isola di quattro weak map persistenti.

Trasferire la complessità su un cloud backend affidabile

Gestire i cicli di vita delle sessioni dei player, i limiti del database e la logica di cleanup manuale in Verse può diventare rapidamente complesso. Se dovete creare progressioni tra sessioni diverse, inventari sincronizzati a livello globale o Matchmaking regionale, gestire questi stati manualmente richiede la configurazione di webhook, lo scaling di database esterni e la gestione della sincronizzazione server-to-server.

Con horizOn, queste sfide di backend vengono gestite automaticamente. Integrando l'SDK di horizOn nel vostro game server, potete delegare la gestione delle sessioni dei player a un database cloud dedicato. Quando un player si disconnette, horizOn avvia un cleanup automatico della sessione, aggiorna i database globali e sincronizza i record dell'inventario tra le istanze dei server, senza rischiare di raggiungere i limiti di memoria di 256 KB di Verse o causare crash a runtime.

Siete pronti a scalare il vostro backend UEFN? Provate horizOn gratuitamente o consultate la documentazione delle API.

---

Source: When using weak maps, does a player's entry in the map automatically get removed on them leaving the game?