Caça ao Tesouro

O ScavengerHunt módulo de desenvolvedor oferece aos jogadores uma maneira gamificada de explorar sua experiência, introduzindo-os organicamente a todo o lugar. O progresso do jogador é persistente, portanto, as caças ao tesouro podem continuar entre as sessões.

Uso do módulo

Instalação

Para usar o módulo ScavengerHunt em uma experiência:

1. No menu Window do Studio ou na barra de ferramentas da guia Home, abra a Toolbox e selecione a guia Creator Store.

   

2. Certifique-se de que a classificação Models esteja selecionada, em seguida, clique no botão See All para Categories.

   

3. Localize e clique no bloco Packages.

4. Localize o módulo Scavenger Hunt e clique nele, ou arraste e solte-o na visualização 3D.

   

5. Na janela Explorer, mova todo o modelo ScavengerHunt para ReplicatedStorage. Ao executar a experiência, o módulo começará a rodar.

Usar tokens

O módulo de caça ao tesouro usa tokens como os itens que os jogadores procuram e coletam. O módulo vem com um modelo de token que você pode posicionar no mundo 3D.

1. Localize a malha Token1 dentro da pasta Workspace da pasta principal do módulo.

   

2. Mova Token1 para a hierarquia de nível superior Workspace e posicione-a onde desejar.

3. Dê ao token um nome único; este nome é como o módulo rastreia quais tokens cada jogador coletou.

4. Para adicionar mais tokens, duplique um token existente e dê a ele um nome único.

Se você não quiser usar os tokens de malha agrupados, qualquer Model ou BasePart funcionará, desde que atenda aos seguintes critérios:

• O objeto tem uma tag CollectionService de ScavengerHuntPart. Se desejado, o nome da tag CollectionService que o módulo utiliza pode ser alterado definindo um valor diferente para tokenTag em uma chamada configureServer.

• O objeto contém uma instância StringValue filho configurada com o "texto sabor" a ser exibido quando o token for coletado.

  

  

Usar regiões

As regiões diferem ligeiramente dos tokens, já que são grandes áreas que são marcadas como "coletadas" assim que o jogador entra nelas. Além disso, quando um jogador sai da região, o modal de texto de sabor é automaticamente dispensado e a região em si é removida do espaço de trabalho.

1. Crie uma parte ancorada ao redor da região, como um bloco ou esfera. O módulo desativará automaticamente a propriedade CanCollide em tempo de execução para que os jogadores não colidam fisicamente com a região.

2. Dê a ela um nome único. Este nome é como o módulo rastreia quais regiões cada jogador entrou.

3. Usando a seção Tags das propriedades da parte, aplique a tag ScavengerHuntPart na parte para que o CollectionService a detecte. Se desejado, o nome da tag que o módulo utiliza pode ser alterado definindo um valor diferente para tokenTag em uma chamada configureServer.

4. Inclua uma instância StringValue filho configurada com o "texto sabor" a ser exibido quando a região for entrado.

   

Configuração

O módulo está pré-configurado para trabalhar na maioria dos casos de uso, mas pode ser facilmente personalizado. Por exemplo, para alterar a velocidade de rotação do token e personalizar a mensagem modal de informação:

1. Em StarterPlayerScripts, crie um novo LocalScript e renomeie-o para ConfigureScavengerHunt.

2. Cole o seguinte código no novo script.

   LocalScript - ConfigureScavengerHunt
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)
   
   ScavengerHunt.configureClient({
   	infoModalText = "Bem-vindo à minha Caça ao Tesouro!",
   	completeModalText = "Obrigado por jogar minha Caça ao Tesouro!",
   	tokenRotationSpeed = 60,
   })

Eventos de coleção

Toda vez que um jogador coleta um token ou entra em uma região, o evento collected é acionado. Você pode ouvir a este evento a partir de um Script do lado do servidor e responder de acordo. A função conectada recebe o Player que colidiu com o token ou entrou na região e o nome daquele token ou região.

Da mesma forma, quando um jogador coleta todos os tokens ou entra em todas as regiões marcadas, o evento allCollected é acionado e a função conectada recebe o Player associado. Esta função é acionada apenas uma vez por jogador e pode ser usada para recompensar esse jogador com um distintivo, acesso a uma nova área, moeda dentro da experiência, 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 .. " completou a caça!")
end)

GUI personalizada

Este módulo expõe várias opções para personalizar sua GUI padrão, mas você pode optar por exibir elementos de GUI personalizados em vez disso.

Quando useCustomModals é definido como true na função configureClient, o evento showInfoModal é acionado toda vez que o jogador ativa o rastreador de tokens. Da mesma forma, o evento showCompleteModal é acionado quando o jogador coletou tudo na caça ao tesouro. Ambos esses eventos podem ser ouvidos em um LocalScript.

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.showInfoModal:Connect(function()
	-- Mostra um modal de informação personalizado
	local infoModal = Players.LocalPlayer.PlayerGui.ScavengerInfoModal
	infoModal.Enabled = true
end)

