This code sample includes a simple example of how the local player's
`PlayerMouse` can be retrieved using the `Class.Player:GetMouse()` function in
a `LocalScript`. This code should be placed in a `LocalScript` in
`StarterPlayerScripts`.


The PlayerMouse behaves identically to the `Class.Mouse` object that is
obtained using `Class.Tool.Equipped`. It can be accessed from
`Class.LocalScript|LocalScripts` using the local player's
`Class.Player:GetMouse()` method. Both PlayerMouse and `Class.Mouse` are
legacy APIs, superseded by `Class.UserInputService`.

The only difference between the PlayerMouse and the `Class.Mouse` object is
the PlayerMouse can be obtained using the `Class.Player:GetMouse()` method.

In most cases developers are advised to use the new `Class.UserInputService`.
However the PlayerMouse and Mouse objects remain supported for a number of
reasons. See [Input and Camera](/input) for more information
on customizing inputs in your experience.


PlayerMouse

The PlayerMouse behaves identically to the `Class.Mouse` object that is
obtained using `Class.Tool.Equipped`. Both PlayerMouse and `Class.Mouse` are
legacy APIs, superseded by `Class.UserInputService`.


**Mouse** has been superseded by `Class.UserInputService` and
`Class.ContextActionService`, which cover a broader scope, are more feature
rich, and support **cross-platform** patterns better. It remains supported
because of its widespread use, but you should strongly consider using these
alternatives.

The **Mouse** object houses various API for pointers, primarily for buttons
and raycasting. It can be accessed through `Class.Player:GetMouse()` called on
the `Class.Players.LocalPlayer` in a `Class.LocalScript`. It is also passed by
the `Class.Tool.Equipped` event.

- It is most notable for the `Class.Mouse.Icon|Icon` property, which changes
  the cursor's appearance.
- It continually raycasts the screen mouse position into the 3D world using
  the `Class.Mouse.TargetFilter|TargetFilter` property, storing the results of
  the raycast in the `Class.Mouse.Hit|Hit`, `Class.Mouse.Target|Target`, and
  `Class.Mouse.TargetSurface|TargetSurface` properties. These can be useful
  for simple cases, but `Class.WorldRoot:Raycast()` should be used in more
  complicated [raycasting](/workspace/raycasting) scenarios.
- `Class.Plugin|Plugins` can use `Class.Plugin:GetMouse()` to get a
  `Class.PluginMouse`, which behaves similarly.

```lua
-- From a LocalScript:
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
-- Setting the mouse icon
mouse.Icon = "rbxasset://SystemCursors/Wait"
```

Note:

- This object does not control/restrict pointer movement. For this, see
  `Class.UserInputService.MouseBehavior` and
  `Class.UserInputService.MouseDeltaSensitivity`.
- If two functions are connected to same input event, such as
  `Class.Mouse.Button1Down|Button1Down`, **both** functions will run when the
  event fires. There is no concept of sinking/passing input, as events don't
  support this behavior. However, `Class.ContextActionService` does have this
  behavior through `Class.ContextActionService:BindAction()|BindAction`.
- While a mouse may not be available on all platforms, Mouse will still
  function on mobile (touch) and console (gamepad), which don't typically have
  mice or pointer hardware. For explicit cross-platform behaviors, use
  `Class.UserInputService` and `Class.ContextActionService`.

  See [Input and Camera](/input) for more information on
  customizing inputs in your experience.


This event fires when the player presses their left mouse button. Note
that this can be accessed from a `Class.Tool`; for example, when placed in
a `Class.LocalScript`, the code below prints `Button1Down` whenever the
left mouse button is pressed.

```lua
local tool = script.Parent  -- Make sure this is a Tool object

tool.Equipped:Connect(function(mouse)
	mouse.Button1Down:Connect(function()
		print("Button1Down")
	end)
end)
```

You can find out the position of the mouse in world space and if it's
pointing at any `Class.BasePart` using the `Class.Mouse.Hit|Hit` and
`Class.Mouse.Target|Target` properties.


Mouse.Button1Down

Fires when the left mouse button is pressed.


This event fires when the player releases their left mouse button. Note
that this can be accessed from a `Class.Tool`; for example, when placed in
a `Class.LocalScript`, the code below prints `Button1Up` whenever the left
mouse button is released.

```lua
local tool = script.Parent  -- Make sure this is a Tool object

tool.Equipped:Connect(function(mouse)
	mouse.Button1Up:Connect(function()
		print("Button1Up")
	end)
end)
```

You can find out the position of the mouse in world space and if it's
pointing at any `Class.BasePart` using the `Class.Mouse.Hit|Hit` and
`Class.Mouse.Target|Target` properties.


Mouse.Button1Up

Fires when the left mouse button is released.


This event fires when the player presses their right mouse button. Note
that this can be accessed from a `Class.Tool`; for example, when placed in
a `Class.LocalScript`, the code below prints `Button2Down` whenever the
right mouse button is pressed.

```lua
local tool = script.Parent  -- Make sure this is a Tool object

tool.Equipped:Connect(function(mouse)
	mouse.Button2Down:Connect(function()
		print("Button2Down")
	end)
end)
```

You can find out the position of the mouse in world space and if it's
pointing at any `Class.BasePart` using the `Class.Mouse.Hit|Hit` and
`Class.Mouse.Target|Target` properties.


Mouse.Button2Down

Fires when the right mouse button is pressed.


This event fires when the player releases their right mouse button. Note
that this can be accessed from a `Class.Tool`; for example, when placed in
a `Class.LocalScript`, the code below prints `Button2Up` whenever the
right mouse button is released.

```lua
local tool = script.Parent  -- Make sure this is a Tool object

tool.Equipped:Connect(function(mouse)
	mouse.Button2Up:Connect(function()
		print("Button2Up")
	end)
end)
```

You can find out the position of the mouse in world space and if it's
pointing at any `Class.BasePart` using the `Class.Mouse.Hit|Hit` and
`Class.Mouse.Target|Target` properties.


Mouse.Button2Up

Fired when the right mouse button is released.


