Chasse au trésor

Le module ScavengerHunt développeur donne aux joueurs un moyen intrinsèquement ludique d'explorer votre jeu, les introduisant de manière organique à l'ensemble de l'endroit. La progression des joueurs est persistante, donc les chasses au trésor peuvent se poursuivre à travers les sessions.

Utilisation du module

Installation

Pour utiliser le module ScavengerHunt dans un jeu :

1. Dans le menu Fenêtre de Studio ou la barre d'outils de l'onglet Accueil, ouvrez la Boîte à outils et sélectionnez l'onglet Boutique des créateurs.

   

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

   

3. Localisez et cliquez sur le carreau Packages.

4. Localisez le module Chasse au trésor et cliquez dessus, ou faites-le glisser dans la vue 3D.

   

5. Dans la fenêtre Explorateur, déplacez l'ensemble du modèle ScavengerHunt dans ReplicatedStorage. Lors de l'exécution du jeu, le module commencera à fonctionner.

Utiliser des jetons

Le module de chasse au trésor utilise des jetons comme les 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 Workspace du dossier principal du module.

   

2. Déplacez Token1 dans la hiérarchie de Workspace au niveau supérieur et positionnez-le où vous le souhaitez.

3. Donnez au jeton un nom unique ; ce nom est la façon dont le module suit quels jetons 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 en maillage fournis, tout Model ou BasePart fonctionnera, tant qu'il répond aux critères suivants :

• L'objet a une étiquette CollectionService de ScavengerHuntPart. Si vous le souhaitez, le nom de l'étiquette CollectionService que le module utilise peut être changé en définissant une valeur différente pour tokenTag dans un appel à configureServer.

• L'objet contient une instance enfant StringValue définie sur le "texte de saveur" à afficher lorsque le jeton est collecté.

  

  

Utiliser des régions

Les régions diffèrent légèrement des jetons, car ce sont de grandes zones qui sont marquées comme "collectées" une fois que le joueur y entre. De plus, lorsque le joueur quitte la région, la fenêtre contextuelle de texte de saveur se ferme automatiquement et la région elle-même est supprimée de l'espace de travail.

1. Créez une pièce 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 ne heurtent pas physiquement la région.

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

3. En utilisant la section Étiquettes des propriétés de la pièce, appliquez l'étiquette ScavengerHuntPart à la pièce afin que CollectionService la détecte. Si vous le souhaitez, le nom de l'étiquette que le module utilise peut être changé en définissant une valeur différente pour tokenTag dans un appel à configureServer.

4. Incluez une instance enfant StringValue définie sur le "texte de saveur" à afficher lorsque la région est entrée.

   

Configuration

Le module est préconfiguré pour fonctionner dans la plupart des cas d'utilisation, mais il peut être facilement personnalisé. Par exemple, pour changer la vitesse de rotation des jetons et personnaliser le message d'information de la fenêtre contextuelle :

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

2. Collez le code suivant dans le nouveau script.

   LocalScript - ConfigureScavengerHunt

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)
   
   ScavengerHunt.configureClient({
   	infoModalText = "Bienvenue dans ma chasse au trésor !",
   	completeModalText = "Merci d'avoir participé à ma chasse au trésor !",
   	tokenRotationSpeed = 60,
   })

Événements de collecte

Chaque fois qu'un joueur collecte un jeton ou entre dans une région, l'événement collected se déclenche. Vous pouvez écouter cet événement depuis un Script côté serveur et répondre en conséquence. La fonction connectée reçoit le Player qui a heurté 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 étiquetées, l'événement allCollected se déclenche et la fonction connectée reçoit le Player associé. Cette fonction n'est déclenchée qu'une seule fois par joueur et peut être utilisée pour récompenser ce joueur avec un badge, l'accès à une nouvelle zone, de la monnaie en jeu, etc.

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 .. " a terminé la chasse !")
end)

GUI personnalisée

Ce module expose plusieurs options pour personnaliser son GUI par défaut, mais vous pouvez choisir d'afficher des éléments 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 traqueur de jetons. De même, l'événement showCompleteModal se déclenche lorsque le joueur a collecté tout dans la chasse au trésor. Ces deux événements peuvent être écoutés dans un LocalScript.

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.showInfoModal:Connect(function()
	-- Afficher une fenêtre contextuelle d'information personnalisée
	local infoModal = Players.LocalPlayer.PlayerGui.ScavengerInfoModal
	infoModal.Enabled = true
end)

ScavengerHunt.showCompleteModal:Connect(function()
	-- Afficher une fenêtre contextuelle de complétion personnalisée
	local completeModal = Players.LocalPlayer.PlayerGui.ScavengerCompleteModal
	completeModal.Enabled = true
end)

Visibilité de la GUI

