이 코드 샘플은 로컬 플레이어의
`PlayerMouse`를 `Class.Player:GetMouse()` 함수를 사용하여
`LocalScript`에서 가져오는 간단한 예제를 포함합니다. 이 코드는
`StarterPlayerScripts`의 `LocalScript`에 배치해야 합니다.


PlayerMouse는 `Class.Tool.Equipped`를 사용하여 얻은 `Class.Mouse` 객체와 동일하게 동작합니다. 이는
로컬 플레이어의 `Class.Player:GetMouse()` 메서드를 사용하여 `Class.LocalScript|LocalScripts`에서 접근할 수 있습니다.
PlayerMouse와 `Class.Mouse`는 모두 레거시 API로, `Class.UserInputService`에 의해 대체되었습니다.

PlayerMouse와 `Class.Mouse` 객체의 유일한 차이점은 PlayerMouse가 `Class.Player:GetMouse()` 메서드를 사용하여
얻을 수 있다는 것입니다.

대부분의 경우 개발자는 새로운 `Class.UserInputService`를 사용하는 것이 좋습니다.
그러나 PlayerMouse와 Mouse 객체는 여러 가지 이유로 지원됩니다. 경험에서 입력을 사용자 지정하는 방법에 대한
자세한 내용은 [Input and Camera](/input)를 참조하십시오.


PlayerMouse

PlayerMouse는 `Class.Tool.Equipped`를 사용하여 얻은 `Class.Mouse` 객체와 동일하게 동작합니다.
PlayerMouse와 `Class.Mouse`는 모두 레거시 API로, `Class.UserInputService`에 의해 대체되었습니다.


**마우스**는 더 넓은 범위를 커버하며, 기능이 풍부하고 **크로스 플랫폼** 패턴을 더 잘 지원하는 `Class.UserInputService` 및 `Class.ContextActionService`로 대체되었습니다. 광범위하게 사용되기 때문에 여전히 지원되지만, 이러한 대안을 사용하는 것을 강력히 고려해야 합니다.

**마우스** 객체는 버튼과 레이캐스팅을 주로 위한 포인터 API를 다양하게 포함하고 있습니다. `Class.LocalScript`의 `Class.Players.LocalPlayer`에서 호출된 `Class.Player:GetMouse()`를 통해 접근할 수 있습니다. 또한 `Class.Tool.Equipped` 이벤트를 통해 전달됩니다.

- `Class.Mouse.Icon|Icon` 프로퍼티는 커서를 변경하여 가장 주목할 만합니다.
- `Class.Mouse.TargetFilter|TargetFilter` 프로퍼티를 사용하여 화면 마우스 위치를 3D 세계로 지속적으로 레이캐스트하며, 레이캐스트 결과를 `Class.Mouse.Hit|Hit`, `Class.Mouse.Target|Target`, `Class.Mouse.TargetSurface|TargetSurface` 프로퍼티에 저장합니다. 이는 간단한 경우에 유용할 수 있지만, 더 복잡한 [레이캐스팅](/workspace/raycasting) 시나리오에서는 `Class.WorldRoot:Raycast()`를 사용해야 합니다.
- `Class.Plugin|Plugins`는 `Class.Plugin:GetMouse()`를 사용하여 유사하게 동작하는 `Class.PluginMouse`를 얻을 수 있습니다.

```lua
-- 로컬 스크립트에서:
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
-- 마우스 아이콘 설정하기
mouse.Icon = "rbxasset://SystemCursors/Wait"
```
참고:

- 이 객체는 포인터 이동을 제어하거나 제한하지 않습니다. 이를 위해서는 `Class.UserInputService.MouseBehavior` 및 `Class.UserInputService.MouseDeltaSensitivity`를 참조하세요.
- 동일한 입력 이벤트에 두 개의 함수가 연결된 경우, `Class.Mouse.Button1Down|Button1Down`와 같은 경우 **두 개**의 함수가 이벤트가 발생할 때 실행됩니다. 이벤트는 이 행동을 지원하지 않으므로 입력을 흡수하거나 전달하는 개념은 없습니다. 그러나 `Class.ContextActionService`는 `Class.ContextActionService:BindAction()|BindAction`를 통해 이러한 기능을 가지고 있습니다.
- 마우스가 모든 플랫폼에서 사용 가능하지 않을 수도 있지만, 마우스나 포인터 하드웨어가 없는 모바일(터치) 및 콘솔(게임패드)에서도 마우스는 여전히 작동합니다. 명시적인 크로스 플랫폼 행동을 원하신다면 `Class.UserInputService` 및 `Class.ContextActionService`를 사용하세요.

  경험에서 입력을 사용자화하는 데 대한 추가 정보는 [입력 및 카메라](/input)를 참조하세요.

이 이벤트는 플레이어가 왼쪽 마우스 버튼을 누를 때 발생합니다. 이는 `Class.Tool`에서 접근할 수 있습니다. 예를 들어, `Class.LocalScript`에 배치된 경우, 아래의 코드는 왼쪽 마우스 버튼이 눌릴 때마다 `Button1Down`을 출력합니다.

```lua
local tool = script.Parent  -- 이것이 Tool 객체인지 확인

tool.Equipped:Connect(function(mouse)
	mouse.Button1Down:Connect(function()
		print("Button1Down")
	end)
end)
```
마우스의 월드 스페이스 위치와 `Class.BasePart`를 가리키고 있는지 확인할 수 있습니다. `Class.Mouse.Hit|Hit` 및 `Class.Mouse.Target|Target` 속성을 사용하세요.

Mouse.Button1Down

왼쪽 마우스 버튼이 눌릴 때 발생합니다.

이 이벤트는 플레이어가 왼쪽 마우스 버튼을 놓을 때 발생합니다. 이는 `Class.Tool`에서 접근할 수 있습니다. 예를 들어, `Class.LocalScript`에 배치된 경우, 아래의 코드는 왼쪽 마우스 버튼이 놓일 때마다 `Button1Up`을 출력합니다.

```lua
local tool = script.Parent  -- 이것이 Tool 객체인지 확인

tool.Equipped:Connect(function(mouse)
	mouse.Button1Up:Connect(function()
		print("Button1Up")
	end)
end)
```
마우스의 월드 스페이스 위치와 `Class.BasePart`를 가리키고 있는지 확인할 수 있습니다. `Class.Mouse.Hit|Hit` 및 `Class.Mouse.Target|Target` 속성을 사용하세요.

Mouse.Button1Up

왼쪽 마우스 버튼이 놓일 때 발생합니다.

이 이벤트는 플레이어가 오른쪽 마우스 버튼을 누를 때 발생합니다. 이는 `Class.Tool`에서 접근할 수 있습니다. 예를 들어, `Class.LocalScript`에 배치된 경우, 아래의 코드는 오른쪽 마우스 버튼이 눌릴 때마다 `Button2Down`을 출력합니다.

```lua
local tool = script.Parent  -- 이것이 Tool 객체인지 확인

tool.Equipped:Connect(function(mouse)
	mouse.Button2Down:Connect(function()
		print("Button2Down")
	end)
end)
```
마우스의 월드 스페이스 위치와 `Class.BasePart`를 가리키고 있는지 확인할 수 있습니다. `Class.Mouse.Hit|Hit` 및 `Class.Mouse.Target|Target` 속성을 사용하세요.

Mouse.Button2Down

오른쪽 마우스 버튼이 눌릴 때 발생합니다.

이 이벤트는 플레이어가 오른쪽 마우스 버튼을 놓을 때 발생합니다. 이는 `Class.Tool`에서 접근할 수 있습니다. 예를 들어, `Class.LocalScript`에 배치된 경우, 아래의 코드는 오른쪽 마우스 버튼이 놓일 때마다 `Button2Up`을 출력합니다.

