ContextActionService

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

Retours

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)

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)

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

Retours

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)

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

Retours

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

* 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

Retours

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

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

Retours

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

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

Retours

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

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

Retours

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

Retours

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

Retours

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

Retours

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

Retours

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

Paramètres

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

Paramètres