We use cookies on this site to enhance your user experience

Avatar Context Menu

Avatar Context Menu

Aug 19 2018, 1:28 PM PST 10 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 in order to open a window with several options. The player can send a friend request, begin a private chat or wave. This menu may be customized with custom actions, such as initiating trades, battles, and more.

A player opens the Avatar Context Menu interface in Lumber Tycoon 2

Enabling the Avatar Context Menu

The Avatar Context Menu may not be ideal for all games, so it must be enabled using StarterGui/SetCore option "SetAvatarContextMenuEnabled" in a LocalScript. The ACM is best used in games where there is no pre-defined behavior for clicking/tapping on other players, such as social games instead of combat games.

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

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.

*The AvatarContextMenuOption enum value used when adding/removing these default options.

Character Selection Carousel

Once the ACM is open, the player can swipe and click/tap to select other 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.

Closing the Menu

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

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.

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

-- First, connect a function to a BindableEvent
local event = 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)

-- Then, add the ACM option using SetCore "AddAvatarContextMenuOption"
local options = {"Custom ACM Action", event}
StarterGui:SetCore("AddAvatarContextMenuOption", options)

Here’s a broad overview of this code sample:

  1. The first few lines get the necessary game services, such as StarterGui and Players.
  2. Define a function, onCustomACMAction, and connect it to a BindableEvent.
  3. Call StarterGui/SetCore with the option "AddAvatarContextMenuOption" and provide a table with the name of the action and the BindableEvent from the previous step.

Removing Actions

To remove a custom action from the Avatar Context Menu, use StarterGui/SetCore with the option "RemoveAvatarContextMenuOption" and the name of the action (the first value in the table passed to "AddAvatarContextMenuOption").

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

Alternatively, the default options may be removed by using Enum/AvatarContextMenuOption:

-- Below, the Friend option is removed. You can also choose Chat or Emote.
StarterGui:SetCore("RemoveAvatarContextMenuOption", Enum.AvatarContextMenuOption.Friend)
  • gui