```lua
local tool = script.Parent  -- 이것이 Tool 객체인지 확인

tool.Equipped:Connect(function(mouse)
	mouse.Button2Up:Connect(function()
		print("Button2Up")
	end)
end)
```
마우스의 월드 스페이스 위치와 `Class.BasePart`를 가리키고 있는지 확인할 수 있습니다. `Class.Mouse.Hit|Hit` 및 `Class.Mouse.Target|Target` 속성을 사용하세요.

Mouse.Button2Up

오른쪽 마우스 버튼이 놓일 때 발생합니다.

이 예제는 각 프레임 동안 마우스 이벤트가 어떻게 전달되는지를 보여줍니다


마우스가 다른 마우스 이벤트에 전달되지 않을 때마다 발생합니다.

참고: 이 이벤트는 마우스가 고정되어 있는지 확인하기 위해 사용하면 안 됩니다. 모든 업데이트마다 발생하므로 `Class.Mouse.Move` 이벤트 사이에 발생합니다.

`Class.Mouse` 객체를 얻는 방법에 대한 정보는 `Class.Mouse` 페이지를 참조하십시오.

개발자는 마우스의 월드 스페이스 위치와 `Class.BasePart`를 가리키고 있는지 확인할 수 있습니다. `Class.Mouse.Hit`와 `Class.Mouse.Target` 속성이 그것을 도와줍니다.

참고: 개발자는 새 작업에서 `Class.Mouse` 객체 대신 `Class.UserInputService`를 사용하는 것이 좋습니다.

Mouse.Idle

마우스가 다른 마우스 이벤트에 전달되지 않을 때마다 발생합니다.

아래 예제는 'mouse'가 정의되었다고 가정할 때, 눌린 키(예: "q")와 해당 키의 아스키 값(예: 113)을 출력합니다.


이 이벤트는 키가 눌릴 때 발생하며, 전달된 인자는 눌린 키입니다.

참고:

- 모든 키가 이 이벤트를 생성하는 것은 아닙니다. 하지만 몇몇 키는 `Class.Mouse.KeyUp` 이벤트를 사용하여 우회할 수 있습니다. 예를 들어, "/" 키가 이에 해당합니다.
- 일부 키는 다른 키와 동일한 문자열을 생성합니다.
- 문자열이 비어 있을 가능성이 있습니다(아마도 "\0" 키 코드 때문일 수 있습니다).

Mouse.KeyDown

Mouse.keyDown

아래 예제는 'mouse'가 정의되어 있다고 가정할 때, 해제된 키(예: "q")와 해당 키의 아스키 값(예: 113)을 출력합니다.


이 이벤트는 키가 해제될 때 발생하며, 전달된 인자는 해제된 키입니다.

주의:

- 모든 키가 이 이벤트를 생성하지는 않습니다. 그러나 몇몇 키로 우회할 수 있습니다. 예를 들어, "/" 키를 사용하는 경우
  [[API:Class/Mouse/KeyUp|KeyUp]] 이벤트를 사용할 수 있습니다.
- 일부 키는 다른 키와 동일한 문자열을 생성합니다.
- 문자열이 비어 있을 수 있습니다(어쩌면 "\\0" 키 코드 때문일 수 있습니다).

Mouse.KeyUp

아래 예제는 `Class.Players.LocalPlayer|로컬 플레이어`가
마우스로 부품을 이동할 수 있도록 합니다.

플레이어가 부품 위에서 왼쪽 마우스 버튼을 누르면, 그 부품이
`Class.Mouse.Target|마우스의 타겟`이 되어 _지점_이 됩니다. 플레이어가
왼쪽 마우스 버튼을 놓을 때까지, 그 부품은 플레이어가 마우스를
움직일 때 마우스의 월드 위치로 이동합니다.

`Class.Mouse.TargetFilter` 속성은 마우스의 월드 위치를 결정할 때
이동 중인 부품을 무시하도록 코드를 허용합니다.

코드는 `LocalScript`에 배치되었을 때 예상대로 작동해야 합니다.


마우스가 이동할 때 발생합니다.

이 이벤트는 마우스 위치가 업데이트될 때 발생하므로, 이동 중일 때 반복적으로 발생합니다.

`Class.Mouse` 객체를 얻는 방법에 대한 정보는 `Class.Mouse` 페이지를 참조하십시오.

개발자는 세계 공간에서 마우스의 위치를 확인하고, `Class.Mouse.Hit` 및 `Class.Mouse.Target` 속성을 사용하여 마우스가 어떤 `Class.BasePart`를 가리키고 있는지 확인할 수 있습니다.

```
mouse.Move:Connect(function()
	local position = mouse.Hit.p
	local target = mouse.Target
	print(target, position)
end)
```
개발자는 새 작업에서 `Class.Mouse` 객체 대신 `Class.UserInputService`를 사용하는 것이 좋습니다.

Mouse.Move

마우스가 이동할 때 발생합니다.

아래 예제는 플레이어의 마우스를 이미 가져왔고(변수 이름을 'mouse'로 설정했으며), `Class.Tool`, `Class.HopperBin` 또는 `Class.Player:GetMouse()` 메서드를 사용했음을 가정합니다. 플레이어가 스크롤을 뒤로 할 때 "휠이 뒤로 갔습니다!"를 출력합니다.


WheelBackward 이벤트는 마우스 휠이 뒤로 스크롤될 때 발생합니다. 이 이벤트의 가능한 사용 예시로는 1인칭 슈팅 게임(FPS)에서 총의 조준경을 전환하거나 플레이어의 카메라를 확대하는 것이 있습니다.

이 이벤트는 스크롤 앞으로 이벤트인 `Class.Mouse.WheelForward`와 함께 사용할 수 있습니다.

`Class.Mouse` 객체를 얻는 방법에 대한 정보는 `Class.Mouse` 페이지를 참조하십시오.

개발자는 새 작업에서 `Class.Mouse` 객체 대신 `Class.UserInputService`를 사용하는 것이 좋습니다.

Mouse.WheelBackward

마우스 휠이 뒤로 스크롤될 때 발생합니다.

아래 예제는 플레이어의 마우스를 이미 가져왔고(변수 이름을 'mouse'로 설정했으며), `Tool`, `HopperBin` 또는 `Class.Player:GetMouse()` 메서드를 사용했음을 가정합니다. 플레이어가 스크롤을 앞으로 할 때 "휠이 앞으로 갔습니다!"를 출력합니다.


WheelForward 이벤트는 마우스 휠이 앞으로 스크롤될 때 발생합니다. 이 이벤트의 가능한 사용 예시로는 1인칭 슈팅 게임(FPS)에서 총의 조준경을 전환하거나 플레이어의 카메라를 확대하는 것이 있습니다.

이 이벤트는 스크롤 뒤로 이벤트인 `Class.Mouse.WheelBackward`와 함께 사용할 수 있습니다.

`Class.Mouse` 객체를 얻는 방법에 대한 정보는 `Class.Mouse` 페이지를 참조하십시오.

개발자는 새 작업에서 `Class.Mouse` 객체 대신 `Class.UserInputService`를 사용하는 것이 좋습니다.

Mouse.WheelForward

마우스 휠이 앞으로 스크롤될 때 발생합니다.

Mouse

이 샘플의 코드는 `StarterPlayerScripts` 내의 `LocalScript`에 배치되면 캐릭터의 머리와 `Class.Mouse.Hit` 사이에 항상 빨간 레이저 빔을 그립니다.

이 빔은 3인칭에서 장애물을 직접 통과합니다. 왜냐하면 `Mouse`의 레이캐스팅은 머리가 아닌 `Class.Workspace.CurrentCamera`에서 수행되기 때문입니다.


