Pacchetto Missioni

Questo pacchetto di funzionalità è in beta.

Il pacchetto di funzionalità Missioni offre funzionalità pronte all'uso per creare missioni che i giocatori possono completare per ottenere ricompense e progredire nella tua esperienza. Tutte le missioni devono avere un ID, una categoria e un elenco di compiti che i giocatori devono completare per terminare la missione. Tuttavia, l'elenco dei compiti può essere vuoto, consentendo di reclamare immediatamente le ricompense della missione.

Utilizzando le opzioni di personalizzazione del pacchetto, puoi personalizzare tutte le missioni per soddisfare i tuoi requisiti di gameplay unici, come ad esempio:

Creare missioni che introducano i nuovi giocatori alla tua esperienza e migliorino il tasso di ritenzione D1.
Mirare alla ritenzione D7 e D30 aggiungendo obiettivi a medio e lungo termine e un senso di progressione.
Aumentare il coinvolgimento mettendo in evidenza i vari sistemi nel tuo gioco e premiando i giocatori per interagire con essi.

Per informazioni su come fornire ai giocatori nuovi obiettivi e incentivi affinché siano motivati a giocare più a lungo e aumentare il loro coinvolgimento, consulta Introduzione al Design delle Missioni.

Ottieni il pacchetto

Il Creator Store è una scheda del Toolbox che puoi utilizzare per trovare tutti gli asset realizzati da Roblox e dalla community di Roblox per l'uso nei tuoi progetti, inclusi modelli, immagini, mesh, audio, plugin, video e font. Puoi utilizzare il Creator Store per aggiungere uno o più asset direttamente in un'esperienza aperta, inclusi i pacchetti di funzionalità!

Ogni pacchetto di funzionalità richiede il pacchetto di funzionalità Core per funzionare correttamente. Una volta che gli asset del pacchetto di funzionalità Core e Missioni sono all'interno del tuo inventario, puoi riutilizzarli in qualsiasi progetto sulla piattaforma.

Per ottenere i pacchetti dal tuo inventario nella tua esperienza:

Aggiungi il Core e le Missioni al tuo inventario all'interno di Studio facendo clic sul link Aggiungi all'Inventario nel seguente set di componenti.

Pacchetto di Funzionalità Core
Il pacchetto di funzionalità Core offre logica del negozio dati condivisa per tutti i pacchetti di funzionalità.
Pacchetto di Funzionalità Missioni
Il pacchetto di funzionalità Missioni offre funzionalità per creare missioni che i giocatori possono completare per ottenere ricompense e progredire nella tua esperienza.
Dal menu Finestra di Studio o dalla barra degli strumenti della scheda Home, apri il Toolbox.
Nella finestra Toolbox, fai clic sulla scheda Inventario. Il filtro I Miei Modelli viene visualizzato.
Fai clic sul riquadro Pacchetto di Funzionalità Core, quindi sul riquadro Pacchetto di Funzionalità Missioni. Entrambe le cartelle del pacchetto vengono visualizzate nella finestra Explorer.
Trascina le cartelle del pacchetto in ReplicatedStorage.

Definire le missioni

Ogni missione completabile include un insieme di compiti che devono essere terminati per completare la missione, opzioni di configurazione e metadati di visualizzazione facoltativi, tutti i quali possono essere definiti all'interno di ReplicatedStorage.Missions.Configs.Missions, con i tipi esportati dallo script Types nella stessa cartella.

Campi richiesti

I seguenti campi sono richiesti per ciascuna missione.

Nome	Tipo	Descrizione
missionId	string	La chiave principale della tabella Missioni. Tutte le missioni sono identificate dalla loro stringa unica.
categoryId	string	Le missioni devono appartenere a una categoria e sono raggruppate per categoria nell'interfaccia utente.
tasks	table	Un elenco di compiti che il giocatore deve completare per portare a termine la missione.

Condizioni di sblocco

Per impostazione predefinita, le missioni vengono sbloccate per i giocatori automaticamente e possono essere completate una sola volta. Tuttavia, puoi utilizzare le seguenti opzioni di configurazione opzionali per modificare questo comportamento.

Nome	Tipo	Descrizione
prerequisites	table	Un elenco di altri missionId che devono essere completati prima che la missione possa essere sbloccata.
manualOnly	bool	Disattiva lo sblocco automatico della missione. Invece, deve essere chiamata una funzione per sbloccare la missione. Anche altre condizioni di sblocco devono comunque essere soddisfatte.
availableAfterUtc	bool	La missione non può essere sbloccata prima dell'orario specificato in UTC.
availableBeforeUtc	bool	La missione non può essere sbloccata dopo l'orario specificato in UTC. Se è stata sbloccata ma non completata prima di questo orario, la missione verrà considerata fallita.
repeatable	bool	La missione diventa nuovamente sbloccata dopo essere stata completata.
repeatLimit	number	Se la missione è ripetibile, non può essere ripetuta più di questo numero di volte.
repeatCooldownSeconds	number	Se la missione è ripetibile, c'è un ritardo prima che diventi sbloccata.
expireSeconds	number	Se la missione è sbloccata e non completata entro il numero specificato di secondi, allora fallirà invece.
expireCountOffline	bool	Se la missione ha expireSeconds e expireCountOffline è impostato su true, il tempo in cui il giocatore non è effettivamente nell'esperienza conterà verso la scadenza della missione.

