ContextActionService

Vincule una acción a la entrada del usuario dada una función de manejo de acciones.Una vez que se realice una entrada coincidente, se llamará la función del manejador de acciones con los argumentos enumerados a continuación.Los elementos de enumeración de entrada válidos incluyen los siguiendo: Enum.KeyCode, Enum.UserInputType o Enum.PlayerActions .Llama a esta función cuando un jugador entra en el contexto en el que se puede realizar una acción.Cuando el jugador abandona el contexto, llama UnbindAction con el mismo actionName.Puedes llamar manualmente la función de manejo de acciones de una acción usando CallFunction.

El ejemplo de código a continuación muestra cómo un Sound puede ser played mientras se presiona una tecla ( H ), botón del controlador de juegos o botón de pantalla táctil.

local ContextActionService = game:GetService("ContextActionService")

-- Un sonido de bocina de coche
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

-- Cuando el jugador se sienta en el vehículo:
ContextActionService:BindAction("HonkHorn", handleAction, true, Enum.KeyCode.H, Enum.KeyCode.ButtonY)

-- Cuando el jugador sale:
ContextActionService:UnbindAction("HonkHorn")

Parámetros del manipulador de acciones

Las funciones del manipulador de acciones se llaman con los siguientes parámetros:

<th>Tipo</th>

  <th>Descripción</th>
</tr>

<tr>
  <td>1</td>

  <td><code>cadena</code></td>

  <td>La misma cadena que se pasó originalmente a BindAction†</td>
</tr>

<tr>
  <td>2</td>

  <td><code>Enum.UserInputState</code></td>

  <td>El estado de la entrada (Comenzar, Cambiar, Finalizar o Cancelar)*</td>
</tr>

<tr>
  <td>3</td>

  <td><code>Objeto de entrada</code></td>

  <td>Un objeto que contiene información sobre la entrada (varía según el tipo de entrada de usuario)</td>
</tr>

† Esto permite que una función gestione múltiples acciones a la vez, si es necesario.:*Se envía cancelar si alguna entrada estaba en progreso y otra acción se vinculó a la entrada en progreso, o si la acción de enlace en progreso era unbound.

Pila de atajos de acción

Las vinculaciones de acción se comportan como una pila: si dos acciones están vinculadas a la misma entrada de usuario, se usará el manejador de acción más recientemente vinculado .Si un manipulador de acciones devuelve Enum.ContextActionResult.Pass , se llamará al siguiente manipulador de acciones más recientemente vinculado, y así hasta que un manipulador drene la entrada (devolviendo nil o Enum.ContextActionResult.Sink ).Cuando se llama UnbindAction, el manipulador de acciones se elimina de la pila.Este comportamiento de pila se puede anular usando BindActionAtPriority , donde un parámetro de prioridad adicional después de createTouchButton puede anular el orden en que se vinculan las acciones (mayor antes de menor).

Botones táctiles

Además de los tipos de entrada, el tercer parámetro de esta función controla si se crea un botón para dispositivos TouchEnabled .Al creacionesel primer botón de toque, se agrega un ScreenGui llamado "ContextActionGui" al PlayerGui.Dentro del ScreenGui se agrega un Frame llamado "ContextButtonFrame" que se llama.Es en este marco en el que ImageButtons para acciones vinculadas son padres; puedes usar GetButton para recuperar tales botones para la personalización.

Parámetros

Devuelve

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 comporta como BindAction pero también permite asignar una prioridad a la acción vinculada.Si varias acciones están vinculadas a la misma entrada, se llama la función de prioridad más alta independientemente de la orden en que se vincularon las acciones.En otras palabras, esta función anula el comportamiento normal de "pila" de BindAction.

Parámetros

Devuelve

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)

Vincula un Enum.KeyCode que se puede usar con un Enum.UserInputType para activar eventos ClickDetector , Tools y GuiButtons .Cuando se presiona la clave/botón dada, se activa el evento Mouse.Button1Down en el ratón enviado a Tool.Equipped .Esto a su vez activa el evento Tool.Activated si Tool.ManualActivationOnly no está configurado como verdadero.Para la entrada del gamepad, esta función es llamada por los scripts de control predeterminados con el fin de vincular el botón R2 Enum.KeyCode .

Tenga en cuenta que el Enum.UserInputType especificado debe ser Keyboard o Gamepad1 a través de Gamepad8 para ser válido.

Parámetros

Devuelve

GetAllBoundActioninfo devuelve una tabla que mapea todos los nombres de acciones (aquellos que originalmente se pasaron a BindAction ) a una tabla devuelta por GetBoundActionInfo cuando se llama con el nombre de acción en sí.Al usar esta función, puedes inspeccionar todas las acciones actualmente vinculadas.Esto es útil al depurar sus niveles de prioridad o órdenes de pila.

Devuelve

GetBoundActionInfo devuelve una tabla con las siguientes claves que describen una acción vinculada dada su nombre.Para obtener la misma información para todas las acciones a la vez, use GetAllBoundActionInfo .

<th>Tipo</th>

  <th>Descripción</th>
</tr>

<tr>
  <td><code>orden de pila</code></td><td>número</td>

  <td>
    Describe el índice de la acción en la pila (aumentando)
  </td>
</tr>