아래 코드는 `Class.Mouse.Hit`와 `Class.Mouse.Origin`의 차이를 시각화합니다.
이를 위해 코드는 히트와 원점 `Datatype.CFrame` 값의 `Datatype.Vector3` 위치를 사용하여 `.p`를 사용합니다.

차이점은 원점이 "마우스가 온 곳"(그 원점)이고 히트는 마우스가 닿는 위치(플레이어가 마우스를 클릭할 때)입니다.

이 예제는 또한 마우스 원점이 `CurrentCamera`의 위치와 매우 유사하다는 것을 시각화하며, 두 위치 간의 크기(거리)를 출력합니다.


이 프로퍼티는 3D 공간에서 마우스의 위치를 나타내는 `Datatype.CFrame`을 나타냅니다. `Class.Mouse.TargetFilter` 및 그 하위 요소는 무시됩니다.

개발자는 다음과 같이 Hit의 위치를 얻을 수 있습니다:

```
local position = mouse.Hit.Position
```
Hit는 종종 `Class.Tool|Tools`에 의해 무기를 마우스를 향해 발사하는 데 사용됩니다.

마우스가 가리키고 있는 `Class.BasePart`을 찾고 있는 개발자는 `Class.Mouse.Target`을 사용해야 합니다.

#### Mouse.Hit는 어떻게 계산되나요?

Hit CFrame의 위치는 마우스 내부의 `Datatype.Ray`(`Class.Mouse.UnitRay`의 확장 버전)와 3D 공간의 객체(예: 파트) 사이의 교차점으로 계산됩니다.

Hit CFrame의 방향은 `Class.Mouse.UnitRay`의 방향과 관련이 있습니다.

```
local unitRayDirection = mouse.UnitRay.Direction
local mouseHitDirection = mouse.Hit.lookVector
-- unitRayDirection ≈ mouseHitDirection
-- 벡터는 대략적으로 같습니다.
```
참고로, Hit `Datatype.CFrame`의 방향을 계산할 때 `Class.Workspace.CurrentCamera`의 롤은 사용되지 않습니다.

마우스의 내부 레이는 1,000 스터드까지 확장됩니다. 마우스가 3D 공간의 객체를 가리키고 있지 않다면(예를 들어 하늘을 가리키는 경우), 이 프로퍼티는 `Class.Workspace.CurrentCamera`로부터 1,000 스터드 떨어져 있게 됩니다.

Mouse.Hit

3D 공간에서 마우스의 위치를 나타내는 `Datatype.CFrame`입니다.

Mouse.hit

이 예제는 `Class.Players.LocalPlayer` 마우스 아이콘을 드래곤 이미지처럼 보이도록 변경합니다.


**아이콘**은 포인터로 사용되는 이미지를 결정하는 속성입니다. 비어있으면 기본 화살표가 사용됩니다. 커서가
`Class.GuiButton` 위에 있을 때 이 속성은 일시적으로 무시됩니다.

커서를 완전히 숨기려면 **투명한** 이미지를 사용하지 마세요 &ndash; 대신 `Class.UserInputService.MouseIconEnabled`를 false로 설정하십시오.

경험에서 사용자 마우스 아이콘을 가져오거나 설정하려면 `Class.UserInputService.MouseIcon`을 사용해야 합니다. `Class.Mouse.Icon`은 마우스 커서를 설정하기 위한 새로운 API가 출시된 후 사용 중지됩니다.

##### 커서 디자인

다음 가이드라인은 자신의 마우스 커서를 만들 때 유용할 수 있습니다:

- 사용되는 이미지의 크기가 커서의 크기를 결정합니다.
- 이미지의 크기는 어떤 축에서도 256픽셀을 초과해서는 안 됩니다.
- 이미지의 **중앙**이 마우스 입력이 발행되는 위치입니다.
- 기본 마우스 이미지는 64x64 픽셀이며, 마우스는 17x24 픽셀의 공간을 차지합니다.

##### 시스템 커서

`Class.PluginMouse`를 `Class.Plugin:GetMouse()`에서 가져와 사용할 때 손, 화살표, I-빔 등 시스템의 기본 커서와 유사한 다음 아이콘을 사용할 수 있습니다. 이러한 아이콘은 `Class.GuiObject.MouseEnter|MouseEnter`,
`Class.GuiObject.MouseLeave|MouseLeave`, `Class.GuiButton.MouseButton1Down|MouseButton1Down`과 같은 GUI 이벤트와 함께 사용하여 특정 종류의 GUI 컴포넌트와 상호작용할 때 일관된 스튜디오 경험을 제공합니다. 이러한 것은 스튜디오 플러그인용으로만 작동하며, 다른 `Class.Mouse` 객체에는 작동하지 않음을 유의하십시오.

<table>
    <thead>
        <tr>
            <th>모양*</th>
            <th>자산</th>
            <th>추천 사용</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>기본 클릭 및 선택.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-PointingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/PointingHand</code></td>
            <td>활성 링크/버튼 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-OpenHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/OpenHand</code></td>
            <td>드래그 가능한 항목 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-GrabbingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/ClosedHand</code></td>
            <td>항목 드래그 중.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-IBeam.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/IBeam</code></td>
            <td>텍스트 필드 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNS.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNS</code></td>
            <td>수직 크기 조절 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeEW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeEW</code></td>
            <td>수평 크기 조절 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNESW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNESW</code></td>
            <td>코너 크기 조절 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNWSE.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNWSE</code></td>
            <td>코너 크기 조절 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeAll.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeAll</code></td>
            <td>다방향 크기 조절 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitV.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitNS</code></td>
            <td>수직 "분할" 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitH.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitEW</code></td>
            <td>수평 "분할" 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Forbidden.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Forbidden</code></td>
            <td>잠긴/금지된 항목 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Wait.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Wait</code></td>
            <td>작업이 진행 중임을 나타냅니다.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Busy.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Busy</code></td>
            <td>시스템이 바쁨을 나타냅니다.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Crosshair.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Cross</code></td>
            <td>핀포인트 선택 영역 위.</td>
        </tr>
    </tbody>
</table>

<figcaption>* 이러한 모양은 근사치입니다 &mdash; 실제 모양은 운영 체제에 따라 다릅니다.</figcaption>

Mouse.Icon

`Class.Mouse` 아이콘으로 사용되는 이미지의 콘텐츠 ID입니다.

**아이콘**은 포인터로 사용되는 이미지를 결정하는 속성입니다. 비어있으면 기본 화살표가 사용됩니다. 커서가
`Class.GuiButton` 위에 있을 때 이 속성은 일시적으로 무시됩니다. 이 속성은 자산 URI만 지원합니다.

커서를 완전히 숨기려면 **투명한** 이미지를 사용하지 마세요 &ndash; 대신 `Class.UserInputService.MouseIconEnabled`를 false로 설정하십시오.

경험에서 사용자 마우스 아이콘을 가져오거나 설정하려면 `Class.UserInputService.MouseIcon`을 사용해야 합니다. `Class.Mouse.Icon`은 마우스 커서를 설정하기 위한 새로운 API가 출시된 후 사용 중지됩니다.

##### 커서 디자인

다음 가이드라인은 자신의 마우스 커서를 만들 때 유용할 수 있습니다:

- 사용되는 이미지의 크기가 커서의 크기를 결정합니다.
- 이미지의 크기는 어떤 축에서도 256픽셀을 초과해서는 안 됩니다.
- 이미지의 **중앙**이 마우스 입력이 발행되는 위치입니다.
- 기본 마우스 이미지는 64x64 픽셀이며, 마우스는 17x24 픽셀의 공간을 차지합니다.

##### 시스템 커서

