> 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-zh/chang-jing-sdk7/mei-ti/video-playing.md).

# 视频播放

将视频流传输到场景中

在场景中显示视频有三种不同方式：

* 将视频文件作为场景内容的一部分上传
* 从外部来源串流视频
* 通过 Decentraland Cast 进行直播

{% hint style="info" %}
**💡 提示**：在 [Creator Hub 中的场景编辑器](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/ru-men/about-editor.md)中，你可以使用 **视频播放器** [智能物品](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/jiao-hu-xing/smart-items.md) 以免编写代码的方式实现此功能。
{% endhint %}

无论采用哪种方式，你都需要：

* 一个带有 [基础形状](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/shape-components.md) 的实体，例如平面、立方体，甚至圆锥体。
* 一个 [材质](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/materials.md) ，其 `VideoTexture` 已指定为其纹理
* 一个 `VideoPlayer` 组件，用于控制视频状态。

## 性能注意事项

请注意，串流视频会给玩家的设备带来显著负担。建议一次不要播放多个视频。

如果场景中同时播放的视频过多，引擎会暂停其中一些视频。屏幕暂停的优先级由多项因素决定，包括与玩家的距离、屏幕大小，以及屏幕是否位于玩家的视野范围内。可同时播放的视频数量上限取决于玩家的画质设置。

* 低：1
* 中：5
* 高：10

我们还建议在玩家靠近或执行相应操作时才开始播放视频。如果场景还在远处地平线上加载时就开始播放视频，会在玩家访问相邻场景时对性能造成不必要的影响。

此外，避免串流分辨率过高的视频。请勿使用高于 *HD*.

的分辨率。理想情况下，也应使用 Basic（无光照）材质播放视频，以降低性能负担；下方的所有示例片段均采用这种做法。

## 显示视频

以下说明适用于三种视频显示方式：

1. 创建一个实体作为视频屏幕。为该实体添加 `MeshRenderer` 组件，使其具有可见形状。
2. 创建一个 `VideoPlayer` 组件，并指定串流 URL 或视频文件路径。你还可以在此设置视频的 `playing` 状态和音量。此组件可以分配给视频屏幕实体，也可以分配给场景中的任何其他实体。
3. 创建一个 `VideoTexture` 对象，并在其 `videoPlayerEntity` 属性中指定拥有 `VideoPlayer` 组件的实体。
4. 创建一个 `Material`，将其分配给屏幕实体，并设置其 `texture` 到 `VideoTexture` 你创建的对象。

此示例使用场景项目中本地存储在 `/videos` 文件夹内的视频：

```ts
// #1
const screen = engine.addEntity()
MeshRenderer.setPlane(screen)
Transform.create(screen, { position: { x: 4, y: 1, z: 4 } })

// #2
VideoPlayer.create(screen, {
	src: 'videos/myVideo.mp4',
	playing: true,
})

// #3
const videoTexture = Material.Texture.Video({ videoPlayerEntity: screen })

// #4
Material.setBasicMaterial(screen, {
	texture: videoTexture,
})
```

若要使用外部流媒体 URL 中的视频，请修改第 2 步，将 `src` 属性设置为 `VideoPlayer` 组件所引用的流媒体 URL。

```ts
// #2
VideoPlayer.create(screen, {
	src: 'https://vz-7c61c1b5-d59.b-cdn.net/ccea595a-b910-4de6-b160-092819db021d/playlist.m3u8',
	playing: true,
})
```

