Chasse aux trésors

Le module de développement ScavengerHunt offre aux joueurs un moyen de manière intrinsèque et gamifiée d'explorer votre expérience, en les introduisant organiquement à l'intégralité de l'emplacement. La progression du joueur est persistante, donc les scavenger hunts peuvent se poursuivre d'une session à l'autre.

Utilisation du module

Installation

Pour utiliser le module ScavengerHunt dans une expérience :

1. Dans l'onglet Voir, ouvrez la Boîte à outils et sélectionnez l'onglet Marketplace.

   

2. Assurez-vous que le filtre Modèles est sélectionné, puis cliquez sur le bouton Voir tout pour afficher les catégories.

   

3. Localisez et cliquez sur la vignette MODULES DEV.

   

4. Localisez le module Scavenger Hunt et cliquez dessus, ou faites-le glisser dans la vue 3D.

   

5. Dans la fenêtre Explorateur, déplacez l'intégralité du modèle ScavengerHunt dans ServerScriptService. Lors de l'exécution de l'expérience, le module se distribuera lui-même vers divers services et commencera à s'exécuter.

   

Utiliser les jetons

Le module scavenger hunt utilise les jetons comme objets que les joueurs recherchent et collectent. Le module est livré avec un modèle de jeton que vous pouvez positionner dans le monde 3D.

1. Localisez le maillage Token1 dans le dossier Espace de travail du dossier principal du module.

   

2. Déplacez Token1 dans la hiérarchie de l'Espace de travail du premier niveau et positionnez-le où vous le souhaitez.

3. Donnez au jeton un nom unique. Ce nom est la façon dont le module suit les jetons que chaque joueur a collectés.

4. Pour ajouter plus de jetons, dupliquez un jeton existant et donnez-lui un nom unique.

Si vous ne souhaitez pas utiliser les jetons de maillage groupés, tout Model ou BasePart fonctionnera, tant qu'il répond aux critères suivants :

• L'objet a une balise CollectionService de ScavengerHuntPart. Si vous le souhaitez, le nom de la balise que le module utilise peut être modifié en définissant une valeur différente pour tokenTag dans un appel configureServer.
• L'objet comporte une instance enfant StringValue définie sur le « texte de saveur » pour s'afficher lorsque le jeton est collecté.

Utiliser les régions

Les régions diffèrent légèrement des jetons, car de grandes zones sont marquées comme « collectées » une fois que le joueur y pénètre. En outre, lorsqu'un joueur quitte la région, la modale de texte de saveur est automatiquement rejetée et la région elle-même est supprimée de l'espace de travail.

1. Créez une partie ancrée autour de la région, comme un bloc ou une sphère. Le module désactivera automatiquement la propriété CanCollide à l'exécution afin que les joueurs n'entrent pas physiquement en collision avec la région.

2. Donnez-lui un nom unique. Ce nom est la façon dont le module suit les régions dans lesquelles chaque joueur est entré.

3. Assigner la partie une balise CollectionService de ScavengerHuntPart. Si vous le souhaitez, le nom de la balise que le module utilise peut être modifié en définissant une valeur différente pour tokenTag dans un appel configureServer.

4. Incluez une instance StringValue enfant définie sur le « texte de saveur » pour s'afficher lorsque la région est entrée.

   

Paramétrage

Le module est préfiguré pour fonctionner pour la plupart des cas d'utilisation, mais il peut être facilement personnalisé. Par exemple, pour modifier la vitesse de rotation du jeton et personnaliser le message d'informations modales :

1. Dans StarterPlayerScripts, créez un nouveau LocalScript et renommez-le ConfigureScavengerHunt.

2. Collez le code suivant dans le nouveau script.

   LocalScript - ConfigureScavengerHunt
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
   ScavengerHunt.configureClient({
    infoModalText = "Welcome to my Scavenger Hunt!",
    completeModalText = "Thanks for playing my Scavenger Hunt!",
    tokenRotationSpeed = 60,
   })

Événements de collection