`Class.PluginMouse`를 `Class.Plugin:GetMouse()`에서 가져와 사용할 때 손, 화살표, I-빔 등 시스템의 기본 커서와 유사한 다음 아이콘을 사용할 수 있습니다. 이러한 아이콘은 `Class.GuiObject.MouseEnter|MouseEnter`,
`Class.GuiObject.MouseLeave|MouseLeave`, `Class.GuiButton.MouseButton1Down|MouseButton1Down`과 같은 GUI 이벤트와 함께 사용하여 특정 종류의 GUI 컴포넌트와 상호작용할 때 일관된 스튜디오 경험을 제공합니다. 이러한 것은 스튜디오 플러그인용으로만 작동하며, 다른 `Class.Mouse` 객체에는 작동하지 않음을 유의하십시오.

<table>
    <thead>
        <tr>
            <th>모양*</th>
            <th>자산</th>
            <th>추천 사용</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>기본 클릭 및 선택.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-PointingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/PointingHand</code></td>
            <td>활성 링크/버튼 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-OpenHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/OpenHand</code></td>
            <td>드래그 가능한 항목 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-GrabbingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/ClosedHand</code></td>
            <td>항목 드래그 중.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-IBeam.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/IBeam</code></td>
            <td>텍스트 필드 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNS.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNS</code></td>
            <td>수직 크기 조절 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeEW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeEW</code></td>
            <td>수평 크기 조절 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNESW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNESW</code></td>
            <td>코너 크기 조절 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNWSE.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNWSE</code></td>
            <td>코너 크기 조절 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeAll.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeAll</code></td>
            <td>다방향 크기 조절 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitV.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitNS</code></td>
            <td>수직 "분할" 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitH.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitEW</code></td>
            <td>수평 "분할" 핸들 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Forbidden.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Forbidden</code></td>
            <td>잠긴/금지된 항목 위.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Wait.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Wait</code></td>
            <td>작업이 진행 중임을 나타냅니다.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Busy.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Busy</code></td>
            <td>시스템이 바쁨을 나타냅니다.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Crosshair.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Cross</code></td>
            <td>핀포인트 선택 영역 위.</td>
        </tr>
    </tbody>
</table>

<figcaption>* 이러한 모양은 근사치입니다 &mdash; 실제 모양은 운영 체제에 따라 다릅니다.</figcaption>

Mouse.IconContent

`Class.Mouse` 아이콘으로 사용되는 이미지의 내용입니다. 자산 URI만 지원합니다.

원래 `Class.Mouse` 속성은 마우스가 시작된 위치를 나타내는 `Datatype.CFrame`입니다. 이것은 `Class.Workspace.CurrentCamera`에 위치하고 마우스의 3D 위치를 향하고 있습니다.

`Class.Mouse.UnitRay`는 원점과 동일한 위치에서 시작되어 같은 방향으로 스터드를 확장합니다.

```lua
local unitRay = mouse.UnitRay
local origin = mouse.Origin
-- unitRay.Direction = origin.p
-- unitRay.Direction ≈ origin.lookVector
```
3D 공간에서 `Class.Mouse`의 위치는 `Class.Mouse.Hit`를 참조하십시오.

Mouse.Origin

`Class.Workspace.CurrentCamera`에 위치하고 마우스의 3D 위치를 향하는 `Datatype.CFrame`입니다.

이 코드를 `StarterPlayerScripts`의 `LocalScript`에 배치하면,
플레이어가 클릭하는 모든 `BasePart`의 `Class.BasePart.BrickColor`가 변경됩니다.
예를 들어, 스폰 위치나 기본 판이 있습니다.


`Class.Mouse|mouse`가 가리키고 있는 3D 공간의 객체입니다.

주의:

- `Class.Mouse.TargetFilter`가 설정된 경우, 대상 필터와 그 자손은 무시됩니다.
- 마우스가 `Class.BasePart`를 가리키고 있지 않을 때, 예를 들어 하늘을 가리키고 있는 경우, 대상은 `nil`이 됩니다.
- 3D 공간에서 마우스의 위치를 찾고 있는 개발자는 `Class.Mouse.Hit`를 사용해야 합니다.

Mouse.Target

`Class.Mouse|mouse`가 가리키고 있는 3D 공간의 객체입니다.

Mouse.target

이 속성은 마우스가 `Class.Mouse.Hit` 및 `Class.Mouse.Target`을 계산할 때 무시할 객체를 결정합니다. 객체의 자손도 무시되므로, 이 속성이 설정된 객체의 자손이라면 여러 객체를 무시하는 것도 가능합니다. 이 속성은 `Class.Mouse.Hit` 또는 `Class.Mouse.Target`에 영향을 주지 않아야 하는 특수 효과나 장식이 포함된 모델을 필터링할 때 유용합니다.

이 속성은 모든 `Class.Instance`나 `nil`로 설정할 수 있으며, 예를 들어:

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

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

`Class.Players.LocalPlayer`의 `Class.Player.Character|Character`는 마우스에 의해 자동으로 무시됩니다.

Mouse.TargetFilter

`Class.Mouse.Hit`와 `Class.Mouse.Target`를 결정할 때 무시할 객체(및 그 자손)를 결정합니다.

이 샘플의 코드는 `StarterPlayerScripts` 내의 `LocalScript`에 배치되면 클릭한 `BasePart`의 표면을 무작위 표면으로 설정합니다.


이것은 `Class.Mouse.TargetSurface`를 보여줍니다.


이 속성은 마우스가 가리키고 있는 `Class.BasePart` 표면의 `Enum.NormalId`를 나타냅니다. 이 속성은 마우스의 세계 위치(`Class.Mouse.Hit`)와 마우스가 가리키고 있는 파트(`Class.Mouse.Target`)에서 파생됩니다.

마우스가 파트를 가리키고 있지 않을 때, 예를 들어 마우스가 하늘을 가리키고 있을 때 이 속성은 의미가 없습니다. 현재 이러한 상황에서는 이 속성이 'Right'로 설정됩니다. 이 속성을 사용하기 전에 마우스의 대상이 `nil`이 아닌지 확인하세요.


Mouse.TargetSurface

마우스가 가리키고 있는 `Class.BasePart` 표면의 `Enum.NormalId`를 나타냅니다.

`Class.Mouse.UnitRay`를 시연합니다.


UnitRay 속성은 3D 공간에서 마우스의 위치를 향하는 `Datatype.Ray`입니다(이는 `Class.Mouse.Hit`로 설명됩니다). 이 속성은 `Class.Workspace.CurrentCamera`의 `Class.Camera.CFrame|CFrame`에서 시작됩니다. 모든 유닛 레이와 마찬가지로 거리는 1입니다.


Mouse.UnitRay

마우스의 월드 위치를 향하는 `Datatype.Ray`로, `Class.Workspace.CurrentCamera` 월드 위치에서 시작됩니다.

이 코드 샘플은 `Datatype.Vector2`를 생성하여 `Mouse` 객체의 화면에서의 위치를 나타내는 방법을 보여줍니다 (`Class.Mouse.X|X()` 및 `Class.Mouse.Y|Y()`)와 화면 자체의 크기 (`Class.Mouse.ViewSizeX|ViewSizeX()` 및 `Class.Mouse.ViewSizeY|ViewSizeY()`). 이를 사용하여 화면에서 마우스의 위치를 정규화할 수 있으며, 상단 바 바로 아래의 왼쪽 상단은 (0, 0)으로, 오른쪽 하단은 (1, 1)로 매핑됩니다. 이 정규화된 위치는 마우스가 이동할 때 `Class.Mouse.Move|Move()` 이벤트를 사용하여 계산되고 출력됩니다.


ViewSizeX 속성은 게임 윈도우의 너비 픽셀 단위를 설명합니다.

Mouse.ViewSizeX

게임 윈도우의 너비를 픽셀 단위로 설명합니다.

