> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/colliders.md).

# 콜라이더

엔티티에 3D 형태와 충돌을 부여하는 다양한 컴포넌트에 대해 알아봅니다.

콜라이더가 있는 엔티티는 공간을 차지하고 플레이어의 경로를 막으며, 콜라이더가 없는 엔티티는 플레이어의 아바타가 통과할 수 있습니다.

콜라이더는 엔티티를 클릭 가능하게 만드는 데에도 필요합니다. 버튼 이벤트는 엔티티의 보이는 모양이 아니라 콜라이더 모양을 기준으로 합니다.

플레이어의 물리와 상호작용하는 충돌 레이어와 포인터 이벤트와 상호작용하는 충돌 레이어는 서로 별개이며, 콜라이더는 둘 중 하나에만 상호작용하도록 구성할 수 있습니다. 또한 사용자 지정 레이어와 상호작용하도록 구성할 수 있으며, 이는 [레이캐스트](/creator/content-creator-ko/sdk7/3d/colliders.md) 에 사용할 수 있으며, 장면에 적합한 방식으로 처리할 수 있습니다.

{% hint style="warning" %}
**📔 참고**: 콜라이더는 다른 엔티티들이 서로 상호작용하는 방식에는 영향을 주지 않으며, 엔티티는 항상 겹칠 수 있습니다. 충돌 설정은 엔티티가 플레이어의 아바타 및 버튼 이벤트와 상호작용하는 방식에만 영향을 줍니다. Decentraland에는 기본 물리 엔진이 없으므로, 엔티티가 떨어지거나, 부딪히거나, 튕기게 하려면 이 동작을 직접 장면에 코딩하거나, 이를 처리할 라이브러리를 가져와야 합니다.
{% endhint %}

## Scene Editor 사용

엔티티의 콜라이더를 관리하는 가장 쉬운 방법은 [Scene Editor를 사용하는 것입니다.](/creator/content-creator-ko/scene-editor/get-started/about-editor.md).

