Tool
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.
Échantillons de code
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)
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)
Résumé
Propriétés
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.
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.
Méthodes
Méthodes hérités de ModelSets 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.
Évènements
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.
Propriétés
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 Workspace and removed from the player's Backpack. If false, nothing will happen when backspace is pressed, and the tool will remain equipped.
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 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.
Échantillons de code
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
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.
Échantillons de code
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
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.
Échantillons de code
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
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.
Échantillons de code
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
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.
Échantillons de code
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
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.
Échantillons de code
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
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.
Échantillons de code
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
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:
tool.ToolTip = "Shovel"
or
tool.ToolTip = "Use to dig"
or
tool.ToolTip = "Shovel - Use to dig"
Méthodes
Activate
This function simulates activation of the Tool. The tool must be equipped for this function to work.
Retours
Échantillons de code
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
This function simulates deactivation of the Tool. The tool must be equipped for this function to work.
Retours
Échantillons de code
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)
Évènements
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.
Paramètres
The player's mouse.
Échantillons de code
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.