ViewSizeY 속성은 게임 윈도우의 높이 픽셀 단위를 설명합니다. 이 길이는 상단 바에서 사용되는 공간을 포함합니다.

Mouse.ViewSizeY

게임 윈도우의 높이를 픽셀 단위로 설명합니다.

화면에서 마우스의 위치 변경을 감지할 때는 이 및 관련 속성을 사용하는 것보다 `Class.ContextActionService:BindAction()`을 사용하고,
`Enum.UserInputType.MouseMovement` 또는 `Class.UserInputService.InputChanged`를 사용하는 것이 좋습니다. 이 두 가지는 `Class.InputObject`의 `Class.InputObject.Position|Position` (a `Datatype.Vector3`)을 사용하여 마우스의 위치를 설명합니다.

X 속성은 화면에서 마우스의 위치의 수평 구성 요소를 설명합니다. 위치는 상단 바 아래의 왼쪽 상단 모서리를 기준으로 픽셀로 측정됩니다. 이 속성은 `Class.Mouse.Y`와 함께 사용되어 마우스의 위치를 나타내는 `Datatype.Vector2`를 생성할 수 있습니다:

```lua
local position = Vector2.new(mouse.X, mouse.Y)
```
이 속성은 `Class.Object.Changed|Changed` 또는 `Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal`에서 반환된 신호를 발생시키지 않습니다. 대신 `Class.Mouse.Move` 이벤트를 사용하세요.

Mouse.X

화면에서 마우스의 위치의 X(수평) 구성 요소를 설명합니다.

화면에서 마우스의 위치 변경을 감지할 때는 이 및 관련 속성을 사용하는 것보다 `Class.ContextActionService:BindAction()`을 사용하고,
`Enum.UserInputType.MouseMovement` 또는 `Class.UserInputService.InputChanged`를 사용하는 것이 좋습니다. 이 두 가지는 `Class.InputObject`의 `Class.InputObject.Position|Position` (a `Datatype.Vector3`)을 사용하여 마우스의 위치를 설명합니다.

Y 속성은 화면에서 마우스의 위치의 수직 구성 요소를 설명합니다. 위치는 상단 바 아래의 왼쪽 상단 모서리를 기준으로 픽셀로 측정됩니다. 이 속성은 `Class.Mouse.X`와 함께 사용되어 마우스의 위치를 나타내는 `Datatype.Vector2`를 생성할 수 있습니다:

```lua
local position = Vector2.new(mouse.X, mouse.Y)
```
이 속성은 `Class.Object.Changed|Changed` 또는 `Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal`에서 반환된 신호를 발생시키지 않습니다. 대신 `Class.Mouse.Move` 이벤트를 사용하세요.

Mouse.Y

화면에서 마우스의 위치의 Y(수직) 구성 요소를 설명합니다.

포인터 입력에 유용한 멤버를 포함하는 레거시 객체입니다.

`Instance`는 Roblox 클래스 계층 구조의 모든 클래스의 기본 클래스입니다
`Class.DataModel` 트리의 일부가 될 수 있습니다.

루트 `Instance` 객체를 직접 생성하는 것은 불가능하지만, 특별한
`Datatype.Instance.new()` 생성자는 코드로 객체를 생성하며,
클래스의 이름을 매개변수로 받아 생성된 객체를 반환합니다.


인스턴스의 조상을 변경하는 것을 감지하기 위해 `Class.Instance.AncestryChanged` 이벤트에 연결하는 방법을 보여줍니다.

ChangingPart의 부모는 시간이 지남에 따라 다른 값으로 설정됩니다. 파트의 부모는 파트의 조상이므로, `Class.Instance.AncestryChanged` 이벤트는 변경될 때마다 발생합니다.

이 인스턴스가 재부모되거나 그 조상 중 하나가 재부모될 때 발생합니다.

이 이벤트를 사용하여 Studio에서 인스턴스의 삭제를 추적할 수 있습니다. 예를 들어, 탐색기에서 수동으로 삭제하거나 플러그인을 통해 삭제하는 경우입니다. `Class.Instance:Destroy()`를 사용하여 인스턴스가 파괴될 때를 감지해야 하는 경우, 대신 `Class.Instance.Destroying` 이벤트를 사용하십시오.


Instance.AncestryChanged

child

`Class.Instance.Parent|Parent` 속성이 변경된 인스턴스입니다. 이 인스턴스일 수도 있고 더 먼 조상일 수도 있으며, 반드시 핸들러가 연결된 인스턴스일 필요는 없습니다.


parent

`child` 매개변수의 새로운 부모입니다.


이 객체 또는 그 조상의 `Class.Instance.Parent` 속성이 변경될 때 발생합니다.


이 이벤트는 인스턴스의 속성이 변경될 때마다 발생하며, 속성이 `nil`로 설정될 때도 포함됩니다. 변경된 속성의 이름이 연결된 함수에 전달됩니다.

예를 들어, 다음 코드 조각은 파트의 속성이 변경될 때마다 `attributeChanged()` 함수를 연결합니다:

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

local part = Workspace.Part

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

part.AttributeChanged:Connect(attributeChanged)
```
특정 속성이 변경될 때 발생하는 이벤트를 반환하는 `Class.Instance:GetAttributeChangedSignal()`도 참조하십시오.


Instance.AttributeChanged

attribute

`Class.Instance`에서 속성이 변경될 때마다 발생합니다.


이 코드 조각은 객체가 Workspace에 추가될 때 그 이름을 출력합니다:


이 `Class.Instance`에 자식이 추가된 후 발생합니다.

클라이언트에서 서버가 생성한 객체를 감지하기 위해 이 메서드를 사용할 때는, 이러한 객체의 자손을 인덱싱할 때 `Class.Instance:WaitForChild()`를 사용해야 합니다. 이는 객체와 그 자손이 서버에서 클라이언트로 동시에 복제될 것이라는 보장이 없기 때문입니다. 예를 들어:

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

Workspace.ChildAdded:Connect(function(child)
	-- 자손이 아직 복제되지 않았을 수 있으므로 WaitForChild()를 사용하십시오
	local head = child:WaitForChild("Head")
end)
```
이 이벤트는 `Class.Instance`의 즉각적인 자식에 대해서만 작동합니다. 모든 자손을 캡처하는 이벤트는 `Class.Instance.DescendantAdded`를 사용하십시오.

`Class.Instance.ChildRemoved`도 참조하십시오.


Instance.ChildAdded

이 `Class.Instance`에 자식이 추가된 후 발생합니다.


Instance.childAdded

이 코드 조각은 객체가 작업 공간에서 제거될 때 그 이름을 출력합니다:


이 `Class.Instance`에서 자식이 제거된 후 발생합니다.

제거된 것은 객체의 부모가 이 `Class.Instance`에서 이 `Class.Instance`가 아닌 다른 것으로 변경된 경우를 의미합니다. 이 이벤트는 자식이 파괴될 때도 발생합니다(`Class.Instance:Destroy()` 사용) 왜냐하면 파괴 함수가 객체의 부모를 `nil`로 설정하기 때문입니다.

이 이벤트는 `Class.Instance`의 즉각적인 자식에 대해서만 작동합니다. 모든 자손을 캡처하는 이벤트는 `Class.Instance.DescendantRemoving`을 사용하십시오.

`Class.Instance.ChildAdded`도 참조하십시오.


Instance.ChildRemoved

이 `Class.Instance`에서 자식이 제거된 후 발생합니다.


다음 예제는 Workspace에 추가되는 모든 객체의 이름을 출력합니다:

이 이벤트는 이 `Class.Instance`에 자손이 추가된 후 발생합니다.

