# Hitbox Options

## 개요

히트박스 시스템은 캐릭터의 피격 판정 단위를 설정하는 기능입니다. 월드의 성격, 성능 요구, 게임 디자인 목적에 따라 사용할 수 있는 히트박스 옵션을 제공합니다.

*실제 피격 효과(데미지 처리, 색상 변경 등)는 크리에이터가 직접 구현해야 하며, 히트박스 시스템은 물리 충돌, **Touched 이벤트**, **Raycast** 기능을 사용할 때 캐릭터의 어느 단위까지 판정할지를 결정하는 역할만 수행합니다.*

## 기능 구성

히트박스 옵션은 **Workspace**에서 설정할 수 있습니다.\
**Workspace**에서 히트박스를 설정하면, 모든 캐릭터의 피격 판정은 해당 히트박스 옵션을 따르게 됩니다.

{% hint style="info" %}
현재는 **런타임 중 옵션 변경을 지원하지 않으므로**, 월드가 실행 중인 상태에서는 스크립트를 통해 히트박스 옵션을 변경할 수 없습니다.
{% endhint %}

<figure><img src="https://2697870212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhRPi87oM9ttlk5nyu7L7%2Fuploads%2Fgit-blob-07f0f522db59e079552da3b4c15c1fbb202ff2f3%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

히트박스 옵션은 다음과 같이 3개의 옵션을 제공합니다.

<table><thead><tr><th width="168.166748046875">옵션</th><th>설명</th></tr></thead><tbody><tr><td>Single</td><td>캐릭터 전체를 하나의 캡슐로 감싸는 단일 히트박스</td></tr><tr><td>SixBody</td><td>신체 주요 부위(머리, 몸통, 팔다리)에 고정된 히트박스를 생성</td></tr><tr><td>FittedSixBody</td><td>외형 및 의상에 맞춰 조정된 6개 히트박스 생성</td></tr></tbody></table>

### 각 히트박스 옵션 타입 상세 설명

#### **Single**

* **형태**: HumanoidRootPart를 기준으로 하는 단일 캡슐 히트박스
* **특징**:
  * 성능 중심의 간단한 월드에 적합
  * 부위별 피격 판정이 필요 없는 경우에 추천
  * 항상 존재하는 캡슐 형태의 히트박스를 사용

<figure><img src="https://2697870212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhRPi87oM9ttlk5nyu7L7%2Fuploads%2Fgit-blob-b8aeaf6bb12647f64d9d1dce82ea74b987393fe7%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

#### **SixBody**

캐릭터의 신체는 **머리, 몸통, 팔, 다리 등 6개의 고정된 부위**로 나뉘며, 각 부위에 별도의 히트박스가 추가로 생성됩니다.

하나의 메시 파트에는 실제로 여러 개의 히트박스가 생성되며, 이는 **캐릭터 가이드에 명시된 Bone 구조**를 기반으로 생성됩니다.

**Touched 이벤트**나 **Raycast**는 해당 히트박스가 **속한 메시 파트**를 기준으로 검출됩니다.\
예를 들어 왼팔에는 Upper Arm, Lower Arm, Hand에 해당하는 3개의 히트박스가 존재하지만, 이 중 어떤 히트박스에 충돌이 발생해도 모두 LeftArm 메시 파트의 **Touched 이벤트가 호출**됩니다.

***\*만일 Single옵션인 경우, 부위별 히트박스 자체가 생성되지 않습니다.***

* **형태**: 신체를 6개 부위(머리, 몸통, 팔, 다리 등)로 나누고 각 부위에 여러 개의 히트박스를 생성
* **특징**:
  * 부위별 데미지, 헤드샷 등 정밀한 피격 판정이 필요한 경우 적합
  * 아바타 외형과 무관하게 고정된 판정 구조 제공
  * **Touched 이벤트**와 **Raycast**는 해당 히트박스가 속한 메시파트 기준으로 작동