Metadati

Le missioni hanno metadati che specificano come verranno visualizzate nell'interfaccia utente delle Missioni. Puoi utilizzare i seguenti campi opzionali per personalizzare i suoi metadati.

Nome	Tipo	Descrizione
displayName	string	Un nome da visualizzare per la missione nell'interfaccia utente invece di missionId.
description	string	Un blocco di testo più lungo che fornisce informazioni aggiuntive o contesto sulla missione.
visibleAfterComplete	bool	Se impostato su true, la missione apparirà nell'elenco delle missioni anche dopo essere stata completata, ma contrassegnata come completata.
visibleAfterFailed	bool	Se impostato su true, la missione apparirà nell'elenco delle missioni anche dopo essere fallita, ma contrassegnata come fallita.
visibleBeforeUnlocked	bool	Se impostato su true, la missione sarà visibile ma bloccata nell'elenco delle missioni prima di essere disponibile per la completamento.
invisibleWhileActive	bool	Se impostato su true, la missione sarà invisibile anche mentre è attivamente in corso.
rewards	table	Un elenco di informazioni sulla visualizzazione delle ricompense. assetID (number) - L'ID dell'immagine che viene visualizzato nell'interfaccia utente delle missioni sotto le ricompense per una missione. Questo è richiesto se è presente una ricompensa. displayName (string) - Il nome che viene visualizzato nell'interfaccia utente delle missioni sotto l'icona.

Definire i compiti

Ogni missione può avere zero o più compiti. Se una missione ha zero compiti, è reclamabile immediatamente dopo essere stata sbloccata; se una missione ha uno o più compiti, una volta completati i compiti, il giocatore può raccogliere eventuali ricompense associate alla missione. Ogni compito ha un taskId, che è la chiave associata al compito per una determinata missione.

I compiti possono essere di due tipi:

Compiti Temporizzati - Ti consente di avviare e fermare il compito in momenti diversi. Deve passare un certo intervallo di tempo mentre il timer del compito è in esecuzione, quindi il compito è completato.
Compiti di Conteggio - Ti consente di aggiungere o impostare il progresso del compito. Quando il progresso raggiunge un valore impostato, il compito è completo.

Entrambi i tipi di compiti condividono i seguenti campi:

Nome	Tipo	Descrizione
taskType	string	Specifica se il tipo di compito è di conteggio o temporizzato.
counter	object	(Opzionale) Il contatore che questo compito tiene traccia. I contatori sono memorie persistenti specifiche per il giocatore per un numero o un timer. Più compiti possono tenere traccia di un singolo contatore; ad esempio, se più compiti tracciano quanti gettoni un giocatore ha raccolto, possono condividere lo stesso contatore "getttoni". Questi compiti possono tenere autonomamente traccia dei nuovi gettoni raccolti, partendo da zero, o continuare a contare dal valore del contatore (tutti i gettoni già raccolti). counterId (string) - L'ID del contatore da tenere traccia. Usa questo ID per ottenere o impostare il valore del contatore. continueFromCounter (Opzionale bool) - Se impostato su true, il progresso del compito corrisponderà direttamente al valore del contatore piuttosto che all'ammontare che è aumentato.
metadata	object	(Opzionale) Informazioni su come il compito viene visualizzato nell'interfaccia utente. displayName (string) - Nome del compito, utilizzato quando viene mostrato nell'interfaccia utente. numericType (Opzionale string) - come dovrebbe essere visualizzato il numero di progresso nel compito. Frazi, es. 5/10 o 5k/50k Percentuale, es. 50% o 10% LongFraction, es. 5/10 o 5000/50000 Booleano, es. Incompleto
callToAction	object	(Opzionale) Un pulsante che attiva una funzione di callback. callback (function) - Funzione attivata dal pulsante callToAction. buttonText (string) - Il testo che viene visualizzato nell'interfaccia utente del pulsante.

Campi dei compiti di conteggio

I compiti di conteggio hanno un valore richiesto. Quando il progresso del compito soddisfa questa quantità, il compito è completato.

Nome	Tipo	Descrizione
goalCount	number	(Opzionale) Il progresso richiesto per completare il compito.

Campi dei compiti temporizzati

I compiti temporizzati hanno un obiettivo di tempo trascorso, e possono essere avviati e fermati. Quando l'obiettivo di tempo è raggiunto, il compito è completato.

