Caccia al Tesoro

La Caccia al Tesoro modulo per sviluppatori offre ai giocatori un modo intrinsecamente gamificato per esplorare la tua esperienza, introducendoli organicamente all'intero luogo. I progressi dei giocatori sono persistenti, quindi le cacce al tesoro possono continuare tra le sessioni.

Utilizzo del modulo

Installazione

Per utilizzare il modulo Caccia al Tesoro in un'esperienza:

1. Dal menu Finestra di Studio o dalla barra degli strumenti della scheda Home, apri il Toolbox e seleziona la scheda Creator Store.

   

2. Assicurati che sia selezionato l'ordinamento Modelli, quindi fai clic sul pulsante Vedi Tutti per le Categorie.

   

3. Trova e fai clic sulla tile Pacchetti.

4. Trova il modulo Caccia al Tesoro e fai clic su di esso, oppure trascinalo e rilascialo nella vista 3D.

   

5. Nella finestra Esplora, sposta l'intero modello Caccia al Tesoro in ReplicatedStorage. All'avvio dell'esperienza, il modulo inizierà a funzionare.

Utilizzare i token

Il modulo della caccia al tesoro utilizza token come oggetti che i giocatori cercano e raccolgono. Il modulo viene fornito con un modello di token che puoi posizionare nel mondo 3D.

1. Trova il mesh Token1 all'interno della cartella Workspace della cartella principale del modulo.

   

2. Sposta Token1 nella gerarchia Workspace di livello superiore e posizionalo dove desiderato.

3. Dai al token un nome unico; questo nome è il modo in cui il modulo tiene traccia dei token che ciascun giocatore ha raccolto.

4. Per aggiungere più token, duplica un token esistente e dagli un nome unico.

Se non desideri utilizzare i token mesh inclusi, qualsiasi Model o BasePart funzionerà, purché soddisfi i seguenti criteri:

• L'oggetto ha un tag CollectionService di ScavengerHuntPart. Se desiderato, il nome del tag CollectionService che il modulo utilizza può essere cambiato impostando un valore diverso per tokenTag in una chiamata configureServer.

• L'oggetto contiene un'istanza figlio di StringValue impostata sul "testo sapore" da visualizzare quando il token viene raccolto.

  

  

Utilizzare le regioni

Le regioni differiscono leggermente dai token, poiché sono aree ampie che vengono contrassegnate come "raccolte" una volta che il giocatore vi entra. Inoltre, quando un giocatore esce dalla regione, il modal del testo di sapore si chiude automaticamente e la regione stessa viene rimossa dallo spazio di lavoro.

1. Crea una parte ancorata attorno alla regione, come un blocco o una sfera. Il modulo disabiliterà automaticamente la proprietà CanCollide durante l'esecuzione in modo che i giocatori non possano collidere fisicamente con la regione.

2. Dagli un nome unico. Questo nome è il modo in cui il modulo tiene traccia delle regioni che ciascun giocatore ha visitato.

3. Utilizzando la sezione Tag delle proprietà della parte, applica il tag ScavengerHuntPart alla parte affinché CollectionService possa rilevarlo. Se desiderato, il nome del tag che il modulo utilizza può essere cambiato impostando un valore diverso per tokenTag in una chiamata configureServer.

4. Includi un'istanza figlio di StringValue impostata sul "testo sapore" da visualizzare quando la regione viene attraversata.

   

Configurazione

Il modulo è preconfigurato per funzionare nella maggior parte dei casi d'uso, ma può essere facilmente personalizzato. Ad esempio, per cambiare la velocità di rotazione dei token e personalizzare il messaggio informativo del modal:

1. In StarterPlayerScripts, crea un nuovo LocalScript e rinominalo in ConfigureScavengerHunt.

2. Incolla il seguente codice nel nuovo script.

   LocalScript - ConfigureScavengerHunt
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)
   
   ScavengerHunt.configureClient({
       infoModalText = "Benvenuto nella mia Caccia al Tesoro!",
       completeModalText = "Grazie per aver partecipato alla mia Caccia al Tesoro!",
       tokenRotationSpeed = 60,
   })

Eventi di raccolta

Ogni volta che un giocatore raccoglie un token o entra in una regione, l'evento collected viene attivato. Puoi ascoltare questo evento da uno Script lato server e rispondere di conseguenza. La funzione connessa riceve il Player che ha colliso con il token o è entrato nella regione e il nome di quel token o della regione.

Allo stesso modo, quando un giocatore raccoglie tutti i token o entra in tutte le regioni contrassegnate, l'evento allCollected viene attivato e la funzione connessa riceve il Player associato. Questa funzione viene attivata solo una volta per giocatore e può essere utilizzata per premiare quel giocatore con un badge, accesso a una nuova area, moneta in esperienza, ecc.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.collected:Connect(function(player, itemName)
   print(player.DisplayName, itemName)
end)

ScavengerHunt.allCollected:Connect(function(player)
   print(player.DisplayName .. " ha completato la caccia!")
end)

GUI personalizzato

Questo modulo espone diverse opzioni per personalizzare la sua GUI predefinita, ma puoi scegliere di visualizzare elementi GUI personalizzati invece.

Quando useCustomModals è impostato su true nella funzione configureClient, l'evento showInfoModal viene attivato ogni volta che il giocatore attiva il tracker dei token. Allo stesso modo, l'evento showCompleteModal viene attivato quando il giocatore ha raccolto tutto nella caccia al tesoro. Entrambi questi eventi possono essere ascoltati in uno LocalScript.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.showInfoModal:Connect(function()
   -- Mostra un modal informativo personalizzato
   local infoModal = Players.LocalPlayer.PlayerGui.ScavengerInfoModal
   infoModal.Enabled = true
end)