모든 자손에 대해 발생하므로, 객체를 `Class.Instance`에 부모로 설정하면 이 객체와 그 모든 자손에 대해 개별적으로 이벤트가 발생합니다.

`Class.Instance`의 **직접 자식**에만 관심이 있다면, 대신 `Class.Instance.ChildAdded`를 사용하십시오.

`Class.Instance.DescendantRemoving`도 참조하십시오.


Instance.DescendantAdded

descendant

이 `Class.Instance`에 자손이 추가된 후 발생합니다.


다음 예제는 Workspace에서 제거되는 하위 항목의 이름을 출력합니다:

이 이벤트는 **자손** 인스턴스가 더 이상 자손이 되지 않도록 부모 `Class.Instance`가 변경되기 **직전**에 발생합니다. `Class.Instance:Destroy()|Destroy()`는 인스턴스의 `Class.Instance.Parent|Parent`를 `nil`로 변경하므로, 부모의 자손에 대해 이 메서드를 호출하면 이 이벤트가 발생합니다.

이 이벤트가 발생할 때 자손의 부모는 변경되지 않습니다. 만약 자손이 부모의 **직접 자식**이라면, 이 이벤트는 `Class.Instance.ChildRemoved`보다 먼저 발생합니다.

자손이 자식을 가지고 있다면, 이 이벤트는 자손을 먼저 발생시키고, 그 다음에 자손을 발생시킵니다.

#### 경고

이 이벤트는 제거되는 자손 객체와 함께 발생합니다. 자손의 `Class.Instance.Parent|Parent`를 다른 것으로 설정하려고 하면 실패합니다. 아래는 이를 보여주는 예입니다:

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

Workspace.DescendantRemoving:Connect(function(descendant)
	-- 이 함수에서 자손의 부모를 조작하지 마십시오!
	-- 이 이벤트는 부모가 조작되었기 때문에 발생하며, 변경이 아직 발생하지 않았습니다
	-- 따라서 이렇게 부모를 변경하는 것은 문제가 됩니다:
	descendant.Parent = game
end)

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

`Class.Instance.DescendantAdded|DescendantAdded`도 참조하십시오.


Instance.DescendantRemoving

제거되고 있는 `Class.Instance`입니다.


이 `Class.Instance`의 자손이 제거되기 직전에 발생합니다.


이 샘플은 즉시 신호 동작을 사용할 때 인스턴스가 파괴되더라도 연결된 함수가 yield될 때까지 그대로 유지된다는 것을 보여줍니다.

이 샘플은 Deferred 신호 동작을 사용할 때, 인스턴스가 신호가 발생하기 전에 어떻게 파괴되는지를 보여줍니다.

`Class.Instance`는 연결된 함수가 여전히 사용 중일 때 메모리에서 삭제되지 않습니다. 그러나 함수가 어느 시점에서 대기하면, `Class.Instance`와 그 자손은 `nil`로 부모가 설정됩니다.

`Class.Workspace.SignalBehavior` 속성이 `Enum.SignalBehavior.Immediate`로 설정된 경우, 이 이벤트는 `Class.Instance` 또는 그 조상이 `Class.Instance:Destroy()`로 파괴되기 직전에 발생합니다.

`Class.Workspace.SignalBehavior` 속성이 `Enum.SignalBehavior.Deferred`로 설정된 경우, 이 이벤트는 다음 재개 지점에서 발생하며, 이는 `Class.Instance` 또는 그 조상이 `Class.Instance:Destroy()`로 파괴된 후입니다.

`Enum.SignalBehavior.Deferred|Deferred` 동작에서는 스크립트를 자신의 `Class.Instance.Destroying` 이벤트에 연결하는 것이 문제가 될 수 있습니다. 왜냐하면 스크립트가 콜백이 호출되기 전에 파괴되기 때문입니다(즉, 실행되지 않음).

Studio에서 `Class.Instance`를 삭제할 때, 예를 들어 탐색기를 통해 수동으로 삭제하거나 플러그인을 통해 삭제할 때, `Class.Instance`는 파괴되지 않습니다. 대신 부모가 `nil`로 설정되며, 이는 `Class.Instance.AncestryChanged`로 추적할 수 있습니다.


Instance.Destroying

`Class.Instance:Destroy()`를 통해 인스턴스가 파괴되기 직전에 발생합니다.


 `Class.Instance.StyledPropertiesChanged`를 보여줍니다.


이 이벤트는 인스턴스에서 스타일 속성이 변경될 때마다 발생하며, 속성이 `nil`로 설정될 때도 포함됩니다.


Instance.StyledPropertiesChanged

인스턴스에서 스타일 속성이 변경될 때마다 발생하며, 속성이 `nil`로 설정될 때도 포함됩니다.


이 메서드는 인스턴스에 태그를 적용하며, 태그가 이미 적용된 경우에는 아무런 효과가 없습니다.
태그를 성공적으로 추가하면 `Class.CollectionService:GetInstanceAddedSignal()`에 의해 생성된 신호가 주어진 태그로 발생합니다.

#### 경고

- 클라이언트 측에서 추가된 인스턴스의 태그는 서버가 나중에 해당 인스턴스에서 태그를 추가하거나 제거하면 삭제됩니다.
  서버는 모든 태그를 함께 복제하고 이전 태그를 덮어씁니다.

- 인스턴스에 태그를 추가할 때, 태그의 기능을 제공하기 위해 일부 리소스가 사용되는 경우가 많습니다.
  예를 들어 이벤트 연결 또는 테이블입니다. 메모리 누수를 방지하기 위해 태그에 더 이상 필요하지 않을 때는 이를 정리하는 것이 좋습니다(연결 해제, `nil`로 설정 등).
  `Class.Instance:RemoveTag()`를 호출하거나 `Class.Instance:Destroy()`를 호출하거나 `Class.CollectionService:GetInstanceRemovedSignal()`에 의해 반환된 신호에 연결된 함수에서 이를 수행하십시오.


Instance:AddTag

인스턴스에 태그를 적용합니다.


자식 함수는 객체의 자식 배열을 반환합니다.


Instance:children

자식 객체/인스턴스의 배열입니다.


객체의 자식 배열을 반환합니다.


이 메서드는 인스턴스의 모든 자식과 자손을 파괴합니다.

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

-- 반짝임 추가
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
```
모든 자식과 자손을 파괴하고 싶지 않다면,
`Class.Instance:GetChildren()` 또는 `Class.Instance:GetDescendants()`를 사용하여
그 자식/자손을 반복하고 파괴할 대상을 선택하십시오. 예를 들어, 다음 코드 샘플은 `Class.BasePart|BaseParts`를 파괴합니다.
`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

이 메서드는 인스턴스의 모든 자식을 파괴합니다.


 `Class.Instance:Clone()` 를 사용하여 모델을 복제하는 방법을 보여줍니다.

`Clone()`은 인스턴스와 모든 자손의 복사본을 생성하며,
`Class.Instance.Archivable|Archivable`이 아닌 모든 인스턴스를 무시합니다.
루트 인스턴스의 복사본은 이 메서드에 의해 반환되며,
`Class.Instance.Parent|Parent`는 `nil`로 설정됩니다. 인스턴스 자체가
`Class.Instance.Archivable|Archivable`가 `false`로 설정되어 있으면,
이 메서드는 `nil`을 반환합니다.

`Class.ObjectValue.Value`와 같은 참조 속성이 복제된 인스턴스에서 설정되면,
복사본의 속성 값은 원본의 값에 따라 달라집니다:

- 참조 속성이 **또한** 복제된 인스턴스를 참조하면,
  복사본은 복사본을 참조합니다.
- 참조 속성이 **복제되지 않은** 인스턴스를 참조하면,
  복사본에서 동일한 값이 유지됩니다.


Instance:Clone

