Localizador de Amigos

Pode ser desafiador localizar amigos dentro da experiência. O módulo FriendsLocator de desenvolvedor permite que os jogadores encontrem e se teletransportem facilmente para seus amigos dentro de um lugar.

Uso do Módulo

Instalação

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

1. No menu Janela do Studio ou na barra de ferramentas da aba Início, abra a Caixa de Ferramentas e selecione a aba Loja do Criador.

   

2. Certifique-se de que a ordenação Modelos esteja selecionada, então clique no botão Ver Todos da categoria Categorias.

   

3. Localize e clique no quadrado Pacotes.

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

   

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

Testar no Studio

Para testar o módulo no Studio, o módulo FriendsLocator deve ser executado em uma simulação de múltiplos clientes, já que não haverá amigos presentes em um teste solo.

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

   

2. Cole o seguinte código no novo script ConfigureFriendsLocator. A configuração showAllPlayers dentro da função configure garante que localizadores sejam mostrados para todos os usuários enquanto testa no Studio, mas não em um lugar publicado.

   LocalScript - ConfigureFriendsLocator
   local RunService = game:GetService("RunService")
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local FriendsLocator = require(ReplicatedStorage.FriendsLocator)
   
   FriendsLocator.configure({
   	showAllPlayers = RunService:IsStudio(), -- Permite depuração no Studio
   })

3. No mezzanino do Studio, inicie uma simulação de múltiplos clientes com 2 clientes. Três novas instâncias do Studio serão abertas; um servidor simulado e dois clientes simulados.

   

4. Vá para uma das instâncias cliente do Studio, mova uma distância de 100 studs do outro personagem, e você deverá ver um ícone de localizador aparecer sobre a cabeça dele.

   

   Devido à forma como os IDs de usuários são tratados no Studio, as imagens dos avatares não aparecerão nos ícones de localizadores durante os testes.

   Por padrão, clicar/tocar no ícone de um amigo teletransportará seu personagem para a localização desse personagem. Se você mantiver esse comportamento padrão e perceber que a pausa de streaming está ocorrendo na arquitetura de streaming de instâncias, talvez queira solicitar streaming de área ao redor da localização de teletransporte, conforme mostrado no exemplo de código do evento clicked.

Conectar a eventos

O módulo FriendsLocator expõe eventos para que você possa introduzir comportamentos personalizados quando os usuários interagem com um ícone de localizador.

1. Certifique-se de que você criou o script ConfigureFriendsLocator descrito em testando no Studio.

2. Adicione as linhas 8 e 11-13 ao script:

   LocalScript - ConfigureFriendsLocator
   local RunService = game:GetService("RunService")
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local FriendsLocator = require(ReplicatedStorage.FriendsLocator)
   
   FriendsLocator.configure({
   	showAllPlayers = RunService:IsStudio(), -- Permite depuração no Studio
   	teleportToFriend = false, -- Impede o teletransporte ao clicar/tocar no ícone
   })
   
   FriendsLocator.clicked:Connect(function(player, playerCFrame)
   	print("Você clicou no ícone de localizador de", player.DisplayName)
   end)

3. Realize um teste de múltiplos clientes e clique no ícone de localizador de outro personagem. Note que seu personagem não se teletransporta para essa localização, e o evento é acionado para permitir o manuseio personalizado dos cliques em ícones.

UI de localizador personalizada

Se o estilo padrão não se adequa à sua experiência, você pode substituir a UI do retrato do avatar padrão pela sua própria UI.

Para substituir a UI padrão:

1. Crie uma nova instância ScreenGui dentro do contêiner StarterGui.

   

2. Crie uma instância Frame chamada FriendLocator como filho do novo ScreenGui, em seguida, adicione elementos como ImageLabels, TextLabels para projetar sua UI personalizada.

   

3. Quando terminar, desative o ScreenGui pai para que o módulo não mostre a UI de localizador personalizada até que seja necessário.

   

4. (Opcional) Se você quiser que o retrato do avatar do amigo e o DisplayName apareçam em algum lugar na UI personalizada, você pode colocar as seguintes instâncias dentro do quadro FriendLocator.

   • Um ImageLabel com o nome Portrait.
   • Um TextLabel com o nome DisplayName.

   

   O módulo procurará por esses itens e exibirá o retrato do avatar do amigo e/ou o nome de exibição respectivamente.

Referência da API

Funções

configure

Substitui opções de configuração padrão através das seguintes chaves/valores na tabela config.

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

local FriendsLocator = require(ReplicatedStorage.FriendsLocator)

FriendsLocator.configure({
	alwaysOnTop = true,
	showAllPlayers = false,
	teleportToFriend = true,
	thresholdDistance = 100,
	maxLocators = 10
})

Eventos

clicked

Dispara quando um ícone de localizador é clicado/ativado pelo jogador local. Este evento só pode ser conectado em um LocalScript.

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

local FriendsLocator = require(ReplicatedStorage.FriendsLocator)

local localPlayer = Players.LocalPlayer

FriendsLocator.clicked:Connect(function(player, playerCFrame)
	-- Solicitar streaming ao redor da localização alvo
	if Workspace.StreamingEnabled then
		local success, errorMessage = pcall(function()
			localPlayer:RequestStreamAroundAsync(playerCFrame.Position)
		end)
		if not success then
			print(errorMessage)
		end
	end

	print("Você clicou no ícone de localizador de", player.DisplayName, "na posição", playerCFrame.Position)
end)

visibilityChanged

Dispara quando um ícone de localizador é mostrado/oculto na tela do jogador local. Este evento só pode ser conectado em um LocalScript.

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

local FriendsLocator = require(ReplicatedStorage.FriendsLocator)

FriendsLocator.visibilityChanged:Connect(function(player, playerCFrame, isVisible)
	print("Visibilidade do ícone de localizador de", player.DisplayName, ":", isVisible)
end)