有关如何使用这种第三种方法的详情，请参阅 [直播流](#live-streaming) 。

## 关于外部流媒体

流媒体源必须是 *https* URL（不支持*http* URL）。

通常可以粘贴来自大多数热门视频流媒体网站的视频 URL。请留意这些平台的服务条款。

若要从本地计算机上的视频文件进行流式传输，最简单的方法是将视频上传到公开的 Google Drive，然后粘贴链接。

另一种选择是使用托管服务提供商，例如 [Vimeo](https://vimeo.com/) , [Livepeer Studio](https://livepeer.studio/) 或 [Serraform](https://serraform.gitbook.io/streaming-docs/guides/decentraland-playback) 向服务提供商支付费用，由其管理所有流媒体基础设施。

功能最强大的方式是使用免费软件搭建自己的服务器，并支付费用在 [Digital Ocean](https://try.digitalocean.com/developerbrand/?_campaign=emea_brand_kw_en_cpc&_adgroup=digitalocean_exact_exact&_keyword=digitalocean&_device=c&_adposition=&_content=conversion&_medium=cpc&_source=bing\&msclkid=160bfc160a2a1bab9bbf9933594bd9c5\&utm_source=bing\&utm_medium=cpc\&utm_campaign=emea_brand_kw_en_cpc\&utm_term=digitalocean\&utm_content=DigitalOcean%20Exact_Exact) 或 [Cloudflare](https://www.cloudflare.com/products/cloudflare-stream/)等平台上托管。你可以部署类似 [Node Media Server](https://github.com/illuspas/Node-Media-Server)的服务，它开箱即用地提供了大部分所需功能。

这些方案各有优缺点，适用于不同场景。你应结合自身需求、技术能力和预算，评估哪种方案最适合自己。

## 设置 OBS 以确保顺利直播

[OBS](https://obsproject.com/) 是一款广受欢迎的免费直播管理工具。

无论你使用的是场馆提供的流密钥，还是自己的 RTMP 服务器，OBS 中的设置都对直播能否顺利进行至关重要。应尽量确保连接稳定可靠。

### OBS 简易设置

建议采用以下简单设置：

* 比特率 2500kbps（适用于所有 Decentraland 场馆）
* 音频比特率 160kbps
* 视频编码器预设：Hardware NVENC
* 音频编码器 AAC
* 最大分辨率：720（在 DCL 中，分辨率更高会导致问题）
* 帧率 30fps

{% hint style="warning" %}
**📔 注意**：请确保在 OBS 中关闭多轨直播。此选项位于“设置”>“串流”中。
{% endhint %}

### 给新主播的建议

* 提前进行声音测试至关重要，这样可以在场馆中测试你的设置。
* 一些小错误（例如串流密钥中输错一个数字）最容易导致直播出问题。
* 分辨率不要超过 720，比特率不要超过 2500 kbps。

## 直播

你可以通过以下功能使用摄像头进行直播，或分享屏幕： [直播](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-shi-yun-ying/live-streaming.md) （位于 [管理工具](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-shi-yun-ying/scene-admin.md) 智能组件）

此串流方式采用与玩家实时通信相同的通信架构。设置简单，延迟也远低于从外部来源进行串流。

1. 在场景中添加一个 [管理工具](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-shi-yun-ying/scene-admin.md) 智能组件，以及一个 [视频播放器](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/jiao-hu-xing/video-screen.md) 智能组件。
2. 发布场景，可以发布到 World 或 Genesis City。
3. 以拥有管理工具使用权限的玩家身份进入场景。
4. 打开管理控制台，选择 **视频** 选项卡，然后选择 **直播** 功能，并点击 **获取串流密钥** 按钮。
5. 将 **服务器 URL** 和 *串流密钥*\* 复制到你的串流软件（例如 OBS）中。
6. 点击 **启用** 按钮，开始串流。

你也可以不在场景中添加视频播放器智能组件，而是使用 URL `livekit-video://current-stream` 作为视频源，在场景中播放串流。你仍然需要使用管理工具获取串流密钥。

```ts
// #1
const screen = engine.addEntity()
MeshRenderer.setPlane(screen)
Transform.create(screen, { position: { x: 4, y: 1, z: 4 } })

// #2
VideoPlayer.create(screen, {
	src: `livekit-video://current-stream`,
	playing: true,
})

// #3
const videoTexture = Material.Texture.Video({ videoPlayerEntity: screen })

// #4
Material.setBasicMaterial(screen, {
	texture: videoTexture,
})
```

## 视频材质

大多数情况下，你会希望在不受光照影响的 [基础材质](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/materials.md#unlit-materials)上播放视频，而不是使用 PBR 材质。这样图像会明亮、清晰得多，而且性能更好。

```ts
Material.setBasicMaterial(screen, {
	texture: videoTexture,
})
```

通常建议在不受光照影响的基础材质上播放视频，因为这样性能更好。不过，如果你想将视频投射到 PBR 材质上，请注意，默认属性会让视频看起来比较不透明。你可以调整材质的其他属性来改善效果。以下是一些能让视频更醒目的推荐设置：

```ts
Material.setPbrMaterial(screen, {
	texture: videoTexture,
	roughness: 1.0,
	specularIntensity: 0,
	metallic: 0,
	emissiveTexture: videoTexture,
	emissiveIntensity: 0.6,
	emissiveColor: Color3.White(),
})
```

{% hint style="info" %}
**💡 提示**：由于视频是添加到材质中的纹理，你也可以尝试调整材质的其他属性，例如为其添加色调，或叠加其他纹理层，以产生屏幕脏污效果。

有关详情，请参阅 [材质](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/materials.md) 。
{% endhint %}

## 关于视频文件

支持以下文件格式：

* *.mp4*
* *.ogg*
* *.webm*

请注意，视频文件会增加场景的总大小，导致玩家进入场景时需要更长时间下载场景。视频文件的大小也可能导致你超出 [场景限制](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/you-hua/scene-limitations.md)，因为每个地块最多只能使用 15 MB。我们建议尽可能压缩视频，以减少其带来的影响。

我们还建议在玩家靠近时或执行某个操作来触发视频时再开始播放。如果场景加载时就在远处播放视频，那么玩家访问邻近场景时会造成不必要的性能影响。

## 开始、暂停和停止视频

要开始播放视频或暂停视频，请将 `playing` 属性设为 *true* 或 *false*。如果 `playing` 设为 false，视频会暂停在最后显示的帧。

你可以按如下所示为屏幕添加指针事件，使其可切换播放状态：

```ts
pointerEventsSystem.onPointerDown(
	{
		entity: screen,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Play/Pause' },
	},
	function () {
		const videoPlayer = VideoPlayer.getMutable(screen)
		videoPlayer.playing = !videoPlayer.playing
	}
)
```

要停止视频并返回第一帧，请将 `position` 属性设为 0。在以下示例中，点击视频即可停止播放。

```ts
pointerEventsSystem.onPointerDown(
	{
		entity: screen,
		opts: { button: InputAction.IA_POINTER, hoverText: 'STOP' },
	},
	function () {
		const videoPlayer = VideoPlayer.getMutable(screen)
		videoPlayer.playing = false
		videoPlayer.position = 0
	}
)
```

## 配置视频播放器

以下可选属性可用于设置 `VideoPlayer` 组件：

* `playing`：用于确定视频当前是否正在播放。如果为 false，视频将暂停。

{% hint style="warning" %}
**📔 注意**：同时播放的视频数量有限，具体取决于玩家的画质设置。如果场景中播放的视频超过此数量，引擎会暂停优先级最低的视频。请参阅 [性能注意事项](#performance-considerations).
{% endhint %}

* `playbackRate`：更改视频的播放速度。 *1* （默认值）。
* `volume`：用于调整音量。 *1* （默认值）。
* `position`：用于设置视频的其他起始位置。单位为秒，从视频原始开头开始计时。 *0* 默认情况下，因此会从视频的实际起始位置开始播放。
* `loop`：布尔值，用于确定视频是否循环播放，还是播放一次后停止。 *false* （默认值）。

## 播放多个视频

为避免性能问题，请尽量减少同时播放的不同视频数量；引擎允许同时播放的视频数量有限，具体取决于玩家的画质设置（请参阅 [性能注意事项](#performance-considerations)）。不过，场景可以在多个不同屏幕上播放同一视频纹理的多个副本。这不受限制，因为与播放多个不同的视频相比，它对性能的影响要小得多。要在多个实体上播放同一视频，只需将同一个视频纹理对象实例分配给每个屏幕实体的 `Material` 组件。

```ts
// #1
const screen1 = engine.addEntity()
MeshRenderer.setPlane(screen1)
Transform.create(screen1, { position: { x: 4, y: 1, z: 4 } })

const screen2 = engine.addEntity()
MeshRenderer.setPlane(screen2)
Transform.create(screen2, { position: { x: 6, y: 1, z: 4 } })

// #2
VideoPlayer.create(screen1, {
	src: 'https://vz-7c61c1b5-d59.b-cdn.net/ccea595a-b910-4de6-b160-092819db021d/playlist.m3u8',
	playing: true,
})

// #3
const videoTexture = Material.Texture.Video({ videoPlayerEntity: screen1 })

// #4
Material.setBasicMaterial(screen1, {
	texture: videoTexture,
})

Material.setBasicMaterial(screen2, {
	texture: videoTexture,
})
```

请注意，在上面的示例中，只需创建一个 `VideoPlayer` 组件即可控制两个视频屏幕的状态。在此示例中，该组件分配给 `screen1` 实体，但也可以分配给场景中的任何其他实体，不一定要分配给某个屏幕实体。

## 视频事件

轻松处理视频状态变化，以便在视频开始播放、暂停等情况发生时作出响应。例如，可用此功能使动画与视频完美同步，确保它们与视频同时开始。

使用 `videoEventsSystem.registerVideoEventsEntity` 定义一个函数，每当分配给某个实体的视频状态发生变化时，就会运行该函数。每次状态变化时，函数都可以检查新状态并作出相应响应。

```ts
import {
	engine,
	Entity,
	VideoPlayer,
	videoEventsSystem,
	VideoState,
} from '@dcl/sdk/ecs'

// ... 创建带有 VideoPlayer 组件、Transform、MeshRenderer.setPlane() 等的 videoPlayerEntity ...

videoEventsSystem.registerVideoEventsEntity(
	videoPlayerEntity,
	function (videoEvent) {
		console.log(
			'video event - state: ' +
				videoEvent.state +
				'\ncurrent offset:' +
				videoEvent.currentOffset +
				'\nvideo length:' +
				videoEvent.videoLength
		)

		switch (videoEvent.state) {
			case VideoState.VS_READY:
				console.log('video event - video is READY')
				break
			case VideoState.VS_NONE:
				console.log('video event - video is in NO STATE')
				break
			case VideoState.VS_ERROR:
				console.log('video event - video ERROR')
				break
			case VideoState.VS_SEEKING:
				console.log('video event - video is SEEKING')
				break
			case VideoState.VS_LOADING:
				console.log('video event - video is LOADING')
				break
			case VideoState.VS_BUFFERING:
				console.log('video event - video is BUFFERING')
				break
			case VideoState.VS_PLAYING:
				console.log('video event - video started PLAYING')
				break
			case VideoState.VS_PAUSED:
				console.log('video event - video is PAUSED')
				break
		}
	}
)
```

作为函数输入传入的 videoEvent 对象包含以下属性：

* `currentOffset` (*数字*)：视频上 `position` 属性的当前值。此值表示距离视频原始起始位置的秒数。 *-1* 如果视频尚未开始播放。
* `state`：新的视频状态，以 `VideoState` 枚举中的值表示。此枚举可能包含以下值：
  * `VideoState.VS_READY`
  * `VideoState.VS_NONE`
  * `VideoState.VS_ERROR`
  * `VideoState.VS_SEEKING`
  * `VideoState.VS_LOADING`
  * `VideoState.VS_BUFFERING`
  * `VideoState.VS_PLAYING`
  * `VideoState.VS_PAUSED`
* `videoLength` (*数字* )：整个视频的长度，以秒为单位。 *-1* 如果长度未知。
* `timestamp` ( *数字*)：一个 *Lamport* 时间戳，每次视频状态发生变化时递增。
* `tickNumber` (*数字*)：事件发生的时间，以场景开始运行以来经过的时钟刻度数表示。

如果在已有回调的实体上重新注册回调（例如，更改状态变化时的处理方式），新回调会替换旧回调，并保留最后报告的状态。这意味着，对于已向旧回调报告过的状态，不会再次调用新回调。

### 检查实体是否已注册

使用 `videoEventsSystem.hasVideoEventsEntity()` 检查实体是否已经注册了视频事件回调。

```ts
if (videoEventsSystem.hasVideoEventsEntity(videoPlayerEntity)) {
	console.log('This entity already has a video event listener')
}
```

### 最新视频事件

使用 `videoEventsSystem.getVideoState()`查询视频最近一次状态变化。这会返回该实体最新的 `VideoEvent` 值；如果尚未报告任何事件，则返回 `undefined` 。你可以在系统中调用此方法，每帧轮询视频状态，而无需注册回调。

```ts
function mySystem() {
	const latestVideoEvent = videoEventsSystem.getVideoState(videoPlayerEntity)
	if (!latestVideoEvent) return

	console.log(`state: ${latestVideoEvent.state}
    \ncurrentOffset: ${latestVideoEvent.currentOffset}
    \nvideoLength: ${latestVideoEvent.videoLength}`)
}
```

## 视频上的 Alpha 遮罩

要创建非矩形视频屏幕，一个巧妙的方法是在平面上叠加 Alpha 纹理。你可以将平面的一部分裁掉，塑造为任意形状。

使用以下图像将视频裁剪为圆形，并让角落保持透明。

![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-ee3e152f3312f46d04d8640b44f42f1254e26f3b%2Fcircle_mask.webp?alt=media)

```ts
const videoTexture = Material.Texture.Video({
	videoPlayerEntity: screen,
})
const alphaMask = Material.Texture.Common({
	src: 'assets/scene/circle_mask.png',
	wrapMode: TextureWrapMode.TWM_MIRROR,
})

Material.setBasicMaterial(screen, {
	texture: videoTexture,
	alphaTexture: alphaMask,
})
```

![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-901568ee2ece2fed1734c93716d4c7069869c47c%2Fcircular-video-screen.webp?alt=media)

{% hint style="warning" %}
**📔 注意**：在旧版本中， `alphaTexture` 属性仅适用于 PBR 材质。目前，它仅适用于基础材质。
{% endhint %}

## 在 glTF 模型上播放视频

你可以使用 *glTF* 模型，并通过 [GltfNodeModifiers](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/materials.md#modify-gltf-materials) 组件在模型上播放视频。详情请参阅 [修改 glTF 材质](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/materials.md#modify-gltf-materials) 。

这样，你就可以在任意形状上播放视频，而不仅限于平面。例如，你可以在弧形屏幕上播放视频，甚至可以在 NPC 的整个身体上播放视频。

```ts
const myEntity = engine.addEntity()

GltfContainer.create(myEntity, {
	src: 'models/myModel.glb',
})

Transform.create(myEntity, {
	position: Vector3.create(4, 0, 4),
})

VideoPlayer.create(myEntity, {
	src: 'https://vz-7c61c1b5-d59.b-cdn.net/ccea595a-b910-4de6-b160-092819db021d/playlist.m3u8',
	playing: true,
})

GltfNodeModifiers.create(myEntity, {
	modifiers: [
		{
			path: '',
			material: {
				material: {
					$case: 'pbr',
					pbr: {
						texture: Material.Texture.Video({
							videoPlayerEntity: myEntity,
						}),
					},
				},
			},
		},
	],
})
```

视频的映射会遵循模型使用的原始 UV 映射。这意味着，如果模型的某个纹理映射到模型的特定部分，视频也会映射到同一部分。

你还可以使用 `GltfNodeModifiers` 组件，仅在模型内部的特定网格上播放视频。例如，即使模型覆盖了整栋建筑，你也可以仅在建筑的某一面墙上播放视频。详情请参阅 [修改 glTF 材质](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/materials.md#modify-gltf-materials) 。

## 空间音频

默认情况下， `VideoPlayer` 组件播放的视频音频是全局的，也就是说，整个场景中的音量始终一致。如果玩家离开场景，就完全听不到流媒体音频。

若要启用空间音频，请将 `spatial` 属性设为 *true*.

```ts
VideoPlayer.create(entity, {
	src: 'https://player.vimeo.com/progressive_redirect/playback/1145666916/rendition/540p/file.mp4%20%28540p%29.mp4?loc=external&signature=db1cd6946851313cb8f7be60d1f6c30af0902bcc46fdae0ba2a06e5fdf44c329',
	playing: true,
	spatial: true,
})
```

现在，视频音频将从拥有 `VideoPlayer` 组件的实体所在位置传出；玩家越接近该实体，音量就越大。

可通过以下属性控制空间音频：

* `spatialMinDistance`：音频开始呈现空间效果的最小距离。如果玩家距离更近，音频将以最大音量播放。 *0* （默认值）。
* `spatialMaxDistance`：音频可听到的最大距离。如果玩家距离更远，音量将为 0。 *60* （默认值）

```ts
const videoPlayerEntity = engine.addEntity()

Transform.create(videoPlayerEntity, {
	position: Vector3.create(8, 2, 8),
})

VideoPlayer.create(videoPlayerEntity, {
	src: 'https://player.vimeo.com/progressive_redirect/playback/1145666916/rendition/540p/file.mp4%20%28540p%29.mp4?loc=external&signature=db1cd6946851313cb8f7be60d1f6c30af0902bcc46fdae0ba2a06e5fdf44c329',
	playing: true,
	spatial: true,
	spatialMinDistance: 5,
	spatialMaxDistance: 10,
})

MeshRenderer.setPlane(videoPlayerEntity)

Material.setBasicMaterial(videoPlayerEntity, {
	texture: Material.Texture.Video({ videoPlayerEntity: videoPlayerEntity }),
})
```

{% hint style="warning" %}
**📔 注意**：某些视频格式不支持空间音频。请确保流采用以下格式编码： *mp4*, *m4a*或 *mov*.
{% endhint %}

## 音频分析

你可以读取 `VideoPlayer` 实体音轨的实时振幅和频率数据，用于驱动与视频配乐同步的响应式视觉效果。请参阅 [音频分析](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/mei-ti/audio-analysis.md).

{% hint style="info" %}
**💡 提示**：如需了解如何在 GLTF 模型而非基本图元上播放视频，请参阅 [`74,-8-gltfnodemodifier`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/74,-8-gltfnodemodifier) 测试场景。该场景使用 `GltfNodeModifiers` 视频纹理将 HLS 流应用到指定的 GLTF 节点上。
{% endhint %}


---

# 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-zh/chang-jing-sdk7/mei-ti/video-playing.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.