This example demonstrates how mouse events are passed during each frame


Fired during every heartbeat that the mouse isn't being passed to another
mouse event.

Note, this event should not be used to determine when the mouse is still.
As it fires every heartbeat it will fire between `Class.Mouse.Move`
events.

For information on how to obtain the `Class.Mouse` object, please see the
`Class.Mouse` page.

Developers can find out the position of the mouse in world-space, and if
it is pointing at any `Class.BasePart` using the `Class.Mouse.Hit` and
`Class.Mouse.Target` properties.

Note, developers are recommended to use `Class.UserInputService` instead
of the `Class.Mouse` object in new work.


Mouse.Idle

Fired during every heartbeat that the mouse isn't being passed to another
mouse event.


The below example, assuming that 'mouse' was defined, would print the key that
was pressed (e.g. "q") along with the ascii value for that key (e.g. 113).


This event fires when a Key is pressed, with the passed argument being the
key that was pressed.

Note:

- Not all keys generate this event. However, you can get around this with
  a few of the keys, "/" for example, by using the `Class.Mouse.KeyUp`
  event.
- Some keys generate the same string as other keys.
- It's possible for the string to be empty (possibly due to "\0" key
  code).


Mouse.KeyDown

Mouse.keyDown

The below example, assuming that 'mouse' was defined, would print the key that
was released (e.g. "q") along with the ascii value for that key (e.g. 113).


This event is fired when a Key is released, with the passed argument being
the key that was released.

Note:

- Not all keys generate this event. However, you can get around this with
  a few of the keys, "/" for example, by using the
  [[API:Class/Mouse/KeyUp|KeyUp]] event.
- Some keys generate the same string as other keys.
- It's possible for the string to be empty (possibly due to "\0" key
  code).


Mouse.KeyUp

The example below allows the `Class.Players.LocalPlayer|local player` to move
parts with their mouse.

When the player presses their left mouse button over a part, that part is the
`Class.Mouse.Target|mouse's target` and becomes the _point_. Until the player
releases their left mouse button, that part will move to the mouse's world
position when the player moves their mouse.

Note that the `Class.Mouse.TargetFilter` property allows the code to ignore
the part being moved when determining the mouse's world position.

The code should work as expected when placed in a `LocalScript`.


Fired when the mouse is moved.

Note, this event is fired when the mouse's position is updated, therefore
it will fire repeatedly while being moved.

For information on how to obtain the `Class.Mouse` object, please see the
`Class.Mouse` page.

Developers can find out the position of the mouse in world-space, and if
it is pointing at any `Class.BasePart` using the `Class.Mouse.Hit` and
`Class.Mouse.Target` properties.

```
mouse.Move:Connect(function()
	local position = mouse.Hit.p
	local target = mouse.Target
	print(target, position)
end)
```

Note, developers are recommended to use `Class.UserInputService` instead
of the `Class.Mouse` object in new work.


Mouse.Move

The below example assumes that you have already got the player's mouse (and
set it as a variable named 'mouse'), whether by use of a `Class.Tool`,
`Class.HopperBin` or the `Class.Player:GetMouse()` method. It will print
"Wheel went backwards!" when the player scrolls backwards.


The WheelBackward event fires when the mouse wheel is scrolled backwards.
Possible uses for this event include toggling a gun's scope in a first
person shooter (FPS) or zooming the player's camera.

This can be used alongside the scrolling forward event,
`Class.Mouse.WheelForward`.

For information on how to obtain the `Class.Mouse` object, please see the
`Class.Mouse` page.

Note, developers are recommended to use `Class.UserInputService` instead
of the `Class.Mouse` object in new work.


Mouse.WheelBackward

Fires when the mouse wheel is scrolled backwards.


The below example assumes that you have already got the player's mouse (and
set it as a variable named 'mouse'), whether by use of a `Tool`, `HopperBin`
or the `Class.Player:GetMouse()` method. It will print "Wheel went forward!"
when the player scrolls forwards.


The WheelForward event fires when the mouse wheel is scrolled forwards.
Possible uses for this event include toggling a gun's scope in a first
person shooter (FPS) or zooming the player's camera.

This can be used alongside the scrolling backward event,
`Class.Mouse.WheelBackward`.

For information on how to obtain the `Class.Mouse` object, please see the
`Class.Mouse` page.

Note, developers are recommended to use `Class.UserInputService` instead
of the `Class.Mouse` object in new work.


Mouse.WheelForward

Fires when the mouse wheel is scrolled forwards.


Mouse

The code in this sample, when placed inside a `LocalScript` within
`StarterPlayerScripts` will draw a red laser beam between the character's head
and `Class.Mouse.Hit` at all times.

Note, this beam will pass directly through obstructions in third person as the
`Mouse`'s raycasting is done from the `Class.Workspace.CurrentCamera` not the
head.


The code below visualizes the difference between `Class.Mouse.Hit` and
`Class.Mouse.Origin`. In order to do this, the code uses the
`Datatype.Vector3` positions of the hit and origin `Datatype.CFrame` values
using `.p`.

The difference is that the origin is "where the mouse came from" (its origin)
and the hit is the position where the mouse hits (is when the player presses
their mouse).

This example also visualizes that the mouse origin is very similar to the
position of the `CurrentCamera` by printing the magnitude (distance) between
the two positions.


This property indicates `Datatype.CFrame` of the mouse's position in 3D
space. Note that `Class.Mouse.TargetFilter` and its descendants will be
ignored.

Developers can get obtain the position of Hit like so:

```
local position = mouse.Hit.Position
```

Hit is often used by `Class.Tool|Tools` to fire a weapon towards the mouse
in third person.

Developers looking for the `Class.BasePart` the mouse is pointing at
should use `Class.Mouse.Target`.

#### How is Mouse.Hit calculated?

The position of the Hit CFrame is calculated as the point of intersection
between the mouse's internal `Datatype.Ray` (an extended version of
`Class.Mouse.UnitRay`) and an object in 3D space (such as a part).

The orientation of the Hit CFrame corresponds with the direction of the
`Class.Mouse.UnitRay`.

