# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: Tool
type: class
memory_category: BaseParts
summary: |
  An object, such as a weapon, that can be equipped by a `Class.Humanoid`.
description: |
  A `Tool` is an object that a `Class.Humanoid` object can equip. For players,
  they are stored in a `Class.Backpack` object parented to a `Class.Player`
  object. In-experience, players may have multiple tools which appear as icons
  at the bottom of the screen. Equipping a tool moves it from the
  `Class.Backpack` and into a `Class.Player.Character` model in the
  `Class.Workspace`. By default, tools are held in the right hand and have a
  handle in them, which is a `Class.BasePart` named `Handle` inside (although
  one isn't required if `Class.Tool.RequiresHandle` is `false`). Tools that are
  to be provided to (re)spawning players should be stored in the
  `Class.StarterPack`.
code_samples:
  - Explode-Tool-Example
  - Sword-Tool-Example
inherits:
  - BackpackItem
descendants:
  - Flag
tags: []
deprecation_message: ''
properties:
  - name: Tool.CanBeDropped
    summary: |
      Controls whether the player can drop the tool.
    description: |
      The CanBeDropped property controls whether the player can drop the
      `Class.Tool`.

      If true, when the backspace button is pressed, the tool will be parented
      to `Class.Workspace` and removed from the player's `Class.Backpack`. If
      false, nothing will happen when backspace is pressed, and the tool will
      remain equipped.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Behavior
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Input
  - name: Tool.Enabled
    summary: |
      Relates to whether or not the tool can be used.
    description: |
      The **Enabled** property relates to whether or not the `Class.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 `Class.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 `Class.Tool:Activate()` and
      `Class.Tool:Deactivate()` methods, and it prevents the
      `Class.Tool.Activated` and `Class.Tool.Deactivated` events from firing.
    code_samples:
      - superjump-tool
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: State
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Input
  - name: Tool.Grip
    summary: |
      Stores the tool's "grip" properties as one `Datatype.CFrame`.
    description: |
      The `Grip` property stores the tool's "grip" properties as a single
      `Datatype.CFrame`. These properties position how the player holds the tool
      and include `Class.Tool.GripUp|GripUp`, `Class.Tool.GripRight|GripRight`,
      `Class.Tool.GripForward|GripForward`, and `Class.Tool.GripPos|GripPos`.
    code_samples:
      - grip-stick
    type: CFrame
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Transform
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Input
  - name: Tool.GripForward
    summary: |
      Represents the `R02`, `R12`, and `R22` values of the grip
      `Datatype.CFrame` rotation matrix.
    description: |
      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
      `Datatype.CFrame` rotation matrix.

      Other tool properties that control how a character holds a tool include
      `Class.Tool.GripUp`, `Class.Tool.GripRight`, and `Class.Tool.GripPos`. All
      of these properties are stored in a single `Datatype.CFrame` in the
      `Class.Tool.Grip` property.
    code_samples:
      - grip-stick
    type: Vector3
    tags:
      - Hidden
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Transform
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Input
  - name: Tool.GripPos
    summary: |
      The positional offset of the tool's weld matrix.
    description: |
      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
      `Class.Tool.GripUp`, `Class.Tool.GripRight`, and `Class.Tool.GripForward`.
      All of these properties are stored in a single `Datatype.CFrame` in the
      `Class.Tool.Grip` property.
    code_samples:
      - grip-stick
    type: Vector3
    tags:
      - Hidden
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Transform
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Input
  - name: Tool.GripRight
    summary: |
      Represents the `R00`, `R10`, and `R20` values of the grip
      `Datatype.CFrame` rotation matrix.
    description: |
      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
      `Datatype.CFrame` rotation matrix.

      Other tool properties that control how a character holds a tool include
      `Class.Tool.GripUp`, `Class.Tool.GripForward`, and `Class.Tool.GripPos`.
      All of these properties are stored in a single `Datatype.CFrame` in the
      `Class.Tool.Grip` property.
    code_samples:
      - grip-stick
    type: Vector3
    tags:
      - Hidden
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Transform
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Input
  - name: Tool.GripUp
    summary: |
      Represents the `R01`, `R11`, and `R21` values of the grip
      `Datatype.CFrame` rotation matrix.
    description: |
      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
      `Datatype.CFrame` rotation matrix.

      Other tool properties that control how a character holds a tool include
      `Class.Tool.GripRight`, `Class.Tool.GripForward`, and
      `Class.Tool.GripPos`. All of these properties are stored in a single
      `Datatype.CFrame` in the `Class.Tool.Grip` property.
    code_samples:
      - grip-stick
    type: Vector3
    tags:
      - Hidden
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Transform
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Input
  - name: Tool.ManualActivationOnly
    summary: |
      Controls whether the `Class.Tool` can be activated without executing
      `Class.Tool:Activate()`.
    description: |
      This property controls whether the `Class.Tool` can be activated without
      explicitly executing `Class.Tool:Activate()` in a script.

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

      When set to `false`, mouse clicks (when the tool is equipped) will also
      fire `Class.Tool.Activated`.
    code_samples:
      - sprint-tool
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Behavior
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Input
  - name: Tool.RequiresHandle
    summary: |
      Determines whether a `Class.Tool` functions without a handle.
    description: |
      This property determines whether a `Class.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.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Behavior
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Input
  - name: Tool.ToolTip
    summary: |
      Controls the message displayed when the player's mouse hovers over the
      tool in their backpack.
    description: |
      The ToolTip property controls the message that will be displayed when the
      player's `Class.Mouse` hovers over the `Class.Tool` in their
      `Class.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:

      ```lua
      tool.ToolTip = "Shovel"
      ```

      or

      ```lua
      tool.ToolTip = "Use to dig"
      ```

      or

      ```lua
      tool.ToolTip = "Shovel - Use to dig"
      ```
    code_samples: []
    type: string
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Input
methods:
  - name: Tool:Activate
    summary: |
      Simulates activation of the `Class.Tool`.
    description: |
      This function simulates activation of the `Class.Tool`. The tool must be
      equipped for this function to work.
    code_samples:
      - invisibility-tool
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Input
  - name: Tool:Deactivate
    summary: |
      Simulates deactivation of the `Class.Tool`.
    description: |
      This function simulates deactivation of the `Class.Tool`. The tool must be
      equipped for this function to work.
    code_samples:
      - invisibility-tool
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Input
events:
  - name: Tool.Activated
    summary: |
      Fires when the player clicks while the tool is equipped.
    description: |
      This event fires when the player clicks while the `Class.Tool` is
      equipped. It is **not** fired if the <kbd>Ctrl</kbd> 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 `Class.LocalScript`, creates a tool in
      the local player's `Class.Backpack` and prints "Tool activated" when the
      player clicks while the created tool is equipped.

      ```lua
      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)
      ```
    code_samples: []
    parameters: []
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Input
  - name: Tool.Deactivated
    summary: |
      Fires when the player releases their click while the tool is equipped and
      activated.
    description: |
      This event fires when the player releases their click while the
      `Class.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 `Class.LocalScript`, creates a tool in
      the local player's `Class.Backpack` and prints "Tool deactivated" when the
      player releases their click while the tool is equipped and activated.

      ```lua
      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)
      ```
    code_samples: []
    parameters: []
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Input
  - name: Tool.Equipped
    summary: |
      Fires when the tool is equipped.
    description: |
      This event fires when a player equips the `Class.Tool` (takes it out of
      their `Class.Backpack`).

      The opposite of this event, `Class.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 `Class.Tool.RequiresHandle` is
      enabled and no handle is present.
    code_samples:
      - Tool-Equipped1
    parameters:
      - name: mouse
        type: Mouse
        default:
        summary: |
          The player's mouse.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Input
  - name: Tool.Unequipped
    summary: |
      Fires when the tool is unequipped.
    description: |
      This event fires when a player unequips the `Class.Tool` (puts it in their
      `Class.Backpack`).

      The opposite of this event, `Class.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 `Class.Tool.RequiresHandle` is
      enabled and no handle is present.
    code_samples: []
    parameters: []
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Input
callbacks: []