ScavengerHunt.showCompleteModal:Connect(function()
   -- Mostra un modal completo personalizzato
   local completeModal = Players.LocalPlayer.PlayerGui.ScavengerCompleteModal
   completeModal.Enabled = true
end)

Visibilità della GUI

Per impostazione predefinita, la caccia al tesoro nasconde tutte le ScreenGuis e CoreGuis (eccetto l'elenco dei giocatori) quando il modal informativo o il modal di completamento appare. Se desideri sovrascrivere questo comportamento di nascondimento automatico e decidere programmaticamente quali GUI dovrebbero rimanere visibili, includi i callback hideOtherGuis e showOtherGuis e rispondi con la tua logica personalizzata.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local StarterGui = game:GetService("StarterGui")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

local player = Players.LocalPlayer
local playerGui = player:WaitForChild("PlayerGui")
local hiddenInstances = {}

-- Crea una screen GUI che non verrà nascosta
local specialGuiInstance = Instance.new("ScreenGui")
-- Disegna la screen GUI sopra la GUI della caccia al tesoro
specialGuiInstance.DisplayOrder = 1
specialGuiInstance.Parent = playerGui
-- Aggiungi un'etichetta di testo alla GUI
local specialLabel = Instance.new("TextLabel")
specialLabel.Size = UDim2.fromScale(1, 0.1)
specialLabel.Text = "Resta visibile durante la visualizzazione dei modali"
specialLabel.Font = Enum.Font.GothamMedium
specialLabel.TextSize = 24
specialLabel.Parent = specialGuiInstance

ScavengerHunt.hideOtherGuis(function()
   -- Nascondi tutte le screen GUI definite dallo sviluppatore
   local instances = playerGui:GetChildren()
   for _, instance in instances do
       if instance:IsA("ScreenGui") and not instance.Name == "ScavengerHunt" and instance.Enabled then
           instance.Enabled = false
           table.insert(hiddenInstances, instance)
       end
   end
   -- Nascondi specifiche core GUI
   StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)
end)

ScavengerHunt.showOtherGuis(function()
   -- Mostra tutte le screen GUI definite dallo sviluppatore che erano nascoste
   for _, instance in hiddenInstances do
       instance.Enabled = true
   end
   hiddenInstances = {}
   -- Mostra specifiche core GUI che erano nascoste
   StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, true)
end)

Riferimento API

Funzioni

configureClient

Sovrascrive le opzioni di configurazione predefinite lato client attraverso le seguenti chiavi/valori nella tabella config. Questa funzione può essere chiamata solo da uno LocalScript.

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.configureClient({
   infoModalText = "Benvenuto nella mia Caccia al Tesoro!",
   completeModalText = "Grazie per aver partecipato alla mia Caccia al Tesoro!",
   tokenRotationSpeed = 60,
   navigationBeam = {
       lightEmission = 1
   },
   modal = {
       textSize = 14
   },
})

configureServer

Sovrascrive le opzioni di configurazione predefinite lato server attraverso le seguenti chiavi/valori nella tabella config. Questa funzione può essere chiamata solo da uno Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.configureServer({
   tokenTag = "GreenGem",
})

disable

Nasconde tutta l'interfaccia utente per la caccia al tesoro, disconnette tutti i listener per gli eventi di input e impedisce ai giocatori di raccogliere token o interagire con le regioni. Questa funzione può essere chiamata solo da uno Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.disable()

enable

Mostra tutta l'interfaccia utente per la caccia al tesoro, collega tutti i listener per gli eventi di input e consente ai giocatori di raccogliere token e interagire con le regioni. Questa funzione può essere chiamata solo da uno Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.enable()

Eventi

collected

Si attiva quando un giocatore collida con un token o entra in una regione. La funzione connessa riceverà il Player che ha colliso con il token o è entrato nella regione e il nome del token con cui è colliso o la regione che è stata attraversata. Questo evento può essere connesso solo in uno Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.collected:Connect(function(player, itemName, totalCollected)
   print(player.DisplayName, itemName, totalCollected)
end)

allCollected

Si attiva quando un giocatore raccoglie tutti i token o entra in tutte le regioni nella caccia al tesoro. La funzione connessa riceverà il Player che ha raccolto tutti i token e viene attivata solo una volta per giocatore. Questo evento può essere connesso solo in uno Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.allCollected:Connect(function(player)
   print(player.DisplayName .. " ha completato la caccia!")
end)

showInfoModal

Si attiva quando il giocatore fa clic sul tracker dei token quando l'opzione di configurazione useCustomModals è impostata su true. Questo evento può essere connesso solo in uno LocalScript.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.showInfoModal:Connect(function()
   local infoModal = Players.LocalPlayer.PlayerGui.InfoModal
   infoModal.Enabled = true
end)

showCompleteModal

Si attiva quando il giocatore fa clic sul tracker dei token quando l'opzione di configurazione useCustomModals è impostata su true e il giocatore ha raccolto tutti i token nella caccia al tesoro. Questo evento può essere connesso solo in uno LocalScript.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.showCompleteModal:Connect(function()
   local completeModal = Players.LocalPlayer.PlayerGui.CompleteModal
   completeModal.Enabled = true
end)

Callback

hideOtherGuis

Questo callback viene eseguito immediatamente prima che venga visualizzato un modal, consentendoti di disabilitare intere ScreenGuis o elementi al loro interno prima che il modal venga mostrato. Vedi Visibilità della GUI per dettagli e codice di esempio.

showOtherGuis

Questo callback viene eseguito immediatamente dopo che un modal è stato chiuso, consentendoti di abilitare intere ScreenGuis o elementi al loro interno. Vedi Visibilità della GUI per dettagli e codice di esempio.