```
local unitRayDirection = mouse.UnitRay.Direction
local mouseHitDirection = mouse.Hit.lookVector
-- unitRayDirection ≈ mouseHitDirection
-- the vectors are approximately equal
```

Note, the roll of the `Class.Workspace.CurrentCamera` is not used when
calculating the orientation of the Hit `Datatype.CFrame`.

The mouse's internal ray extends for 1,000 studs. If the mouse is not
pointing at an object in 3D space (for example when pointing at the sky),
this property will be 1,000 studs away from the
`Class.Workspace.CurrentCamera`.


Mouse.Hit

The `Datatype.CFrame` of the mouse's position in 3D space.


Mouse.hit

This example changes the `Class.Players.LocalPlayer` mouse icon to look like a
dragon image.


**Icon** is a property that determines the image used as the pointer. If
blank, a default arrow is used. While the cursor hovers over a
`Class.GuiButton`, this property is temporarily ignored.

To hide the cursor entirely, **do not** use a transparent image &ndash;
instead, set `Class.UserInputService.MouseIconEnabled` to false.

For getting/setting the user mouse icon in experiences, you should use
`Class.UserInputService.MouseIcon`. `Class.Mouse.Icon` will be deprecated
after the new API for plugins to set the mouse cursor is released.

##### Designing a Cursor

The following guidelines may prove useful when creating your own mouse
cursors:

- The dimensions of the image used determines the size of the cursor.
- The dimensions of the image should not exceed 256 pixels on any axis.
- The **center** of the image is where mouse inputs are issued.
- The default mouse image is 64x64 pixels, with the mouse taking up 17x24
  pixels of space.

##### System Cursors

When using a `Class.PluginMouse` retrieved from `Class.Plugin:GetMouse()`,
you can use the following icons similar to your system's default cursors,
such as hands, arrows, I-beams, etc. You can use these with GUI events
like `Class.GuiObject.MouseEnter|MouseEnter`,
`Class.GuiObject.MouseLeave|MouseLeave`, and
`Class.GuiButton.MouseButton1Down|MouseButton1Down` to provide a
consistent Studio experience when interacting with certain kinds of GUI
components. Note that these only work for Studio plugins; they will not
work for other `Class.Mouse` objects.

<table>
    <thead>
        <tr>
            <th>Look*</th>
            <th>Asset</th>
            <th>Suggested Use</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Pointer.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Arrow</code></td>
            <td>Default clicking and selection.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-PointingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/PointingHand</code></td>
            <td>Hovering over an active link/button.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-OpenHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/OpenHand</code></td>
            <td>Hovering over a draggable item.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-GrabbingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/ClosedHand</code></td>
            <td>Dragging an item.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-IBeam.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/IBeam</code></td>
            <td>Hovering in a text field.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNS.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNS</code></td>
            <td>Hovering over a vertical resize handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeEW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeEW</code></td>
            <td>Hovering over a horizontal resize handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNESW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNESW</code></td>
            <td>Hovering over a corner resize handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNWSE.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNWSE</code></td>
            <td>Hovering over a corner resize handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeAll.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeAll</code></td>
            <td>Hovering over a multi-direction resize handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitV.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitNS</code></td>
            <td>Hovering over a vertical "split" handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitH.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitEW</code></td>
            <td>Hovering over a horizontal "split" handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Forbidden.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Forbidden</code></td>
            <td>Hovering over a locked/forbidden item.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Wait.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Wait</code></td>
            <td>Indicating an action is in progress.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Busy.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Busy</code></td>
            <td>Indicating the system is busy.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Crosshair.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Cross</code></td>
            <td>Hovering over a pinpoint selection area.</td>
        </tr>
    </tbody>
</table>

<figcaption>* These appearances are approximations &mdash; the actual look is dependent on your operating system.</figcaption>


Mouse.Icon

The content ID of the image used as the `Class.Mouse` icon.


**Icon** is a property that determines the image used as the pointer. If
blank, a default arrow is used. While the cursor hovers over a
`Class.GuiButton`, this property is temporarily ignored. This property
only supports asset URIs.

To hide the cursor entirely, **do not** use a transparent image &ndash;
instead, set `Class.UserInputService.MouseIconEnabled` to false.

For getting/setting the user mouse icon in experiences, you should use
`Class.UserInputService.MouseIcon`. `Class.Mouse.Icon` will be deprecated
after the new API for plugins to set the mouse cursor is released.

##### Designing a Cursor

The following guidelines may prove useful when creating your own mouse
cursors:

- The dimensions of the image used determines the size of the cursor.
- The dimensions of the image should not exceed 256 pixels on any axis.
- The **center** of the image is where mouse inputs are issued.
- The default mouse image is 64x64 pixels, with the mouse taking up 17x24
  pixels of space.

##### System Cursors

When using a `Class.PluginMouse` retrieved from `Class.Plugin:GetMouse()`,
you can use the following icons similar to your system's default cursors,
such as hands, arrows, I-beams, etc. You can use these with GUI events
like `Class.GuiObject.MouseEnter|MouseEnter`,
`Class.GuiObject.MouseLeave|MouseLeave`, and
`Class.GuiButton.MouseButton1Down|MouseButton1Down` to provide a
consistent Studio experience when interacting with certain kinds of GUI
components. Note that these only work for Studio plugins; they will not
work for other `Class.Mouse` objects.

