chasse au trésor

Le module ScavengerHunt module développeur donne aux joueurs un moyen intrinsèquement ludique d'explorer votre expérience, les introduisant de manière organique à l'ensemble de l'endroit. Les progrès des joueurs sont persistants, donc les chasses au trésor peuvent se poursuivre à travers les sessions.

Utilisation du module

Installation

Pour utiliser le module ScavengerHunt dans une expérience :

1. Dans le menu Fenêtre de Studio ou dans 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 par Modèles est sélectionné, puis cliquez sur le bouton Voir tout pour Catégories.

   

3. Localisez et cliquez sur la tuile 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 de l'expérience, le module commencera à fonctionner.

Utiliser des jetons

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

   

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

3. Donnez au jeton un nom unique ; ce nom est la manière dont le module suit quels jetons chaque joueur a collectés.

4. Pour ajouter d'autres jetons, dupliquez un jeton existant et donnez-lui un nom unique.

Si vous ne souhaitez pas utiliser les jetons de maillage inclus, n'importe quel Model ou BasePart fonctionnera, tant qu'il respecte les critères suivants :

• L'objet a une étiquette de CollectionService de ScavengerHuntPart. Si vous le souhaitez, le nom de l'étiquette de CollectionService utilisé par le module peut être modifié 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 modale de texte de saveur se dissipe automatiquement et la région elle-même est retiré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 au moment de l'exécution afin que les joueurs ne puissent pas entrer en collision physiquement avec la région.

2. Donnez-lui un nom unique. Ce nom est la manière dont le module suit quelles régions chaque joueur a pénétrées.

3. En utilisant la section Tags des propriétés de la partie, appliquez l'étiquette ScavengerHuntPart à la partie afin que CollectionService la détecte. Si vous le souhaitez, le nom de l'étiquette que le module utilise peut être modifié 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 modal informatif :

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 à ma Chasse au Trésor !",
   	completeModalText = "Merci d'avoir joué à 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 à partir d'un Script côté serveur et réagir en conséquence. La fonction connectée reçoit le Player qui est entré en collision avec le jeton ou qui est entré dans la région, ainsi que 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 insigne, un accès à une nouvelle zone, une monnaie en expérience, etc.

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 .. " a terminé la chasse !")
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 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 de jetons. De même, l'événement showCompleteModal se déclenche lorsque le joueur a collecté tous les éléments de la chasse au trésor. Tous ces événements peuvent être écoutés dans un LocalScript.

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

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

ScavengerHunt.showCompleteModal:Connect(function()
	-- Afficher une modale 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 toutes les ScreenGuis et CoreGuis (sauf pour la liste des joueurs) lorsque la modale d'information ou la modale de complétion apparaît. Si vous souhaitez remplacer ce comportement de masquage automatique et décider par programmation quelles GUIs doivent rester visibles, incluez les rappels hideOtherGuis et showOtherGuis et réagissez 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.ScavengerHunt)

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

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

ScavengerHunt.hideOtherGuis(function()
	-- Cacher toutes les GUI d'écran définies 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 les GUIs de base spécifiques
	StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)
end)

ScavengerHunt.showOtherGuis(function()
	-- Afficher toutes les GUI d'écran définies par le développeur qui étaient cachées
	for _, instance in hiddenInstances do
		instance.Enabled = true
	end
	hiddenInstances = {}
	-- Afficher des GUIs de base spécifiques qui ont été cachées
	StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, true)
end)

Référence API

Fonctions

configureClient

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

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

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

configureServer

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

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

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

disable

Cache toute l'interface utilisateur pour 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.

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.disable()

enable

Affiche toute l'interface utilisateur pour 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.

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 est entré en collision avec le jeton ou qui est entré dans la région et le nom du jeton qui a été heurté ou de la région qui a été pénétrée. Cet événement ne peut être connecté que dans un 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

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 cela ne se déclenche qu'une seule fois par joueur. Cet événement ne peut être connecté que dans un Script.

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

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

showInfoModal

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

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

Rappels

hideOtherGuis

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

showOtherGuis

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