<figure><img src="https://2697870212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhRPi87oM9ttlk5nyu7L7%2Fuploads%2Fgit-blob-d667ef87f5d334b4a6fe8bba43ef780d784c4f14%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

#### **FittedSixBody**

신체 6부위 히트박스를 아바타의 의상이나 형태에 맞게 크기와 위치를 유동적으로 조정합니다.

* **형태**: **SixBody 구조**를 기반으로 외형에 맞게 히트박스 크기 및 위치를 조정
* **특징**:
  * 커스텀 아바타 및 다양한 의상 적용 시 유리
  * 플레이어 외형에 따라 유동적으로 히트박스 반영
  * **Touched 이벤트**와 **Raycast** 동작은 **SixBody**와 동일

## 물리 기반에서 히트박스 시스템 활용 방법

### 히트박스 옵션에 따른 Collision Group 사용 안내

OVERDARE Studio는 물리 판정을 위해 다음과 같은 **4개의 시스템 Collision Group**을 제공합니다:

<figure><img src="https://2697870212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhRPi87oM9ttlk5nyu7L7%2Fuploads%2Fgit-blob-84f4d4c2e2fb1715be41525ad0e85bc71835a2b3%2Fimage%20(6).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

<table><thead><tr><th width="152.6666259765625">Collision Group</th><th width="361.4998779296875">설명</th><th width="231.83343505859375">비고</th></tr></thead><tbody><tr><td>Default</td><td>대부분의 일반 Part 및 MeshPart의 기본 그룹</td><td></td></tr><tr><td>RootPart</td><td>캐릭터의 HumanoidRootPart 전용 그룹</td><td>SixBody, FittedSixbody<br>사용 시 활성화</td></tr><tr><td>BodyPart</td><td>신체 부위(팔, 다리, 몸통)용 그룹</td><td>SixBody, FittedSixbody<br>사용 시 활성화</td></tr><tr><td>Projectile</td><td>BodyPart와 충돌하기 위한 발사체, 투사체 전용 그룹</td><td>SixBody, FittedSixbody<br>사용 시 활성화</td></tr></tbody></table>

> **Collision Group의 활성 여부는 히트박스 옵션에 따라 자동으로 설정됩니다.**

### 히트박스 옵션별 Collision Group 동작 방식

* **Single 옵션**
  * Default 그룹만 활성화됩니다.
  * HumanoidRootPart는 Default 그룹에 소속됩니다.
* **SixBody, FittedSixBody 옵션**
  * RootPart, BodyPart, Projectile 그룹이 자동 활성화됩니다.
  * 이 경우, HumanoidRootPart는 RootPart 그룹으로 소속이 변경됩니다.
  * BodyPart와 물리적으로 충돌하는 객체는 Projectile 그룹을 사용하는 것을 권장합니다.

### 그룹 간 충돌 처리 가이드

#### **Default - RootPart**

* 캐릭터가 바닥 아래로 떨어지지 않는 이유는 HumanoidRootPart(RootPart 그룹)와 대부분의 오브젝트(Default 그룹)가 충돌 가능하기 때문입니다.
* **SixBody** 및 **FittedSixBody** 옵션에서는 HumanoidRootPart가 RootPart 그룹으로 이동하므로,\
  **Default - RootPart 충돌이 반드시 활성화되어야** 캐릭터가 물리적으로 정상적으로 동작합니다.
* 반면, **Single** 옵션에서는 HumanoidRootPart 자체가 Default 그룹에 포함되므로 **별도의 설정 없이도 충돌이 정상 작동**합니다.

#### **Default - BodyPart**

* Default - BodyPart 충돌을 활성화해도 이미 Default - RootPart 충돌이 존재하기 때문에 **추가적인 체감 효과는 적을 수 있습니다.**
* **부위별 판정이 필요한 경우**, Projectile 그룹을 활용해 발사체와 BodyPart 간 충돌을 구현하는 것이 효과적입니다.