<table>
    <thead>
        <tr>
            <th>Look*</th>
            <th>Asset</th>
            <th>Suggested Use</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Pointer.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Arrow</code></td>
            <td>Default clicking and selection.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-PointingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/PointingHand</code></td>
            <td>Hovering over an active link/button.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-OpenHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/OpenHand</code></td>
            <td>Hovering over a draggable item.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-GrabbingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/ClosedHand</code></td>
            <td>Dragging an item.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-IBeam.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/IBeam</code></td>
            <td>Hovering in a text field.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNS.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNS</code></td>
            <td>Hovering over a vertical resize handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeEW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeEW</code></td>
            <td>Hovering over a horizontal resize handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNESW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNESW</code></td>
            <td>Hovering over a corner resize handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNWSE.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNWSE</code></td>
            <td>Hovering over a corner resize handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeAll.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeAll</code></td>
            <td>Hovering over a multi-direction resize handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitV.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitNS</code></td>
            <td>Hovering over a vertical "split" handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitH.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitEW</code></td>
            <td>Hovering over a horizontal "split" handle.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Forbidden.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Forbidden</code></td>
            <td>Hovering over a locked/forbidden item.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Wait.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Wait</code></td>
            <td>Indicating an action is in progress.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Busy.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Busy</code></td>
            <td>Indicating the system is busy.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Crosshair.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Cross</code></td>
            <td>Hovering over a pinpoint selection area.</td>
        </tr>
    </tbody>
</table>

<figcaption>* These appearances are approximations &mdash; the actual look is dependent on your operating system.</figcaption>


Mouse.IconContent

The content of the image used as the `Class.Mouse` icon. Only supports
asset URIs.


The origin `Class.Mouse` property is a `Datatype.CFrame` indicating where
the mouse originated from. It is positioned at the
`Class.Workspace.CurrentCamera` and oriented toward the mouse's 3D
position.

`Class.Mouse.UnitRay` starts at the same position as Origin, and extends
for a stud in the same direction.

```lua
local unitRay = mouse.UnitRay
local origin = mouse.Origin
-- unitRay.Direction = origin.p
-- unitRay.Direction ≈ origin.lookVector
```

For the position of the `Class.Mouse` in 3D space, see `Class.Mouse.Hit`.


Mouse.Origin

A `Datatype.CFrame` positioned at the `Class.Workspace.CurrentCamera` and
oriented toward the mouse's 3D position.


When placed in a `LocalScript` in `StarterPlayerScripts`, the following code
changes the `Class.BasePart.BrickColor` of every `BasePart` the player clicks
on, such as the spawn location or baseplate.


The object in 3D space the `Class.Mouse|mouse` is pointing to.

Note:

- If `Class.Mouse.TargetFilter` has been set, the target filter and its
  descendants will be ignored.
- When the mouse is not pointing at a `Class.BasePart`, for example when
  it is pointing at the sky, Target will be `nil`.
- Developers looking for the position of the mouse in 3D space should use
  `Class.Mouse.Hit`.


Mouse.Target

The object in 3D space the `Class.Mouse|mouse` is pointing to.


Mouse.target

This property determines an object to be ignored by the mouse when
calculating `Class.Mouse.Hit` and `Class.Mouse.Target`. The descendants of
the object are also ignored, so it is possible to ignore multiple objects
so long as they are a descendant of the object to which this property is
set. This property is useful when filtering models containing special
effects or decorations that should not affect `Class.Mouse.Hit` or
`Class.Mouse.Target`.

This property can be set to any `Class.Instance` or `nil`, for example:

```lua
local Players = game:GetService("Players")
local Workspace = game:GetService("Workspace")

local player = Players.LocalPlayer
local mouse = player:GetMouse()
mouse.TargetFilter = Workspace.Model
```

Note that the `Class.Player.Character|Character` of the
`Class.Players.LocalPlayer` is ignored by the mouse automatically.


Mouse.TargetFilter

Determines an object (and its descendants) to be ignored when determining
`Class.Mouse.Hit` and `Class.Mouse.Target`.


The code in this sample, when placed in a `LocalScript` inside
`StarterPlayerScripts` will set the surface of any `BasePart` clicked on to a
random surface.


This property indicates the `Enum.NormalId` of the `Class.BasePart`
surface at which the mouse is pointing. This property is derived from the
world position of mouse (`Class.Mouse.Hit`) and the part toward which the
mouse is pointing (`Class.Mouse.Target`).

This property isn't meaningful when the mouse is not pointing at a part,
for example when the mouse is pointing at the sky. At the moment, this
property is set to 'Right' under these circumstances. Before using this
property, check that the mouse's target is not `nil`.

```lua
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
-- Check that there exists a part at which the mouse is pointing
if mouse.Target then
	print("The mouse is pointing to the " .. mouse.TargetSurface.Name .. " side of " .. mouse.Target.Name)
else
	print("The mouse is not pointing at anything.")
end
```


Mouse.TargetSurface

Indicates the `Enum.NormalId` of the `Class.BasePart` surface at which the
mouse is pointing.


The UnitRay property is a `Datatype.Ray` directed toward the mouse's
position in 3D space (described by `Class.Mouse.Hit`). It originates from
the `Class.Camera.CFrame|CFrame` of the `Class.Workspace.CurrentCamera`.
Like all unit rays, it has a distance of 1.

```lua
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
print(mouse.UnitRay.Direction.Magnitude) -- Always 1
```


Mouse.UnitRay

A `Datatype.Ray` directed towards the mouse's world position, originating
from the `Class.Workspace.CurrentCamera` world position.


This code sample shows how you can create a `Datatype.Vector2` representing
the `Mouse` object's position on screen (`Class.Mouse.X|X()` and
`Class.Mouse.Y|Y()`) and the size of the screen itself
(`Class.Mouse.ViewSizeX|ViewSizeX()` and `Class.Mouse.ViewSizeY|ViewSizeY()`).
Using these, you can normalize the position of the mouse on-screen such that
the top-left just under the topbar maps to (0, 0) and the bottom-right maps to
(1, 1). This normalized position is calculated and printed as the mouse moves
using the `Class.Mouse.Move|Move()` event.


The ViewSizeX property describes the horizontal component of the game
window's size in pixels.


Mouse.ViewSizeX

Describes the width of the game window in pixels.


The ViewSizeY property describes the vertical component of the game
window's size in pixels. This length includes the space used by the
topbar.


Mouse.ViewSizeY

Describes the height of the game window in pixels.


