Avatar Context Menu

Oct 09 2019, 11:07 AM PST 5 min

The Avatar Context Menu (ACM) is an opt-in feature that allows easy player-to-player social interaction. When the ACM is enabled, a player can walk up to another player and tap/click on them to open a window with several options. The player can send a friend request, begin a private chat, or wave. This menu can even be customized with custom actions, such as initiating trades, battles, and more.

Enabling the Avatar Context Menu

The Avatar Context Menu isn’t ideal for all games, so it must be enabled using the StarterGui/SetCore|StarterGui:SetCore() option "AvatarContextMenuEnabled" in a LocalScript. The ACM is best used in games where there is no pre-defined behavior for clicking/tapping on other players.

Expand

-- Run in a LocalScript, ideally within "StarterPlayerScripts"
local StarterGui = game:GetService("StarterGui")
StarterGui:SetCore("AvatarContextMenuEnabled", true)

Copy Code Light Theme

If you need to detect whether the ACM is enabled, for instance within the script of a model or third-party library, call StarterGui/GetCore|StarterGui:GetCore() with the parameter "AvatarContextMenuEnabled". This will return a boolean indicating if the ACM is currently enabled.

Avatar Context Menu in Action

Opening the Menu

In games where this feature is enabled, clicking or tapping a character will open the ACM. By default, the menu will have the following options:

Menu Option	Enum	Description
Friend	Friend	Sends a friend request to the selected player.
Chat	Chat	Opens a private conversation with the selected player in the in-game chat.
Wave	Emote	Currently initiates a wave animation to the selected player. The list of available emotes will be expanded upon in the near future.

To forcibly open the ACM with a specific player pre-selected, call StarterGui:SetCore("AvatarContextMenuTarget", targetPlayer) where targetPlayer is a valid Player object.

The ACM will not open if a Tool is equipped. While the menu is open, movement controls are taken over until the menu is closed.

Character Selection Carousel

Once the ACM is open, the player can swipe and click/tap to select other Player|Players on the character selection carousel. Characters are sorted based on distance to the selected character (ascending). The menu only updates when first opened, and wraps around from beginning to end.

The character that’s currently selected in the carousel is the one being interacted with. A player could quickly swap between characters using the selection carousel to Add Friend, Chat, etc. with multiple different characters.