Par défaut, la chasse au trésor cache tous les ScreenGuis et CoreGuis (sauf pour la liste des joueurs) lorsque la fenêtre contextuelle d'information ou la fenêtre contextuelle de complétion apparaît. Si vous souhaitez remplacer ce comportement de masquage automatique et décider par programme quelles GUIs doivent rester visibles, incluez les rappels hideOtherGuis et showOtherGuis et répondez avec votre propre logique personnalisée.

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 = {}

-- Créer un Screen GUI qui ne sera pas caché
local specialGuiInstance = Instance.new("ScreenGui")
-- Dessiner le Screen GUI au-dessus du GUI de la chasse au trésor
specialGuiInstance.DisplayOrder = 1
specialGuiInstance.Parent = playerGui
-- Ajouter une étiquette de texte au GUI
local specialLabel = Instance.new("TextLabel")
specialLabel.Size = UDim2.fromScale(1, 0.1)
specialLabel.Text = "Reste visible lors de l'affichage des fenêtres contextuelles"
specialLabel.Font = Enum.Font.GothamMedium
specialLabel.TextSize = 24
specialLabel.Parent = specialGuiInstance

ScavengerHunt.hideOtherGuis(function()
	-- Cacher tous les Screen GUIs définis par le développeur
	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
	-- Cacher des core GUIs spécifiques
	StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)
end)

ScavengerHunt.showOtherGuis(function()
	-- Afficher tous les Screen GUIs définis par le développeur qui ont été cachés
	for _, instance in hiddenInstances do
		instance.Enabled = true
	end
	hiddenInstances = {}
	-- Afficher des core GUIs spécifiques qui ont été cachés
	StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, true)
end)

Référence API

Fonctions

configureClient

Remplace les options de configuration par défaut côté client à travers les clés/valeurs suivantes dans la table config. Cette fonction ne peut être appelée que depuis un LocalScript.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.configureClient({
	infoModalText = "Bienvenue dans ma chasse au trésor !",
	completeModalText = "Merci d'avoir participé à ma chasse au trésor !",
	tokenRotationSpeed = 60,
	navigationBeam = {
		lightEmission = 1
	},
	modal = {
		textSize = 14
	},
})

configureServer

Remplace les options de configuration par défaut côté serveur à travers les clés/valeurs suivantes dans la table config. Cette fonction ne peut être appelée que depuis un Script.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

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

disable

Cache toute l'interface utilisateur de la chasse au trésor, déconnecte tous les écouteurs d'événements d'entrée et empêche les joueurs de collecter des jetons ou d'interagir avec des régions. Cette fonction ne peut être appelée que depuis un Script.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.disable()

enable

Affiche toute l'interface utilisateur de la chasse au trésor, connecte tous les écouteurs d'événements d'entrée et permet aux joueurs de collecter des jetons et d'interagir avec des régions. Cette fonction ne peut être appelée que depuis un Script.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.enable()

Événements

collected

Se déclenche lorsqu'un joueur entre en collision avec un jeton ou entre dans une région. La fonction connectée recevra le Player qui a heurté le jeton ou est entré dans la région et le nom du jeton avec lequel il a heurté ou la région dans laquelle il est entré. Cet événement ne peut être connecté que dans un 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

Se déclenche lorsqu'un joueur collecte tous les jetons ou entre dans toutes les régions de la chasse au trésor. La fonction connectée recevra le Player qui a collecté tous les jetons, et elle n'est déclenchée qu'une seule fois par joueur. Cet événement ne peut être connecté que dans un Script.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.allCollected:Connect(function(player)
	print(player.DisplayName .. " a terminé la chasse !")
end)

showInfoModal

Se déclenche lorsque le joueur clique sur le traqueur de jetons lorsque l'option de configuration useCustomModals est définie sur true. Cet événement ne peut être connecté que dans un 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

Se déclenche lorsque le joueur clique sur le traqueur de jetons lorsque l'option de configuration useCustomModals est définie sur true et que le joueur a collecté tous les jetons dans la chasse au trésor. Cet événement ne peut être connecté que dans un 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)

Rappels

hideOtherGuis

Ce rappel s'exécute immédiatement avant qu'une fenêtre contextuelle ne soit affichée, vous permettant de désactiver des ScreenGuis entiers ou des éléments à l'intérieur d'eux avant que la fenêtre contextuelle ne soit affichée. Voir Visibilité de la GUI pour plus de détails et un code d'exemple.

showOtherGuis

Ce rappel s'exécute immédiatement après qu'une fenêtre contextuelle a été fermée, vous permettant d'activer des ScreenGuis entiers ou des éléments à l'intérieur d'eux. Voir Visibilité de la GUI pour plus de détails et un code d'exemple.