When detecting changes in the mouse's position on-screen, it is
recommended that you use `Class.ContextActionService:BindAction()` with
`Enum.UserInputType.MouseMovement` or
`Class.UserInputService.InputChanged`, which both describe the position of
the mouse using the `Class.InputObject.Position|Position` (a
`Datatype.Vector3`) of an `Class.InputObject`, instead of using this and
related properties.

The X property describes the horizontal component of the mouse's position
on the screen. The position is measured in pixels relative to the top left
corner, under the topbar. This property can be used in conjunction with
`Class.Mouse.Y` to produce a `Datatype.Vector2` representing the mouse's
position:

```lua
local position = Vector2.new(mouse.X, mouse.Y)
```

This property does not fire `Class.Object.Changed|Changed` or the signal
returned from
`Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal`. Use
the `Class.Mouse.Move` event instead.


Mouse.X

Describes the X (horizontal) component of the mouse's position on the
screen.


When detecting changes in the mouse's position on-screen, it is
recommended that you use `Class.ContextActionService:BindAction()` with
`Enum.UserInputType.MouseMovement` or
`Class.UserInputService.InputChanged`, which both describe the position of
the mouse using the `Class.InputObject.Position|Position` (a
`Datatype.Vector3`) of an `Class.InputObject`, instead of using this and
related properties.

The Y property describes the vertical component of the mouse's position on
the screen. The position is measured in pixels relative to the top left
corner, under the topbar. This property can be used in conjunction with
`Class.Mouse.X` to produce a `Datatype.Vector2` representing the mouse's
position:

```lua
local position = Vector2.new(mouse.X, mouse.Y)
```

This property does not fire `Class.Object.Changed|Changed` or the signal
returned from
`Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal`. Use
the `Class.Mouse.Move` event instead.


Mouse.Y

Describes the Y (vertical) component of the mouse's screen position.


Legacy object that contains members useful for pointer input.


`Instance` is the base class for all classes in the Roblox class hierarchy
which can be part of the `Class.DataModel` tree.

It is not possible to directly create root `Instance` objects, but the special
`Datatype.Instance.new()` constructor creates objects via code, taking the
name of the class as a parameter and returning the created object.


Demonstrates detecting changes to an instance's ancestry by connecting to the
`Class.Instance.AncestryChanged` event.

The ChangingPart's Parent is set to different values overtime. The parent of
the part is the part's ancestor, so the `Class.Instance.AncestryChanged` event
will fire whenever it changes.


Fires when this instance is reparented or when any of its ancestors is
reparented.

You can use this event to track the deletion of an instance in Studio,
such as manual deletion in the Explorer or through a plugin. If you need
to detect when an instance is destroyed using `Class.Instance:Destroy()`,
use the `Class.Instance.Destroying` event instead.


Instance.AncestryChanged

child

The instance whose `Class.Instance.Parent|Parent` property changed,
which can be this instance or a more distant ancestor, **not**
necessarily the instance the handler is connected to.


parent

The new parent of the `child` parameter.


Fires when the `Class.Instance.Parent` property of this object or one of
its ancestors is changed.


This event fires whenever any attribute is changed on the instance,
including when an attribute is set to `nil`. The name of the changed
attribute is passed to the connected function.

For example, the following code snippet connects the `attributeChanged()`
function to fire whenever one of the part's attributes changes:

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part

local function attributeChanged(attributeName)
	print(attributeName, "changed")
end

part.AttributeChanged:Connect(attributeChanged)
```

See also `Class.Instance:GetAttributeChangedSignal()` which returns an
event that fires when a specific given attribute changes.


Instance.AttributeChanged

attribute

The name of the attribute that has been changed.


Fires whenever an attribute is changed on the `Class.Instance`.


This snippet prints the names of objects as they are added to the Workspace:


Fires after an object is parented to this `Class.Instance`.

Note, when using this method on a client to detect objects created by the
server it is necessary to use `Class.Instance:WaitForChild()` when
indexing these object's descendants. This is because the object and its
descendants are not guaranteed to replicate from the server to the client
simultaneously. For example:

```
local Workspace = game:GetService("Workspace")

Workspace.ChildAdded:Connect(function(child)
	-- Use WaitForChild() since descendants may not have replicated yet
	local head = child:WaitForChild("Head")
end)
```

Note, this event only operates for immediate children of the
`Class.Instance`. For an event that captures all descendants, use
`Class.Instance.DescendantAdded`.

See also `Class.Instance.ChildRemoved`.


Instance.ChildAdded

The `Class.Instance` that has been added.


Fires after an object is parented to this `Class.Instance`.


Instance.childAdded

This snippet prints the names of objects as they are removed from the
Workspace:


Fires after a child is removed from this `Class.Instance`.

Removed refers to when an object's parent is changed from this
`Class.Instance` to something other than this `Class.Instance`. Note, this
event will also fire when a child is destroyed (using
`Class.Instance:Destroy()`) as the destroy function sets an object's
parent to `nil`.

This event only operates for immediate children of the `Class.Instance`.
For an event that captures all descendants, use
`Class.Instance.DescendantRemoving`.

See also `Class.Instance.ChildAdded`.


Instance.ChildRemoved

The `Class.Instance` that has been removed.


Fires after a child is removed from this `Class.Instance`.


This following example will print the name of any object that is added to the
Workspace:


This event fires after a descendant is added to the `Class.Instance`.

As it fires for every descendant, parenting an object to the
`Class.Instance` will fire the event for this object and all of its
descendants individually.

If you're only concerned with the **direct children** of the
`Class.Instance`, use `Class.Instance.ChildAdded` instead.

See also `Class.Instance.DescendantRemoving`.


Instance.DescendantAdded

descendant

Fires after a descendant is added to the `Class.Instance`.


The following example prints the name of any descendant as it is being removed
from the Workspace:


This event fires **immediately before** the parent `Class.Instance`
changes such that a **descendant** instance will no longer be a
descendant. `Class.Instance:Destroy()|Destroy()` changes an instance's
`Class.Instance.Parent|Parent` to `nil`, so calling that method on a
descendant of the parent will cause this event to fire.

Since this event fires **before** the descendant's removal, the parent of
the descendant will be unchanged at the time of this event firing. If the
descendant is also a **direct child** of the parent, this event will fire
before `Class.Instance.ChildRemoved`.

If a descendant has children, this event fires with the descendant first,
followed by its descendants.

#### Warning

This event fires with the descendant object that is being removed.
Attempting to set the `Class.Instance.Parent|Parent` of the descendant to
something else will fail. Below is an example that demonstrates this:

```
local Workspace = game:GetService("Workspace")

