ContextActionService

Afficher les obsolètes

*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.

Création impossible
Service

Permet à une expérience de lier l'entrée de l'utilisateur à des actions contextuelles ou des actions qui ne sont activées que sous certaines conditions ou période de temps.Par exemple, permettre à un joueur d'ouvrir une porte seulement lorsqu'il est à proximité.En code, une action est simplement une chaîne (le nom de l'action) utilisée par le service pour distinguer les actions uniques.La chaîne d'action est fournie à BindAction et UnbindAction , parmi d'autres fonctions membres.Si deux actions sont liées à la même entrée, la plus récemment liée prendra la priorité.Lorsque l'action la plus récente est désolidarisée, celle qui a été liée avant prend à nouveau le contrôle.Comme ce service traite les entrées de l'utilisateur, vous ne pouvez l'utiliser que du côté client LocalScripts .

Contexte et action

Un contexte est simplement une condition pendant laquelle un joueur peut effectuer une action.Certains exemples incluent la détention d'un Tool , être seated dans une voiture ou se tenir près d'une porte.Quelle que soit la situation, c'est à votre LocalScripts de rappeler BindAction lorsque le contexte est entré et UnbindAction lorsque le contexte est laissé.

Une action action est simplement une entrée qui peut être exécutée par le joueur dans ce contexte.Une telle action pourrait ouvrir/fermer un menu, déclencher une action d'outil secondaire ou envoyer une demande au serveur en utilisant RemoteFunction:InvokeServer() .Une action est identifiée par une chaîne unique en tant que premier paramètre de BindAction et UnbindAction.La chaîne peut être n'importe quoi, mais elle doit refléter l'action effectuée, pas l'entrée utilisée .Par exemple, n'utilisez pas « KeyH » comme nom d'action - utilisez plutôt « CarHorn ».Il est préférable de définir vos actions comme une constante en haut de votre script puisque vous les utiliserez dans au moins trois endroits différents de votre code.

Lier des actions contextuellement

Il vaut mieux utiliser ContextActionService's BindAction que UserInputService.InputBegan pour la plupart des cas.Pour UserInputService.InputBegan , votre fonction connectée devrait vérifier si le joueur est dans le contexte de l'action effectuée.Dans la plupart des cas, c'est plus difficile que d'appeler simplement une fonction lorsqu'un contexte est entré/quitté.Par exemple, si vous voulez que la touche H déclenche un son de klaxon de voiture pendant que le joueur s'y trouve, le joueur peut saisir « bonjour » dans le chat ou utiliser la touche H pour autre chose.Il est plus difficile de déterminer si quelque chose d'autre utilise la touche H (comme le chat) - la voiture peut sonner quand le joueur ne le voulait pas.Si vous utilisez plutôt BindAction et UnbindAction lorsque le joueur entre/sort de la voiture, ContextActionService fera en sorte que les presses de touche H déclenchent l'action d'honk seulement lorsque c'est l'action la plus récemment liée.Si quelque chose d'autre (comme le chat) prend le contrôle, vous n'aurez pas à vous soucier de vérifier cela.

Inspection des actions liées

Pour voir une liste d'actions et de leurs entrées liées, vous pouvez inspecter l'onglet « Liaisons d'action » dans la console du développeur (F9 pendant le jeu).Cela montre toutes les bindings, y compris celles liées aux scripts du noyau Roblox et aux scripts de caméra/contrôle par défaut aussi.Cela est utile pour déboguer si vos actions sont liées/déliées au bon moment ou si une autre action vole l'entrée de vos actions.Par exemple, si vous essayez de lier WASD , il se peut que les scripts de mouvement par défaut se lient sur ces mêmes clés.De même, le script de contrôle de la caméra peut voler l'entrée par clic droit si le script s'exécute après le vôtre.

Saisie sans clavier

Ce service est particulièrement utile pour prendre en charge la manette de jeu et l'entrée tactile.Pour l'entrée du gamepad, vous pouvez choisir de lier le bouton B à une action qui ramène l'utilisateur au menu précédent lorsqu'il entre dans un autre menu.Pour la touche, les boutons de touche sur écran peuvent être utilisés à la place des presses de touche : ces boutons s'affichent uniquement lorsque l'action est liée, et la position, le texte et/ou les images de ces boutons peuvent être configurés via ce service.Ils sont quelque peu limités dans la quantité de personnalisation fournie par ce service ; il est généralement une meilleure idée de créer vos propres boutons sur écran en utilisant ImageButton ou TextButton .

Échantillons de code

This example properly shows how to use ContextActionService in binding user input to a contextual action. The context is the tool being equipped; the action is reloading some weapon. Test this code sample by placing it in a LocalScript parented to a Tool. When the Tool is equipped, a "Reload" action is bound, and when the Tool is unequipped the "Reload" action is unbound. When the player presses R with the Tool equipped, the message "Reloading!" will appear.

ContextActionService Tool Reload

local ContextActionService = game:GetService("ContextActionService")
local ACTION_RELOAD = "Reload"
local tool = script.Parent
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_RELOAD and inputState == Enum.UserInputState.Begin then
print("Reloading!")
end
end
tool.Equipped:Connect(function()
ContextActionService:BindAction(ACTION_RELOAD, handleAction, true, Enum.KeyCode.R)
end)
tool.Unequipped:Connect(function()
ContextActionService:UnbindAction(ACTION_RELOAD)
end)

Résumé

Méthodes

Évènements

Propriétés

Méthodes

BindAction

()

Lier une action à l'entrée de l'utilisateur donnée une fonction de traitement d'action.Lorsqu'une entrée correspondante est exécutée, la fonction du gestionnaire d'action sera appelée avec les arguments listés ci-dessous.Les éléments d'enumération d'entrée valides incluent ceux qui se trouvent dans les éléments suivre: Enum.KeyCode , Enum.UserInputType ou Enum.PlayerActions .Appellez cette fonction lorsqu'un joueur entre dans le contexte dans lequel une action peut être exécutée.Lorsque le joueur quitte le contexte, appelez UnbindAction avec le même actionName.Vous pouvez appeler manuellement la fonction de traitement des actions d'une action en utilisant CallFunction .

L'exemple de code ci-dessous montre comment un Sound peut être played alors qu'une touche ( H ), un bouton de manette de jeu ou un bouton d'écran tactile est pressé.


local ContextActionService = game:GetService("ContextActionService")
-- Un son de klaxon de voiture
local honkSound = Instance.new("Sound", workspace)
honkSound.Looped = true
honkSound.SoundId = "rbxassetid://9120386436"
local function handleAction(actionName, inputState, inputObject)
if actionName == "HonkHorn" then
if inputState == Enum.UserInputState.Begin then
honkSound:Play()
else
honkSound:Pause()
end
end
end
-- Lorsque le joueur se trouve dans le véhicule :
ContextActionService:BindAction("HonkHorn", handleAction, true, Enum.KeyCode.H, Enum.KeyCode.ButtonY)
-- Lorsque le joueur sort :
ContextActionService:UnbindAction("HonkHorn")

Paramètres du gestionnaire d'action

Les fonctions du gestionnaire d'action sont appelées avec les paramètres suivants :


<th>Type</th>
<th>Avertissement</th>
</tr>
<tr>
<td>1</td>
<td><code>chaîne</code></td>
<td>La même chaîne qui a été initialement transmise à BindAction†</td>
</tr>
<tr>
<td>2</td>
<td><code>Enum.UserInputState</code></td>
<td>L'état de l'entrée (Commencer, Changer, Terminer ou Annuler)*</td>
</tr>
<tr>
<td>3</td>
<td><code>Objet d'entrée</code></td>
<td>Un objet qui contient des informations sur l'entrée (varie en fonction de UserInputType)</td>
</tr>
#

† Cela permet à une fonction de gérer plusieurs actions à la fois, si nécessaire.:*Annuler est envoyé si une entrée était en cours et qu'une autre action était liée à l'entrée en cours, ou si l'action liée en cours était unbound.

Pile d'actions de liens

Les liens d'action se comportent comme une pile : si deux actions sont liées à la même entrée d'utilisateur, le traitement d'action le plus récemment lié sera utilisé.Si un gestionnaire d'action renvoie Enum.ContextActionResult.Pass , le gestionnaire d'action le plus récemment lié sera appelé, et ainsi de suite jusqu'à ce qu'un gestionnaire envoie l'entrée (en retournant nil ou Enum.ContextActionResult.Sink ).Lorsque UnbindAction est appelé, le gestionnaire d'action est retiré de la pile.Ce comportement de pile peut être annulé en utilisant BindActionAtPriority , où un paramètre de priorité supplémentaire après createTouchButton peut annuler l'ordre dans lequel les actions sont liées (plus élevé avant plus bas).

Boutons tactiles

En plus des types d'entrée, le troisième paramètre de cette fonction contrôle si un bouton est créé pour TouchEnabled les appareils.À la créationsdu premier bouton de touche, un ScreenGui nommé "ContextActionGui" est ajouté au PlayerGui.À l'intérieur du ScreenGui, un Frame appelé "ContextButtonFrame" est ajouté.C'est dans ce cadre que les actions liées ImageButtons sont parentées ; vous pouvez utiliser GetButton pour récupérer de tels boutons pour la personnalisation.

Paramètres

actionName: string

Une chaîne représentant l'action effectuée (par exemple, "HonkHorn" ou "OpenDoor").

Valeur par défaut : ""
functionToBind: function

La fonction de gestion des actions, appelée avec les paramètres suivants lorsque les entrées liées sont déclenchées : chaîne (actionName), Enum.UserInputState et un objet d'entrée.

Valeur par défaut : ""
createTouchButton: boolean

Si un bouton GUI doit être créé pour l'action sur les appareils d'entrée tactile.

Valeur par défaut : ""
inputTypes: Tuple

Nombre quelconque de Enum.KeyCode ou Enum.UserInputType représentant les entrées à lier à l'action.

Valeur par défaut : ""

Retours

()

Échantillons de code

This example properly shows how to use ContextActionService in binding user input to a contextual action. The context is the tool being equipped; the action is reloading some weapon. Test this code sample by placing it in a LocalScript parented to a Tool. When the Tool is equipped, a "Reload" action is bound, and when the Tool is unequipped the "Reload" action is unbound. When the player presses R with the Tool equipped, the message "Reloading!" will appear.

ContextActionService Tool Reload

local ContextActionService = game:GetService("ContextActionService")
local ACTION_RELOAD = "Reload"
local tool = script.Parent
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_RELOAD and inputState == Enum.UserInputState.Begin then
print("Reloading!")
end
end
tool.Equipped:Connect(function()
ContextActionService:BindAction(ACTION_RELOAD, handleAction, true, Enum.KeyCode.R)
end)
tool.Unequipped:Connect(function()
ContextActionService:UnbindAction(ACTION_RELOAD)
end)

This code sample uses ContextActionService to bind an action named "BoundAction" to a general action handler function on the F key. Place this in a LocalScript inside StarterPlayerScripts and press F to see the message "Handling action: BoundAction".

General Action Handler

local ContextActionService = game:GetService("ContextActionService")
local function handleAction(actionName, inputState, inputObj)
if inputState == Enum.UserInputState.Begin then
print("Handling action: " .. actionName)
print(inputObj.UserInputType)
end
-- Since this function does not return anything, this handler will
-- "sink" the input and no other action handlers will be called after
-- this one.
end
ContextActionService:BindAction("BoundAction", handleAction, false, Enum.KeyCode.F)

This code sample demonstrates how BindAction acts like a stack. It binds two actions, FirstAction (Z, X, and C keys) and SecondAction (Z and X keys) to two action handling functions. The second one will pass on a certain input (the X key).

Both actions use the Z and X keys, however the second handler will pass input only if X is pressed. So, when X is pressed, the second handler is called and then the first. The first action is also bound to the C key, and can be triggered even though the other two inputs are "covered" by the second action.

Test this code out by pasting it into a LocalScript within StarterPlayerScripts, then pressing Z, X and C. Observe which action handlers are called with what actions.

Stacked Action Handlers

local ContextActionService = game:GetService("ContextActionService")
-- Define an action handler for FirstAction
local function actionHandlerOne(actionName, inputState, _inputObj)
if inputState == Enum.UserInputState.Begin then
print("Action Handler One: " .. actionName)
end
-- This action handler returns nil, so it is assumed that
-- it properly handles the action.
end
-- Binding the action FirstAction (it's on the bottom of the stack)
ContextActionService:BindAction("FirstAction", actionHandlerOne, false, Enum.KeyCode.Z, Enum.KeyCode.X, Enum.KeyCode.C)
-- Define an action handler for SecondAction
local function actionHandlerTwo(actionName, inputState, inputObj)
if inputState == Enum.UserInputState.Begin then
print("Action Handler Two: " .. actionName)
end
if inputObj.KeyCode == Enum.KeyCode.X then
return Enum.ContextActionResult.Pass
else
-- Returning nil implicitly Sinks inputs
return Enum.ContextActionResult.Sink
end
end
-- Binding SecondAction over the first action (since it bound more recently, it is on the top of the stack)
-- Note that SecondAction uses the same keys as
ContextActionService:BindAction("SecondAction", actionHandlerTwo, false, Enum.KeyCode.Z, Enum.KeyCode.X)

BindActionAtPriority

()

BindActionAtPriority se comporte comme BindAction mais permet également d'attribuer une priorité à l'action liée.Si plusieurs actions sont liées à la même entrée, la fonction de priorité supérieure est appelée indépendamment de l'ordre dans lequel les actions ont été liées.En d'autres termes, cette fonction remplace le comportement normal "stack" de BindAction.

Paramètres

actionName: string

Une chaîne représentant l'action effectuée (par exemple, "HonkHorn" ou "OpenDoor").

Valeur par défaut : ""
functionToBind: function

La fonction de gestion des actions, appelée avec les paramètres suivants lorsque les entrées liées sont déclenchées : chaîne (actionName), Enum.UserInputState et un objet d'entrée.

Valeur par défaut : ""
createTouchButton: boolean

Si un bouton GUI doit être créé pour l'action sur les appareils d'entrée tactile.

Valeur par défaut : ""
priorityLevel: number

Le niveau de priorité auquel l'action doit être liée (plus élevé avant plus bas).

Valeur par défaut : ""
inputTypes: Tuple

Nombre quelconque de Enum.KeyCode ou Enum.UserInputType représentant les entrées à lier à l'action.

Valeur par défaut : ""

Retours

()

Échantillons de code

This code sample demonstrates how ContextActionService:BindActionAtPriority() can be used to bind actions out of order yet still have the same priority levels. Normally, BindAction() would operate on order (last bound action has highest priority), but priority levels override this. You can test this code by pasting it into a Script with RunContext = Client in ReplicatedStorage.

ContextActionService BindAction Priorities

local ContextActionService = game:GetService("ContextActionService")
local INPUT_KEY1 = Enum.KeyCode.Q
local INPUT_KEY2 = Enum.KeyCode.E
local function handleThrow(actionName: string, inputState: Enum.UserInputState, inputObject: InputObject)
if inputState ~= Enum.UserInputState.Begin then
return Enum.ContextActionResult.Pass
end
print(`Action [{actionName}] occurred. KeyCode [{inputObject.KeyCode}] pressed.`)
return Enum.ContextActionResult.Sink
end
local function handlePunch(actionName: string, inputState: Enum.UserInputState, inputObject: InputObject)
if inputState ~= Enum.UserInputState.Begin then
return Enum.ContextActionResult.Pass
end
print(`Action [{actionName}] occurred. KeyCode [{inputObject.KeyCode}] pressed.`)
return Enum.ContextActionResult.Sink
end
-- Without specifying priority, the most recently bound action is called first,
-- so pressing INPUT_KEY1 prints "Punch" and then sinks the input.
ContextActionService:BindAction("DefaultThrow", handleThrow, false, INPUT_KEY1)
ContextActionService:BindAction("DefaultPunch", handlePunch, false, INPUT_KEY1)
-- Here we bind both functions in the same order as above, but with explicitly swapped priorities.
-- That is, we give "Throw" a higher priority of 2 so it will be called first,
-- despite "Punch" still being bound more recently.
-- Pressing INPUT_KEY2 prints "Throw" and then sinks the input.
ContextActionService:BindActionAtPriority("PriorityThrow", handleThrow, false, 2, INPUT_KEY2)
ContextActionService:BindActionAtPriority("PriorityPunch", handlePunch, false, 1, INPUT_KEY2)

BindActivate

()

Liaison d'un Enum.KeyCode qui peut être utilisé avec un Enum.UserInputType pour activer ClickDetector événements, Tools et GuiButtons.Lorsque la clé/le bouton donné est pressé, il déclenche l'événement Mouse.Button1Down sur la souris envoyée à Tool.Equipped .Cela enclenche à son tour l'événement Tool.Activated si Tool.ManualActivationOnly n'est pas réglé sur true.Pour l'entrée du gamepad, cette fonction est appelée par les scripts de contrôle par défaut afin de lier le bouton R2 Enum.KeyCode .

Notez que le Enum.UserInputType spécifié doit être Keyboard ou Gamepad1 à travers Gamepad8 pour être valide.

Paramètres

userInputTypeForActivation: Enum.UserInputType

Doit être clavier ou manette de jeu1 via Gamepad8.

Valeur par défaut : ""
keyCodesForActivation: Tuple
Valeur par défaut : ""

Retours

()

GetAllBoundActionInfo

GetAllBoundActioninfo renvoie une table qui mappe tous les noms d'actions (ceux initialement envoyés à BindAction ) à une table renvoyée par GetBoundActionInfo lorsqu'on l'appelle avec le nom de l'action lui-même.En utilisant cette fonction, vous pouvez inspecter toutes les actions actuellement liées.Cela est utile lors du débogage de leurs niveaux de priorité ou d'ordres d'empilement.


Retours

GetBoundActionInfo

GetBoundActionInfo renvoie une table avec les clés suivantes décrivant une action liée donnée son nom.Pour obtenir les mêmes informations pour toutes les actions à la fois, utilisez GetAllBoundActionInfo .


<th>Type</th>
<th>Avertissement</th>
</tr>
<tr>
<td><code>ordre de pile</code></td><td>nombre</td>
<td>
Décrit l'index de l'action sur la pile (augmentation)
</td>
</tr>
<tr>
<td><code>niveau de priorité</code> \*</td><td>nombre</td>
<td>
Décrit le niveau <code>Class.ContextActionService:BindActionAtPriority()|priority</code> de l'action
</td>
</tr>
<tr>
<td><code>créer un bouton de toucher</code></td><td>bool</td>
<td>
Détermine si un bouton tactile doit être créé sur <code>Class.UserInputService.TouchEnabled|TouchEnabled</code> appareils
</td>
</tr>
<tr>
<td><code>types d'entrée</code></td><td>table</td>
<td>
Les types d'entrée transmis à <code>Class.ContextActionService:BindAction()|BindAction</code> pour lequel cette action sera déclencheur
</td>
</tr>
<tr>
<td><code>description</code> †</td><td>chaîne</td>
<td>
La description de l'action définie par <code>Class.ContextActionService:SetDescription()|SetDescription</code>
</td>
</tr>
<tr>
<td><code>titre</code> †</td><td>chaîne</td>
<td>
Le titre de l'action définie par <code>Class.ContextActionService:SetTitle()|SetTitle</code>
</td>
</tr>
<tr>
<td><code>image</code> †</td><td>chaîne</td>
<td>
L'image du bouton d'action défini par <code>Class.ContextActionService:SetImage()|SetImage</code>
</td>
</tr>
Nom

* Le niveau de priorité sera toujours inclus même si BindActionAtPriority n'a pas été utilisé - par défaut, il sera de 2000.

† Indique que ce champ sera nil s'il n'a pas été appelé la méthode associée pour l'action donnée.

Paramètres

actionName: string
Valeur par défaut : ""

Retours

GetCurrentLocalToolIcon

GetCurrentLocalToolIcon retournera le BackpackItem.TextureId d'un Tool actuellement equipped par le Player , ou nil s'il n'y a pas de tel outil ou si le joueur manque d'un Character.


Retours

Une chaîne de contenu de l'ID de la texture de l'outil, ou nil si on ne peut en trouver aucune.

SetDescription

()

SetDescription définira la description d'une action liée par BindAction.Dans une liste d'actions disponibles, ce serait du texte qui décrit l'action donnée.

Bien que le nom puisse suggérer que cette méthode est liée à la famille de fonctions qui personnalisent un bouton tactile pour les actions qui les créent (SetTitle, SetImage et SetPosition), cette méthode n'affecte pas un tel bouton.Cette méthode ne définit que une description textuelle d'une action, et rien de plus.

Paramètres

actionName: string

Le nom de l'action initialement transmis à BindAction.

Valeur par défaut : ""
description: string

Une description textuelle de l'action, comme « Honk the car's horn » ou « Ouvrir l'inventaire ».

Valeur par défaut : ""

Retours

()

Échantillons de code

This code sample demonstrates binding an "Inspect" action to a touch button created automatically by ContextActionService. The button is customized using SetImage(), SetTitle(), SetDescription() and SetPosition(). The button is further customized by using GetButton() to get a reference to the ImageButton itself and tinting it green by setting ImageButton.ImageColor3.

Paste this code into a LocalScript placed within StarterPlayerScripts to test it. In Studio, be sure to toggle the touch device emulator in order for the button to actually be created.

ContextActionService Touch Button

local ContextActionService = game:GetService("ContextActionService")
local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
print("Inspecting")
end
end
-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
end

SetImage

()

Cette méthode définit l'image affichée sur un bouton tactile créé par BindAction().Spécifiquement, il définit la propriété ImageLabel.Image de la ImageLabel dans le ImageButton qui serait renvoyé par GetButton .Si aucune action liée n'existe (par exemplerien n'est renvoyé par GetButton), cette fonction ne fait rien et ne lance aucune erreur.

Cette fonction fait partie d'une famille de méthodes qui personnalisent le bouton de touche d'une action. D'autres membres de cette famille incluent SetPosition et SetTitle .

Paramètres

actionName: string

Le nom de l'action initialement transmis à BindAction.

Valeur par défaut : ""
image: string

La valeur à laquelle la propriété Image devrait être configurer.

Valeur par défaut : ""

Retours

()

Échantillons de code

This code sample demonstrates binding an "Inspect" action to a touch button created automatically by ContextActionService. The button is customized using SetImage(), SetTitle(), SetDescription() and SetPosition(). The button is further customized by using GetButton() to get a reference to the ImageButton itself and tinting it green by setting ImageButton.ImageColor3.

Paste this code into a LocalScript placed within StarterPlayerScripts to test it. In Studio, be sure to toggle the touch device emulator in order for the button to actually be created.

ContextActionService Touch Button

local ContextActionService = game:GetService("ContextActionService")
local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
print("Inspecting")
end
end
-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
end

SetPosition

()

Cette méthode définit la position d'un bouton tactile créé par BindAction().Spécifiquement, il définit la propriété GuiObject.Position de la ImageButton qui serait renvoyée par GetButton .Si aucune action liée n'existe (par exemplerien n'est renvoyé par GetButton), cette fonction ne fait rien et ne lance aucune erreur.

Cette fonction fait partie d'une famille de méthodes qui personnalisent le bouton de touche d'une action. D'autres membres de cette famille incluent SetImage et SetTitle .

Paramètres

actionName: string

Le nom de l'action initialement transmis à BindAction.

Valeur par défaut : ""
position: UDim2

La position dans le cadre de bouton contextuel.

Valeur par défaut : ""

Retours

()

Échantillons de code

This code sample demonstrates binding an "Inspect" action to a touch button created automatically by ContextActionService. The button is customized using SetImage(), SetTitle(), SetDescription() and SetPosition(). The button is further customized by using GetButton() to get a reference to the ImageButton itself and tinting it green by setting ImageButton.ImageColor3.

Paste this code into a LocalScript placed within StarterPlayerScripts to test it. In Studio, be sure to toggle the touch device emulator in order for the button to actually be created.

ContextActionService Touch Button

local ContextActionService = game:GetService("ContextActionService")
local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
print("Inspecting")
end
end
-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
end

SetTitle

()

SetTitle définira le texte affiché sur un bouton tactile créé par BindAction.Spécifiquement, cela définit la propriété TextLabel.Text de un TextLabel dans le ImageButton qui serait renvoyé par GetButton .Si aucune action liée n'existe (par exemplerien n'est renvoyé par GetButton), cette fonction ne fait rien et ne lance aucune erreur.

Cette fonction fait partie d'une famille de méthodes qui personnalisent le bouton de touche d'une action. D'autres membres de cette famille incluent SetImage et SetPosition .

Paramètres

actionName: string

Le nom de l'action initialement transmis à BindAction.

Valeur par défaut : ""
title: string

Le texte à afficher sur le bouton.

Valeur par défaut : ""

Retours

()

Échantillons de code

This code sample demonstrates binding an "Inspect" action to a touch button created automatically by ContextActionService. The button is customized using SetImage(), SetTitle(), SetDescription() and SetPosition(). The button is further customized by using GetButton() to get a reference to the ImageButton itself and tinting it green by setting ImageButton.ImageColor3.

Paste this code into a LocalScript placed within StarterPlayerScripts to test it. In Studio, be sure to toggle the touch device emulator in order for the button to actually be created.

ContextActionService Touch Button

local ContextActionService = game:GetService("ContextActionService")
local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
print("Inspecting")
end
end
-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
end

UnbindAction

()

UnbindAction désolidarisera une action par son nom des entrées de l'utilisateur afin que la fonction de gestionnaire d'action ne soit plus appelée.Appellez cette fonction lorsque le contexte d'une action n'est plus applicable, comme la fermeture d'une interface utilisateur, la sortie d'une voiture ou unequipping une Tool .Voir BindAction pour plus d'informations sur le fonctionnement des actions liées.

Cette fonction ne lancera pas d'erreur s'il n'y a pas d'action liée à la chaîne donnée.En utilisant GetAllBoundActionInfo ou l'onglet "Actions de la console du développeur", vous pouvez découvrir quelles actions sont actuellement liées.

Paramètres

actionName: string
Valeur par défaut : ""

Retours

()

Échantillons de code

This example properly shows how to use ContextActionService in binding user input to a contextual action. The context is the tool being equipped; the action is reloading some weapon. Test this code sample by placing it in a LocalScript parented to a Tool. When the Tool is equipped, a "Reload" action is bound, and when the Tool is unequipped the "Reload" action is unbound. When the player presses R with the Tool equipped, the message "Reloading!" will appear.

ContextActionService Tool Reload

local ContextActionService = game:GetService("ContextActionService")
local ACTION_RELOAD = "Reload"
local tool = script.Parent
local function handleAction(actionName, inputState, _inputObject)
if actionName == ACTION_RELOAD and inputState == Enum.UserInputState.Begin then
print("Reloading!")
end
end
tool.Equipped:Connect(function()
ContextActionService:BindAction(ACTION_RELOAD, handleAction, true, Enum.KeyCode.R)
end)
tool.Unequipped:Connect(function()
ContextActionService:UnbindAction(ACTION_RELOAD)
end)

UnbindActivate

()

UnbindActivate désactive un Enum.KeyCode utilisé avec un Enum.UserInputType pour activer un Tool (ou un HopperBin ) en utilisant BindActivate .Cette fonction annule essentiellement l'action effectuée par cette fonction.

Paramètres

userInputTypeForActivation: Enum.UserInputType

Le même type d'entrée utilisateur initialement envoyé à BindActivate.

Valeur par défaut : ""
keyCodeForActivation: Enum.KeyCode

Le même code clé initialement envoyé à BindActivate.

Valeur par défaut : "Unknown"

Retours

()

UnbindAllActions

()

Supprime toutes les fonctions liées.Aucun nom d'action ne restera.Tous les boutons tactiles seront supprimés.Si un bouton a été manipulé manuellement, il n'y a aucune garantie qu'il sera nettoyé.


Retours

()

GetButton

Rendement

GetButton renvoie le ImageButton créé par BindAction si son troisième paramètre était vrai et que l'appareil est TouchEnabled .Le seul paramètre de cette fonction doit correspondre exactement au nom de l'action initialement envoyée à BindAction.

Si aucune telle action n'a été liée ou si un bouton n'a pas été créé, cette fonction renvoie nil .

Paramètres

actionName: string

Le nom de l'action initialement transmis à BindAction.

Valeur par défaut : ""

Retours

Un bouton d'image créé par BindAction.

Évènements

LocalToolEquipped

Se déclenche lorsque le joueur actuel équipe un Tool .

Paramètres

toolEquipped: Instance

LocalToolUnequipped

Se déclenche lorsque le joueur actuel déséquipe un Tool .

Paramètres

toolUnequipped: Instance