If you need to determine which Player is currently selected in the ACM (assuming it's open), call StarterGui:GetCore("AvatarContextMenuTarget").

Closing the Menu

The ACM can be closed by clicking the in the top-right corner (or tap somewhere outside it). After closing, controls are returned to the player. For gamepad controllers, the “B” button closes the menu.

To forcibly close the ACM, call StarterGui:SetCore("AvatarContextMenuTarget", nil).

Customizing the Avatar Context Menu

Once enabled, game-specific actions can be added to the menu. For example, a game might allow for trade requests, add-to-party options, or other special interactions.

Adding Custom Actions

The following example shows how add a custom action to the Avatar Context Menu.

Expand

local Players = game:GetService("Players")
local StarterGui = game:GetService("StarterGui")
local player = Players.LocalPlayer

-- Connect a function to a "BindableEvent"
local bindableEvent = Instance.new("BindableEvent")
local function onCustomACMAction(targetPlayer)
	-- At this point, you could call InvokeServer() on a RemoteFunction to alert the server of the selection
	print("ACM event selected by " .. player.Name .. " on " .. targetPlayer.Name)
end
bindableEvent.Event:Connect(onCustomACMAction)

-- Add the ACM option using SetCore() with "AddAvatarContextMenuOption"
local options = {"Custom ACM Action", bindableEvent}
StarterGui:SetCore("AddAvatarContextMenuOption", options)

Copy Code Light Theme

Here’s a broad overview of this code sample:

The first few lines get the necessary game services such as Players and StarterGui.
The next block defines a function, onCustomACMAction(), and connects it to a BindableEvent.
The final block calls StarterGui/SetCore|StarterGui:SetCore() with the option "AddAvatarContextMenuOption", providing a table with the name of the action and the BindableEvent.

Removing Actions

To remove a custom action which you added to the Avatar Context Menu, call StarterGui/SetCore|StarterGui:SetCore() with the option "RemoveAvatarContextMenuOption" and the name of the action (the first value in the options table as shown on line 14 above).

Expand

StarterGui:SetCore("RemoveAvatarContextMenuOption", "Custom ACM Action")

Copy Code Light Theme

Additionally, any default option may be removed by using Enum/AvatarContextMenuOption enums:

Expand

-- Remove the "Friend" option (you can also choose "Chat" or "Emote")
StarterGui:SetCore("RemoveAvatarContextMenuOption", Enum.AvatarContextMenuOption.Friend)

Copy Code Light Theme

The ACM will not add/remove options while open. Your code should verify that an action is still relevant in case the action was removed from the menu. For example, if a marketplace area adds/removes an option to send trade requests, you should verify both players are still in the marketplace.

Visual Customization

To change the appearance of the Avatar Context Menu, call StarterGui/SetCore|StarterGui:SetCore() with the option "AvatarContextMenuTheme", providing a table of parameters and values from the following options.

Name Tag (the character being interacted with).
Button Frame (contains all of the ACM buttons).
Buttons for the default or custom ACM actions.

Background Parameters
BackgroundColor	A `datatype/Color3` for the overall background of the ACM (most useful when not using a background image).
BackgroundTransparency	Transparency value (0–1) for the overall background of the ACM (most useful when not using a background image).
BackgroundImage	A valid asset ID of an image for the ACM background.
BackgroundImageTransparency	Transparency value (0–1) for the background image.
BackgroundImageScaleType	A `enum/ScaleType` enum for background image scaling.
BackgroundImageSliceCenter	A `datatype/Rect` specifying the center of a nine-slice image when BackgroundImageScaleType is set to `Enum.ScaleType.Slice`.
Name Tag Parameters
NameTagColor	A `datatype/Color3` for the bar showing which player is being interacted with.
NameUnderlineColor	A `datatype/Color3` for the thin line between the name tag and action buttons.
Button Frame Parameters
ButtonFrameColor	A `datatype/Color3` for the section (frame) containing the action buttons.
ButtonFrameTransparency	Transparency value (0–1) for the button frame section.
Button Parameters
ButtonColor	A `datatype/Color3` for the background of the ACM action buttons.
ButtonTransparency	Transparency value (0–1) for the background color of the action buttons.
ButtonHoverColor	A `datatype/Color3` for the "hover" state of the action buttons.
ButtonHoverTransparency	Transparency value (0–1) for the "hover" color of the action buttons.
ButtonUnderlineColor	A `datatype/Color3` for the thin line which separates each action button.
ButtonImage	A valid asset ID of an image for the background of buttons.
ButtonImageScaleType	A `enum/ScaleType` enum for button image scaling.
ButtonImageSliceCenter	A `datatype/Rect` specifying the center of a nine-slice image when ButtonImageScaleType is set to `enum/ScaleType\|Enum.ScaleType.Slice`.
Text Parameters
Font	A `enum/Font` enum value for the name tag and button text.
TextColor	A `datatype/Color3` for all text within the ACM.
TextScale	A float value to scale the default text sizes of each element.
Various Image Parameters
LeaveMenuImage	A valid asset ID of an image for the ACM close button.
ScrollLeftImage	A valid asset ID of an image for the carousel "scroll left" button.
ScrollRightImage	A valid asset ID of an image for the carousel "scroll right" button.
Selected Character Parameters
SelectedCharacterIndicator	The `MeshPart` which floats above a character's head to indicate he/she is selected.
Size and Position Parameters
Size	A `datatype/UDim2` for the overall size of the ACM.
MinSize	A `datatype/Vector2` specifying the minimum size of the ACM.
MaxSize	A `datatype/Vector2` specifying the maximum size of the ACM.
AspectRatio	A float value specifying the relative width and height of the ACM.
AnchorPoint	The `GuiObject/AnchorPoint\|AnchorPoint` of the ACM.
OnScreenPosition	A `datatype/UDim2` specifying the on-screen position of the ACM (the position where it tweens to when opened).
OffScreenPosition	A `datatype/UDim2` specifying the off-screen position of the ACM (the position where it tweens from/to when opened/closed).

As an example, this code customizes the ACM theme using some basic parameters:

Expand

local StarterGui = game:GetService("StarterGui")

StarterGui:SetCore("AvatarContextMenuTheme", { 
	BackgroundImage = "", 
	BackgroundTransparency = 0.5, 
	BackgroundColor = Color3.fromRGB(111, 145, 242),
	NameTagColor = Color3.fromRGB(0, 0, 200),
	NameUnderlineColor = Color3.fromRGB(213, 233, 255),
	ButtonFrameColor = Color3.fromRGB(15, 24, 65), 
	ButtonFrameTransparency = 0.2, 
	ButtonUnderlineColor = Color3.fromRGB(213, 233, 255), 
	Font = Enum.Font.SciFi
})

Copy Code Light Theme

Tags:

gui
context
interaction