5 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

Friends Locator

It can be challenging to locate friends in-game. 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 a game:

1. From Studio's Window menu or Home tab toolbar, 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 Packages 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 ReplicatedStorage. Upon running the game the module will begin running.

Test 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.

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

3. From Studio's mezzanine, start a multi-client simulation with 2 clients. 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.

   

Note

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

Note

By default, clicking/tapping a friends'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.

Connect 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:

   local RunService = game:GetService("RunService")
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local FriendsLocator = require(ReplicatedStorage.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 game, 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.

   

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

configure(config: table)

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

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local FriendsLocator = require(ReplicatedStorage.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.

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)
	-- 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.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local FriendsLocator = require(ReplicatedStorage.FriendsLocator)

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