Configurazioni dell'esperienza

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

• Attiva o disattiva funzionalità, come abilitare o disabilitare un nuovo dungeon di onboarding.
• Regola i valori di gioco come la salute dei boss, l'acquisizione di esperienza o i prezzi degli oggetti.
• Avvia contenuti a tempo, come un evento di Halloween che inizia a mezzanotte.

Le configurazioni assumono la forma di chiavi e valori. Anziché utilizzare costanti codificate nel tuo codice, puoi utilizzare la chiave per ottenere un valore (stringa, numero, booleano o oggetto JSON) e poi aggiornare quel valore ogni volta che vuoi senza pubblicare una nuova versione della tua esperienza. Le modifiche al codice necessarie 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 aiutare te 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 della 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 non le utilizzi all'interno del tuo codice.

Per ulteriori informazioni su come lavorare con le configurazioni nei tuoi script, vedi 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 delle configurazioni 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 disponibile pubblicamente. Le modifiche in fase di preparazione sono disponibili per te e il tuo team nelle sessioni di gioco in Studio, non per i giocatori nelle esperienze dal vivo. La pagina Configurazioni su Creator Hub mostra tutte le modifiche attive e in fase di preparazione.

1. Dopo aver testato le modifiche in fase di preparazione, fai clic su Pubblica ora per pubblicare a tutti i giocatori entro cinque minuti. Puoi anche scegliere Pubblica in 15 min se preferisci un periodo di distribuzione più lungo.
2. (Consigliato) Aggiungi un messaggio di pubblicazione descrittivo che indichi cosa hai aggiornato. Questo messaggio appare nella pagina Cronologia e può aiutare te e il tuo team a identificare in seguito lo scopo della modifica.

Crea e modifica configurazioni in Studio

Se preferisci, puoi creare, modificare, mettere in fase di preparazione e pubblicare configurazioni in Roblox Studio. Fai clic su File > Apri Configurazioni. L'interfaccia di Studio è particolarmente conveniente per mettere in fase di preparazione e testare nuovi valori.

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 mettere in fase di preparazione il valore "prima". Tieni presente che ripristinare una configurazione scarta 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 momento attuale. Ci sono due metodi per ottenere un'istantanea:

• ConfigService:GetConfigAsync() è per configurazioni globali che vuoi 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.

Aggiorna le istantanee

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

Per ottenere manualmente i valori più recenti, usa 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 un'istantanea, 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 stato caricato in precedenza, ConfigService:GetConfigAsync() restituisce un'istantanea con i valori disponibili più recenti. Queste istantanee cercano di riconnettersi e attivano l'evento UpdateAvailable quando riescono a caricare 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 l'istantanea si riconnetta, o qualche altra soluzione.

Testa configurazioni

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

Per impostare un valore di test locale, chiama ConfigService:SetTestingValue() da uno script server o tramite la Console per sviluppatori. Le modifiche ai valori di test attivano un aggiornamento della configurazione insieme al segnale ConfigSnapshot.UpdateAvailable. Proprio come un aggiornamento di produzione, devi aggiornare le istantanee 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 dell'attuale server e non si propagano ad altri server. In Studio, si applicano alla sessione di gioco corrente e non influiscono sui server dal vivo. Puoi cancellare manualmente le modifiche di test con ConfigService:ClearTestingValue().