Configurazioni dell'esperienza

Configurazioni dell'esperienza ti consentono di aggiornare i valori di gioco in tempo reale senza riavviare i server:

• Attiva e disattiva funzionalità, come abilitare o disabilitare un nuovo dungeon di onboarding.
• Regola i valori di gioco come la salute del boss, il guadagno di esperienza o i prezzi degli oggetti.
• Lancia contenuti a tempo, come un evento di Halloween che inizia a mezzanotte.

Le configurazioni assumono la forma di chiavi e valori. Invece di utilizzare costanti codificate nel tuo codice, puoi utilizzare la chiave per ottenere un valore (stringa, numero, booleano o oggetto JSON) e quindi aggiornare quel valore ogni volta che desideri senza pubblicare una nuova versione della tua esperienza. Le modifiche al codice richieste sono minime:

local ConfigService = game:GetService("ConfigService")
local configSnapshot = ConfigService:GetConfigAsync()
local myValue = configSnapshot:GetValue("my_key_name")

Puoi avere fino a 1.000 configurazioni attive in qualsiasi momento e gestirle su Creator Hub o in Roblox Studio.

Crea e modifica configurazioni

1. Nella pagina Configurazioni su Creator Hub per la tua esperienza, fai clic su Crea configurazione.

2. Specifica una chiave, un tipo, un valore e, facoltativamente, una descrizione per aiutarti o il tuo team a identificare in seguito lo scopo della configurazione. I tipi supportati sono stringa, numero, booleano e oggetto JSON.

3. Copia il frammento di codice generato in uno script server nella tua esperienza, probabilmente in ServerScriptService. Il codice dovrebbe apparire simile a questo:

   local ConfigService = game:GetService("ConfigService")
   
   local configSnapshot = ConfigService:GetConfigAsync()
   local MY_KEY = "my_key" -- facoltativo, memorizza la chiave di configurazione come costante
   local myValue = configSnapshot:GetValue(MY_KEY)

4. Usa il valore come faresti con qualsiasi altra variabile. Le configurazioni non fanno nulla a meno che tu non le utilizzi nel tuo codice.

Per ulteriori informazioni su come lavorare con le configurazioni nei tuoi script, consulta Aggiungi configurazioni al tuo codice.

Modificare una configurazione non è diverso dal crearne una. Fai clic sul pulsante Modifica e aggiorna il valore e la descrizione come desiderato.

Limiti

I valori di configurazione hanno i seguenti limiti per tipo.

Pubblica configurazioni

Dopo aver creato una configurazione, passa a uno stato in fase di preparazione in modo da poterla testare prima che diventi pubblicamente disponibile. Le modifiche in fase di preparazione sono disponibili per te e il tuo team nelle sessioni di gioco di Studio, non per i giocatori nelle esperienze live. La pagina Configurazioni su Creator Hub mostra tutte le modifiche attive e in fase di preparazione.

1. Dopo aver testato le tue modifiche in fase di preparazione, fai clic su Pubblica ora per pubblicare a tutti i giocatori quasi istantaneamente (circa tra 15 secondi e 1 minuto). Puoi anche scegliere Pubblica in 15 minuti se preferisci un periodo di distribuzione più lungo e graduale. In alcuni casi, i client potrebbero impiegare alcuni minuti per riflettere le modifiche dopo la pubblicazione.
2. (Consigliato) Aggiungi un messaggio di pubblicazione descrittivo che indichi cosa hai aggiornato. Questo messaggio appare nella pagina Cronologia e può aiutarti e il tuo team a identificare in seguito lo scopo della modifica.

Crea e modifica configurazioni in Studio

Se preferisci, puoi creare, modificare, preparare e pubblicare configurazioni in Roblox Studio. Fai clic su File > Apri Configurazioni per aprire il widget. L'interfaccia di Studio è particolarmente comoda per preparare e testare nuovi valori.

Pubblica configurazioni in un'altra esperienza

In Studio, puoi pubblicare le tue configurazioni in un'altra esperienza, sovrascrivendo completamente le configurazioni per quell'esperienza. Questo può essere particolarmente utile per sincronizzare le configurazioni da un'esperienza di staging o sviluppo all'esperienza live.

1. In Roblox Studio, vai al menu in alto e seleziona File > Apri Configurazioni.

2. Nella scheda Pubblicate del widget Configurazioni, fai clic sull'icona ⋮ e seleziona Pubblica come.

   

3. Nella finestra di dialogo che appare, trova e seleziona l'esperienza target dall'elenco dei gruppi in cui hai permessi di modifica.

   

Visualizza cronologia e ripristina configurazioni

Nella pagina Configurazioni, fai clic su Cronologia per vedere gli aggiornamenti passati. Ogni aggiornamento ha l'ora e la data della modifica, chi ha effettuato la modifica e il messaggio di pubblicazione.

• Espandi ogni riga per vedere la chiave, il valore prima della modifica e il valore dopo.
• Usa la casella Cerca Chiave per cercare chiavi, non descrizioni o valori, solo chiavi.

La pagina Cronologia ti consente anche di ripristinare le configurazioni a uno stato precedente:

