ContextActionService

Vincule uma ação à entrada do usuário dada uma função de processamento de ação.Após uma entrada correspondente ser executada, a função de processador de ação será chamada com os argumentos listados abaixo.Itens de enumeração de entrada válidos incluem aqueles dentro do seguindo: Enum.KeyCode , Enum.UserInputType ou Enum.PlayerActions .Chame essa função quando um jogador entrar no contexto em que uma ação pode ser realizada.Quando o jogador deixa o contexto, chame UnbindAction com o mesmo actionName.Você pode chamar manualmente a função de processamento de ação de uma ação usando CallFunction.

O exemplo de código abaixo mostra como um Sound pode ser played enquanto uma chave ( H ), botão do gamepad ou botão da tela de toque é pressionado.

local ContextActionService = game:GetService("ContextActionService")

-- Um som de buzina de carro
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

-- Quando o jogador senta no veículo:
ContextActionService:BindAction("HonkHorn", handleAction, true, Enum.KeyCode.H, Enum.KeyCode.ButtonY)

-- Quando o jogador sai:
ContextActionService:UnbindAction("HonkHorn")

Parâmetros do Gerenciador de Ação

As funções do manipulador de ação são chamadas com os seguintes parâmetros:

<th>Tipo</th>

  <th>Descrição</th>
</tr>

<tr>
  <td>1</td>

  <td><code>string / cadeia / texto</code></td>

  <td>A mesma string que foi originalmente passada para BindAction†</td>
</tr>

<tr>
  <td>2</td>

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

  <td>O estado da entrada (Começar, Mudar, Finalizar ou Cancelar)*</td>
</tr>

<tr>
  <td>3</td>

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

  <td>Um objeto que contém informações sobre a entrada (varia de acordo com o tipo de entrada do usuário)</td>
</tr>

† Isso permite que uma função lidar com várias ações de uma vez, se necessário.Cancelar é enviado se alguma entrada estiver em andamento e outra ação for vinculada à entrada em andamento, ou se a ação de vinculação em andamento fosse unbound.

Pilha de Vinculações de Ação

As ligações de ação se comportam como uma pilha: se duas ações forem vinculadas ao mesmo usuário de entrada, o mais recentemente vinculado manipulador de ação será usado.Se um manipulador de ação retornar Enum.ContextActionResult.Pass, o próximo manipulador de ação mais recentemente vinculado será chamado, e assim por diante até que um manipulador afunde a entrada (retornando nil ou Enum.ContextActionResult.Sink).Quando UnbindAction é chamado, o manipulador de ação é removido da pilha.Este comportamento de pilha pode ser substituído usando BindActionAtPriority, onde um parâmetro de prioridade adicional após createTouchButton pode substituir a ordem em que as ações são vinculadas (maior antes de menor).

Botões de Toque

Além dos tipos de entrada, o terceiro parâmetro desta função controla se um botão é criado para TouchEnabled .Após a criaçõesdo primeiro botão de toque, um ScreenGui chamado "ContextActionGui" é adicionado ao PlayerGui.Dentro do ScreenGui há um Frame chamado "ContextButtonFrame" que é adicionado.É neste quadro em que ImageButtons para ações vinculadas são parentadas; você pode usar GetButton para recuperar esses botões para personalização.

Parâmetros

Devolução

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 mas também permite que uma prioridade seja atribuída à ação vinculada.Se várias ações estiverem vinculadas ao mesmo input, a função de prioridade mais alta é chamada independentemente da ordem em que as ações foram vinculadas.Em outras palavras, essa função substitui o comportamento normal de "pilha" do BindAction.

Parâmetros

Devolução

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)

Vincule um Enum.KeyCode que pode ser usado com um Enum.UserInputType para ativar ClickDetector eventos, Tools e GuiButtons.Quando a chave/botão dada é pressionada, ela dispara o evento Mouse.Button1Down no mouse enviado para Tool.Equipped .Isso, por sua vez, ativa o evento Tool.Activated se Tool.ManualActivationOnly não estiver definido como verdadeiro.Para a entrada do gamepad, esta função é chamada pelos scripts de controle padrão para vincular o BotãoR2 Enum.KeyCode .

Observe que o Enum.UserInputType especificado deve ser Keyboard ou Gamepad1 através de Gamepad8 para ser válido.

Parâmetros

Devolução

GetAllBoundActioninfo retorna uma tabela que mapeia todos os nomes de ações (aqueles originalmente enviados para BindAction ) para uma tabela retornada por GetBoundActionInfo quando chamada com o próprio nome da ação.Usando essa função, você pode inspecionar todas as ações atualmente vinculadas.Isso é útil ao depurar seus níveis de prioridade ou ordens de pilha.

Devolução

GetBoundActionInfo retorna uma tabela com as seguintes chaves que descrevem uma ação vinculada dada seu nome.Para obter a mesma informação para todas as ações de uma vez, use GetAllBoundActionInfo .

<th>Tipo</th>

  <th>Descrição</th>
</tr>

<tr>
  <td><code>ordem de pilha</code></td><td>número</td>

  <td>
    Descreve o índice da ação na pilha (aumentando)
  </td>
</tr>

