Tool

Show Deprecated

Tools are objects that a Humanoid object can equip. For players, they are stored in a Backpack object parented to a Player object. In-game, players may have multiple tools which appear as icons at the bottom of the screen. Equipping a tool moves it from the Backpack and into a Player.Character model in the Workspace. By default, tools are held in the right hand and have a handle in them, which is a Part named "Handle" inside (though one isn't required if Tool.RequiresHandle is off). Tools that are to be provided to (re)spawning players ought to be stored in the StarterPack.

On desktop, pressing a number key (1, 2, 3...) will equip a tool. Equipped tools can be dropped into the Workspace by pressing Backspace. It's recommended that you turn Tool.CanBeDropped off so it isn't possible to drop a tool, die, respawn and drop again to duplicate tools. On gamepads, LB and RB buttons will equip tools. You can disable activation via left click (or right trigger on gamepad) by setting Tool.ManualActivationOnly on. Doing so requires that you call Activate yourself through some sort of other user input.

Tools aren't the only way to capture user input. You can also use ContextActionService, UserInputService or Player:GetMouse(). If you need a Tool to have multiple actions, such as pressing a key while the Tool is equipped, you should use ContextActionService's BindAction and UnbindAction in the Equipped and Unequipped events, respectively. Use a LocalScript send these actions to the server via a RemoteFunction inside the Tool.

Code Samples

Explode Tool Example
local tool = script.Parent



local function explode(point)

	local e = Instance.new("Explosion")

	e.DestroyJointRadiusPercent = 0 -- Make the explosion non-deadly

	e.Position = point

	e.Parent = workspace

end



local function onActivated()

	-- Get the Humanoid that Activated the tool

	local human = tool.Parent.Humanoid

	-- Call explode with the current point the Humanoid is targetting

	explode(human.TargetPoint)

end



tool.Activated:Connect(onActivated)
Sword Tool Example
local tool = script.Parent



local function onTouch(partOther)

	-- First, try to see if the part we touched was part of a Humanoid

	local humanOther = partOther.Parent:FindFirstChild("Humanoid")

	-- Ignore touches by non-humanoids

	if not humanOther then

		return

	end



	-- Ignore touches by the Humanoid carrying the sword

	if humanOther.Parent == tool.Parent then

		return

	end



	humanOther:TakeDamage(5)

end



-- Trigger a slash animation

local function slash()

	-- Default character scripts will listen for a "toolanim" StringValue

	local value = Instance.new("StringValue")

	value.Name = "toolanim"

	value.Value = "Slash" -- try also: Lunge

	value.Parent = tool

end



tool.Activated:Connect(slash)

tool.Handle.Touched:Connect(onTouch)

Summary

Properties

  • CanBeDropped:bool
    Read Parallel

    Controls whether the player can drop the tool.

  • Enabled:bool
    Read Parallel

    Relates to whether or not the tool can be used.

  • Grip:CFrame
    Read Parallel

    Stores the tool's "grip" properties as one CFrame.

  • GripForward:Vector3
    Hidden
    Not Replicated
    Read Parallel

    Represents the R02, R12, and R22 values of the grip CFrame rotation matrix.

  • GripPos:Vector3
    Hidden
    Not Replicated
    Read Parallel

    The positional offset of the tool's weld matrix.

  • GripRight:Vector3
    Hidden
    Not Replicated
    Read Parallel

    Represents the R00, R10, and R20 values of the grip CFrame rotation matrix.

  • GripUp:Vector3
    Hidden
    Not Replicated
    Read Parallel

    Represents the R01, R11, and R21 values of the grip CFrame rotation matrix.

  • ManualActivationOnly:bool
    Read Parallel

    The ManualActivationOnly property controls whether the Tool can be activated without executing Tool:Activate().

  • RequiresHandle:bool
    Read Parallel

    Determines whether a Tool functions without a handle.

  • ToolTip:string
    Read Parallel

    Controls the message displayed when the player's mouse hovers over the tool in their backpack.

Properties inherited from BackpackItem
  • TextureId:ContentId
    Read Parallel

    The texture icon that is displayed for a tool in the player's backpack.

Properties inherited from ModelProperties inherited from PVInstance
View all inherited from Instance
View all inherited from Object

Methods

Methods inherited from Model
  • AddPersistentPlayer(playerInstance : Player):void

    Sets this model to be persistent for the specified player. Model.ModelStreamingMode must be set to PersistentPerPlayer for behavior to be changed as a result of addition.

  • GetBoundingBox():Tuple

    Returns a description of a volume that contains all parts of a Model.

  • GetExtentsSize():Vector3

    Returns the size of the smallest bounding box that contains all of the BaseParts in the Model, aligned with the Model.PrimaryPart if it is set.

  • GetPersistentPlayers():Instances

    Returns all the Player objects that this model object is persistent for. Behavior varies based on whether this method is called from a Script or a LocalScript.

  • GetScale():number

    Returns the canonical scale of the model, which defaults to 1 for newly created models and will change as it is scaled via Model/ScaleTo.

  • MoveTo(position : Vector3):void

    Moves the PrimaryPart to the given position. If a primary part has not been specified, the root part of the model will be used.

  • RemovePersistentPlayer(playerInstance : Player):void

    Makes this model no longer persistent for specified player. Model.ModelStreamingMode must be set to PersistentPerPlayer for behavior to be changed as a result of removal.

  • ScaleTo(newScaleFactor : number):void

    Sets the scale factor of the model, adjusting the sizing and location of all descendant Instances such that they have that scale factor relative to their initial sizes and locations when scale factor was 1.

  • TranslateBy(delta : Vector3):void

    Shifts a Model by the given Vector3 offset, preserving the model's orientation. If another BasePart or Terrain already exists at the new position then the Model will overlap said object.

Methods inherited from PVInstance
View all inherited from Instance
View all inherited from Object

Events

View all inherited from Instance
View all inherited from Object

Properties

CanBeDropped

bool
Read Parallel

The CanBeDropped property controls whether the player can drop the Tool.

If true, when the backspace button is pressed, the tool will be parented to Workspace and removed from the player's Backpack. If false, nothing will happen when backspace is pressed, and the tool will remain equipped.

Enabled

bool
Read Parallel

The Enabled property relates to whether or not the Tool can be used. This is useful if you want to prevent a player from using a tool, but don't want to remove it from their Backpack.

When set to true, the player can use the tool. When set to false, the tool is disabled and the player cannot use it; this prevents the tool from being activated or deactivated by the Tool:Activate() and Tool:Deactivate() methods, and it prevents the Tool.Activated and Tool.Deactivated events from firing.

Code Samples

Superjump Tool
local Players = game:GetService("Players")



local player = Players.LocalPlayer

local character = player.Character or player.CharacterAdded:Wait()

local humanoid = character:WaitForChild("Humanoid")



local tool = Instance.new("Tool")

tool.Name = "SuperJump"

tool.RequiresHandle = false

tool.Parent = player.Backpack



function toolActivated()

	humanoid.JumpPower = 150

	tool.Enabled = false

	task.wait(5)

	tool.Enabled = true

	humanoid.JumpPower = 50

end



tool.Activated:Connect(toolActivated)

tool.Unequipped:Connect(function()

	humanoid.JumpPower = 50

end)

Grip

CFrame
Read Parallel

The Grip property stores the tool's "grip" properties as a single CFrame. These properties position how the player holds the tool and include GripUp, GripRight, GripForward, and GripPos.

Code Samples

Grip Stick
local Players = game:GetService("Players")



local player = Players.LocalPlayer



local tool = Instance.new("Tool")

tool.Name = "Stick"

tool.Parent = player.Backpack



local handle = Instance.new("Part")

handle.Name = "Handle"

handle.Parent = tool

handle.Size = Vector3.new(0.1, 3, 0.1)

handle.Color = Color3.fromRGB(108, 88, 75) -- Brown



tool.Activated:Connect(function()

	print(tool.Grip)

	print(tool.GripUp)

	print(tool.GripRight)

	print(tool.GripForward)

	print(tool.GripPos)

end)

GripForward

Vector3
Hidden
Not Replicated
Read Parallel

One of the properties that specifies a tool's orientation in a character's hand. This represents the R02, R12, and R22 values of the grip CFrame rotation matrix.

Other tool properties that control how a character holds a tool include Tool.GripUp, Tool.GripRight, and Tool.GripPos. All of these properties are stored in a single CFrame in the Tool.Grip property.

Code Samples

Grip Stick
local Players = game:GetService("Players")



local player = Players.LocalPlayer



local tool = Instance.new("Tool")

tool.Name = "Stick"

tool.Parent = player.Backpack



local handle = Instance.new("Part")

handle.Name = "Handle"

handle.Parent = tool

handle.Size = Vector3.new(0.1, 3, 0.1)

handle.Color = Color3.fromRGB(108, 88, 75) -- Brown



tool.Activated:Connect(function()

	print(tool.Grip)

	print(tool.GripUp)

	print(tool.GripRight)

	print(tool.GripForward)

	print(tool.GripPos)

end)

GripPos

Vector3
Hidden
Not Replicated
Read Parallel

This property controls the positional offset of the tool's weld matrix. It is one of several properties used to position how the player character holds the tool.

Other properties that control how a character holds a tool include Tool.GripUp, Tool.GripRight, and Tool.GripForward. All of these properties are stored in a single CFrame in the Tool.Grip property.

Code Samples

Grip Stick
local Players = game:GetService("Players")



local player = Players.LocalPlayer



local tool = Instance.new("Tool")

tool.Name = "Stick"

tool.Parent = player.Backpack



local handle = Instance.new("Part")

handle.Name = "Handle"

handle.Parent = tool

handle.Size = Vector3.new(0.1, 3, 0.1)

handle.Color = Color3.fromRGB(108, 88, 75) -- Brown



tool.Activated:Connect(function()

	print(tool.Grip)

	print(tool.GripUp)

	print(tool.GripRight)

	print(tool.GripForward)

	print(tool.GripPos)

end)

GripRight

Vector3
Hidden
Not Replicated
Read Parallel

One of the properties that specifies a tool's orientation in a character's hand. This represents the R00, R10, and R20 values of the grip CFrame rotation matrix.

Other tool properties that control how a character holds a tool include Tool.GripUp, Tool.GripForward, and Tool.GripPos. All of these properties are stored in a single CFrame in the Tool.Grip property.

Code Samples

Grip Stick
local Players = game:GetService("Players")



local player = Players.LocalPlayer



local tool = Instance.new("Tool")

tool.Name = "Stick"

tool.Parent = player.Backpack



local handle = Instance.new("Part")

handle.Name = "Handle"

handle.Parent = tool

handle.Size = Vector3.new(0.1, 3, 0.1)

handle.Color = Color3.fromRGB(108, 88, 75) -- Brown



tool.Activated:Connect(function()

	print(tool.Grip)

	print(tool.GripUp)

	print(tool.GripRight)

	print(tool.GripForward)

	print(tool.GripPos)

end)

GripUp

Vector3
Hidden
Not Replicated
Read Parallel

One of the properties that specifies a tool's orientation in a character's hand. This represents the R01, R11, and R21 values of the grip CFrame rotation matrix.

Other tool properties that control how a character holds a tool include Tool.GripRight, Tool.GripForward, and Tool.GripPos. All of these properties are stored in a single CFrame in the Tool.Grip property.

Code Samples

Grip Stick
local Players = game:GetService("Players")



local player = Players.LocalPlayer



local tool = Instance.new("Tool")

tool.Name = "Stick"

tool.Parent = player.Backpack



local handle = Instance.new("Part")

handle.Name = "Handle"

handle.Parent = tool

handle.Size = Vector3.new(0.1, 3, 0.1)

handle.Color = Color3.fromRGB(108, 88, 75) -- Brown



tool.Activated:Connect(function()

	print(tool.Grip)

	print(tool.GripUp)

	print(tool.GripRight)

	print(tool.GripForward)

	print(tool.GripPos)

end)

ManualActivationOnly

bool
Read Parallel

The ManualActivationOnly property controls whether the Tool can be activated without explicitly executing Tool:Activate() in a script.

When set to true, the tool will only fire Tool.Activated when Tool:Activate() is called. This also suppresses the ContextActionService:BindActivate() function.

When set to false, mouse clicks (when the tool is equipped) will also fire Tool.Activated.

Code Samples

Sprint Tool
local Players = game:GetService("Players")



local player = Players.LocalPlayer

local character = player.Character or player.CharacterAdded:Wait()

local humanoid = character:WaitForChild("Humanoid")



local tool = Instance.new("Tool")

tool.Name = "Sprint"

tool.RequiresHandle = false

tool.Parent = player:WaitForChild("Backpack")



function toolActivated()

	humanoid.WalkSpeed = 30

	tool.ManualActivationOnly = true

	task.wait(5)

	tool.ManualActivationOnly = false

	humanoid.WalkSpeed = 16

end



tool.Activated:Connect(toolActivated)

tool.Unequipped:Connect(function()

	humanoid.WalkSpeed = 16

end)

RequiresHandle

bool
Read Parallel

This property determines whether a Tool functions without a handle.

A tool has a handle when it contains a child part named Handle. Tools with handles typically require the player equipping them to hold an object to use them, for instance weapons. Tools without handles typically don't require the player equipping them to hold anything to use them, for instance "fly" or "summon" tools.

When set to true, the tool will function only with a handle. When set to false, the tool will function even without a handle.

ToolTip

string
Read Parallel

The ToolTip property controls the message that will be displayed when the player's Mouse hovers over the Tool in their Backpack.

Generally, the value of this property should describe the what the tool is or its use. For instance, for a shovel tool, you may choose to set the ToolTip to:

tool.ToolTip = "Shovel"

or

tool.ToolTip = "Use to dig"

or

tool.ToolTip = "Shovel - Use to dig"
View all inherited from Instance
View all inherited from Object

Methods

Activate

void

This function simulates activation of the Tool. The tool must be equipped for this function to work.


Returns

void

Code Samples

Invisibility Tool
local Players = game:GetService("Players")



local player = Players.LocalPlayer

local character = player.Character



local tool = Instance.new("Tool")

tool.Name = "Invisibility Tool"

tool.RequiresHandle = false

tool.Parent = player.Backpack



local invisible = false



local function toolActivated()

	if invisible then

		return

	end

	invisible = true



	for _, bodypart in pairs(character:GetChildren()) do

		if bodypart:IsA("MeshPart") or bodypart:IsA("Part") then

			bodypart.Transparency = 1

		end

	end



	task.wait(3)

	tool:Deactivate()

	task.wait(1)

	invisible = false

end



local function toolDeactivated()

	if not invisible then

		return

	end

	for _, bodypart in pairs(character:GetChildren()) do

		if bodypart.Name ~= "HumanoidRootPart" then

			if bodypart:IsA("MeshPart") or bodypart:IsA("Part") then

				bodypart.Transparency = 0

			end

		end

	end

end



local function toolEquipped()

	tool:Activate()

end



tool.Equipped:Connect(toolEquipped)

tool.Activated:Connect(toolActivated)

tool.Deactivated:Connect(toolDeactivated)

tool.Unequipped:Connect(toolDeactivated)

Deactivate

void

This function simulates deactivation of the Tool. The tool must be equipped for this function to work.


Returns

void

Code Samples

Invisibility Tool
local Players = game:GetService("Players")



local player = Players.LocalPlayer

local character = player.Character



local tool = Instance.new("Tool")

tool.Name = "Invisibility Tool"

tool.RequiresHandle = false

tool.Parent = player.Backpack



local invisible = false



local function toolActivated()

	if invisible then

		return

	end

	invisible = true



	for _, bodypart in pairs(character:GetChildren()) do

		if bodypart:IsA("MeshPart") or bodypart:IsA("Part") then

			bodypart.Transparency = 1

		end

	end



	task.wait(3)

	tool:Deactivate()

	task.wait(1)

	invisible = false

end



local function toolDeactivated()

	if not invisible then

		return

	end

	for _, bodypart in pairs(character:GetChildren()) do

		if bodypart.Name ~= "HumanoidRootPart" then

			if bodypart:IsA("MeshPart") or bodypart:IsA("Part") then

				bodypart.Transparency = 0

			end

		end

	end

end



local function toolEquipped()

	tool:Activate()

end



tool.Equipped:Connect(toolEquipped)

tool.Activated:Connect(toolActivated)

tool.Deactivated:Connect(toolDeactivated)

tool.Unequipped:Connect(toolDeactivated)
View all inherited from Instance
View all inherited from Object

Events

Activated

This event fires when the player clicks while the Tool is equipped. It is not fired if the Ctrl key is pressed during the click.

This event is typically used to perform an action when the player uses the tool, for instance to launch a rocket from a rocket launcher weapon tool.

The below code, when placed in a LocalScript, creates a tool in the local player's Backpack and prints "Tool activated" when the player clicks while the created tool is equipped.

local tool = Instance.new("Tool")

tool.RequiresHandle = false

tool.Parent = game.Players.LocalPlayer.Backpack



function onActivation()

	print("Tool activated")

end



tool.Activated:Connect(onActivation)

Deactivated

This event fires when the player releases their click while the Tool is equipped and activated. It is typically used to perform an action when the player stops using a tool.

The below code, when placed in a LocalScript, creates a tool in the local player's Backpack and prints "Tool deactivated" when the player releases their click while the tool is equipped and activated.

local tool = Instance.new("Tool")

tool.RequiresHandle = false

tool.Parent = game.Players.LocalPlayer.Backpack



function toolDeactivated()

	print("Tool deactivated")

end



tool.Deactivated:Connect(toolDeactivated)

Equipped

This event fires when a player equips the Tool (takes it out of their Backpack).

The opposite of this event, Tool.Unequipped, can be used to determine when the player unequips the tool by putting it in their backpack.

Note that this event does not fire when Tool.RequiresHandle is enabled and no handle is present.

Parameters

mouse: Mouse

The player's mouse.


Code Samples

Print when a Player Equips a Tool
local Tool = script.Parent



local function onEquipped(_mouse)

	print("The tool was equipped")

end



Tool.Equipped:Connect(onEquipped)

Unequipped

This event fires when a player unequips the Tool (puts it in their Backpack).

The opposite of this event, Tool.Equipped, can be used to determine when the player equips the tool by taking it out of their backpack.

Note that this event does not fire when Tool.RequiresHandle is enabled and no handle is present.


View all inherited from Instance
View all inherited from Object