Rufous

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 Sampleslocal 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)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)SummaryControls 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.Represents the R02, R12, and R22 values of the grip
CFrame rotation matrix.The positional offset of the tool's weld matrix.Represents the R00, R10, and R20 values of the grip
CFrame rotation matrix.Represents the R01, R11, and R21 values of the grip
CFrame rotation matrix.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.The texture icon that is displayed for a tool in the player's backpack.Sets the level of detail on the model for experiences with instance
streaming enabled.Controls the model streaming behavior on Models when
instance streaming is enabled.The primary part of the Model, or nil if not explicitly set.Editor-only property used to scale the model around its pivot. Setting
this property will move the scale as though Model/ScaleTo was called on
it.Determines where the pivot of a Model which does not have a
set Model.PrimaryPart is located.Simulates activation of the Tool.Simulates deactivation of the Tool.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.Returns a description of a volume that contains all parts of a Model.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.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.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.Moves the PrimaryPart to the given position. If
a primary part has not been specified, the root part of the model will be
used.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.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.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.Gets the pivot of a PVInstance.Transforms the PVInstance along with all of its descendant
PVInstances such that the pivot is now located at the
specified CFrame.Fires when the player clicks while the tool is equipped.Fires when the player releases their click while the tool is equipped and
activated.Fires when the tool is equipped.Fires when the tool is unequipped.CanBeDroppedThe 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.EnabledThe 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 Sampleslocal 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)GripThe 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 Sampleslocal 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)GripForwardHiddenNot ReplicatedRead ParallelOne 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 Sampleslocal 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)GripPosHiddenNot ReplicatedRead ParallelThis 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 Sampleslocal 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)GripRightHiddenNot ReplicatedRead ParallelOne 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 Sampleslocal 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)GripUpHiddenNot ReplicatedRead ParallelOne 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 Sampleslocal 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)ManualActivationOnlyThe 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 Sampleslocal 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)RequiresHandleThis 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.ToolTipThe 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:

or
tool.ToolTip = "Use to dig"
or
tool.ToolTip = "Shovel - Use to dig"Properties inherited from BackpackItemProperties inherited from ModelProperties inherited from PVInstanceThis function simulates activation of the Tool. The tool must be
equipped for this function to work.ReturnsCode Sampleslocal 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)This function simulates deactivation of the Tool. The tool must be
equipped for this function to work.ReturnsCode Sampleslocal 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)Properties inherited from ModelProperties inherited from PVInstanceActivatedThis 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 Players = game:GetService("Players")
local tool = Instance.new("Tool")
tool.RequiresHandle = false
tool.Parent = Players.LocalPlayer.Backpack
function onActivation()
print("Tool activated")
end
tool.Activated:Connect(onActivation)DeactivatedThis 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 Players = game:GetService("Players")
local tool = Instance.new("Tool")
tool.RequiresHandle = false
tool.Parent = Players.LocalPlayer.Backpack
function toolDeactivated()
print("Tool deactivated")
end
tool.Deactivated:Connect(toolDeactivated)EquippedThis 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.ParametersCode Sampleslocal Tool = script.Parent
local function onEquipped(_mouse)
print("The tool was equipped")
end
Tool.Equipped:Connect(onEquipped)UnequippedThis 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.