<tr>
  <td><code>prioridadeLevel</code> \*</td><td>número</td>

  <td>
    Descreve o nível <code>Class.ContextActionService:BindActionAtPriority()|priority</code> da ação
  </td>
</tr>

<tr>
  <td><code>criar botão de toque</code></td><td>bool</td>

  <td>
    Descreve se um botão de toque deve ser criado em <code>Class.UserInputService.TouchEnabled|TouchEnabled</code> dispositivos
  </td>
</tr>

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

  <td>
    Os tipos de entrada passados para <code>Class.ContextActionService:BindAction()|BindAction</code> para o qual esta ação será gatilho
  </td>
</tr>

<tr>
  <td><code>descrição</code> †</td><td>string</td>

  <td>
    A descrição da ação definida por <code>Class.ContextActionService:SetDescription()|SetDescription</code>
  </td>
</tr>

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

  <td>
    O título do conjunto de ações definido por <code>Class.ContextActionService:SetTitle()|SetTitle</code>
  </td>
</tr>

<tr>
  <td><code>imagem</code> †</td><td>string</td>

  <td>
    A imagem do botão de toque da ação definido por <code>Class.ContextActionService:SetImage()|SetImage</code>
  </td>
</tr>

:* O nível de prioridade ainda será incluído mesmo se BindActionAtPriority não foi usado - por padrão, será 2000.

† Indica que este campo será nil se o método associado não foi chamado para a ação dada.

Parâmetros

Devolução

GetCurrentLocalToolIcon retornará o BackpackItem.TextureId de um Tool atualmente equipped pelo Player ou nil se não houver tal Ferramenta ou se o jogador não tiver uma Character .

Devolução

SetDescription definirá a descrição de uma ação vinculada por BindAction.Em uma lista de ações disponíveis, este seria o texto que descreve a ação dada.

Embora o nome possa sugerir que esse método está relacionado à família de funções que personalizam um botão de toque para ações que os criam (SetTitle, SetImage e SetPosition), esse método não afeta um botão como esse.Este método apenas define uma descrição de texto de uma ação e nada mais.

Parâmetros

Devolução

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 define a imagem exibida em um botão de toque criado por BindAction().Especificamente, define a propriedade ImageLabel.Image da do ImageLabel dentro do ImageButton que seria retornada pelo GetButton .Se não existe nenhuma ação vinculada assim (por exemplo,nada é retornado por GetButton), esta função não faz nada e não lança nenhum erro.

Essa função faz parte de uma família de métodos que personalizam o botão de toque de uma ação. Outros nessa família incluem SetPosition e SetTitle .

Parâmetros

Devolução

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 define a posição de um botão de toque criado por BindAction().Especificamente, define a propriedade GuiObject.Position da do ImageButton que seria retornada pelo GetButton .Se não existe nenhuma ação vinculada assim (por exemplo,nada é retornado por GetButton), esta função não faz nada e não lança nenhum erro.

Essa função faz parte de uma família de métodos que personalizam o botão de toque de uma ação. Outros nessa família incluem SetImage e SetTitle .

Parâmetros

Devolução

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

O SetTitle definirá o texto exibido em um botão de toque criado por BindAction.Especificamente, isso define a propriedade TextLabel.Text de um TextLabel dentro do ImageButton que seria retornado por GetButton .Se não existe nenhuma ação vinculada assim (por exemplo,nada é retornado por GetButton), esta função não faz nada e não lança nenhum erro.

Essa função faz parte de uma família de métodos que personalizam o botão de toque de uma ação. Outros nessa família incluem SetImage e SetPosition .

Parâmetros

Devolução

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

O UnbindAction desvinculará uma ação por nome dos inputs do usuário para que a função de processamento de ações não seja mais chamada.Chame essa função quando o contexto para alguma ação não for mais Aplicável, como fechar uma interface de usuário, sair de um carro ou unequipping de um Tool.Veja BindAction para mais informações sobre como as ações vinculadas operam.

Essa função não vai lançar um erro se não houver uma ação assim vinculada com a string / cadeia / textodada.Usando GetAllBoundActionInfo ou a aba "Action Bindings" do Console do Desenvolvedor, você pode descobrir quais ações estão atualmente vinculadas.

Parâmetros

Devolução

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)

DesvincularAtivar desvincula um Enum.KeyCode usado com um Enum.UserInputType para ativar um Tool (ou um HopperBin ) usando BindActivate .Essa função essencialmente desfaz a ação realizada por essa função.

Parâmetros

Devolução

Remove todas as funções vinculadas.Nenhum actionName permanecerá. todos os botões de toque serão removidos.Se um botão foi manipulado manualmente, não há garantia de que ele será limpo.

Devolução

GetButton retorna o ImageButton criado por BindAction se seu terceiro parâmetro for verdadeiro e o dispositivo for TouchEnabled.O único parâmetro para essa função deve exatamente corresponder ao nome da ação originalmente enviada para BindAction.

Se nenhuma ação semelhante foi vinculada ou se um botão não foi criado, esta função retorna nil .

Parâmetros

Devolução

Incêndios quando o jogador atual equipa um Tool .

Parâmetros

Dispara quando o jogador atual desequipa um Tool .

Parâmetros