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 is not 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 is not 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 are not 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

Sword Tool Example

1local tool = script.Parent
2
3local function onTouch(partOther)
4 -- First, try to see if the part we touched was part of a Humanoid
5 local humanOther = partOther.Parent:FindFirstChild("Humanoid")
6 -- Ignore touches by non-humanoids
7 if not humanOther then
8 return
9 end
10
11 -- Ignore touches by the Humanoid carrying the sword
12 if humanOther.Parent == tool.Parent then
13 return
14 end
15
16 humanOther:TakeDamage(5)
17end
18
19-- Trigger a slash animation
20local function slash()
21 -- Default character scripts will listen for a "toolanim" StringValue
22 local value = Instance.new("StringValue")
23 value.Name = "toolanim"
24 value.Value = "Slash" -- try also: Lunge
25 value.Parent = tool
26end
27
28tool.Activated:Connect(slash)
29tool.Handle.Touched:Connect(onTouch)
Explode Tool Example

1local tool = script.Parent
2
3local function explode(point)
4 local e = Instance.new("Explosion")
5 e.DestroyJointRadiusPercent = 0 -- Make the explosion non-deadly
6 e.Position = point
7 e.Parent = workspace
8end
9
10local function onActivated()
11 -- Get the Humanoid that Activated the tool
12 local human = tool.Parent.Humanoid
13 -- Call explode with the current point the Humanoid is targetting
14 explode(human.TargetPoint)
15end
16
17tool.Activated:Connect(onActivated)

Summary

Properties

Controls whether the player can drop the tool.

Relates to whether or not the tool can be used.

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

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's rotation matrix.

NOT REPLICATED

The positional offset of a Tool weld matrix.

NOT REPLICATED

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's rotation matrix.

NOT REPLICATED

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's rotation matrix.

NOT REPLICATED

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

Determines whether a Tool functions without a handle.

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

Events


Fired when the player clicks while a tool is equipped.


Fired when the left mouse button is released.


Fired when the tool is equipped.


Fired when the tool is unequipped.

Methods

Activate(): void  

Simulates a click on a Tool.

Deactivate(): void  

Simulates the deactivation of a Tool.

Properties

CanBeDropped

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 the Workspace and removed from the player's Backpack. If false, the when the backspace button is pressed the tool will go back to the player's Backpack and it will not be dropped.

Enabled

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 do not 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.

Grip

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

Unlike the grip properties that it stores, this consolidated property is not visible in the Properties window in Studio. Regardless, it can be set and retrieved using a Script or LocalScript.

GripForward

Not Replicated

The GripForward properties is 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's rotation matrix.

Other tool properties that control how a player holds a tool include: Up, Right, and Pos properties. All of these properties are stored in a single CFrame in the Tool.Grip property.

In order to change a tool's grip properties, you must either use a Script or LocalScript or a Studio plugin such as the Tool Grip Editor example.

GripPos

Not Replicated

The GripPos property controls the positional offset of a Tool weld matrix. It is one of several properties used to position how the player holds the tool.

Other tool properties that control how a player holds a tool include: Up, Right, and Forward properties. All of these properties are stored in a single CFrame in the Tool.Grip property.

In order to change a tool's grip properties, you must either use a Script or LocalScript or a plugin such as the Tool Grip Editor example.

GripRight

Not Replicated

The GripRight property is 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's rotation matrix.

Other tool properties that control how a player holds a tool include: Up, Right, and Pos properties. All of these properties are stored in a single CFrame in the Tool.Grip property.

In order to change a tool's grip properties, you must either use a Script or LocalScript or a plugin such as the Tool Grip Editor example.

GripUp

Not Replicated

The GripUp property is 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's rotation matrix.

Other tool properties that control how a player holds a tool include: Right, Forward, and Pos properties. All of these properties are stored in a single CFrame in the Tool.Grip property.

In order to change a tool's grip properties, you must either use a Script or LocalScript or a plugin such as the Tool Grip Editor example.

ManualActivationOnly

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's ContextActionService:BindActivate() function.

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