1. Fai clic su Ripristina accanto alla modifica per preparare il valore "prima". Tieni presente che ripristinare una configurazione annulla eventuali modifiche in fase di preparazione esistenti.
2. Torna alla pagina Configurazioni e pubblica la configurazione.

Aggiungi configurazioni al tuo codice

La classe principale per lavorare con le configurazioni è ConfigService, che recupera le ultime chiavi e valori per la tua esperienza. ConfigService è disponibile solo per gli script server. Tentare di chiamare i suoi metodi da uno script client genera un errore.

Il primo passo per lavorare con le configurazioni è recuperare un ConfigSnapshot, i valori più recenti per tutte le configurazioni nel punto attuale nel tempo. Ci sono due metodi per ottenere uno snapshot:

• ConfigService:GetConfigAsync() è per configurazioni globali che desideri applicare a tutti i giocatori nell'esperienza:

  local ConfigService = game:GetService("ConfigService")
  local configSnapshot = ConfigService:GetConfigAsync()
  local bossHealth = configSnapshot:GetValue("bossHealth")

• ConfigService:GetConfigForPlayerAsync() è per esperimenti. Recupera configurazioni specifiche per il giocatore in modo che giocatori diversi possano ottenere valori diversi.

  local ConfigService = game:GetService("ConfigService")
  local Players = game:GetService("Players")
  
  local function onPlayerAdded(player)
      local playerConfigSnapshot = ConfigService:GetConfigForPlayerAsync(player)
      local bossHealth = playerConfigSnapshot:GetValue("bossHealth")
  end
  
  Players.PlayerAdded:Connect(onPlayerAdded)

In entrambi i casi, se la chiave non esiste, ConfigSnapshot:GetValue() restituisce nil.

Completamento automatico

Le configurazioni sono integrate nel completamento automatico dell'Editor di Script. Quando chiami ConfigSnapshot:GetValue(), l'editor suggerisce i nomi delle chiavi di configurazione e visualizza il tipo di ciascuna configurazione quando passi il mouse sopra il nome della variabile.

Se il tuo script utilizza la modalità --!strict, il linter può rilevare e verificare il tipo per te.

Il completamento automatico funziona anche con configurazioni che utilizzano tipi JSON complessi annidati.

Aggiorna snapshot

ConfigSnapshots rappresentano un punto nel tempo, lo stato della configurazione quando hai richiesto lo snapshot. Per evitare di interrompere il gioco, gli aggiornamenti a una configurazione non si propagano automaticamente agli snapshot. In uno sparatutto competitivo, ad esempio, potresti voler solo nuovi valori di configurazione tra i round in modo che gli attributi delle armi non fluttuino durante la partita.

Per ottenere i valori più recenti manualmente, utilizza il metodo ConfigSnapshot:Refresh(). Facoltativamente, collega una funzione all'evento ConfigSnapshot.UpdateAvailable per aggiornare automaticamente:

configSnapshot.UpdateAvailable:Connect(function()
    configSnapshot:Refresh()
end)

Dopo aver aggiornato uno snapshot, puoi utilizzare ConfigSnapshot:GetValueChangedSignal() per ascoltare le modifiche a una chiave specifica in modo da poter aggiornare il codice della tua esperienza:

configSnapshot:GetValueChangedSignal("bossHealth"):Connect(function(newHealthValue)
    spawnNewBoss(newHealthValue)
end)

Gestione degli errori

In rari casi in cui la configurazione non riesce a caricarsi e non è mai stata caricata prima, ConfigService:GetConfigAsync() genera un errore.

Se ConfigService perde la connessione ai server Roblox dopo essere stata precedentemente caricata, ConfigService:GetConfigAsync() restituisce uno snapshot con i valori più recenti disponibili. Questi snapshot tentano di riconnettersi e attivano l'evento UpdateAvailable quando caricano con successo nuovi aggiornamenti.

Come gestisci queste situazioni poco comuni dipende da te. Puoi racchiudere la chiamata in un pcall() e avere valori di fallback nel tuo codice, mostrare un errore al giocatore e attendere che lo snapshot si riconnetta, o qualche altra soluzione.

Testa le configurazioni

ConfigService ha metodi integrati per testare temporaneamente le modifiche alle configurazioni sia in Studio che sui server live senza influenzare l'intera esperienza.

Per impostare un valore di test locale, chiama ConfigService:SetTestingValue() da uno script server o tramite la Console Sviluppatore. Le modifiche ai valori di test attivano un aggiornamento della configurazione insieme al segnale ConfigSnapshot.UpdateAvailable. Proprio come un aggiornamento di produzione, devi aggiornare gli snapshot esistenti per ottenere il valore di test:

local ConfigService = game:GetService("ConfigService")
ConfigService:SetTestingValue("bossHealth", 200)

local configSnapshot = ConfigService:GetConfigAsync()
local bossHealth = configSnapshot:GetValue("bossHealth") -- Ora 200!

Le modifiche di test si applicano per la durata del server corrente e non si propagano ad altri server. In Studio, si applicano alla sessione di gioco corrente e non influenzano i server live. Puoi cancellare manualmente le modifiche di test con ConfigService:ClearTestingValue().