Chaque fois qu'un joueur collecte un jeton ou entre dans une région, l'événement collecté se déclenche. Vous pouvez écouter cet événement à partir d'un Script côté serveur et répondre en fonction. La fonction liée reçoit le Player qui est entré en collision avec le jeton ou est entré dans la région et le nom de ce jeton ou de cette région.

De même, lorsqu'un joueur collecte tous les jetons ou entre dans toutes les régions balisées, l'événement allCollected se déclenche et la fonction liée reçoit le Player. Cette fonction n'est déclenchée qu'une fois par joueur et elle peut être utilisée pour récompenser ce joueur avec un badge, l'accès à une nouvelle zone, la monnaie de l'expérience, etc.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
ScavengerHunt.collected:Connect(function(player, itemName)
    print(player.DisplayName, itemName)
end)
ScavengerHunt.allCollected:Connect(function(player)
    print(player.DisplayName .. " completed the hunt!")
end)
end)

GUI personnalisée

Ce module expose plusieurs options pour personnaliser sa GUI par défaut, mais vous pouvez choisir d'afficher des éléments de GUI personnalisés à la place.

Lorsque useCustomModals est défini sur true dans la fonction configureClient, l'événement showInfoModal se déclenche chaque fois que le joueur active le suivi du jeton. De même, l'événement showCompleteModal se déclenche lorsque le joueur a tout collecté dans la scavenger hunt. Ces deux événements peuvent être écoutés dans un LocalScript.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
ScavengerHunt.showInfoModal:Connect(function()
    -- Show a custom info modal
    local infoModal = Players.LocalPlayer.PlayerGui.ScavengerInfoModal
    infoModal.Enabled = true
end)
ScavengerHunt.showCompleteModal:Connect(function()
    -- Show a custom complete modal
    local completeModal = Players.LocalPlayer.PlayerGui.ScavengerCompleteModal
    completeModal.Enabled = true
end)

Visibilité de la GUI

Par défaut, la scavenger hunt masque tous les ScreenGuis et CoreGuis (à l'exception de la liste des joueurs) lorsque la modale d'informations ou la modale d'achèvement apparaît. Si vous souhaitez remplacer ce comportement de masquage automatique et décider via un programme des GUI qui doivent rester visibles, incluez les rappels hideOtherGuis et showOtherGuis et répondez avec votre propre logique personnalisée.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local StarterGui = game:GetService("StarterGui")
local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
local player = Players.LocalPlayer
local playerGui = player:WaitForChild("PlayerGui")
local hiddenInstances = {}
-- Create a screen GUI that will not be hidden
local specialGuiInstance = Instance.new("ScreenGui")
-- Draw the screen GUI above the scavenger hunt GUI
specialGuiInstance.DisplayOrder = 1
specialGuiInstance.Parent = playerGui
-- Add text label to the GUI
local specialLabel = Instance.new("TextLabel")
specialLabel.Size = UDim2.fromScale(1, 0.1)
specialLabel.Text = "Remains visible when displaying modals"
specialLabel.Font = Enum.Font.GothamMedium
specialLabel.TextSize = 24
specialLabel.Parent = specialGuiInstance
ScavengerHunt.hideOtherGuis(function()
    -- Hide all developer-defined screen GUIs
    local instances = playerGui:GetChildren()
    for _, instance in pairs(instances) do
        if instance:IsA("ScreenGui") and not instance.Name == "ScavengerHunt" and instance.Enabled then
            instance.Enabled = false
            table.insert(hiddenInstances, instance)
        end
    end
    -- Hide specific core GUIs
    StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)
end)
ScavengerHunt.showOtherGuis(function()
    -- Show all developer-defined screen GUIs that were hidden
    for _, instance in pairs(hiddenInstances) do
        instance.Enabled = true
    end
    hiddenInstances = {}
    -- Show specific core GUIs that were hidden
    StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, true)
end)

Référence API

Fonctions

configureClient

configureClient(config:table):nil

Remplace les options de paramétrage par défaut du côté client par le biais des clés/valeurs suivantes dans le tableau config. Cette fonction peut uniquement être appelée à partir d'un LocalScript.