인스턴스와 모든 자손의 복사본을 생성하며,
`Class.Instance.Archivable|Archivable`이 아닌 인스턴스는 무시합니다.


Instance:clone

`Class.Instance:Destroy()` 함수를 사용하여 Part를 파괴하는 방법을 보여줍니다.

이 함수는 더 이상 필요하지 않은 객체를 처리하는 올바른 방법입니다.

`Class.Instance.Parent` 속성을 `nil`로 설정하고,
`Class.Instance.Parent` 속성을 잠그며,
모든 연결을 끊고 모든 자식에 대해 `Destroy()`를 호출합니다. 이 메서드는 더 이상 필요하지 않은 객체를 처리하는 올바른 방법입니다.

불필요한 객체를 처리하는 것은 중요합니다. 왜냐하면 장소에 불필요한 객체와 연결이 있으면 메모리를 사용하여 시간이 지남에 따라 심각한 성능 문제를 초래할 수 있기 때문입니다.

`Destroy()`를 호출한 후에는 객체(또는 그 자손)를 참조하는 변수를 `nil`로 설정하는 것이 모범 사례입니다. 이렇게 하면 코드가 객체와 관련된 어떤 것도 접근하지 못하게 됩니다.

```lua
local part = Instance.new("Part")
part.Name = "Hello, world"
part:Destroy()
-- 이렇게 하지 마세요:
print(part.Name)  --> "Hello, world"
-- 위의 줄이 작동하지 않도록 하려면:
part = nil
```

`Class.Instance`가 이 메서드에 의해 파괴된 후에는 재사용할 수 없습니다.
`Class.Instance.Parent` 속성이 잠겨 있기 때문입니다. 객체를 파괴하는 대신 **일시적으로** 제거하려면,
`Class.Instance.Parent|Parent`를 `nil`로 설정하십시오. 예를 들어:

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

object.Parent = nil
task.wait(2)
object.Parent = Workspace
```
설정된 시간 후에 객체를 파괴하려면,
`Class.Debris:AddItem()`을 사용하십시오.


Instance:Destroy

`Class.Instance.Parent` 속성을 `nil`로 설정하고,
`Class.Instance.Parent` 속성을 잠그며,
모든 연결을 끊고 모든 자식에 대해 `Destroy()`를 호출합니다.


Instance:destroy

`Class.Instance.Name`이 주어진 이름과 같은 첫 번째 조상을 반환합니다.

이 메서드는 위로 작동하며, 인스턴스의 즉각적인 `Class.Instance.Parent`에서 시작하여
`Class.DataModel`로 올라갑니다. 일치하는 조상이 없으면 `nil`을 반환합니다.

다음 코드 조각은 `Car`라는 이름의 객체의 첫 번째 조상을 찾습니다.

```
local car = object:FindFirstAncestor("Car")
```
특정 클래스의 조상을 찾는 이 메서드의 변형은 `Class.Instance:FindFirstAncestorOfClass()`와
`Class.Instance:FindFirstAncestorWhichIsA()`를 참조하십시오.


Instance:FindFirstAncestor

name

찾고자 하는 `Class.Instance.Name`입니다.


`Class.Instance.Name`이 주어진 이름과 같은 첫 번째 조상을 반환합니다.


`Class.Object.ClassName`이 주어진 className과 같은 첫 번째 조상을 반환합니다.

이 메서드는 위로 작동하며, 인스턴스의 즉각적인 `Class.Instance.Parent`에서 시작하여
`Class.DataModel`로 올라갑니다. 일치하는 조상이 없으면 `nil`을 반환합니다.

이 메서드의 일반적인 사용은 `Class.BasePart`가 속한 `Class.Model`을 찾는 것입니다. 예를 들어:

```
local model = part:FindFirstAncestorOfClass("Model")
```
이 메서드는 `Class.Instance:FindFirstAncestor()`의 변형으로,
`Class.Object.ClassName` 속성을 확인하며,
`Class.Instance.Name` 대신 사용됩니다. `Class.Instance:FindFirstAncestorWhichIsA()`도 존재하며,
`Class.Object:IsA()` 메서드를 사용하여 클래스 상속을 존중합니다.


Instance:FindFirstAncestorOfClass

className

찾고자 하는 `Class.Object.ClassName`입니다.


`Class.Object.ClassName`이 주어진 className과 같은 첫 번째 조상을 반환합니다.


`Class.Instance`의 첫 번째 조상을 반환하며,
`Class.Object:IsA()`가 주어진 className에 대해 true를 반환합니다.

이 메서드는 위로 작동하며, 인스턴스의 즉각적인 `Class.Instance.Parent`에서 시작하여
`Class.DataModel`로 올라갑니다. 일치하는 조상이 없으면 `nil`을 반환합니다.

`Class.Instance:FindFirstAncestorOfClass()`와는 달리,
이 메서드는 `Class.Object:IsA()`를 사용하여 클래스 상속을 존중합니다. 예를 들어:

```
print(part:IsA("Part"))  --> true
print(part:IsA("BasePart"))  --> true
print(part:IsA("Instance"))  --> true
```
따라서 다음 코드 샘플은 첫 번째 `Class.BasePart` 조상을 반환합니다.
`Class.WedgePart`, `Class.MeshPart` 또는 `Class.Part`인지 여부에 관계없이.

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

`Class.Instance:FindFirstAncestor()`도 참조하십시오.


Instance:FindFirstAncestorWhichIsA

`Class.Instance`의 첫 번째 조상을 반환하며,
`Class.Object:IsA()`가 주어진 className에 대해 true를 반환합니다.


아래 코드는 Workspace에서 객체 이름 "Brick"을 찾습니다. 찾으면,
객체의 이름을 "Foo"로 변경합니다.

주어진 이름으로 `Class.Instance`의 첫 번째 자식을 반환하며,
해당 자식이 존재하지 않으면 `nil`을 반환합니다. 선택적 `recursive` 인수가
`true`인 경우, 이 메서드는 `Class.Instance`의 즉각적인 자식뿐만 아니라 모든 자손을 검색합니다.

#### 객체 존재 확인

`FindFirstChild()`는 객체가 존재하는지 확인해야 할 경우 필요합니다.
이름으로 자식을 인덱싱하려고 하면 자식이 존재하지 않으면 오류가 발생합니다.

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

-- 다음 줄은 파트가 작업 공간에 존재하지 않으면 오류가 발생합니다.
Workspace.Part.Transparency = 0.5
```
더 나은 접근 방식은 `FindFirstChild()`를 사용하여 먼저 `Part`를 확인한 다음,
필요한 코드를 실행하기 위해 `if` 문을 사용하는 것입니다.

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

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

#### 속성과 일치하는 자식 찾기

때때로 객체의 `Class.Instance.Name|Name`이 그 `Class.Instance.Parent|Parent`의 속성과 동일합니다.
점 연산자를 사용할 때, 속성이 이름을 공유하면 자식보다 우선합니다.

다음 예제에서는 `Class.Part`에 `Color`라는 `Class.Folder`가 추가되며,
`Class.Part.Color` 속성도 있습니다. `part.Color`는 자식 `Class.Folder` 인스턴스가 아닌
`Datatype.Color3` 속성 값을 참조합니다. `Class.Instance:FindFirstChild()|FindFirstChild()`를 사용하면
새로운 속성이 도입되어도 코드에 위험을 주지 않습니다.

```lua
local part = Instance.new("Part")
local folder = Instance.new("Folder")
folder.Name = "Color"
folder.Parent = part
local c1 = part.Color  -- 속성
local c2 = part:FindFirstChild("Color")  -- 자식 폴더
```

#### 성능 주의 사항