엔티티에 **Mesh Collider** 컴포넌트를 엔티티에 추가하여 기본 도형(큐브, 평면, 구, 원기둥 또는 원뿔)을 할당할 수 있습니다. 그런 다음 [충돌 레이어](#collision-layers) 를 드롭다운에서 선택할 수 있습니다.

또한 **GLTF** 컴포넌트에서 충돌 레이어를 구성하여 기본값을 변경할 수 있습니다. [충돌 레이어](#collision-layers) 를 콜라이더 기하 또는 모델의 보이는 기하 중 어느 쪽에 사용할지 변경할 수 있습니다. 다음을 참조하세요: [컴포넌트 추가](/creator/content-creator-ko/scene-editor/build/components.md#add-components).

![\u0001](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-a1566c33728b1ef858f518365390d2ce5c97fe82%2Fgltf-component.png?alt=media\&token=43fa7d3f-2ed6-48b5-9fcd-842c8a75c4dc)

## 기본 도형의 콜라이더

이 `MeshCollider` 컴포넌트는 기본 도형(박스, 구, 평면, 원기둥 또는 원뿔)을 기반으로 엔티티에 단순한 콜라이더를 부여합니다.

MeshRenderer `MeshRenderer` 컴포넌트를 사용하여 [기본 도형](/creator/content-creator-ko/sdk7/3d/shape-components.md#primitive-shapes) 에 대한 콜라이더 `MeshCollider` 컴포넌트도 부여해야 합니다.

다음 콜라이더 모양은 `MeshCollider`에서 사용할 수 있습니다. 일부 모양에는 해당 모양에 특화된 선택적 추가 필드가 포함됩니다.

* **박스**:

  다음을 사용하세요: `MeshCollider.setBox()`를 사용하고, 엔티티를 전달합니다.
* **평면**:

  다음을 사용하세요: `MeshCollider.setPlane()`를 사용하고, 엔티티를 전달합니다.
* **구**:

  다음을 사용하세요: `MeshCollider.setSphere()`를 사용하고, 엔티티를 전달합니다.
* **원기둥**:

  다음을 사용하세요: `MeshCollider.setCylinder()`를 사용하고, 엔티티를 전달합니다. 추가로 `radiusTop` 와 `radiusBottom` 을 추가 선택 필드로 전달하여 원기둥을 수정합니다.

{% hint style="info" %}
**💡 팁**: 다음 중 하나를 `radiusTop` 또는 `radiusBottom` 0으로 설정하여 원뿔로 만드세요.
{% endhint %}

이 예제는 지나갈 수 없는 박스 엔티티를 정의합니다.

```ts
// 엔티티 생성
const myCollider = engine.addEntity()

// 보이는 모양
MeshRenderer.setBox(myCollider)

// 콜라이더
MeshCollider.setBox(myCollider)
```

에서 사용되는 모양은 `MeshCollider` 에서 사용되는 모양과 반드시 일치할 필요는 없습니다. `MeshRenderer`. `MeshCollider` 컴포넌트의 3D 모델이 있는 엔티티에 `GltfContainer` 컴포넌트가 있는 엔티티나, 아예 보이는 모양이 없는 엔티티에도 추가할 수 있습니다.

{% hint style="warning" %}
**📔 참고**: `MeshCollider` 컴포넌트와 `ColliderLayer` 는 다음을 통해 가져와야 합니다:

`import { MeshCollider, ColliderLayer } from "@dcl/sdk/ecs"`

다음을 참조하세요: [가져오기](/creator/content-creator-ko/sdk7/getting-started/coding-scenes.md#imports) 를 참고하여 이를 쉽게 처리하는 방법을 확인하세요.
{% endhint %}

## 3D 모델의 콜라이더

3D 모델에는 두 가지 서로 다른 기하 수준에서 콜라이더를 할당할 수 있습니다:

* `visibleMeshesCollisionMask`: 모델의 보이는 기하를 가리킵니다. 기본적으로 이 기하는 콜라이더가 없습니다.
* `invisibleMeshesCollisionMask`: 이름이 `_collider`로 끝나는 콜라이더 메시를 가리킵니다. 기본적으로 이 기하는 물리와 포인터 이벤트 모두에 대한 콜라이더로 취급됩니다.

3D 모델의 일부로 포함된 메시 중 이름이 `_collider` 로 끝나는 것은 `invisibleMeshesCollisionMask` 레이어의 일부로 간주되며, 기본적으로 콜라이더로 해석됩니다.

콜라이더 기하를 별도의 보이지 않는 레이어로 정의하면 훨씬 더 세밀한 제어가 가능하고, 충돌 오브젝트는 보통 원본 모델보다 훨씬 단순하기 때문에 보이는 기하를 사용하는 것보다 시스템 부담도 훨씬 적습니다.

모델에 콜라이더 기하가 전혀 없고, 이를 물리 또는 포인터 이벤트 시스템에 영향을 주게 하려면 다음 중 하나를 수행할 수 있습니다:

* 을 통해 보이는 기하에 직접 충돌 레이어를 할당합니다. `visibleMeshesCollisionMask`.

{% hint style="warning" %}
**📔 참고**: 객체의 보이는 기하에 정점이 많다면, 성능 비용이 더 커질 수 있습니다.
{% endhint %}

* 엔티티에 `MeshCollider` 컴포넌트를 부여하여 기본 도형 콜라이더를 부여합니다.
* 보이지 않는 엔티티를 겹쳐서 `MeshCollider` 컴포넌트도 부여해야 합니다.
* Blender 같은 외부 도구에서 모델을 편집해 *콜라이더 메쉬*를 포함시킵니다. 콜라이더는 *x\_collider*로 이름 지어야 하며, *x* 는 모델의 이름입니다. 따라서 이름이 *house*인 모델의 경우 콜라이더 이름은 *house\_collider*.

로 설정할 수도 있습니다. 또한 호버 힌트와 포인터 이벤트가 엔티티의 윤곽에 더 정확하게 반응하도록 포인터 이벤트 충돌 레이어를 `visibleMeshesCollisionMask` 에 할당하고 싶을 수도 있습니다. 이는 성능 부담이 더 크다는 점에 유의하세요.

{% hint style="warning" %}
**📔 참고**: 같은 레이어(물리, 포인터 이벤트 또는 사용자 지정 레이어)를 `visibleMeshesCollisionMask` 와 `invisibleMeshesCollisionMask`모두에 할당하지 않도록 하세요. 자원 사용 측면에서 매우 비효율적이기 때문입니다. 예를 들어 보이지 않는 레이어에는 물리, 보이는 레이어에는 포인터 이벤트처럼 서로 다른 레이어를 각각에 사용할 수 있습니다.
{% endhint %}

```ts
// 엔티티 생성
const myEntity = engine.addEntity()

// GLTF 모양 할당
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
	visibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
})
```

다음을 참조하세요: [3D 모델](https://github.com/decentraland/docs/blob/main/creator/3d-modeling/3d-models.md) 3D 모델에 콜라이더 보이지 않는 기하를 추가하는 방법에 대한 자세한 내용.

{% hint style="warning" %}
**📔 참고**: `GltfContainer` 컴포넌트와 `ColliderLayer` 는 다음을 통해 가져와야 합니다:

> `import { GltfContainer, ColliderLayer } from "@dcl/sdk/ecs"`

다음을 참조하세요: [가져오기](/creator/content-creator-ko/sdk7/getting-started/coding-scenes.md#imports) 를 참고하여 이를 쉽게 처리하는 방법을 확인하세요.
{% endhint %}

### 애니메이션이 적용된 모델

팔 관절 기반 애니메이션이 포함된 모델에서 보이는 기하를 사용하도록 콜라이더를 설정하면 [골격 기반 애니메이션](/creator/content-creator-ko/3d/animations.md)을 따라가지 않습니다. 콜라이더 메시는 원래 모양을 유지합니다. 애니메이션이 메시의 기하를 변형하는 경우, 애니메이션이 재생되는 동안 콜라이더 메시는 애니메이션이 적용되지 않은 모양을 유지합니다.

전체 메쉬를 모양 변화 없이 이동시키는 애니메이션을 재생할 때는 이러한 변경 사항이 콜라이더에 정확하게 반영됩니다. 예를 들어 플랫폼이 애니메이션의 일부로 이동하면 해당 플랫폼의 콜라이더도 애니메이션과 함께 이동합니다.

## 충돌 레이어

장면은 서로 다른 동작을 가진 별도의 충돌 레이어를 처리할 수 있습니다.

다음과 같이 구성할 수 있습니다. `MeshCollider` 컴포넌트 또는 `GltfContainer` 컴포넌트는 하나의 상호작용 종류에만, 여러 종류에, 또는 전혀 반응하지 않도록 설정할 수 있습니다. 이를 위해 `MeshCollider` 에서 `collisionMask` 속성을 설정하고, `GltfContainer` 에서 `visibleMeshesCollisionMask` 또는 `invisibleMeshesCollisionMask` 에서 다음 값 중 하나 또는 여러 개로 속성을 설정합니다:

* `ColliderLayer.CL_PHYSICS`: 플레이어 이동을 막습니다(장면의 벽, 바닥, 플랫폼). 포인터 이벤트에는 영향을 주지 않습니다.
* `ColliderLayer.CL_POINTER`: 포인터 이벤트에만 반응합니다. 플레이어 이동을 막지 않습니다.
* `ColliderLayer.CL_PLAYER`: 콜라이더를 아바타 마커로 표시합니다. 이를 대상으로 하는 레이캐스트와 트리거 영역은 `CL_PLAYER` 를 감지하지만, 플레이어 캡슐은 이를 그대로 통과합니다(물리적 차단 없음). 장면 메시에서는 이를 감지 전용 "아바타 같은 대상"으로 표시하는 데 유용합니다.
* `ColliderLayer.CL_MAIN_PLAYER`: `CL_PLAYER`와 같지만, 로컬 플레이어에만 대상이 지정됩니다. 마스크에 `CL_MAIN_PLAYER` 가 있는 레이캐스트/트리거는 이를 감지하지만, 원격 아바타 레이캐스트/트리거는 감지하지 않습니다.
* `ColliderLayer.CL_CUSTOM1` 부터 `CL_CUSTOM8`까지: 레이캐스트 및 트리거 영역과 함께 사용하여 특정 사용자 지정 레이어와의 충돌만 감지할 수 있습니다.
* `ColliderLayer.CL_NONE`: 어떤 종류의 충돌에도 반응하지 않습니다.

{% hint style="info" %}
**💡 팁**: `CL_PLAYER` 와 `CL_MAIN_PLAYER` 의 `MeshCollider` / `GltfContainer` 은 **감지 전용** 레이어입니다 — 플레이어 캡슐은 이를 통과합니다. 메쉬가 아바타로도 감지되고 플레이어를 물리적으로도 막게 하려면 아바타 레이어와 `CL_PHYSICS` (예: `CL_PHYSICS | CL_MAIN_PLAYER`).
{% endhint %}

{% hint style="warning" %}
**📔 참고**: 콜라이더를 비활성화하려면 `MeshCollider` 컴포넌트를 삭제하세요. 충돌 레이어를 `ColliderLayer.CL_NONE`로 설정하지 마세요. `MeshCollider` 컴포넌트에는 알려진 문제가 있습니다. 모든 충돌을 비활성화하는 대신 이 값은 기본값(`ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER`).
{% endhint %}

```ts
// 엔티티 생성
const myEntity = engine.addEntity()
// 보이는 모양
MeshRenderer.setBox(myEntity)

// 플레이어 물리에만 반응하는 MeshCollider 컴포넌트 생성
MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS)
```

하나의 충돌 마스크는 여러 충돌 레이어에 반응할 수 있습니다. 필요한 만큼 많은 레이어를 포함하려면 `|` 문자를 *또는*로 사용하세요. MeshCollider의 기본값은 `ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER`.

```ts
MeshCollider.setBox(
	myEntity,
	ColliderLayer.CL_CUSTOM1 |
		ColliderLayer.CL_CUSTOM3 |
		ColliderLayer.CL_PHYSICS |
		ColliderLayer.CL_POINTER
)
```

8개의 서로 다른 사용자 지정 레이어는 장면에 가장 적합한 용도로 사용할 수 있습니다. 예를 들어 하나는 NPC 시야 계산에 사용하고, 다른 하나는 떨어지는 물체의 궤적을 추정하는 데 사용할 수 있습니다. 서로 다른 시스템에 서로 다른 레이어를 사용하면 각 경우에 관련 엔티티와의 충돌만 검사하므로 더 적은 리소스를 사용할 수 있습니다.

다음을 참조하세요: [레이캐스팅](/creator/content-creator-ko/sdk7/interactivity/raycasting.md) 를 참조하여 사용자 지정 충돌 레이어 사용법을 더 알아보세요.

### 카메라와 콜라이더

플레이어의 카메라가 3인칭 모드로 이동할 때, 엔티티에 할당된 충돌 레이어에 따라 카메라가 콜라이더에 의해 막히거나 막히지 않을 수 있습니다. 장면을 설계할 때 이를 염두에 두세요. 카메라가 벽이나 다른 엔티티를 통과하지 못하게 하고 싶을 수 있습니다.

카메라가 벽을 통과하지 못하게 하려면 `ColliderLayer.CL_PHYSICS` 와 `ColliderLayer.CL_POINTER` 레이어를 모두 카메라를 막고 싶은 엔티티에 할당해야 합니다. 두 레이어가 엔티티의 같은 기하에 할당되는 것이 중요합니다. 따라서 `ColliderLayer.CL_PHYSICS` 레이어를 엔티티의 보이는 레이어에 할당했다면, `ColliderLayer.CL_POINTER` 레이어도 같은 기하에 할당해야 합니다.

예를 들어 Creator Hub에서 다음 설정 조합은 카메라가 벽을 통과하지 못하게 합니다:

![\u0001](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-426b56fda6516e2c2e63296a534d02aa089a566e%2Fcolliders-camera.png?alt=media\&token=7e7dbaa9-0e4f-47b7-8efe-13456cb1761b)

둘 다 `ColliderLayer.CL_PHYSICS` 와 `ColliderLayer.CL_POINTER` 레이어가 엔티티 기하의 같은 보이지 않는 레이어에 할당됩니다. 둘 다 보이는 레이어에 할당되더라도 결과는 동일합니다. 이는 Creator Hub를 통해 엔티티를 추가하든 코드로 추가하든 기본 동작입니다.

![\u0001](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-6c77ca6fce6934f939ce70f2146d972718a25556%2Fcolliders-no-camera.png?alt=media\&token=63d0c60e-c267-45df-a44a-f2c5c58f37b7)

두 번째 예에서는 카메라가 벽을 통과할 수 있는데, 이는 `ColliderLayer.CL_PHYSICS` 레이어가 엔티티의 보이지 않는 레이어에 할당되고, `ColliderLayer.CL_POINTER` 레이어가 엔티티의 보이는 레이어에 할당되기 때문입니다. 두 기하의 전체 모양이 같더라도 마찬가지입니다.

```ts
// 벽을 통과하는 카메라 없음
// 기본값(포인터와 물리 모두 보이지 않는 기하를 사용)
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
})

// 벽을 통과하는 카메라 없음
// 둘 다 같은 보이지 않는 기하를 사용
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask:
		ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER,
})

// 벽을 통과하는 카메라 없음
// 둘 다 같은 보이는 기하를 사용
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	visibleMeshesCollisionMask:
		ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER,
})

// 예, 카메라가 벽을 통과함
// 물리와 포인터가 서로 다른 레이어에 있음
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
	visibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
})

// 예, 카메라가 벽을 통과함
// 물리와 포인터가 서로 다른 레이어에 있음
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
	visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
})
```

### 포인터 차단

콜라이더가 있는 모양만 [포인터 이벤트](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md)로 활성화할 수 있습니다. 엔티티가 포인터 이벤트가 그 안을 통과하지 못하게 하고 뒤에 있는 엔티티를 맞추지 못하게 하려면 콜라이더도 필요합니다. 예를 들어, 플레이어는 상자 주위에 콜라이더가 있다면 상자 안에 잠겨 있는 물건을 집을 수 없습니다. 플레이어의 포인터 이벤트는 `ColliderLayer.CL_POINTER` 레이어에서 활성화된 메시의 영향만 받습니다.

기본적으로 MeshCollider는 물리와 포인터 레이어 모두에 영향을 주지만, 이 값을 하나만, 혹은 둘 다 아니게 바꾸거나 대신 사용자 지정 레이어에 영향을 주도록 변경할 수 있습니다.

{% hint style="warning" %}
**📔 참고**: 콜라이더 외에도 엔티티가 포인터 이벤트에 반응하려면 `PointerEvents` 컴포넌트가 필요합니다. `pointerEventsSystem` 도 이 요구 사항을 처리해 줍니다.
{% endhint %}

```ts
// 플레이어 물리에만 반응
// 예: 지나갈 수는 없지만 클릭은 통과할 수 있는 보이지 않는 벽
MeshCollider.setBox(myEntity, ColliderLayer.CL_PHYSICS)

// 플레이어의 포인터
// 예: 클릭해서 집을 수 있지만 그대로 통과할 수 있는 아이템
MeshCollider.setBox(myEntity2, ColliderLayer.CL_POINTER)
```

기본적으로 `GltfContainer` 의 보이는 기하는 어떤 충돌 레이어에도 매핑되지 않지만, 보이지 않는 기하는 물리와 포인터 레이어 모두에 영향을 줍니다. 이 값을 하나만, 혹은 둘 다 아니게 바꾸거나 대신 사용자 지정 레이어에 영향을 주도록 변경할 수 있습니다. 보이는 기하 레이어도 같은 방식으로 구성할 수 있습니다.

```ts
// 기본값(포인터와 물리 모두 보이지 않는 기하를 사용)
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
})

// 플레이어 물리는 더 단순한 보이지 않는 기하를 사용
// 포인터 이벤트는 보이는 기하의 전체 세부 윤곽을 사용
GltfContainer.create(myEntity2, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS,
	visibleMeshesCollisionMask: ColliderLayer.CL_POINTER,
})

// 플레이어 물리와 포인터 이벤트 모두 보이는 기하의 전체 세부 윤곽을 사용
// 더 단순한 보이지 않는 기하는 둘 다 계산하지 않도록 ColliderLayer.CL_NONE에 매핑됩니다
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_NONE,
	visibleMeshesCollisionMask:
		ColliderLayer.CL_POINTER | ColliderLayer.CL_PHYSICS,
})

// 보이는 기하든 보이지 않는 기하든 어떤 종류의 충돌에도 반응하지 않음:
GltfContainer.create(myEntity, {
	src: '/models/myModel.gltf',
	invisibleMeshesCollisionMask: ColliderLayer.CL_NONE,
})
```

## 고급 MeshCollider 문법

컴포넌트를 생성하는 전체 문법은 `MeshCollider` 보조 도구 없이 단순화하면 다음과 같습니다:

```ts
MeshCollider.create(myBox, {
	mesh: {
		$case: 'box',
		box: {},
	},
})

MeshCollider.create(myPlane, {
	mesh: {
		$case: 'plane',
		plane: {},
	},
})

MeshCollider.create(myShpere, {
	mesh: {
		$case: 'sphere',
		sphere: {},
	},
})

MeshCollider.create(myCylinder, {
	mesh: {
		$case: 'cylinder',
		cylinder: {},
	},
})
```

이것이 기본 프로토콜이 MeshCollider 컴포넌트를 해석하는 방식입니다. 보조 함수는 이를 추상화하여 더 친숙한 문법을 제공하지만, 내부적으로는 이 문법을 출력합니다.

이 `$case` 필드를 사용하면 허용되는 유형 중 하나를 지정할 수 있습니다. 각 유형은 서로 다른 매개변수 집합을 지원합니다.

지원되는 `$case` 값은 다음과 같습니다:

* `박스`
* `평면`
* `구`
* `원기둥`

의 값에 따라, `$case`해당 모양에 맞는 객체를 관련 속성과 함께 정의하는 것이 유효합니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/colliders.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.