RequiresHandle

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

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:


1 tool.ToolTip = "Shovel"
2

or


1 tool.ToolTip = "Use to dig"
2

or


1 tool.ToolTip = "Shovel - Use to dig"
2

Events

Activated

Activated is not called if the Ctrl key is pressed during a click.

The Activated event fires when the player clicks while a Tool is equipped.

This function is used to perform an action when the player uses the tool. For instance, when the player clicks while a Rocket Launcher tool is equipped, the activated event executes the code to create and launch a rocket.

The below code, when placed in a LocalScript, would create a tool in the LocalPlayer's Backpack. It will print "Tool activated" when the player clicks while the created tool is equipped.


1local tool = Instance.new("Tool")
2tool.RequiresHandle = false
3tool.Parent = game.Players.LocalPlayer.Backpack
4
5function onActivation()
6 print("Tool activated")
7end
8
9tool.Activated:Connect(onActivation)
10

Code Samples

Player Fly Tool

1local Players = game:GetService("Players")
2
3local POWER = 30
4
5local bpos = Instance.new("BodyPosition")
6local gyro = Instance.new("BodyGyro")
7
8local fly = false
9local tool = nil
10
11local player = Players.LocalPlayer
12
13local character = player.Character
14if not character or not character.Parent then
15 character = player.CharacterAdded:Wait()
16end
17
18local char = character:WaitForChild("HumanoidRootPart")
19
20local mouse = player:GetMouse()
21
22local function setupTool()
23 tool = Instance.new("Tool")
24 tool.Name = "Fly"
25 tool.RequiresHandle = false
26 tool.Parent = player.Backpack
27
28 gyro.maxTorque = Vector3.new(math.huge, math.huge, math.huge)
29 bpos.maxForce = Vector3.new(math.huge, math.huge, math.huge)
30
31 tool.Parent = player.Backpack
32end
33
34setupTool()
35
36local function onSelected()
37 bpos.Parent = char
38 bpos.position = char.Position + Vector3.new(0, 10, 0)
39 gyro.Parent = char
40
41 character.Humanoid.PlatformStand = true
42
43 for _, v in ipairs(char:GetChildren()) do
44 if v.ClassName == "Motor" then
45 v.MaxVelocity = 0
46 v.CurrentAngle = -1
47 if v.Name == "Left Hip" then
48 v.CurrentAngle = 1
49 end
50 end
51 end
52
53 fly = true
54 task.wait()
55 while fly do
56 local pos = mouse.Hit.Position
57 gyro.CFrame = CFrame.new(char.Position, pos) * CFrame.fromEulerAnglesXYZ(-3.14 / 2, 0, 0)
58 bpos.Position = char.Position + (pos - char.Position).Unit * POWER
59 task.wait()
60 end
61end
62
63function onDeselected()
64 gyro.Parent = nil
65 fly = false
66
67 character.Humanoid.PlatformStand = false
68
69 for _, v in ipairs(char:GetChildren()) do
70 if v.ClassName == "Motor" then
71 v.MaxVelocity = 1
72 end
73 end
74
75 bpos.Parent = nil
76end
77
78tool.Unequipped:Connect(function()
79 fly = false
80end)
81
82tool.Activated:Connect(onSelected)
83tool.Deactivated:Connect(onDeselected)
Creating a Colorful Brick Tool

1local Players = game:GetService("Players")
2
3local player = Players.LocalPlayer
4local character = player.CharacterAdded:Wait()
5local humanoid = character.Humanoid
6
7-- Create a new randomly colored part at *pos* world position
8local function spawnPart(position)
9 local part = Instance.new("Part")
10 part.Anchored = true
11 part.Size = Vector3.new(1, 1, 1)
12 part.Position = position
13 part.Parent = game.Workspace
14 part.BrickColor = BrickColor.random()
15end
16
17-- Spawn a new part at TargetPoint when the tool is activated
18function onActivated()
19 spawnPart(humanoid.TargetPoint)
20end
21
22-- Make a new tool and handle and put it in the player's Backpack
23local function makeTool()
24 -- Create tool
25 local tool = Instance.new("Tool")
26 tool.Parent = player:WaitForChild("Backpack")
27
28 -- Create tool handle
29 local handle = Instance.new("Part")
30 handle.Name = "Handle"
31 handle.Parent = tool
32 handle.BrickColor = BrickColor.random()
33
34 -- Enable and equip tool
35 tool.Enabled = true
36 humanoid:EquipTool(tool)
37
38 -- Handle tool use
39 tool.Activated:Connect(onActivated)
40end
41
42-- Make a new tool when the LocalScript first runs
43makeTool()

