Friends Locator

It can be challenging to locate friends in-experience. The FriendsLocator developer module lets players easily find and teleport to their friends inside a place.

Module Usage

Installation

To use the FriendsLocator module in an experience:

1. From the View tab, open the Toolbox and select the Creator Store tab.

   

2. Make sure the Models sorting is selected, then click the See All button for Categories.

   

3. Locate and click the Dev Modules tile.

   

4. Locate the Friends Locator module and click it, or drag-and-drop it into the 3D view.

   

5. In the Explorer window, move the entire FriendsLocator model into ServerScriptService. Upon running the experience, the module will distribute itself to various services and begin running.

   

Testing in Studio

To test the module in Studio, the FriendsLocator module must be run in a multi-client simulation, since no friends will be present in a solo playtest.

1. In StarterPlayerScripts, create a new LocalScript and rename it ConfigureFriendsLocator.

   

2. Paste the following code into the new ConfigureFriendsLocator script. The showAllPlayers setting within the configure function ensures that locators are shown for all users while testing in Studio, but not in a published place.

   LocalScript - ConfigureFriendsLocator
   local RunService = game:GetService("RunService")
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local FriendsLocator = require(ReplicatedStorage:WaitForChild("FriendsLocator"))
   
   FriendsLocator.configure({
   	showAllPlayers = RunService:IsStudio(),  -- Allows for debugging in Studio
   })

3. From the Test tab, select the following combination for Clients and Servers, then click the Start button. Three new instances of Studio will open; one simulated server and two simulated clients.

   

4. Go into either of the client Studio instances, move a distance of 100 studs away from the other character, and you should see a locator icon appear over its head.

   

   Due to the way user IDs are handled in Studio, avatar images will not appear on the locator icons during testing.

   By default, clicking/tapping a friend's icon will teleport your character to that character's location. If you keep this default behavior and you find that streaming pause is occurring under the instance streaming architecture, you may want to request area streaming around the teleport location as shown in the clicked event code sample.

Connecting to Events

The FriendsLocator module exposes events so that you can introduce custom behaviors when users interact with a locator icon.

1. Make sure that you've created the ConfigureFriendsLocator script outlined in Testing in Studio.

2. Add lines 8 and 11-13 to the script:

   LocalScript - ConfigureFriendsLocator
   local RunService = game:GetService("RunService")
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local FriendsLocator = require(ReplicatedStorage:WaitForChild("FriendsLocator"))
   
   FriendsLocator.configure({
   	showAllPlayers = RunService:IsStudio(),  -- Allows for debugging in Studio
   	teleportToFriend = false,  -- Prevent teleport on icon click/tap
   })
   
   FriendsLocator.clicked:Connect(function(player, playerCFrame)
   	print("You clicked on locator icon for", player.DisplayName)
   end)

3. Conduct a multi-client test and click on another character's locator icon. Notice that your character does not teleport to that location, and the event triggers to allow for custom handling of icon clicks.

Custom Locator UI

If the default style does not fit your experience, you can replace the default avatar portrait UI with your own UI.

To replace the default UI:

1. Create a new ScreenGui instance inside the StarterGui container.

   

2. Create a Frame instance named FriendLocator as a child of the new ScreenGui, then add elements like ImageLabels, TextLabels to design your custom UI.

   

3. When finished, disable the parent ScreenGui so that the module doesn't show the custom locator UI until needed.

   

4. (Optional) If you want the friend's avatar portrait and DisplayName to show up somewhere in the custom UI, you can place the following instances inside the FriendLocator frame.

   • An ImageLabel of the name Portrait.
   • A TextLabel of the name DisplayName.

   

   The module will look for these items and display the friend's avatar portrait and/or display name respectively.

API Reference

Functions

configure

Overrides default configuration options through the following keys/values in the config table.

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

local FriendsLocator = require(ReplicatedStorage:WaitForChild("FriendsLocator"))

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

Events

clicked

Fires when a locator icon is clicked/activated by the local player. This event can only be connected in a LocalScript.

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

local FriendsLocator = require(ReplicatedStorage:WaitForChild("FriendsLocator"))

local localPlayer = Players.LocalPlayer

FriendsLocator.clicked:Connect(function(player, playerCFrame)
	-- Request streaming around target location
	if workspace.StreamingEnabled then
		local success, errorMessage = pcall(function()
			localPlayer:RequestStreamAroundAsync(playerCFrame.Position)
		end)
		if not success then
			print(errorMessage)
		end
	end

	print("You clicked on locator icon for", player.DisplayName, "at position", playerCFrame.Position)
end)

visibilityChanged

Fires when a locator icon is shown/hidden on the local player's screen. This event can only be connected in a LocalScript.

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

local FriendsLocator = require(ReplicatedStorage:WaitForChild("FriendsLocator"))

FriendsLocator.visibilityChanged:Connect(function(player, playerCFrame, isVisible)
	print("Visibility of locator icon for", player.DisplayName, ":", isVisible)
end)