#### **RootPart - Projectile**

* **SixBody** 및 **FittedSixBody** 옵션에서는 **발사체가 RootPart와 충돌하지 않도록** 해당 충돌을 **비활성화**해야 합니다.
* 이를 통해 불필요한 부위 이외의 판정을 방지할 수 있습니다.

#### **BodyPart - Projectile**

* **SixBody** 및 **FittedSixBody** 옵션에서는 **발사체가 BodyPart와 충돌 가능해야 하므로**, 해당 충돌을 **활성화**해야 합니다.

### 물리 충돌로 인한 피격 판정 구현

물리 충돌로 인한 피격 처리는 신체를 구성하는 MeshPart의 **Touched 이벤트**를 통해 처리할 수 있습니다.

물리 효과로 이동하는 발사체의 경우 이동 속도에 따라 충돌하지 않고 관통하는 경우가 있을 수 있습니다.\
총알처럼 빠르게 움직여야 하는 물체는 Touched보다는 Raycast를 활용하여 피격 판정 하는 것을 권장합니다.

{% hint style="warning" %}
현재 Collision Group, CanCollide 설정에 따라 Part의 Touched 이벤트가 비정상적으로 동작하는 오류를 발견하였습니다. 해당 부분은 빠른 시일 내에 해결할 예정입니다.
{% endhint %}

#### **Touch이벤트를 이용한 피격 감지**

<pre class="language-lua"><code class="lang-lua"><strong>local Players = game:GetService("Players")
</strong><strong>local LocalPlayer = Players.LocalPlayer
</strong><strong>local Character = LocalPlayer.Character
</strong>
<strong>local function AttachEvent(character)
</strong>    local BodyParts = 
    {
	character.Head,
	character.Torso,
	character.RightArm,
	character.LeftArm,
	character.RightLeg,
	character.LeftLeg
    }
    
    for _,part in ipairs(BodyParts) do
	part.Touched:Connect(function(otherPart)
	    if(otherPart.Name == "Baseplate") then return end
	    print(part.Name .. " is Hit!")
        end)		
    end	
end
AttachEvent(Character)
</code></pre>

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhRPi87oM9ttlk5nyu7L7%2Fuploads%2FCdUKaWiM33bg97jZoQzJ%2F2025-07-03%2011-55-12.mp4?alt=media&token=f74fe9cd-3828-4244-89fb-238ccf449d38>" %}

## Raycast 기반에서 히트박스 시스템 활용 방법

히트박스 옵션에 따라 **Raycast로 감지되는 파트**가 달라지며, 이에 따라 피격 판정 방식이 달라질 수 있습니다.

<table><thead><tr><th width="249">히트박스 옵션</th><th>HumanoidRootPart 감지 여부</th><th>신체 부위 MeshPart 감지 여부</th></tr></thead><tbody><tr><td><strong>Single</strong></td><td>✅ 감지됨</td><td>❌ 감지되지 않음</td></tr><tr><td><strong>SixBody</strong>, <strong>FittedSixBody</strong></td><td>❌ 감지되지 않음</td><td>✅ 감지됨</td></tr></tbody></table>

* **Single 옵션**
  * Raycast는 HumanoidRootPart만 감지합니다.
  * 머리, 팔, 다리 등 **신체 부위에 해당하는 MeshPart는 감지되지 않습니다.**
* **SixBody, FittedSixBody 옵션**
  * Raycast는 신체 부위(Head, Torso, Arms, Legs)에 해당하는 MeshPart를 감지합니다.
  * **HumanoidRootPart는 감지 대상에서 제외**되므로 중심 판정만 필요한 상황에서는 적합하지 않습니다.
* **정밀한 부위 판정이 필요한 경우**에는 `SixBody` 또는 `FittedSixBody`를 사용하여 `MeshPart` 단위로 Raycast를 활용하세요.
* **간단한 중심 충돌만 필요한 경우**에는 `Single` 옵션이 적합하며, 이 경우 `HumanoidRootPart`만으로도 충분한 판정이 가능합니다.