Généralités

Modales

Faisceau de navigation

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
ScavengerHunt.configureClient({
    infoModalText = "Welcome to my Scavenger Hunt!",
    completeModalText = "Thanks for playing my Scavenger Hunt!",
    tokenRotationSpeed = 60,
    navigationBeam = {
        lightEmission = 1
    },
    modal = {
        textSize = 14
    },
})

configureServer

configureServer(config:table):nil

Remplace les options de configuration par défaut côté serveur par les clés/valeurs suivantes du config tableau. Cette fonction peut uniquement être appelée à partir d'un Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
ScavengerHunt.configureServer({
    tokenTag = "GreenGem",
})

désactiver

disable():nil

Masque toute l'UI pour la scavenger hunt, débranche tous les écouteurs d'événement d'entrée et empêche les joueurs de collecter des jetons ou d'interagir avec les régions. Cette fonction peut uniquement être appelée à partir d'un Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
ScavengerHunt.disable()

activer

enable():nil

Affiche toute l'UI pour la scavenger hunt, relie tous les écouteurs d'événement d'entrée et permet aux joueurs de collecter des jetons et d'interagir avec les régions. Cette fonction peut uniquement être appelée à partir d'un Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
ScavengerHunt.enable()

Événements

collecté

collected(player:Player, itemName:string, totalCollected:number): RBXScriptSignal

Se déclenche lorsqu'un joueur entre en collision avec un jeton ou entre dans une région. La fonction liée recevra le Player qui est entré en collision avec le jeton ou est entré dans la région et le nom du jeton qui a été entré en collision ou de la région qui a été entrée. Cet événement peut uniquement être lié dans un Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
ScavengerHunt.collected:Connect(function(player, itemName, totalCollected)
    print(player.DisplayName, itemName, totalCollected)
end)

Touscollectés

allCollected(player:Player): RBXScriptSignal

Se déclenche lorsqu'un joueur collecte tous les jetons ou entre dans toutes les régions de la scavenger hunt. La fonction liée recevra le Player qui a collecté tous les jetons, et elle n'est jamais déclenchée une fois par joueur. Cet événement peut uniquement être lié dans un Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
ScavengerHunt.allCollected:Connect(function(player)
    print(player.DisplayName .. " completed the hunt!")
end)
end)

showInfoModal

showInfoModal(): RBXScriptSignal

Se déclenche lorsque le joueur clique sur le suivi du jeton lorsque l'option de configuration useCustomModals est définie sur vrai. Cet événement peut uniquement être lié dans un LocalScript.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
ScavengerHunt.showInfoModal:Connect(function()
    local infoModal = Players.LocalPlayer.PlayerGui.InfoModal
    infoModal.Enabled = true
end)

showCompleteModal

showCompleteModal(): RBXScriptSignal

Se déclenche lorsque le joueur clique sur le suivi du jeton lorsque l'option de configuration useCustomModals est définie sur true et le joueur a collecté tous les jetons dans la scavenger hunt. Cet événement peut uniquement être lié dans un LocalScript.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ScavengerHunt = require(ReplicatedStorage:WaitForChild("ScavengerHunt"))
ScavengerHunt.showCompleteModal:Connect(function()
    local completeModal = Players.LocalPlayer.PlayerGui.CompleteModal
    completeModal.Enabled = true
end)

Rappels

hideOtherGuis

hideOtherGuis(callback:function)

Ce rappel s'exécute immédiatement avant l'affichage de la modale, vous permettant de désactiver l'intégralité du ScreenGuis ou des éléments avant que la modale ne soit affichée. Voir Visibilité de la GUI pour plus de détails et un exemple de code.

showOtherGuis

showOtherGuis(callback:function)

Ce rappel s'exécute immédiatement après qu'une modale a été rejetée, vous permettant d'activer l'intégralité du ScreenGuis ou des éléments dans celles-ci. Voir Visibilité de la GUI pour plus de détails et un exemple de code.