<tr>
  <td><code>nivel de prioridad</code> \*</td><td>número</td>

  <td>
    Describe el nivel <code>Class.ContextActionService:BindActionAtPriority()|priority</code> de la acción
  </td>
</tr>

<tr>
  <td><code>crear botón de toque</code></td><td>bool</td>

  <td>
    Describe si debe crearse un botón táctil en <code>Class.UserInputService.TouchEnabled|TouchEnabled</code> dispositivos
  </td>
</tr>

<tr>
  <td><code>tipos de entrada</code></td><td>tabla</td>

  <td>
    Los tipos de entrada pasados a <code>Class.ContextActionService:BindAction()|BindAction</code> para los cuales se desencadenadoresta acción
  </td>
</tr>

<tr>
  <td><code>descripción</code> †</td><td>cadena</td>

  <td>
    La descripción de la acción establecida por <code>Class.ContextActionService:SetDescription()|SetDescription</code>
  </td>
</tr>

<tr>
  <td><code>título</code> †</td><td>cadena</td>

  <td>
    El título del conjunto de acciones establecido por <code>Class.ContextActionService:SetTitle()|SetTitle</code>
  </td>
</tr>

<tr>
  <td><code>imagen</code> †</td><td>cadena</td>

  <td>
    La imagen del botón de toque de la acción establecido por <code>Class.ContextActionService:SetImage()|SetImage</code>
  </td>
</tr>

:* El nivel de prioridad seguirá incluyéndose incluso si BindActionAtPriority no se usó - por defecto será 2000.

† Indica que este campo será nil si el método asociado no se llamó para la acción dada.

Parámetros

Devuelve

GetCurrentLocalToolIcon devolverá el BackpackItem.TextureId de un Tool actualmente equipped por el Player , o nil si no hay tal herramienta o si el jugador carece de una Character .

Devuelve

SetDescription establecerá la descripción de una acción vinculada por BindAction.En una lista de acciones disponibles, este sería el texto que describe la acción dada.

Aunque el nombre pueda sugerir que este método está relacionado con la familia de funciones que personalizan un botón táctil para acciones que los crean (SetTitle, SetImage y SetPosition), este método no afecta a tal botón.Este método simplemente establece una descripción de texto de una acción, y nada más.

Parámetros

Devuelve

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

Este método establece la imagen que se muestra en un botón táctil creado por BindAction().En particular, establece la propiedad ImageLabel.Image de la ImageLabel dentro del ImageButton que se devolvería por GetButton .Si no existe tal acción vinculada (por ejemplo,nada se devuelve por GetButton), esta función no hace nada y no lanza ningún error.

Esta función es parte de una familia de métodos que personalizan el botón táctil de una acción. Otros en esta familia incluyen SetPosition y SetTitle .

Parámetros

Devuelve

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

Este método establece la posición de un botón táctil creado por BindAction() .En particular, establece la propiedad GuiObject.Position de la ImageButton que se devolvería por GetButton .Si no existe tal acción vinculada (por ejemplo,nada se devuelve por GetButton), esta función no hace nada y no lanza ningún error.

Esta función es parte de una familia de métodos que personalizan el botón táctil de una acción. Otros en esta familia incluyen SetImage y SetTitle .

Parámetros

Devuelve

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 establecerá el texto que se muestra en un botón táctil creado por BindAction.Específicamente, esto establece la propiedad TextLabel.Text de un TextLabel dentro del ImageButton que se devolvería por GetButton .Si no existe tal acción vinculada (por ejemplo,nada se devuelve por GetButton), esta función no hace nada y no lanza ningún error.

Esta función es parte de una familia de métodos que personalizan el botón táctil de una acción. Otros en esta familia incluyen SetImage y SetPosition .

Parámetros

Devuelve

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 desvinculará una acción por nombre de las entradas del usuario para que la función de manejo de acciones ya no se llame.Llama a esta función cuando el contexto para alguna acción ya no es aplicable, como cerrar una interfaz de usuario, salir de un automóvil o unequipping de un Tool.Vea BindAction para más información sobre cómo funcionan las acciones vinculadas.

Esta función no arrojará un error si no hay tal acción vinculada con la cadena dada .Al usar GetAllBoundActionInfo o la pestaña "Acciones vinculadas" de la consola del desarrollador, puedes averiguar qué acciones están actualmente vinculadas.

Parámetros

Devuelve

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)

DesvincularActivar desvincula un Enum.KeyCode usado con un Enum.UserInputType para activar un Tool (o un HopperBin ) usando BindActivate .Esta función esencialmente deshace la acción realizada por esa función.

Parámetros

Devuelve

Elimina todas las funciones vinculadas.No quedarán nombres de acción.Todos los botones de toque se eliminarán.Si un botón fue manipulado manualmente, no hay garantía de que se limpie.

Devuelve

GetButton devuelve el ImageButton creado por BindAction si su tercer parámetro era verdadero y el dispositivo es TouchEnabled .El único parámetro de esta función debe coincidir exactamente con el nombre de la acción original enviada a BindAction.

Si no se vinculó tal acción o si un botón no se creó, esta función devuelve nil .

Parámetros

Devuelve

Se enciende cuando el jugador actual se equipa con un Tool.

Parámetros

Se enciende cuando el jugador actual desequipa un Tool .

Parámetros