## 멀티플레이(네트워크) 환경에서의 권장 처리 방식

### 클라이언트에서 피격 판정 수행

서버는 캐릭터의 **애니메이션 상태를 재생하지 않기 때문에**, 실제로 플레이어가 **화면에서 보는 포즈**를 기준으로 히트박스 충돌 및 피격 판정은 **클라이언트에서 처리해야** 합니다.

예를 들어, 클라이언트에서 캐릭터가 춤을 추며 손을 들고 있는 상태일지라도,\
서버는 기본 자세로 **가만히 서 있는 캐릭터만 인식**합니다.\
따라서, 손을 향해 발사체를 날려도 서버 입장에서는 손이 들려 있지 않아 **피격이 무시될 수 있습니다.**

이에 따라 **SixBody 또는 FittedSixBody 옵션을 사용하는 경우**, 다음과 같은 구조가 권장됩니다:

* **클라이언트**: 실제 보이는 캐릭터 상태를 기준으로 피격 여부 판정 수행
* **서버**: 클라이언트로부터 피격 결과(데미지, 명중 여부 등)를 받아 처리 및 동기화 수행

<div><figure><img src="https://2697870212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhRPi87oM9ttlk5nyu7L7%2Fuploads%2Fgit-blob-4642caed7eee87a570c854d4b490b810cfe056d0%2Fimage.png?alt=media" alt=""><figcaption><p>클라이언트에서는 뛰는 애니메이션이 플레이 되지만</p></figcaption></figure> <figure><img src="https://2697870212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhRPi87oM9ttlk5nyu7L7%2Fuploads%2Fgit-blob-e1bc905cec27959a6e9824d1355c08135b51ee5a%2Fimage.png?alt=media" alt=""><figcaption><p>서버에서는 캐릭터의 애니메이션의 포즈 정보가 적용되지 않는다.</p></figcaption></figure></div>

### 발사체의 일관된 시각 동기화 처리

발사체가 **모든 클라이언트에서 동일하게 보이도록** 하려면 다음 방식을 권장합니다:

* **서버**: 발사체의 위치 및 속도 정보만 각 클라이언트에 전달
* **클라이언트**: 해당 정보를 기반으로 발사체를 생성하고 이펙트 등 시각적 요소를 개별적으로 처리

> 이 방식은 서버 부하를 줄이고, 지연 시간을 최소화하며, 클라이언트가 일부 연산을 분산 처리하여\
> 대부분의 멀티플레이 게임에서 안정적인 성능을 제공합니다.

### 서버로 결과 전달 및 검증

* 클라이언트는 피격 판정 결과(예: 명중 부위, 데미지 수치 등)를 **서버에 전달**합니다.
* 서버는 해당 정보를 **모든 클라이언트에 브로드캐스트**하여 상태를 동기화합니다.
* 필요 시 서버는 클라이언트의 판정 결과를 **검증하거나 보정**할 수 있습니다.

### 서버-클라이언트 간 오차 방지

* 서버는 항상 캐릭터의 **기본 자세만 인식**하므로,\
  **정확한 피격 처리를 위해서는 클라이언트 기반의 판정이 우선**되어야 합니다.
* 서버는 클라이언트의 피격 결과를 **신뢰하되, 보정 가능한 구조**를 갖추는 것이\
  **일관된 게임 경험을 보장**하는 핵심입니다.

## 히트박스 타입 선택 가이드

| 월드 성격/요구사항          | 추천 히트박스 옵션    |
| ------------------- | ------------- |
| 성능 최우선, 단순 피격 판정    | Single        |
| 헤드샷, 부위별 효과 등 정밀 판정 | SixBody       |
| 아바타 외형별 가변적 피격 판정   | FittedSixBody |