Deactivated

The Deactivated event fires when the left mouse button is released while a Tool is equipped.

This function is used to perform an action when the player stops using a tool. For instance, a tool may make a player fly until they release their left mouse button.

The below code, when placed in a LocalScript, would create a tool in the LocalPlayer's Backpack. It will print "Tool deactivated" when the player releases the left mouse button, while the tool is equipped.


1local tool = Instance.new("Tool")
2tool.RequiresHandle = false
3tool.Parent = game.Players.LocalPlayer.Backpack
4
5function toolDeactivated()
6 print("Tool deactivated")
7end
8
9tool.Deactivated:Connect(toolDeactivated)
10```"
11

Code Samples

Player Fly Tool

1local Players = game:GetService("Players")
2
3local POWER = 30
4
5local bpos = Instance.new("BodyPosition")
6local gyro = Instance.new("BodyGyro")
7
8local fly = false
9local tool = nil
10
11local player = Players.LocalPlayer
12
13local character = player.Character
14if not character or not character.Parent then
15 character = player.CharacterAdded:Wait()
16end
17
18local char = character:WaitForChild("HumanoidRootPart")
19
20local mouse = player:GetMouse()
21
22local function setupTool()
23 tool = Instance.new("Tool")
24 tool.Name = "Fly"
25 tool.RequiresHandle = false
26 tool.Parent = player.Backpack
27
28 gyro.maxTorque = Vector3.new(math.huge, math.huge, math.huge)
29 bpos.maxForce = Vector3.new(math.huge, math.huge, math.huge)
30
31 tool.Parent = player.Backpack
32end
33
34setupTool()
35
36local function onSelected()
37 bpos.Parent = char
38 bpos.position = char.Position + Vector3.new(0, 10, 0)
39 gyro.Parent = char
40
41 character.Humanoid.PlatformStand = true
42
43 for _, v in ipairs(char:GetChildren()) do
44 if v.ClassName == "Motor" then
45 v.MaxVelocity = 0
46 v.CurrentAngle = -1
47 if v.Name == "Left Hip" then
48 v.CurrentAngle = 1
49 end
50 end
51 end
52
53 fly = true
54 task.wait()
55 while fly do
56 local pos = mouse.Hit.Position
57 gyro.CFrame = CFrame.new(char.Position, pos) * CFrame.fromEulerAnglesXYZ(-3.14 / 2, 0, 0)
58 bpos.Position = char.Position + (pos - char.Position).Unit * POWER
59 task.wait()
60 end
61end
62
63function onDeselected()
64 gyro.Parent = nil
65 fly = false
66
67 character.Humanoid.PlatformStand = false
68
69 for _, v in ipairs(char:GetChildren()) do
70 if v.ClassName == "Motor" then
71 v.MaxVelocity = 1
72 end
73 end
74
75 bpos.Parent = nil
76end
77
78tool.Unequipped:Connect(function()
79 fly = false
80end)
81
82tool.Activated:Connect(onSelected)
83tool.Deactivated:Connect(onDeselected)

Equipped

The Equipped event fires when a player when a player takes a Tool out of their Backpack to use. This event can be used to determine when a player stops using and puts a tool away.

This event does not fire when Tool.RequiresHandle is enabled and no handle is present.

The opposite of this event, Tool.Unequipped, can be used alongside this event to determine unequips a Tool by putting in back in their backpack.

Parameters

mouse: Mouse

The player's mouse.


Code Samples

Print when a Player Equips a Tool

1local Tool = script.Parent
2
3local function onEquipped(_mouse)
4 print("The tool was equipped")
5end
6
7Tool.Equipped:Connect(onEquipped)

Unequipped

The Unequipped event fires when a player unequips a Tool by putting in back in their Backpack. This event can be used to determine when a player stops using and puts a tool away.

This event does not fire when Tool.RequiresHandle is enabled and no handle is present.

The opposite of this event, Tool.Equipped, can be used alongside this event to determine when a player takes a tool out of their backpack to use.

The example shown below will print "A tool was unequipped" each time the tool is unequipped by the player. Please note that the below example assumes that you've already defined what "Tool" is.


1Tool.Unequipped:Connect(function()
2 print("The tool was unequipped")
3end)
4

Code Samples

Player Fly Tool

1local Players = game:GetService("Players")
2
3local POWER = 30
4
5local bpos = Instance.new("BodyPosition")
6local gyro = Instance.new("BodyGyro")
7
8local fly = false
9local tool = nil
10
11local player = Players.LocalPlayer
12
13local character = player.Character
14if not character or not character.Parent then
15 character = player.CharacterAdded:Wait()
16end
17
18local char = character:WaitForChild("HumanoidRootPart")
19
20local mouse = player:GetMouse()
21
22local function setupTool()
23 tool = Instance.new("Tool")
24 tool.Name = "Fly"
25 tool.RequiresHandle = false
26 tool.Parent = player.Backpack
27
28 gyro.maxTorque = Vector3.new(math.huge, math.huge, math.huge)
29 bpos.maxForce = Vector3.new(math.huge, math.huge, math.huge)
30
31 tool.Parent = player.Backpack
32end
33
34setupTool()
35
36local function onSelected()
37 bpos.Parent = char
38 bpos.position = char.Position + Vector3.new(0, 10, 0)
39 gyro.Parent = char
40
41 character.Humanoid.PlatformStand = true
42
43 for _, v in ipairs(char:GetChildren()) do
44 if v.ClassName == "Motor" then
45 v.MaxVelocity = 0
46 v.CurrentAngle = -1
47 if v.Name == "Left Hip" then
48 v.CurrentAngle = 1
49 end
50 end
51 end
52
53 fly = true
54 task.wait()
55 while fly do
56 local pos = mouse.Hit.Position
57 gyro.CFrame = CFrame.new(char.Position, pos) * CFrame.fromEulerAnglesXYZ(-3.14 / 2, 0, 0)
58 bpos.Position = char.Position + (pos - char.Position).Unit * POWER
59 task.wait()
60 end
61end
62
63function onDeselected()
64 gyro.Parent = nil
65 fly = false
66
67 character.Humanoid.PlatformStand = false
68
69 for _, v in ipairs(char:GetChildren()) do
70 if v.ClassName == "Motor" then
71 v.MaxVelocity = 1
72 end
73 end
74
75 bpos.Parent = nil
76end
77
78tool.Unequipped:Connect(function()
79 fly = false
80end)
81
82tool.Activated:Connect(onSelected)
83tool.Deactivated:Connect(onDeselected)

Methods

Activate

void

The Activate function simulates a click on a Tool. The Tool must be equipped for this function to work.

Tools will normally trigger the Tool.Activated event when the player releases the left mouse button, while the tool is equipped.

The below code, when placed in a LocalScript, would create a tool in the LocalPlayer's Backpack. It will simulate the tool being activated and print "Tool activated" when the player equips the tool.


1local tool = Instance.new("Tool")
2tool.RequiresHandle = false
3tool.Parent = game.Players.LocalPlayer.Backpack
4
5tool.Equipped:Connect(function()
6 tool:Activate()
7end)
8
9function toolActivated()
10 print("Tool activated")
11end
12
13tool.Activated:Connect(toolActivated)
14

Returns

void

No return.

Code Samples

Invisibility Tool

1local Players = game:GetService("Players")
2
3local player = Players.LocalPlayer
4local character = player.Character
5
6local tool = Instance.new("Tool")
7tool.Name = "Invisibility Tool"
8tool.RequiresHandle = false
9tool.Parent = player.Backpack
10
11local invisible = false
12
13local function toolActivated()
14 if invisible then
15 return
16 end
17 invisible = true
18
19 for _, bodypart in pairs(character:GetChildren()) do
20 if bodypart:IsA("MeshPart") or bodypart:IsA("Part") then
21 bodypart.Transparency = 1
22 end
23 end
24
25 task.wait(3)
26 tool:Deactivate()
27 task.wait(1)
28 invisible = false
29end
30
31local function toolDeactivated()
32 if not invisible then
33 return
34 end
35 for _, bodypart in pairs(character:GetChildren()) do
36 if bodypart.Name ~= "HumanoidRootPart" then
37 if bodypart:IsA("MeshPart") or bodypart:IsA("Part") then
38 bodypart.Transparency = 0
39 end
40 end
41 end
42end
43
44local function toolEquipped()
45 tool:Activate()
46end
47
48tool.Equipped:Connect(toolEquipped)
49tool.Activated:Connect(toolActivated)
50tool.Deactivated:Connect(toolDeactivated)
51tool.Unequipped:Connect(toolDeactivated)

Deactivate

void

The Deactivate function simulates the deactivation of a Tool. The Tool must be equipped for this function to work.

Tools will normally trigger the Tool.Deactivated event when the player releases the left mouse button, while the tool is equipped.

The below code, when placed in a LocalScript, would create a tool in the LocalPlayer's Backpack. It will simulate the tool being deactivated and print "Tool deactivated" when the player equips the tool.


1local tool = Instance.new("Tool")
2tool.RequiresHandle = false
3tool.Parent = game.Players.LocalPlayer.Backpack
4
5tool.Equipped:Connect(function()
6 tool:Deactivate()
7end)
8
9function toolDeactivated()
10 print("Tool deactivated")
11end
12
13tool.Deactivated:Connect(toolDeactivated)
14

Returns

void

No return.

Code Samples

Invisibility Tool

1local Players = game:GetService("Players")
2
3local player = Players.LocalPlayer
4local character = player.Character
5
6local tool = Instance.new("Tool")
7tool.Name = "Invisibility Tool"
8tool.RequiresHandle = false
9tool.Parent = player.Backpack
10
11local invisible = false
12
13local function toolActivated()
14 if invisible then
15 return
16 end
17 invisible = true
18
19 for _, bodypart in pairs(character:GetChildren()) do
20 if bodypart:IsA("MeshPart") or bodypart:IsA("Part") then
21 bodypart.Transparency = 1
22 end
23 end
24
25 task.wait(3)
26 tool:Deactivate()
27 task.wait(1)
28 invisible = false
29end
30
31local function toolDeactivated()
32 if not invisible then
33 return
34 end
35 for _, bodypart in pairs(character:GetChildren()) do
36 if bodypart.Name ~= "HumanoidRootPart" then
37 if bodypart:IsA("MeshPart") or bodypart:IsA("Part") then
38 bodypart.Transparency = 0
39 end
40 end
41 end
42end
43
44local function toolEquipped()
45 tool:Activate()
46end
47
48tool.Equipped:Connect(toolEquipped)
49tool.Activated:Connect(toolActivated)
50tool.Deactivated:Connect(toolDeactivated)
51tool.Unequipped:Connect(toolDeactivated)
Change Tool Color on Key Press

1local ContextActionService = game:GetService("ContextActionService")
2
3local tool = script.Parent
4
5-- Gives Handle within Tool a random BrickColor
6local function toolDeactivated()
7 tool.Handle.BrickColor = BrickColor.random()
8end
9
10-- Deactivates the tool when any key is pressed down
11local function keyPressed(_actionName, actionInputState, _actionInputObject)
12 if actionInputState == Enum.UserInputState.Begin then
13 tool:Deactivate()
14 end
15end
16
17tool.Deactivated:Connect(toolDeactivated)
18ContextActionService:BindAction("deactivateTool", keyPressed, true, "x")