ScavengerHunt.showCompleteModal:Connect(function()
	-- Mostra um modal de conclusão personalizado
	local completeModal = Players.LocalPlayer.PlayerGui.ScavengerCompleteModal
	completeModal.Enabled = true
end)

Visibilidade da GUI

Por padrão, a caça ao tesouro oculta todas as ScreenGuis e CoreGuis (exceto pela lista de jogadores) quando o modal de informação ou o modal de conclusão aparece. Se você quiser anular esse comportamento automático de ocultação e decidir programaticamente quais GUIs devem permanecer visíveis, inclua os callbacks hideOtherGuis e showOtherGuis e responda com sua própria lógica personalizada.

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

-- Crie uma GUI de tela que não será oculta
local specialGuiInstance = Instance.new("ScreenGui")
-- Desenhe a GUI de tela acima da GUI da caça ao tesouro
specialGuiInstance.DisplayOrder = 1
specialGuiInstance.Parent = playerGui
-- Adicione um rótulo de texto à GUI
local specialLabel = Instance.new("TextLabel")
specialLabel.Size = UDim2.fromScale(1, 0.1)
specialLabel.Text = "Permanece visível ao exibir modais"
specialLabel.Font = Enum.Font.GothamMedium
specialLabel.TextSize = 24
specialLabel.Parent = specialGuiInstance

ScavengerHunt.hideOtherGuis(function()
	-- Oculte todas as GUIs de tela definidas pelo desenvolvedor
	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
	-- Oculte GUIs principais específicas
	StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)
end)

ScavengerHunt.showOtherGuis(function()
	-- Mostre todas as GUIs de tela definidas pelo desenvolvedor que foram ocultas
	for _, instance in hiddenInstances do
		instance.Enabled = true
	end
	hiddenInstances = {}
	-- Mostre GUIs principais específicas que foram ocultas
	StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, true)
end)

Referência da API

Funções

configureClient

Substitui as opções de configuração padrão do lado do cliente através das seguintes chaves/valores na tabela config. Esta função só pode ser chamada a partir de um LocalScript.

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.configureClient({
	infoModalText = "Bem-vindo à minha Caça ao Tesouro!",
	completeModalText = "Obrigado por jogar minha Caça ao Tesouro!",
	tokenRotationSpeed = 60,
	navigationBeam = {
		lightEmission = 1
	},
	modal = {
		textSize = 14
	},
})

configureServer

Substitui as opções de configuração padrão do lado do servidor através das seguintes chaves/valores na tabela config. Esta função só pode ser chamada a partir de um Script.

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

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

disable

Oculta toda a interface do usuário da caça ao tesouro, desconecta todos os ouvintes de eventos de entrada e impede que os jogadores coletem tokens ou interajam com regiões. Esta função só pode ser chamada a partir de um Script.

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.disable()

enable

Mostra toda a interface do usuário da caça ao tesouro, conecta todos os ouvintes de eventos de entrada e permite que os jogadores coletem tokens e interajam com regiões. Esta função só pode ser chamada a partir de um Script.

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.enable()

Eventos

collected

Dispara quando um jogador colide com um token ou entra em uma região. A função conectada receberá o Player que colidiu com o token ou entrou na região e o nome do token que colidiu ou da região que foi entrado. Este evento só pode ser conectado em um 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

Dispara quando um jogador coleta todos os tokens ou entra em todas as regiões na caça ao tesouro. A função conectada receberá o Player que coletou todos os tokens, e é acionada apenas uma vez por jogador. Este evento só pode ser conectado em um Script.

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.allCollected:Connect(function(player)
	print(player.DisplayName .. " completou a caça!")
end)

showInfoModal

Dispara quando o jogador clica no rastreador de tokens quando a opção de configuração useCustomModals configuração está definida como verdadeira. Este evento só pode ser conectado em um 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

Dispara quando o jogador clica no rastreador de tokens quando a opção de configuração useCustomModals configuração está definida como true e o jogador coletou todos os tokens na caça ao tesouro. Este evento só pode ser conectado em um 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)

Callbacks

hideOtherGuis

Este callback é executado imediatamente antes que um modal seja exibido, permitindo que você desative inteiros ScreenGuis ou elementos dentro deles antes que o modal seja mostrado. Veja Visibilidade da GUI para detalhes e código de exemplo.

showOtherGuis

Este callback é executado imediatamente após que um modal foi dispensado, permitindo que você habilite inteiros ScreenGuis ou elementos dentro deles. Veja Visibilidade da GUI para detalhes e código de exemplo.