> 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-pt/scenes-sdk7/tipos-de-projetos/scene-metadata.md). # Metadados da scene Uma scene é um projeto da Decentraland que é delimitado espacialmente e está mapeado para uma ou várias parcelas. Se uma scene for implantada no mapa da Genesis City da Decentraland, os players podem vivenciá-la visitando as coordenadas da scene. Se uma scene for implantada em um [World](/creator/content-creator-pt/worlds/about.md), os players podem visitá-la via URL. Veja [Arquivos em uma scene](/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/scene-files.md) para ver uma lista dos arquivos usados em um projeto de scene. ## Metadados Para editar os metadados de uma scene no [Scene Editor no Creator Hub](/creator/content-creator-pt/scene-editor/comecar/about-editor.md), abra uma scene e clique no **ícone de lápis**. ![](/files/ea4f5a0409da4681504556218c82ae7bcb3285b7) Isso abre o menu da scene, onde você pode configurar várias propriedades. ![](/files/346a3060b640795e9ee0ad9b994c0de6f14abcce) Como alternativa, você pode editar diretamente o `scene.json` arquivo, onde todos esses valores são armazenados. {% hint style="warning" %} **📔 Observação**: Não adicione campos personalizados ao `scene.json` arquivo que não sejam mencionados nesta página, pois isso pode causar problemas ao carregar sua scene. {% endhint %} ## Título, descrição e imagem da scene É muito importante dar à sua scene um título, uma descrição e uma imagem em miniatura para atrair players e ajudá-los a saber o que esperar. Os players verão isso exibido em um modal quando selecionarem as parcelas da sua scene no mapa. Eles também verão isso em uma tela de confirmação quando forem [teletransportados](/creator/content-creator-pt/scenes-sdk7/interatividade/external-links.md) até lá por outra scene. Configurar dados atraentes aqui pode ajudar significativamente a atrair tráfego para sua scene. Quando os players navegam pelo mundo e entram na sua scene, eles conseguem ler o título da scene abaixo do minimapa. ![](/files/d8c5ae9a62b37953aeab1b64c9aa25bd294e1265) Adicione esses dados pelo menu da scene no Scene Editor. A miniatura deve ser uma *.png* imagem com o tamanho recomendado de *228x160* pixels. O tamanho mínimo suportado é *196x143* pixels. A imagem pode ficar esticada se as proporções de largura e altura não corresponderem *228x160*. A imagem em `navmapThumbnail` deve ser um caminho para um arquivo de imagem na pasta do projeto. Ela também pode ser um link URL para uma imagem hospedada em outro lugar. {% hint style="warning" %} **📔 Observação**: Se você hospedar uma imagem em outro lugar, certifique-se de que seja em um site com políticas CORS permissivas para exibir conteúdo em outros sites. {% endhint %} Caso queira que outros desenvolvedores possam entrar em contato com você, você também pode adicionar informações de contato à sua scene. ## Categorias Você pode adicionar categorias à sua scene para ajudar os players a explorar Decentraland. Elas são usadas no [Decentraland Places dApp](https://places.decentraland.org) para categorizar cada lugar e facilitar para os players encontrarem o que lhes interessa. **Categorias** precisam ser escolhidas de uma lista predefinida de opções: * 🎨 Arte * 🕹️ Jogo * 🃏 Cassino * 👥 Social * 🎶 Música * 👠 Moda * 🪙 Cripto * 📚 Educação * 🛍️ Loja * 🏢 Negócios * 🏅 Esportes * 🏃 Parkour Uma scene pode pertencer a mais de uma categoria, com no máximo 3 categorias listadas. No `scene.json` as categorias estão listadas no `tags` array. Estas são as categorias predefinidas: * `arte` * `jogo` * `cassino` * `social` * `música` * `moda` * `cripto` * `educação` * `loja` * `negócios` * `esportes` * `parkour` Por exemplo, uma scene poderia ser marcada como `jogo` e `cassino` adicionando o seguinte ao `scene.json` ```json "tags": [ "game", "casino", ], ``` Depois disso, a scene é listada na dApp Places sob as `jogo` e `cassino` categorias. ## Classificação etária O **Classificação etária** campo é usado para classificar o conteúdo da sua scene. Decentraland é uma plataforma 18+. A seguinte opção está disponível: * **🟡 `A` para adultos (18+)**: Este é o requisito mínimo de idade, conforme especificado nos [Termos de Uso](https://decentraland.org/terms)da Decentraland. Escolha esta categoria se sua scene tiver conteúdo apropriado para adultos, como linguagem moderada ou intensa, violência, conteúdo explícito, jogos de azar ou substâncias como álcool, tabaco e drogas. Ao editar a Classificação Etária via o `scene.json`, a classificação é um **código de uma única letra**, escreva **A** A para adultos. ![](/files/7ff4ea2df3d78eb24bf709f1dd26696ed3902140) ```json "scene": { "rating": "A" } ``` ### Conteúdo restrito Há uma terceira categoria para scenes: 🔴 `R` para Restrito. Essa classificação é aplicada manualmente pelos Moderadores de Conteúdo a scenes que violam a [Política de Conteúdo](https://decentraland.org/content). As violações podem incluir, mas não se limitam a: * conteúdo suspeito ou spam * conteúdo abusivo ou de ódio * conteúdo sexual ou degradante * abuso infantil * assédio ou bullying * promoção de terrorismo/violência * violação de IP/direitos autorais Scenes com essa classificação não serão carregadas e ninguém poderá interagir com elas. Se sua scene se enquadrar nessa categoria, você deve revisá-la e atualizá-la para cumprir a [Política de Conteúdo](https://decentraland.org/content). ## Alternadores de recursos Há certos recursos que podem ser desativados em scenes específicas para que os players não possam usá-los de forma abusiva. Configure isso na aba de **Configurações** das configurações da scene. ![](/files/2e60f925036eafede483b6d294810b3b143afcca) Atualmente, apenas o seguinte recurso é tratado dessa forma: * **Voice Chat**: Refere-se a players usando seus microfones para conversar por voice chat com outros players próximos. * **Desativar experiências portáteis**: Essa configuração definirá o comportamento de qualquer experiência portátil de um player enquanto ele estiver dentro da sua scene. Isso inclui não apenas [experiências portáteis](/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/portable-experiences.md) mas também [smart wearables](/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/smart-wearables.md). Com essa configuração, você pode escolher manter tudo ativado (padrão), desativar ou ocultar a UI deles. Isso é útil para scenes em que experiências portáteis possam dar uma vantagem injusta a alguns players, por exemplo usando um jetpack em um desafio de parkour. Também é recomendado impedir isso em scenes onde ocorrem transações em blockchain e onde uma experiência portátil maliciosa poderia potencialmente se passar pela UI da scene. No `scene.json` arquivo, esses alternadores são gerenciados em `featureToggles`. Os recursos correspondentes ficam ativados por padrão, a menos que sejam especificados como *desativados* no `scene.json` arquivo. ```json "featureToggles": { "voiceChat": "disabled", "portableExperiences": "enabled" | "disabled" | "hideUi" }, ``` Se uma `featureToggles` propriedade não existir no seu `scene.json` arquivo, crie-a no nível raiz da árvore JSON. ### Gorjetas Você pode receber gorjetas de players que visitam sua scene. Para ativar gorjetas, vá para a **Detalhes** aba nas configurações da scene e forneça um endereço Ethereum em **endereço da carteira do criador**. ![](/files/e5deae014e4c2b40ad9f9c95ecf4c173b8a30693) Você também pode fornecer o endereço de gorjetas da sua scene no `scene.json` arquivo, no `creator` campo. ```json "creator": "0x1234567890123456789012345678901234567890" ``` Quando um player visita sua scene, ele verá um ícone de cofrinho no canto superior esquerdo da tela. Clicar nele abre um modal onde ele pode lhe enviar uma gorjeta. Esse menu também pode ser acessado ao abrir as informações da sua scene no mapa. ![](/files/e19d67a06f216c7551de5f8d4bcb880d66e94e47) O modal de gorjeta permite que o player selecione a quantidade de MANA que deseja enviar. O player precisa possuir MANA em sua wallet para enviar uma gorjeta. Se o endereço que você forneceu estiver vinculado a um Decentraland NAME, esse modal mostrará o nome do proprietário da wallet além do endereço Ethereum. ![](/files/636be7d0b3a5670d06388b75dd878008f3048f8a) Você receberá uma notificação na aba de notificações da Decentraland sempre que um player lhe enviar uma gorjeta. ## Local de spawn O **Configurações de spawn** no **Configurações** aba define onde os players surgem quando acessam sua scene diretamente, seja digitando as coordenadas diretamente no navegador ou por teleport. ![](/files/d2622ee973b03986fd6df9c93ba72c4b1bf392a5) Sua scene pode ter objetos que bloqueiem a movimentação dos players se eles surgirem em cima deles, como árvores ou escadas. Sua scene também pode ter terreno elevado. Para evitar que os players surjam em locais onde não consigam se mover, você pode definir várias posições de spawn em locais específicos. A posição consiste em coordenadas dentro da scene. Esses números se referem a uma posição dentro da parcela, semelhante ao que você usaria no código da scene em um componente Transform para [posicionar uma entity](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/entity-positioning.md). {% hint style="warning" %} **📔 Observação**: Todos os pontos de spawn precisam estar dentro das parcelas que compõem a scene. Você não pode fazer o spawn de um player fora do espaço dessas parcelas. {% endhint %} Marque a **Deslocamento aleatório** caixa para deslocar aleatoriamente os players que surgem ao redor do ponto de spawn. Isso impede que todos os players apareçam sobrepostos uns aos outros quando surgem, o que fica especialmente ruim em scenes lotadas. O **Deslocamento máximo** valor é a distância máxima possível do ponto de spawn original, nos eixos X e Z. Defina o **Alvo da câmera** para controlar a direção para a qual os players ficam voltados quando entram na sua scene. Isso oferece a você mais controle sobre a primeira impressão deles e pode ajudar a guiá-los em uma direção específica. Por padrão, isso aponta para `{x: 8, y:1, z:8}`, que é o centro da scene em cenas de uma única parcela, ou o centro da parcela inferior esquerda para scenes maiores. Clique em **Adicionar ponto de spawn** para listar quantos pontos de spawn quiser. Os players aparecerão aleatoriamente em um deles. ### Pontos de spawn em JSON Os pontos de spawn também podem ser configurados pelo `scene.json` arquivo, no `spawnPoints` campo. ```json "spawnPoints": [ { "name": "spawn1", "position": { "x": 5, "y": 1, "z": 4 } } ], ``` Uma única scene pode ter vários pontos de spawn. Isso é especialmente útil em scenes grandes. Para ter muitos pontos de spawn, basta listá-los como um array. ```json "spawnPoints": [ { "name": "spawn1", "position": { "x": 5, "y": 1, "z": 4 } }, { "name": "spawn2", "position": { "x": 3, "y": 1, "z": 1 } } ], ``` Quando há vários pontos de spawn, é selecionado aquele mais próximo das coordenadas indicadas pelo player. Se um ponto de spawn for marcado como `padrão`, ele sempre será usado, independentemente de ser o mais próximo. Se vários pontos de spawn forem marcados como `padrão`, o mais próximo é selecionado. ```json "spawnPoints": [ { "name": "spawn1", "default": true, "position": { "x": 5, "y": 1, "z": 4 } }, { "name": "not-used", "position": { "x": 3, "y": 1, "z": 1 } } ], ``` **Regiões de spawn** Você pode definir uma região inteira na scene para agir como um ponto de spawn. Ao especificar um array de dois números para qualquer dimensão da posição, os players aparecerão em um local aleatório dentro desse intervalo. Isso ajuda a evitar que os players que entram se sobreponham. ```json "spawnPoints": [ { "name": "region", "position": { "x": [1,5], "y": [1,1], "z": [2,4] } } ], ``` No exemplo acima, os players podem aparecer em qualquer ponto do quadrado cujos cantos estão em *1,1,2* e *5,1,4*. Uma scene também pode ter várias regiões de spawn, assim como pode ter vários pontos de spawn. ```json "spawnPoints": [ { "name": "region1", "position": { "x": [1,5], "y": [1,1], "z": [2,4] } }, { "name": "region2", "position": { "x": [1,5], "y": [1,1], "z": [6,8] } } ], ``` **Rotação** Você também pode especificar a rotação dos players quando eles surgem, para que fiquem voltados para uma direção específica. Basta adicionar um `cameraTarget` campo aos dados do ponto de spawn. O valor de `cameraTarget` deve fazer referência a um local no espaço, com coordenadas *x*, *y* e *z* relativas à scene, assim como `position` campo. ```json "spawnPoints": [ { "name": "spawn1", "position": { "x": 5, "y": 1, "z": 4 }, "cameraTarget": { "x": 10, "y": 1, "z": 4 } } ], ``` Este exemplo faz spawn de um player em *5, 1, 4* voltado para Leste em direção a *10, 1, 4*. Se a posição de spawn for um intervalo, a rotação do player sempre corresponderá ao alvo indicado. Se houver vários pontos de spawn, cada um pode ter seu próprio alvo separado. ## Permissões necessárias O `requiredPermissions` propriedade gerencia vários recursos controlados que poderiam ser usados de maneira abusiva e prejudicar a experiência de um player. {% hint style="warning" %} **📔 Observação**: As permissões só são relevantes em [experiências portáteis](/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/portable-experiences.md) e [smart wearables](/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/smart-wearables.md). Cenas normais (tanto em parcels quanto em Worlds) não são afetadas por essas permissões e podem usar livremente a funcionalidade correspondente. {% endhint %} Esses recursos são bloqueados para uso na scene, a menos que a permissão seja solicitada no `scene.json` arquivo. ```json "requiredPermissions": [ "ALLOW_TO_MOVE_PLAYER_INSIDE_SCENE", "OPEN_EXTERNAL_LINK", ], ``` Atualmente, as seguintes permissões são gerenciadas em smart wearables e experiências portáteis: * `ALLOW_TO_MOVE_PLAYER_INSIDE_SCENE`: Refere-se a [mover um jogador](/creator/content-creator-pt/scenes-sdk7/interatividade/player-avatar.md#move-player) * `ALLOW_TO_TRIGGER_AVATAR_EMOTE`: Refere-se a [executar emotes no avatar do jogador](/creator/content-creator-pt/scenes-sdk7/interatividade/player-avatar.md#play-animations) * `USE_WEB3_API`: Refere-se a interagir com as carteiras do navegador do player, para realizar transações ou assinar mensagens. * `USE_FETCH`: Refere-se a enviar requisições HTTP para servidores de terceiros, usando `fetch` ou `signedFetch` * `USE_WEBSOCKET`: Refere-se a abrir conexões WebSocket com servidores de terceiros * `OPEN_EXTERNAL_LINK`: Refere-se a solicitar ao player que abra links para sites externos Se uma `requiredPermissions` propriedade não existir no seu `scene.json` arquivo, crie-a no nível raiz da árvore JSON. ## Parcelas da scene Quando [implantando](/creator/content-creator-pt/scenes-sdk7/publicacao/publishing.md) uma scene, o conteúdo é enviado para as coordenadas atribuídas na configuração da scene. Uma scene pode incluir uma única parcela, ou uma lista de até dezenas delas. Edite isso na segunda aba do menu da scene no Scene Editor. ![](/files/b40cf92313d14f1ee9156be1f22cb13f0a25deb7) Use os menus suspensos e clique em **Aplicar layout** para alterar as dimensões da sua scene. Você também pode clicar em cada parcela individual para desativá-la no seu layout. ![](/files/8738a0024c2b6c5031340f96343de1d2fe83deab) A cena padrão tem suas coordenadas definidas como *0,0*. Você não precisa alterar isso ao desenvolver uma scene offline, a menos que precise ocupar várias parcelas. Você precisará alterar isso antes de implantar em coordenadas nas quais você tenha permissões de deploy. Você também pode alterar as coordenadas da scene no `scene.json` arquivo: ```json "scene": { "parcels": [ "54,-14" ], "base": "54,-14" } ``` O `base` campo define qual parcela considerar como a parcela base. Se sua scene tiver uma única parcela, a base deve ser essa parcela. Se sua scene tiver várias parcelas, a base deve ser a parcela inferior esquerda (sudoeste). Todas as posições das entities são medidas em relação ao canto sudoeste dessa parcela. Para exibir várias parcelas na pré-visualização da scene, liste quantas parcelas pretende usar. Elas não precisam ser as parcelas exatas nas quais você fará o deploy, mas todas devem ser adjacentes e organizadas nas mesmas posições relativas. ```json "scene": { "parcels": [ "54,-14", "55,-14" ], "base": "54,-14" } ``` {% hint style="warning" %} **📔 Observação**: O maior tamanho de scene que você pode definir é de 45 x 45 parcelas. {% endhint %} ### Defina parcels pela linha de comando Você pode definir as parcels na sua scene executando o `npx update-parcels` comando na pasta da sua scene. Isso é especialmente útil para scenes grandes, pois você não precisa listar cada parcela envolvida. **Parcela única** Passe um único argumento com as coords da scene. Essa coordenada também é definida como a parcela base. `npx update-parcels ` Por exemplo: `npx update-parcels 15,-26` **Múltiplas parcelas** Passe dois argumentos: as parcelas sudoeste e nordeste. A parcela sudoeste também é definida como a parcela base. `npx update-parcels ` {% hint style="info" %} **💡 Dica**: A parcela sudoeste é sempre aquela com os menores números em ambas as *X* e *Y* coordenadas. {% endhint %} Por exemplo: `npx update-parcels 15,-26 17,-24` Este comando gera uma scene 3x3, com sua parcela base em `15,-26`. **Personalizar parcela base** Passe três argumentos: as parcelas sudoeste e nordeste, e a parcela a ser usada como parcela base. `npx update-parcels ` {% hint style="warning" %} **📔 Observação**: A parcela base deve ser uma das parcelas da scene. {% endhint %} **Cenas não quadradas** Os comandos acima geram todas cenas em formato retangular. As scenes da Decentraland podem ter formato de L ou outras configurações. Você pode gerar um quadrado maior com `npx update-parcels` e depois remover manualmente as parcelas excedentes de `scene.json` arquivo. {% hint style="warning" %} **📔 Observação**: A parcela base deve ser uma das parcelas da scene. {% endhint %} ## Hora do dia da skybox Você pode definir uma hora do dia fixa para a sua scene. Todos os players verão a scene com essa hora do dia, e a skybox não seguirá o ciclo dia/noite. Abra as configurações da scene e clique na **Configurações** aba para encontrar a **Skybox** seção. Desmarque a opção **Auto** e defina a hora do dia que você quiser. Você também pode definir a hora do dia da skybox no código da sua scene. Para isso, adicione a seguinte seção ao seu `scene.json` no nível raiz: ```json "skyboxConfig": { "fixedTime": 36000 } ``` O número refere-se ao número de segundos desde o início do dia, variando de 0 (representando *00:00*) a 86400 (representando *24:00*). Qualquer número superior a 86400 também é interpretado como meia-noite. Aqui estão mais alguns exemplos de valores válidos: * 0 segundos => *00:00* * 21600 segundos => *06:00* * 43200 segundos => *12:00* * 64800 segundos => *18:00* * 86400 segundos => *24:00* ## Configuração do World Ao publicar num [Decentraland World](/creator/content-creator-pt/worlds/about.md), pode configurar várias definições específicas do World no seu `scene.json` ficheiro usando o `worldConfiguration` objeto. ### Configuração básica do World Para publicar num World, tem de especificar o NAME ou o domínio ENS no seu `scene.json`: ```json { "worldConfiguration": { "name": "my-name.dcl.eth" } } ``` O **name** especificado pode ser um Decentraland NAME ou um domínio ENS e tem de pertencer à wallet que assina a deployment (ou a qualquer wallet a quem tenha sido dada permissão através de Access Control Lists). ### Configuração do serviço de comunicação O `fixedAdapter` propriedade indica qual Communication Service deve ser usado pela scene. Por enquanto, apenas o `offline:offline` valor é permitido. Quando definido, a scene não terá qualquer Communication Service e cada utilizador que entrar nesse World estará sempre sozinho. Se não estiver definido, o server de conteúdo dos Worlds gerará um valor apropriado com base na forma como está configurado. ```json { "worldConfiguration": { "name": "my-name.dcl.eth", "fixedAdapter": "offline:offline" } } ``` {% hint style="warning" %} **📔 Observação**: Definir `fixedAdapter` para `"offline:offline"` (ou ativar **Single Player** em World Settings através do Creator Hub) desativa o live streaming. A funcionalidade de streaming depende da camada de comunicações para entregar vídeo aos espectadores. Se precisar de live streaming no seu World, não use esta opção. {% endhint %} ### Configuração da listagem em Places Todos os Worlds são automaticamente listados na página Places, a menos que opte por não participar. Se quiser optar por não permitir que os seus Worlds sejam indexados em Places, pode adicionar o seguinte: ```json { "worldConfiguration": { "name": "my-name.dcl.eth", "placesConfig": { "optOut": true } } } ``` ### Exemplo completo Aqui está um exemplo completo com todas as opções de configuração do World: ```json { "worldConfiguration": { "name": "my-name.dcl.eth", "fixedAdapter": "offline:offline", "placesConfig": { "optOut": true } } } ``` Veja [Publicar em Worlds](/creator/content-creator-pt/scenes-sdk7/publicacao/publishing.md#publishing-to-worlds) para mais informações sobre publicar em Worlds. ## Obter metadata do código da scene [Referência da Scene API](https://js-sdk-toolchain.pages.dev/modules/js_runtime_apis.__system_Scene_) Pode precisar do código da sua scene para aceder a campos dos metadados da scene, como os parcels para os quais a scene é deployada, ou as posições do spawn point. Isto é especialmente útil para scenes que devem ser replicadas, ou para código que deve ser reutilizado noutras scenes. Também é muito útil para libraries que precisam de saber onde estão os limites da scene. Para aceder a estes dados, primeiro importe a `getSceneInformation` função: ```ts import { getSceneInformation } from '~system/Runtime' ``` Depois pode chamar a `getSceneInformation()` função, que devolve um objeto JSON que inclui a maior parte do conteúdo do ficheiro scene.json. O exemplo abaixo mostra como aceder a vários dos campos mais comuns da resposta desta função: ```ts import { getSceneInformation } from '~system/Runtime' executeTask(async () => { const sceneInfo = await getSceneInformation({}) if (!sceneInfo) return console.log("SCENE INFO: ", sceneInfo) }) ``` {% hint style="warning" %} **📔 Observação**: `getSceneInformation()` tem de ser executado como uma [async function](/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/async-functions.md), uma vez que a resposta pode demorar uma fração de segundo ou mais a devolver dados. Não use a `getSceneInfo()` função descontinuada. {% endhint %} O objeto devolvido por `getSceneInformation()` inclui o seguinte: * `baseUrl`: O URL base onde o conteúdo da scene está alojado * `content`: Uma matriz com todos os ficheiros da scene, incluindo o respetivo hash, que pode ser usada em conjunto com o baseUrl para os obter. * `metadataJson`: O conteúdo completo do scene.json da scene, como uma string. Tem de fazer parse disto para obter valores específicos. * `urn`: O urn único para a scene como um todo. O exemplo abaixo faz parse do conteúdo de `metadataJson` para obter valores das propriedades no ficheiro scene.json ```ts import { getSceneInformation } from '~system/Runtime' executeTask(async () => { const sceneInfo = await getSceneInformation({}) if (!sceneInfo) return const sceneJson = JSON.parse(sceneInfo.metadataJson) const spawnPoints = sceneJson.spawnPoints const parcels = sceneJson.scene.parcels console.log({ parcels, spawnPoints }) }) ``` --- # 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-pt/scenes-sdk7/tipos-de-projetos/scene-metadata.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.