Nome	Tipo	Descrizione
goalSeconds	number	Il numero di secondi che devono passare per completare il compito.
startImmediately	bool	Se il compito dovrebbe iniziare a conteggiare il tempo non appena viene sbloccato, piuttosto che solo dopo essere stato avviato.
includesOfflineTime	bool	Se il compito dovrebbe includere il tempo speso mentre il giocatore non è attivamente nell'esperienza.

Configura le categorie

Le categorie non devono essere esplicitamente definite per essere utilizzate, poiché la categoria per una missione ha valori predefiniti che verranno utilizzati. Tuttavia, puoi configurare questi valori in ReplicatedStorage.Missions.Configs.Categories per aggiungere effetti aggiuntivi alla categoria. Le categorie sono identificate da CategoryIds unici, uguali a quelli referenziati nelle configurazioni delle missioni.

Nome	Tipo	Descrizione
repeatDelaySeconds	number	(Opzionale) Se impostato, tutte le missioni nella categoria vengono reimpostate ogni volta che passa il tempo specificato e possono essere sbloccate, completate e le loro ricompense reclamarle di nuovo. Questo è separato dalle missioni ripetibili, che sono ripetibili all'interno di una data ripetizione della categoria.

Integra la logica del server

Dai un'occhiata a ReplicatedStorage.Missions.Server.Examples.MissionsExample, che mostra come il tuo server interagirà con il pacchetto di funzionalità Missioni.

Devi principalmente collegare quattro cose una volta trascinato il pacchetto di funzionalità Missioni nella tua esperienza:

Definisci le missioni nella tua configurazione delle missioni.

Aggiungi logica alla tua esperienza per aggiornare il progresso dei compiti o i contatori a cui è legato il progresso.

README
-- Aumenta il progresso di una missione Jumping con un compito Jumps
Missions.addProgressToTask(player, "Jumping", "Jumps", 1)

-- Avvia il timer su una missione BattlingTime con un compito TimeInBattle
Missions.startTimedTask(player, "BattlingTime", "TimeInBattle")

-- Ferma il timer su una missione BattlingTime con un compito TimeInBattle
Missions.stopTimedTask(player, "BattlingTime", "TimeInBattle")

-- Aumenta il progresso su tutti i compiti legati al contatore Jumps
CounterSystem.addCounter(player, "Jumps", 1)

-- Avvia il timer su tutti i compiti temporizzati legati al contatore TimeInBattle
CounterSystem.startTimer(player, "TimeInBattle")

-- Ferma il timer su tutti i compiti temporizzati legati al contatore TimeInBattle
CounterSystem.stopTimer(player, "TimeInBattle")

Imposta gestori di completamento delle missioni e, facoltativamente, gestori di sblocco o fallimento. Utilizza il gestore di completamento per premiare i ricompense della missione nella tua esperienza.

README
local function completeHandler(player: Player, missionId: Types.MissionId)
     print(`{player} ha completato la missione {missionId}`)
     -- Premia il giocatore con le sue ricompense.
 end

Missions.setCompletionHandler(missionId, completeHandler)

Sblocca le missioni che non sono sbloccate automaticamente. La logica del pacchetto di funzionalità Missioni garantisce che tutti i requisiti della missione siano soddisfatti prima che la missione sia completata e le sue ricompense siano collezionabili.
```
README
Missions.unlockMission(player, "Manual")
```

Configura le costanti

Le costanti per il pacchetto di funzionalità Core risiedono in due luoghi:

Le costanti condivise risiedono in ReplicatedStorage.FeaturePackagesCore.Configs.SharedConstants.
Le costanti specifiche per il pacchetto, in questo caso il pacchetto di funzionalità Missioni, risiedono in ReplicatedStorage.Missions.Configs.Constants.

Inoltre, puoi trovare le stringhe per la traduzione suddivise in un'unica posizione: ReplicatedStorage.FeaturePackagesCore.Configs.TranslationStrings.

Personalizza i componenti dell'interfaccia utente

Modificando gli oggetti del pacchetto, come colori, font e trasparenza, puoi regolare la presentazione visiva della tua interfaccia utente delle missioni. Ad esempio, in ReplicatedStorage.Missions.Configs.Constants, puoi abilitare SingleTaskMode per visualizzare una barra di avanzamento per un compito direttamente sulla missione stessa per le missioni che hanno un solo compito.

Se sposti uno qualsiasi degli oggetti in modo gerarchico, il codice non sarà in grado di trovarli, e dovrai apportare modifiche in MissionsUI.

Inoltre, se la tua esperienza ha già un'interfaccia utente esistente con cui desideri integrare il pacchetto di funzionalità Missioni, il modulo client ModuleScript MissionsClient contiene tutte le funzioni necessarie per inviare le informazioni sulle missioni di un giocatore dal server.

Pacchetto di Funzionalità Core

Pacchetto di Funzionalità Missioni