> 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/3d-jian-mo-he-dong-hua/textures.md). # 纹理 了解纹理在 Decentraland 中的工作方式 纹理是 3D 美术流程中的关键部分，能够实现你希望场景呈现的视觉效果和质感。在本节中，你将找到创建纹理所需了解的一切，包括限制、Blender 中的节点，以及如何优化它们以发挥最佳性能！ {% hint style="info" %} **💡 提示**: 安装 [Decentraland Tools Blender 插件](https://extensions.blender.org/add-ons/decentraland-tools/)。它包含一些实用功能，可帮助你编辑和导出 3D 模型、穿戴物和表情动作。 {% endhint %} ## 限制 ### 纹理尺寸限制 目前，Decentraland Explorer 会在场景上传到内容服务器后，使用 Asset Bundle Converter 出于优化目的将纹理压缩到最大 1024px。创建资源时请务必考虑到这一限制！ 另一个需要注意的重要点是，纹理应始终为 2 的幂次方，任何不符合此规范的纹理在渲染场景时都可能引发问题。 纹理尺寸必须使用符合以下数值的宽度和高度（以像素为单位）： ``` 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 ``` > 这个序列由 2 的幂组成： `f(x) = 2 ^ x` . **我们允许的纹理最大尺寸为 1024。** 这是其他渲染引擎中相当常见的要求，这是由于图形处理器内部优化所致。 宽度和高度不需要相同，但它们都必须属于这个序列。 **纹理的推荐尺寸是 1024x1024**，我们发现这是通过国内网络传输并提供合理加载/画质体验的最佳尺寸。 其他有效尺寸示例： ``` 32x32px 64x32px 512x256px 512x512px 1024x1024px ``` 另一方面，每个地块的纹理数量也有上限： ``` log2(n+1) x 10 每个地块的纹理数量。它包括作为模型一部分导入的纹理。 ``` ## UV 映射 UV 映射是将 3D 模型的面展开为 2D 坐标的过程，之后会用这些坐标为你的资源添加不同的贴图。这是创作流程中的关键部分。正确展开模型是充分利用模型分辨率的关键因素，同时也能让你的贴图更便于修改和调整。 想了解更多关于 UV 展开的内容，你可以看看 Blender Foundation 制作的这个很棒的视频： [![Video Preview](https://i.ytimg.com/vi/Y7M-B6xnaEM/maxresdefault.jpg)](https://youtu.be/Y7M-B6xnaEM?si=qMnWTMsXxC-vxZAH) 另外还有一个很不错的中级 UV 展开教程，由 \[Blender Guru] () 制作，讲解了如何展开更复杂的模型： [![Video Preview](https://i.ytimg.com/vi/scPSP_U858k/maxresdefault.jpg)](https://youtu.be/scPSP_U858k?si=Uw0xHbv9jtqVstDS) ## 贴图 在 [材质部分](https://docs.decentraland.org/creator/3d-modeling/materials/) 我们已经解释了 Decentraland 如何使用 PBR 着色器。在本节中，我们将向你展示每种纹理贴图如何修改着色器，以及随后将导出到世界中的 3D 对象的外观和质感。 ## 漫反射贴图 这是对象表面的基础颜色。让模型之间拥有平衡的色彩方案，是为你的体验打造统一视觉效果和质感的关键。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-082485ff5c6515c1ff70e8cdea3481ceb1f00daf%2F58-difusemap.png?alt=media) 如果你需要的话，这里有一个很酷的免费调色板生成器！ * **Coolors：** 或者也可以从这些优秀电影提供的配色灵感中获取灵感： * **Movies in Color：** ## 金属度贴图 在金属度贴图中，灰度图表示对象所具有的金属程度，白色表示完全金属，黑色表示非金属。在下面的示例中，我们可以看到光线如何影响模型以及它如何与环境交互。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-940b5a7f16290e63bce2002acc9851492a95e280%2F64-metallic-map.png?alt=media) *在图像中我们可以看到纹理的深色部分如何影响模型。深色条纹是不透明的，而白色条纹则会在金属着色器属性下表现，灰色则是两者之间的混合。* ## 粗糙度贴图 在粗糙度贴图中，较暗的区域对应更平滑的表面，而较亮的区域对应更粗糙的表面。渲染引擎使用这种灰度表示来确定光线应如何在表面的不同位置散射或反射。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-5b1c0831ee575f6d338e36bea0ad524cb11234f3%2F48-roughness.png?alt=media) ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-6c2ac22efcec5853d4d0c74442c8875af3b74bb4%2F49-roughness.gif?alt=media) ## 透明贴图 ### Alpha 裁剪 在 Blender 中使用 Alpha Clip 并搭配纹理时，会使用纹理的 alpha 通道来决定材质的哪些部分应当可见。alpha 值高于指定阈值的像素会显示，低于阈值的像素会被丢弃，从而根据纹理的透明信息创建剪切效果。 在下面的示例中，我们使用了一个带有 alpha clip 的材质，使用了两张纹理：漫反射颜色贴图和黑白 alpha 贴图，将颜色连接到 alpha 通道。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-3dd720ef70aa23ce8f81586df52a17d23fc9ea45%2F33-alpha-clip-leave.jpeg?alt=media) ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-ad0aa8f8c1af4f38fddb769be98d92b9692afb8f%2F33-alpha-clip-mask.jpeg?alt=media) ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-5e7675fecbf72c5c637b1dc5688349e0830e7777%2F33-alpha-blender.png?alt=media) *结果是，我们可以看到涂成黑色的区域被丢弃，而白色区域则被渲染出来。* ### Alpha 混合 *Alpha 混合* 允许你按区域选择中间值。 在 Blender 中使用 Alpha Blend 并搭配纹理时，会根据纹理的 alpha 通道对透明区域和不透明区域进行混合。这使纹理能够平滑地结合可见部分和半透明部分，并与背景或场景中的其他对象自然交互。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-5d905cd398beddec84820f474e90cc9d8f0be614%2F33-alpha-blend.png?alt=media) *而 Alpha Clip 的渲染值为 0 或 1（在特定阈值下），Alpha Blend 则会在 0 和 1 之间插值。上面的示例中，alpha blend 材质显示了完整的渐变过渡，而 alpha clip 则排除了由裁剪阈值设定的部分纹理。* {% hint style="warning" %} **🔥优化提示🔥** * 请注意，透明纹理（RGB+A）在性能方面始终比使用灰度值表示透明度更昂贵。 * 在渲染场景时，透明效果始终是一个较耗性能的操作。请尽量将透明效果保持在最低限度，并且只在必要时使用 Alpha Blend，否则优先使用 Alpha Clip 而不是 Alpha Blend。 {% endhint %} ## 自发光贴图 自发光贴图是一种用于控制 3D 场景中表面自发光或发射光线的纹理贴图类型。它是着色器的一个组成部分，用来决定 3D 模型某一部分会发出多少光（以及什么颜色的光），而不依赖外部光源。自发光贴图通常用于模拟看起来像是自己发光的材质或物体。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-6feb4f69267949ee907f39fe867377396b8fa1f6%2F57-emissive-map.gif?alt=media) *在这个示例中，我们可以看到自发光贴图与自发光强度结合使用，并在使用辉光后期处理的环境中，测试其在世界中的大致表现。* ## 法线贴图 法线贴图是一种用于 3D 图形的纹理，用来模拟细微的表面细节，并在不实际改变模型底层几何体的情况下营造复杂几何形状的错觉。它通常用于通过添加凸起、凹痕和其他表面不规则性来增强低多边形模型的真实感。它还允许你让对象本身更轻量，因为许多细节可以通过法线贴图层提供，而无需复杂几何体。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-a01cce23a0225aba58245fe46db1e03abc54252d%2F51-normal-map.png?alt=media) ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-13d87ebefb8dbb8b4ddc2d72b2d6d3db7181872f%2F50-normal.gif?alt=media) 要在 *着色器编辑器*中为材质添加法线贴图，你需要将 ***法线贴图*** 节点连接在纹理和 *Principled BSDF* 着色器之间。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-28db25db5fcad571186fdbe87a7749a75133540e%2F56-normal-map.png?alt=media) {% hint style="warning" %} **⚠️重要⚠️：** 绝不要同时将一张纹理用作 albedo 和 normal，因为这会在渲染场景时造成问题。 {% endhint %} ## 优化纹理 优化纹理的过程在 Explorer 中渲染场景时带来了很多好处，同时也是让场景风格保持一致、并在设计过程中更灵活的好方法。其中一些好处包括： * 在尺寸和压缩方面优化后的纹理会让场景运行更顺畅、更快速，使其下载更快、渲染更容易（尤其是网络连接较慢的玩家）。 * 它减少了渲染体验所需的内存和处理能力，从而为你的玩家带来更好的用户体验。 * 它节省了社区内容服务器的存储空间。 * 使用 **纹理图集** 和/或 **修边贴图** 会让你在迭代场景创作和保持对象之间的风格一致性方面拥有更大的灵活性。使用这些技术，你可以轻松替换纹理、调整颜色或图案，而不必为每个模型单独处理。 * 在模型之间共享纹理可以减少每个场景中的纹理数量，从而大幅降低游戏中的 draw call。如果你使用的是带有嵌入纹理的 glb，你会在以下指南中找到一个提取工具，用于从中提取纹理，并让模型改为使用相同的纹理。 ## glTF 模型之间共享纹理 优化场景的一个明智且常见的做法，是在整个场景中的模型之间共享纹理和材质。这样做可以大幅减少 draw call，让你的 Decentraland 场景运行得更顺畅。 下面这个基于 [**glTF pipeline**](https://github.com/AnalyticalGraphicsInc/gltf-pipeline)**,** 的工具提供了一些优化，可以让 3D 模型更轻量、并让场景中的玩家更快下载。 **Mac：** [MAC GLB 提取器](https://github.com/decentraland/docs-creator/blob/main/images/3d-models-and-animations/glb-extractor/texture_extractor.sh) **PC：** [PC GLB 提取器](https://github.com/decentraland/docs-creator/blob/main/images/3d-models-and-animations/glb-extractor/glb_texture_extract.bat) 它会将 .gltf 格式转换为 .glb，后者是二进制格式，因此占用空间要小得多。它还会把纹理文件放到 3D 模型外部，这样你就可以在多个模型上使用同一张纹理。 > 📔 注意：.glb 格式默认始终会将纹理嵌入文件中。引擎无法识别两个嵌入纹理是否相同，它们需要是共享相同哈希值的外部文件。 ### 如何使用 GLB 纹理提取器 在这个示例场景中，我们在 Blender 中有一个简单的科幻场景。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-d575f4ffe6da295ae53b389c1750eb0840abd219%2F01-scene-base.png?alt=media) 这个场景包含静态模型所需的基础环境，但还有另外两个资源：一个机器人和一艘宇宙飞船，我们希望将它们单独导出，以便之后通过代码移动它们，使其能够与玩家互动。在这种情况下，我们使用了 4 张纹理（地板一张，大多数资源共用的一张图集颜色贴图，一张自发光贴图，以及面板用的一张科幻 UI 纹理） ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-b5ae85bb52a317d7d3b912719f7af6fa68b486b4%2F02-model-01.png?alt=media) ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-66e7694ca025484b771513bd34eb2aa2a14e170e%2F03-model-02.png?alt=media) 当我们把所有这些资源导出到 models 文件夹后，就会得到 3 个模型：静态环境场景、宇宙飞船和机器人。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-69ff6c40205c8fd498908024c05d3264ce0de238%2F04-models-folder.png?alt=media) 但我们遇到了一个问题，.glb 文件把纹理嵌入其中，所以如果你导出的是会复用纹理的不同资源，每次文件夹中出现新资源时，这些纹理都会被重复复制。为了避免纹理重复，我们可以使用这个实用工具。 {% hint style="warning" %} ⚠️ 重要提示：在使用该工具之前，请先备份你的模型，以防万一出错！！！ {% endhint %} **在 Mac 上** 当你把所有资源导出到 models 文件夹后，可以把脚本文件拖到其中。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-23acc844e0c391e705ae38b4d8faf68f098ed761%2F05-texture-extractor.png?alt=media) 1 - 将文件夹拖到终端中以在终端里打开该文件夹。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-79d1c0f266230d5034fd344431403779bb20d08e%2F06-move-to-terminal.png?alt=media) 2 - 将 texture-extractor.sh 拖到终端中。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-f7e370bb546859650efe900f42039f1a90fc14df%2F06-terminal.png?alt=media) 3 - 运行命令。处理所有资源可能需要几秒钟。之后你会看到类似这样的内容： ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-599d9f4378fa9d37c84a049eaefc0862ccfca295%2F07-run-terminal.png?alt=media) 4 - 前往你的 models 文件夹，你会看到一个名为“out”的新文件夹，其中会有提取出纹理的新资源。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-f1d505887c8a5d4a2aa6773e0da76ca852bffa6a%2F08-out-folder.png?alt=media) 5 - 用新资源替换所有旧资源！另外，完成后请删除“texture-extractor.sh”和空的“out”文件夹。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-df02204ffa5207d1385b235de809f66f8ef9129e%2F09-replace-assets.png?alt=media) **在 Windows 上** 当你把所有资源导出到 models 文件夹后，可以将脚本文件拖入其中。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-4990daa279b27670ced263e8f16487a978da7229%2F10-windows-01.png?alt=media) 1 - 双击 glb\_texture\_extract.bat 以提取文件。如果 Windows 提示你这是无法识别的应用，请前往 **更多信息** 然后 **仍要运行**. ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-550a0241a9125dccf5192e0813dbb64fcd94a0ba%2F11-windows-02.png?alt=media) ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-c069eba1ab8124f6c0ec5a695000fbb1621535de%2F12-windows-03.png?alt=media) 2 - 脚本会生成一个名为 out 的文件夹，你会在那里找到所有带有已提取纹理的新 .glb 文件。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-853904a4678b2554c8c3e612d6cea23db7b42735%2F13-windows-03.png?alt=media) 5 - 用新资源替换所有资源。完成后，删除“texture-extractor.bat”脚本和空的“out”文件夹。 如果你完成了所有步骤，你的场景现在会快得多，而且资源会共享同一张纹理！当我们处理多个资源和大型场景时，改进效果会非常明显！使用这个工具，你可以节省相当多的兆字节信息！ {% hint style="warning" %} ⚠️ 完成这一步后，务必要检查每张纹理是否都符合指南。如果纹理不符合指南或过于庞大，请在部署前先将其优化为更轻量。对于性能良好的场景，推荐的纹理尺寸为 1024x1024。此外也请检查分辨率，超过 72 DPI 的图像会影响性能，而且不会让图像看起来更好。 {% endhint %} ## 纹理图集 / 修边贴图 纹理图集是一种单一图像文件，其中包含了多张较小图像的数据并将它们打包在一起。与每个网格使用一张纹理不同，多个网格共享一张更大的纹理。 你可以在制作资源之前创建纹理图集，这意味着该资源会按照纹理图集进行 UV 展开。这在创建纹理时需要提前规划。 或者，你也可以在资源完成后，通过在绘制软件中合并纹理来创建纹理图集。不过，这也意味着 UV 岛必须根据纹理重新排列。 下面这张图展示了多个使用同一套纹理的 3D 对象： ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-9f156c42d55defe8f368ba8b5989ce694868fae9%2F37-atlas-texture.png?alt=media) ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-9d0189a956bccdbf9a4218e4f09910501899cd47%2F38-uv-atlas.png?alt=media) 实现图集的另一种方法是使用修边贴图（Trim Sheets），这是一种在 3D 建模和游戏开发中常见的技术，大型工作室和游戏行业都使用它来确保视觉一致性和高效的美术流程。修边贴图是使用一张包含多个小细节或元素的单一图像或纹理，并将其应用到模型的不同部分。当创建大型场景时，这种技术非常有用，并且需要在美术流程的第一阶段就加以考虑。 ![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-c54001f41883c274490680f8eb40bac5272efb69%2F39-trim-sheets.png?alt=media) *一张修边贴图拼贴示例，使用了漫反射纹理、法线和自发光。* 这里有一个很棒的 [教程](https://www.artstation.com/blogs/jennifermcgarry/yd4Q/jenns-guide-to-trim-sheets) 乘以 [Jennifer McGarry](https://www.artstation.com/jennifermcgarry/blog) ，讲解了如何在 Blender 中使用修边贴图！ ## 纹理命名 **正确命名纹理至关重要。** 正确的纹理命名将： * 让你的美术流程更高效、更灵活、更有条理，也更容易在必要时定位和修改。 * 避免使用纹理提取器或其他工具时出现同名纹理重叠。 * 避免在使用 Asset Bundles 时出现纹理重叠问题。 * 在分析场景时，更高效地定位问题点。 **如何正确命名你的纹理：** * **资源名称** 应当清楚地表示该纹理是什么。 * 纹理名称应以以下前缀开头 `T_`. * 纹理名称应以定义纹理类型的后缀结尾： * `_D` - **漫反射 / 颜色贴图** * `_A` - **Alpha 纹理** * `_MT` - **金属度** * `_R` - **粗糙度** * `_N` **- 法线贴图** * `_E` - **自发光** 例如：如果它是墙面砖纹理的漫反射贴图，名称 `T_BrickWall_D` 可能是合适的。如果它是同一资源的法线贴图，名称可以是 `T_BrickWall_N` **示例：** * 🟢 **建议** 以 - 开头的纹理名称 `T_Parquet_D`, `T_Floor_R`, `T_Pipes_MT`, * 🔴 **避免** 以 - 开头的纹理名称 `Image_`, `sprite_`,`未命名` ## 可选工具 有许多插件和外部工具可以帮助制作资源，让流程更快、更高效，其中有些是免费的，有些需要购买，举例如下： ### UVTools * **UV Packer（免费）**: * **Zen UV：** * **Uvpackmaster 3：** ### 图片压缩器 你可以使用多个在线图片压缩器来让纹理更轻量。举例如下： * **CompressPNG：** * **TinyPNG：** * **FreeConvert：** --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.decentraland.org/creator/content-creator-zh/3d-jian-mo-he-dong-hua/textures.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.