`Class.Instance:FindFirstChild()|FindFirstChild()`는 점 연산자를 사용하는 것보다 약 20% 더 오래 걸리며,
객체에 대한 참조를 저장하는 것보다 거의 8배 더 오래 걸립니다. 따라서 성능에 의존하는 코드에서,
예를 들어 긴 루프나 `Class.RunService.Heartbeat` 및 `Class.RunService.PreRender`에 연결된 함수에서
이 메서드를 호출하는 것을 피해야 합니다. 대신 결과를 변수에 저장하거나,
`Class.Instance.ChildAdded|ChildAdded` 또는 `Class.Instance:WaitForChild()|WaitForChild()`를 사용하여
주어진 이름의 자식이 사용 가능해질 때 감지하는 것을 고려하십시오.


Instance:FindFirstChild

검색할 `Class.Instance.Name`입니다.


recursive

검색이 재귀적으로 수행되어야 하는지 여부입니다.


주어진 이름으로 찾은 `Class.Instance`의 첫 번째 자식을 반환합니다.


Instance:findFirstChild

`Class.Instance`의 첫 번째 자식을 반환하며,
`Class.Object.ClassName|ClassName`이 주어진 `className`과 같습니다.
`Class.Instance:FindFirstChildWhichIsA()`와는 달리,
이 메서드는 클래스 상속을 무시하고 `className`과 일치하는 객체만 반환합니다.
일치하는 자식이 없으면 이 메서드는 `nil`을 반환합니다.


Instance:FindFirstChildOfClass

`Class.Instance`의 첫 번째 자식을 반환하며,
`Class.Object.ClassName|ClassName`이 주어진 클래스 이름과 같습니다.


`Class.Instance`의 첫 번째 자식을 반환하며,
`Class.Object:IsA()`가 주어진 className에 대해 true를 반환합니다.

일치하는 자식이 없으면 이 메서드는 `nil`을 반환합니다. 선택적
재귀 인수가 true인 경우, 이 메서드는 `Class.Instance`의 즉각적인 자식뿐만 아니라 모든 자손을 검색합니다.

`Class.Instance:FindFirstChildOfClass()`와는 달리,
이 메서드는 클래스 상속을 존중하는 `Class.Object:IsA()`를 사용합니다. 예를 들어:

```lua
print(part:IsA("Part")) --> true
print(part:IsA("BasePart")) --> true
print(part:IsA("Instance")) --> true
```
따라서 다음 코드 샘플은 첫 번째 `Class.BasePart` 자식을 반환합니다.
`Class.WedgePart`, `Class.MeshPart` 또는 `Class.Part`인지 여부에 관계없이.

```
local part = object:FindFirstChildWhichIsA("BasePart")
```
이름으로 자식을 찾으려는 개발자는 대신 `Class.Instance:FindFirstChild()`를 사용해야 합니다.


Instance:FindFirstChildWhichIsA

`Class.Instance`의 첫 번째 자식을 반환하며,
`Class.Object:IsA()`가 주어진 className에 대해 true를 반환합니다.


주어진 `Class.Instance.Name`으로 찾은 첫 번째 자손을 반환합니다.

이 메서드는 비활성화되어 사용할 수 없습니다. 인스턴스의 첫 번째 자손을 찾으려면,
대신 `Class.Instance:FindFirstChild()`의 `recursive` 매개변수를 사용하는 것을 고려하십시오.


Instance:FindFirstDescendant

주어진 `Class.Instance.Name`으로 찾은 첫 번째 자손을 반환합니다.


`Class.Instance`가 `Class.Actor`인 경우, `Class.Actor` 자체가 반환됩니다.
그렇지 않으면 가장 가까운 조상 `Class.Actor`가 반환됩니다. 조상이 `Class.Actor`가 없으면 결과는 `nil`입니다.


Instance:GetActor

인스턴스와 연결된 `Class.Actor`를 반환합니다(있는 경우).


이 메서드는 주어진 속성 이름에 할당된 값을 반환합니다. 속성이 할당되지 않은 경우,
`nil`이 반환됩니다.

예를 들어, 다음 코드 조각은 인스턴스의 `InitialPosition` 속성을 설정한 다음 가져옵니다:

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

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

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

#### 참조

- 주어진 이름으로 속성을 설정하는 `Class.Instance:SetAttribute()`.
- 인스턴스의 모든 속성에 대한 키-값 쌍의 사전을 반환하는 `Class.Instance:GetAttributes()`.


Instance:GetAttribute

주어진 속성 이름에 할당된 값입니다. 속성이 할당되지 않은 경우,
`nil`이 반환됩니다.


주어진 속성 이름에 할당된 값을 반환합니다.


이 메서드는 주어진 속성이 변경될 때 발생하는 이벤트를 반환합니다.
`Class.Object.Changed|Changed` 이벤트와 정확히 같은 방식으로 작동하지만,
특정 주어진 속성이 변경될 때만 발생합니다. 효과적으로 `Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal()`과 유사하지만,
속성에 대한 것입니다.

일반적으로 이 메서드를 사용하는 것이 좋습니다. `Class.Object.Changed|Changed`에 연결하여
속성 이름을 확인하는 함수와 함께 사용하는 것보다.
같은 객체에 대해 같은 속성 이름으로 이 메서드를 여러 번 호출하면 같은 이벤트가 반환됩니다.

다음 코드 예제는 파트의 `InitialPosition` 속성이 변경될 때 `attributeChanged()` 함수를 발생시키는 신호를 반환합니다:

```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)
```
또한 인스턴스에서 속성이 변경될 때마다 발생하는 `Class.Instance.AttributeChanged`를 참조하십시오.


Instance:GetAttributeChangedSignal

변경 신호를 반환할 지정된 속성의 이름입니다.


주어진 속성이 변경될 때 발생하는 이벤트입니다.


주어진 속성이 변경될 때 발생하는 이벤트를 반환합니다.


이 메서드는 속성의 이름이 키이고 비-`nil` 값이 값인 각 속성에 대한 키-값 쌍의 사전을 반환합니다.

예를 들어, 다음 코드 조각은 인스턴스의 속성과 값을 출력합니다:

```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
```
또한 주어진 속성 이름에 할당된 값을 반환하는 `Class.Instance:GetAttribute()`를 참조하십시오.


Instance:GetAttributes

각 속성에 대한 문자열 → 변형 쌍의 사전입니다. 문자열은 속성의 이름이고,
변형은 비-`nil` 값입니다.


인스턴스의 속성 사전을 반환합니다.


아래 코드는 실행 시 워크스페이스에 있는 모든 객체의 이름을 출력합니다.

이 메서드는 인스턴스의 모든 직접 자식을 포함하는 배열(숫자 인덱스 테이블)을 반환합니다.
또는 `Class.Instance`의 `Class.Instance.Parent|Parent`가 객체와 같은 모든 `Class.Instance`입니다.
배열은 숫자 또는 일반 `for` 루프를 사용하여 반복할 수 있습니다:

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

-- 숫자 루프 예제
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")

-- 일반 루프 예제
local children = Workspace:GetChildren()
for i, child in children do
	print(child.Name .. " is child number " .. i)
end
```
반환된 배열은 **특정 순서로 정렬되지 않으므로**, 수동 정렬(예: `Library.table.sort()`)을 권장합니다.
이 메서드에 의해 반환된 자식을 정렬합니다.

또한 `Class.Instance:GetDescendants()|GetDescendants()` 메서드를 참조하십시오.


Instance:GetChildren

인스턴스의 자식을 포함하는 배열입니다.


인스턴스의 모든 자식을 포함하는 배열을 반환합니다.


Instance:getChildren

Instance

`Instance`는 Roblox 클래스 계층 구조의 모든 클래스의 기본 클래스입니다
`Class.DataModel` 트리의 일부가 될 수 있습니다.


/reference/engine/classes/PlayerMouse.yaml