Workspace.DescendantRemoving:Connect(function(descendant)
	-- Do not manipulate the parent of the descendant in this function!
	-- This event fires BECAUSE the parent was manipulated, and the change hasn't happened yet
	-- Therefore, it is problematic to change the parent like this:
	descendant.Parent = game
end)

local part = Instance.new("Part")
part.Parent = Workspace
part.Parent = nil
```

See also `Class.Instance.DescendantAdded|DescendantAdded`.


Instance.DescendantRemoving

The `Class.Instance` that is being removed.


Fires immediately before a descendant of the `Class.Instance` is removed.


This sample demonstrates how, when using Immediate signal behavior, an
Instance being destroyed remains in place until the connected function yields.


This sample demonstrates how, when using Deferred signal behavior, an Instance
is destroyed before the signal fires.


The `Class.Instance` will never be deleted from memory while a connected
function is still using it. However, if the function yields at any point,
the `Class.Instance` and its descendants will be parented to `nil`.

If the `Class.Workspace.SignalBehavior` property is set to
`Enum.SignalBehavior.Immediate`, this event fires immediately before the
`Class.Instance` or one of its ancestors is destroyed with
`Class.Instance:Destroy()`.

If the `Class.Workspace.SignalBehavior` property is set to
`Enum.SignalBehavior.Deferred`, this event fires at the next resumption
point, which will be after the `Class.Instance` or one of its ancestors is
destroyed with `Class.Instance:Destroy()`.

With `Enum.SignalBehavior.Deferred|Deferred` behavior, connecting a script
to its own `Class.Instance.Destroying` event is problematic, as the script
will be destroyed before the callback can be called (meaning it will not
execute).

When deleting an `Class.Instance` in Studio, such as manually deleting
through the [Explorer](/studio/explorer) or through a plugin,
the `Class.Instance` isn't destroyed. Instead, the parent is set to `nil`
which you can track with `Class.Instance.AncestryChanged`.


Instance.Destroying

Fires immediately before (or is deferred until after) the instance is
destroyed via `Class.Instance:Destroy()`.


This event fires whenever any style property is changed on the instance,
including when a property is set to `nil`.

```lua
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local playerGui = player.PlayerGui
local HUDContainer = playerGui:WaitForChild("HUDContainer")
local meterBar = HUDContainer.MeterBar

local function stylePropertyChanged()
	print("Styled properties changed")
end

meterBar:StyledPropertiesChanged():Connect(stylePropertyChanged)
```


Instance.StyledPropertiesChanged

Fires whenever any style property is changed on the instance, including
when a property is set to `nil`.


This method applies a tag to the instance, with no effect if the tag is
already applied. Successfully adding a tag will fire a signal created by
`Class.CollectionService:GetInstanceAddedSignal()` with the given tag.

#### Warnings

- An instance's tags that were added client-side will be dropped if the
  server later adds or removes a tag on that instance because the server
  replicates all tags together and overwrites previous tags.

- When tagging an instance, it is common that some resources are used to
  give the tag its functionality, for example event connections or tables.
  To prevent memory leaks, it's a good idea to clean these up (disconnect,
  set to `nil`, etc.) when no longer needed for a tag. Do this when
  calling `Class.Instance:RemoveTag()`, calling
  `Class.Instance:Destroy()`, or in a function connected to a signal
  returned by `Class.CollectionService:GetInstanceRemovedSignal()`.


Instance:AddTag

The children function returns an array of the object's children.


Instance:children

Returns an array of the object's children.


This method destroys all of an instance's children and descendants.

```
local part = Instance.new("Part")

-- Add some sparkles
for i = 1, 3 do
	local sparkles = Instance.new("Sparkles")
	sparkles.Parent = part

  local sc = Instance.new("Sparkles")
  sc.Parent = sparkles
end

print("Children:", #part:GetChildren())  --> Children: 3

part:ClearAllChildren()

print("Children:", #part:GetChildren())  --> Children: 0
```

If you do not wish to destroy **all** children and descendants, use either
`Class.Instance:GetChildren()` or `Class.Instance:GetDescendants()` to
loop through those children/descendants and select what to destroy. For
example, the following code sample will destroy all
`Class.BasePart|BaseParts` descending from a `Class.Model`:

```
local Workspace = game:GetService("Workspace")

local model = Workspace:FindFirstChild("TestModel")

for _, descendant in model:GetDescendants() do
	if descendant:IsA("BasePart") then
		descendant:Destroy()
	end
end
```


Instance:ClearAllChildren

This method destroys all of an instance's children.


Demonstrates cloning a model using `Class.Instance:Clone()`.


`Clone()` creates a copy of an instance and all of its descendants,
ignoring all instances that are not
`Class.Instance.Archivable|Archivable`. The copy of the root instance is
returned by this method and its `Class.Instance.Parent|Parent` is set to
`nil`. Note that if the instance itself has
`Class.Instance.Archivable|Archivable` set to `false`, this method will
return `nil`.

If a reference property such as `Class.ObjectValue.Value` is set in a
cloned instance, the value of the copy's property depends on the
original's value:

- If a reference property refers to an instance that was **also** cloned,
  the copy will refer to the copy.
- If a reference property refers to an instance that was **not** cloned,
  the same value is maintained in the copy.


Instance:Clone

Create a copy of an instance and all its descendants, ignoring instances
that are not `Class.Instance.Archivable|Archivable`.


Instance:clone

Demonstrates destroying a Part using the `Class.Instance:Destroy()` function.

This function is the correct way to dispose of objects that are no longer
required.


Sets the `Class.Instance.Parent` property to `nil`, locks the
`Class.Instance.Parent` property, disconnects all connections, and calls
`Destroy()` on all children. This method is the correct way to dispose of
objects that are no longer required.

Disposing of unneeded objects is important, since unnecessary objects and
connections in a place use up memory which can lead to serious performance
issues over time.

As a best practice after calling `Destroy()` on an object, set any
variables referencing the object (or its descendants) to `nil`. This
prevents your code from accessing anything to do with the object.

```lua
local part = Instance.new("Part")
part.Name = "Hello, world"
part:Destroy()
-- Don't do this:
print(part.Name)  --> "Hello, world"
-- Do this to prevent the above line from working:
part = nil
```

Once an `Class.Instance` has been destroyed by this method, it cannot be
reused because the `Class.Instance.Parent` property is locked. To
**temporarily** remove an object instead of destroying it, set
`Class.Instance.Parent|Parent` to `nil`. For example:

```
local Workspace = game:GetService("Workspace")

object.Parent = nil
task.wait(2)
object.Parent = Workspace
```

To destroy an object after a set amount of time, use
`Class.Debris:AddItem()`.


Instance:Destroy

Sets the `Class.Instance.Parent` property to `nil`, locks the
`Class.Instance.Parent` property, disconnects all connections, and calls
`Destroy()` on all children.


Instance:destroy

Returns the first ancestor of the `Class.Instance` whose
`Class.Instance.Name` is equal to the given name.

This method works upwards, meaning it starts at the instance's immediate
`Class.Instance.Parent` and works up towards the `Class.DataModel`. If no
matching ancestor is found, it returns `nil`.

The following code snippet would find the first ancestor of the object
named `Car`.

```
local car = object:FindFirstAncestor("Car")
```

For variants of this method that find ancestors of a specific class,
please see `Class.Instance:FindFirstAncestorOfClass()` and
`Class.Instance:FindFirstAncestorWhichIsA()`.


Instance:FindFirstAncestor

name

The `Class.Instance.Name` to be looked for.


Returns the first ancestor of the `Class.Instance` whose
`Class.Instance.Name` is equal to the given name.


Returns the first ancestor of the `Class.Instance` whose
`Class.Object.ClassName` is equal to the given className.

This method works upwards, meaning it starts at the instance's immediate
`Class.Instance.Parent` and works up towards the `Class.DataModel`. If no
matching ancestor is found, it returns `nil`.

A common use of this method is finding the `Class.Model` a
`Class.BasePart` belongs to. For example:

```
local model = part:FindFirstAncestorOfClass("Model")
```

This method is a variant of `Class.Instance:FindFirstAncestor()` which
checks the `Class.Object.ClassName` property rather than
`Class.Instance.Name`. `Class.Instance:FindFirstAncestorWhichIsA()` also
exists, using the `Class.Object:IsA()` method instead to respect class
inheritance.


Instance:FindFirstAncestorOfClass

className

The `Class.Object.ClassName` to be looked for.


Returns the first ancestor of the `Class.Instance` whose
`Class.Object.ClassName` is equal to the given className.


Returns the first ancestor of the `Class.Instance` for whom
`Class.Object:IsA()` returns true for the given className.

This method works upwards, meaning it starts at the instance's immediate
`Class.Instance.Parent` and works up towards the `Class.DataModel`. If no
matching ancestor is found, it returns `nil`.

Unlike `Class.Instance:FindFirstAncestorOfClass()`, this method uses
`Class.Object:IsA()` which respects class inheritance. For example:

```
print(part:IsA("Part"))  --> true
print(part:IsA("BasePart"))  --> true
print(part:IsA("Instance"))  --> true
```

Therefore, the following code sample will return the first
`Class.BasePart` ancestor, regardless of if it is a `Class.WedgePart`,
`Class.MeshPart` or `Class.Part`.

```
local part = object:FindFirstAncestorWhichIsA("BasePart")
```

See also `Class.Instance:FindFirstAncestor()`.


Instance:FindFirstAncestorWhichIsA

Returns the first ancestor of the `Class.Instance` for whom
`Class.Object:IsA()` returns true for the given className.


The below would look in Workspace for an object name "Brick". If found, it
will change the name of the object to "Foo".


Returns the first child of the `Class.Instance` with the given name, or
`nil` if no such child exists. If the optional `recursive` argument is
`true`, this method searches all descendants rather than only the
immediate children of the `Class.Instance`.

#### Checking the Existence of an Object

`FindFirstChild()` is necessary if you need to verify an object exists
before continuing. Attempting to index a child by name using the dot
operator throws an error if the child doesn't exist.

```lua
local Workspace = game:GetService("Workspace")

-- The following line errors if the part doesn't exist in the workspace
Workspace.Part.Transparency = 0.5
```

A better approach is to use `FindFirstChild()` to first check for `Part`,
then use an `if` statement to run code that needs it.

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace:FindFirstChild("Part")
if part then
	part.Transparency = 0.5
end
```

#### Finding a Child Whose Name Matches a Property

Sometimes the `Class.Instance.Name|Name` of an object is the same as that
of a property of its `Class.Instance.Parent|Parent`. When using the dot
operator, properties take precedence over children if they share a name.

In the following example, a `Class.Folder` called `Color` is added to a
`Class.Part`, which also has the `Class.Part.Color` property. Notice that
`part.Color` refers to the `Datatype.Color3` property value, not the child
`Class.Folder` instance. A benefit of using
`Class.Instance:FindFirstChild()|FindFirstChild()` is that the
introduction of new properties does not impose a risk on your code.

```lua
local part = Instance.new("Part")
local folder = Instance.new("Folder")
folder.Name = "Color"
folder.Parent = part
local c1 = part.Color  -- The property
local c2 = part:FindFirstChild("Color")  -- The child folder
```

#### Performance Notes

`Class.Instance:FindFirstChild()|FindFirstChild()` takes about 20% longer
than using the dot operator and almost 8 times longer than simply storing
a reference to an object. Therefore, you should avoid calling it in
performance-dependent code such as in tight loops or functions connected
to `Class.RunService.Heartbeat` and `Class.RunService.PreRender`. Instead,
store the result in a variable, or consider using
`Class.Instance.ChildAdded|ChildAdded` or
`Class.Instance:WaitForChild()|WaitForChild()` to detect when a child of a
given name becomes available.


Instance:FindFirstChild

The `Class.Instance.Name` to be searched for.


recursive

Whether or not the search should be conducted recursively.


Returns the first child of the `Class.Instance` found with the given name.


Instance:findFirstChild

Returns the first child of the `Class.Instance` whose
`Class.Object.ClassName|ClassName` is equal to the given `className`.
Unlike `Class.Instance:FindFirstChildWhichIsA()`, this method only returns
objects whose class matches `className`, ignoring class inheritance. If no
matching child is found, this method returns `nil`.


Instance:FindFirstChildOfClass

Returns the first child of the `Class.Instance` whose
`Class.Object.ClassName|ClassName` is equal to the given class name.


Returns the first child of the `Class.Instance` for whom
`Class.Object:IsA()` returns true for the given className.

If no matching child is found, this method returns `nil`. If the optional
recursive argument is true, this method searches all descendants rather
than only the immediate children of the `Class.Instance`.

Unlike `Class.Instance:FindFirstChildOfClass()`, this method uses
`Class.Object:IsA()` which respects class inheritance. For example:

```lua
print(part:IsA("Part")) --> true
print(part:IsA("BasePart")) --> true
print(part:IsA("Instance")) --> true
```

Therefore, the following code sample will return the first
`Class.BasePart` child, regardless of if it is a `Class.WedgePart`,
`Class.MeshPart` or `Class.Part`.

```
local part = object:FindFirstChildWhichIsA("BasePart")
```

Developers looking for a child by name, should use
`Class.Instance:FindFirstChild()` instead.


Instance:FindFirstChildWhichIsA

The `Class.Object.ClassName` to be searched for.


Returns the first child of the `Class.Instance` for whom
`Class.Object:IsA()` returns true for the given className.


Returns the first descendant found with the given `Class.Instance.Name`.

This method is disabled and cannot be used. To find the first descendant
of an instance, consider using the `recursive` parameter on
`Class.Instance:FindFirstChild()` instead.


Instance:FindFirstDescendant

The `Class.Instance.Name` to search for.


Returns the first descendant found with the given `Class.Instance.Name`.


If the `Class.Instance` is an `Class.Actor`, the `Class.Actor` itself is
returned. Otherwise, its closest ancestor `Class.Actor` is returned. If no
ancestor is an `Class.Actor`, the result is `nil`.


Instance:GetActor

Returns the `Class.Actor` associated with the Instance, if any.


This method returns the value which has been assigned to the given
attribute name. If no attribute has been assigned, `nil` is returned.

For example, the following code snippet sets and then gets the value of
the instance's `InitialPosition` attribute:

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local initialPosition = instance:GetAttribute("InitialPosition")
print(initialPosition)
```

#### See Also

- `Class.Instance:SetAttribute()` which sets the attribute with the given
  name to the given value.
- `Class.Instance:GetAttributes()` which returns a dictionary of key‑value
  pairs for each of the instance's attributes.


Instance:GetAttribute

The name of the attribute being retrieved.


The value which has been assigned to the given attribute name. If no
attribute has been assigned, `nil` is returned.


Returns the value which has been assigned to the given attribute name.


This method returns an event that behaves exactly like the
`Class.Object.Changed|Changed` event, except that it only fires when the
specific given attribute changes; effectively it is similar to
`Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal()` but
for attributes.

It's generally a good idea to use this method instead of a connection to
`Class.Object.Changed|Changed` with a function that checks the attribute
name. Subsequent calls to this method on the same object with the same
attribute name return the same event.

The following code example returns a signal that fires the function
`attributeChanged()` when the part's `InitialPosition` attribute changes:

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local function attributeChanged()
	print("Attribute changed")
end

part:GetAttributeChangedSignal("InitialPosition"):Connect(attributeChanged)
```

See also `Class.Instance.AttributeChanged` which fires whenever any
attribute is changed on the instance.


Instance:GetAttributeChangedSignal

The name of the specified attribute for which the change signal is
being returned.


An event that fires when the given attribute changes.


Returns an event that fires when the given attribute changes.


This method returns a dictionary of key‑value pairs for each attribute
where the key is the attribute's name and the value is a non‑`nil` value.

For example, the following code snippet outputs an instance's attributes
and values:

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)
part:SetAttribute("CanUse", true)

for name, value in part:GetAttributes() do
	print(name .. " = " .. value)
end
```

See also `Class.Instance:GetAttribute()` which returns the value that has
been assigned to the given attribute name.


Instance:GetAttributes

A dictionary of string → variant pairs for each attribute where the
string is the name of the attribute and the variant is a non-nil
value.


Returns a dictionary of the instance's attributes.


The below would print the name of all objects currently in Workspace when ran.


Returns an array (a numerically indexed table) containing all of the
instance's direct children, or every `Class.Instance` whose
`Class.Instance.Parent|Parent` is equal to the object. The array can be
iterated upon using either a numeric or generic `for` loop:

```lua
local Workspace = game:GetService("Workspace")

-- Numeric loop example
local children = Workspace:GetChildren()
for i = 1, #children do
	local child = children[i]
	print(child.Name .. " is child number " .. i)
end
```

```lua
local Workspace = game:GetService("Workspace")

-- Generic loop example
local children = Workspace:GetChildren()
for i, child in children do
	print(child.Name .. " is child number " .. i)
end
```

Note that the returned array is **not** sorted in any particular order, so
manual sorting (for example using `Library.table.sort()`) is advised for
sorting the children returned by this method.

See also the `Class.Instance:GetDescendants()|GetDescendants()` method.


Instance:GetChildren

An array containing the instance's children.


Returns an array containing all of the instance's children.


Instance:getChildren

Instance

`Instance` is the base class for all classes in the Roblox class hierarchy
which can be part of the `Class.DataModel` tree.


/reference/engine/classes/PlayerMouse.yaml