# Referência do manifesto de pacote — App e CLI do AI Game Dev · AI Game Developer Wiki

Todos os campos do aigd-package.json: ids e versões, engines.aigd, eventos de ativação, dependências e cada ponto de contribuição com suas regras.

Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/app/package-manifest).

`aigd-package.json` é o manifesto de um pacote do AI Game Dev: seu id, sua versão, as versões do app com as quais ele funciona e tudo o que ele contribui. O app o lê sem executar nenhum código do pacote, então cada item de menu, comando de barra, switch em Tools e view fica visível antes de o pacote ativar. Esta página lista cada campo e ponto de contribuição com suas regras. Um pacote novo criado com `gamedev pkg init` já vem com um manifesto válido e seu JSON Schema (nomeado por `$schema`) para autocompletar no seu editor.

## Campos de nível superior

| Campo | Obrigatório | O que é |
| --- | --- | --- |
| `publisher` | Sim | Seu id de publisher: 2 a 40 caracteres, começando com uma letra, depois letras minúsculas, dígitos e hífens simples, sem pontos |
| `name` | Sim | O nome do pacote: 2 a 64 caracteres, em minúsculas, começando com uma letra |
| `version` | Sim | Semver `MAJOR.MINOR.PATCH` (um sufixo de pré-lançamento como `1.3.0-beta.2` é permitido) |
| `engines.aigd` | Sim | A versão mais antiga do AI Game Dev de que o pacote precisa, por exemplo `">=0.18.0"` |
| `displayName`, `description` | Não | Exibidos na janela Packages e no catálogo (`displayName` até 60 caracteres, `description` até 400) |
| `icon`, `avatarText` | Não | Uma imagem relativa ao pacote, ou até 4 caracteres desenhados como o avatar |
| `license` | Não | Um id SPDX (`MIT`, `Apache-2.0`) ou `SEE LICENSE IN <file>` |
| `homepage`, `repository`, `keywords` | Não | Links e até 20 palavras-chave |
| `main` | Não | A entrada de código (CommonJS ou ESM) que exporta `activate`; sem ela o pacote é somente contribuições |
| `activationEvents` | Não | Eventos extras que iniciam o código (abaixo) |
| `hosts` | Não | `["desktop"]`, `["cli"]` ou ambos (o padrão); um pacote somente desktop é ignorado pela CLI |
| `dependencies` | Não | Outros pacotes, `{ "<publisher.name>": "<range>" }` |
| `claudePlugins`, `claudeMarketplaces` | Não | Plugins do Claude Code de que o pacote precisa, e onde encontrar seus marketplaces |
| `enabledApiProposals` | Não | API proposta que o pacote usa; o registro recusa qualquer entrada aqui |
| `dataVersion` | Não | A versão dos dados que seu código armazena (informativo) |
| `contributes` | Não | Tudo o que o pacote adiciona (abaixo) |

O id do pacote é `publisher.name`: `acme.level-tools`. Ele precisa ser igual à chave sob a qual o pacote está instalado, ou nada executa (`id-mismatch`). O publisher `aigd` pertence ao AI Game Developer, e os nomes de engine `unity`, `godot`, `unreal`, `brutal`, `bevy` e `threejs` são reservados.

## A versão do app: engines.aigd

`engines.aigd` é um mínimo, como `">=0.18.0"`. Um app mais antigo que isso recusa o pacote e informa de qual versão ele precisa. Um beta do app conta como a versão final que ele pré-visualiza: `0.32.0-beta.1` satisfaz `">=0.32.0"`. O piso mais antigo que o app ainda carrega é `0.18.0`; defina o seu como o app mais antigo com o qual você testou. Um pacote de engine de jogo precisa de `">=0.32.0"`.

As instalações são cacheadas por id e versão: cada alteração que você publicar precisa de uma `version` mais alta.

## Ids que seu pacote possui

Tudo o que um pacote contribui é nomeado dentro do seu próprio id, então dois pacotes nunca colidem:

- Comandos, painéis, views, contêineres de view, submenus, itens da barra de status, tutoriais e editores personalizados: `<package id>.<local>`, por exemplo `acme.level-tools.export`.
- Capacidades: o próprio id do pacote ou `<package id>.<local>`. Um id de capacidade é armazenado por chat, então nunca renomeie um.
- Nomes de servidores MCP: `<publisher>--<name>` ou `<publisher>--<name>-<suffix>`, no máximo 96 caracteres: `acme.level-tools` possui `acme--level-tools` e `acme--level-tools-preview`. O modelo vê esse nome em cada nome de ferramenta, e é por isso que ele usa `--` em vez de um ponto. Um nome sem qualificação é um erro.
- Chaves de contexto que você define com `aigd.commands.setContext`: `<package id>.<key>`.

`gamedev pkg validate` indica cada id que não é seu, com seu campo.

## Pontos de contribuição

| Ponto | Formato | Observações |
| --- | --- | --- |
| `commands` | `{command, title, shortTitle?, category?, icon?, palette?, hosts?, enablement?}` | Entradas da paleta; `enablement` é uma cláusula `when` |
| `slashCommands` | `{name, description, argumentHint?, hosts?}` | `name` como digitado, `/export`; um comando embutido ganha em caso de conflito de nome, depois o primeiro pacote por id |
| `capabilities` | `{id, label, description, defaultEnabled?, mcpServer?, gatesClaudePlugin?, statusful?, hidden?, icon?}` | Um switch na linha Tools de um chat; `mcpServer` nomeia o servidor que ele ativa |
| `mcpServers` | `{ "<server name>": {command, args?, env?} or {type: "http" or "sse", url, headers?} }` | Servidores stdio podem usar `${node}`, `${packageDir}`, `${projectDir}`, `${globalStorage}` |
| `agentProviders` | `{id, serverName, capabilityId, sessionToolViewId?}` | Ferramentas que seu código serve em memória por meio de `aigd.agent.registerProvider` |
| `settings` | `{ "<key>": {type, default?, description, enum?, scope?, …} }` | Tipos `string`, `number`, `boolean`, `string[]`, `path` |
| `menus` | `{ "<menu id>": [{command or submenu, group?, when?, alt?}] }` | Ids de menu fixos (abaixo) |
| `submenus` | `{id, label, icon?}` | Um id de submenu também é uma chave de menu |
| `keybindings` | `{command, key, mac?, win?, linux?, when?, args?}` | Desktop; `ctrl` significa Cmd no macOS, a menos que `mac` seja informado |
| `statusBar` | `{id, text, tooltip?, command?, alignment?, priority?, when?}` | Desktop |
| `panels` | `{viewType, title, icon?}` | Painéis webview que seu código abre |
| `viewsContainers` | `{left?: [{id, title, icon}], right?: [...]}` | Novas abas de painel lateral |
| `views` | `{ "left" or "right" or "<container id>": [{id, name, type: "tree" or "webview", icon?, when?, welcome?, titleBar?}] }` | Exibições em árvore e exibições webview nos painéis laterais |
| `customEditors` | `{viewType, displayName, selector: [{filenamePattern}], priority?}` | `priority` `default` (o padrão) substitui a pré-visualização integrada para os arquivos correspondentes; `option` aparece em Open With |
| `tutorials` | `{id, title, anchor, markdown? and media? or webview?, size?, trigger?, when?, after?, priority?}` | Dicas curtas dentro do app, mostradas uma vez por usuário |
| `claudePlugin` | uma pasta relativa ao pacote | Um plugin do Claude Code incluído no pacote |
| `mediaProviders` | `{id, capabilityId, execution: "local"}` | Um gerador de mídia local que seu código registra com `aigd.media.registerProvider` |
| `sessionTools` | `{id, capabilityId, title, modules?}` | Uma superfície de configuração para uma capability nas Tools de um chat (uma webview view que seu código resolve) |
| `gameEngines` | veja [Pacotes de motor de jogo](https://ai-game.dev/pt-br/docs/wiki/app/game-engine-packages) | Um motor por pacote |
| `runtimes`, `imageModels`, `videoModels`, `model3dModels`, `mediaModels` | declarativo, sem código | Runtimes de geração locais e os modelos que eles executam, e famílias de modelos na nuvem |

Ícones são `$(name)`, um ícone do conjunto de ícones do app, ou um caminho dentro do pacote. `composerButtons` ainda carrega, mas está obsoleto: use um item de menu `composer/toolbar`.

### Ids de menu

| Id do menu | O comando recebe | Chaves de contexto para `when` |
| --- | --- | --- |
| `commandPalette` | nada | — |
| `composer/toolbar` | `{sessionId}` | `sessionId` |
| `session/title` | `{sessionId}` | `sessionId` |
| `session/tool` | `{sessionId, capabilityId}` | `sessionId`, `capability`, `capabilityPackage`, `sessionToolModule` |
| `session/context` | `{sessionId}` | `sessionId`, `sessionState` |
| `chat/message/context` | `{sessionId, messageId, role}` | `sessionId`, `messageRole` |
| `explorer/context` | `{path, isDirectory}` | `resourcePath`, `resourceFilename`, `resourceExtname`, `resourceDirname`, `resourceRelativePath`, `explorerResourceIsFolder` |
| `editor/title` | `{path, viewType}` | as chaves de recurso, `activeCustomEditor`, `previewKind` |
| `preview/<kind>/toolbar` | `{path}` | as chaves de recurso, `previewKind` |
| `view/title` | `{viewId}` | `view` |
| `view/item/context` | `{viewId, itemId}` | `view`, `viewItem` |
| `packages/item/context` | `{packageId}` | `packageId`, `packageLevel`, `packageState` |
| `statusBar/item/context` | `{itemId}` | `statusBarItem` |

O grupo `navigation` cria um botão inline na barra de ferramentas; os outros grupos vão para o menu de excedente "…", e `group@order` ordena dentro de um grupo. Os tipos de pré-visualização são `code diff image svg texture audio video model font markdown table binary`. Um id de menu desconhecido é um aviso, não um erro, então um pacote escrito para um app mais novo ainda carrega.

### Cláusulas when

Menus, `enablement`, keybindings, views, itens da barra de status e tutoriais aceitam uma cláusula `when` na sintaxe do VS Code: `! && || == != < <= > >= =~ /regex/ in` e `not in`, com parênteses. As chaves globais incluem `host`, `platform`, `projectOpen`, `projectEngine`, `activePane`, `activeFilePath`, `activeFileExtname`, `sessionActive`, `sessionRunning`, `attachedCapabilities`, `activePackages`, `installedPackages`, `workspaceEngines` e uma `workspaceHasEngine:<engine>` por motor na pasta aberta. Suas configurações são legíveis como `config.<package id>.<key>` e suas próprias chaves como `<package id>.<key>`.

```json
{
  "contributes": {
    "commands": [{ "command": "acme.level-tools.export", "title": "Export level", "enablement": "projectEngine == 'godot'" }],
    "menus": {
      "explorer/context": [{ "command": "acme.level-tools.export", "when": "resourceExtname == '.tscn'", "group": "navigation" }]
    }
  }
}
```

Uma cláusula que não pode ser analisada é um erro de manifesto e descarta essa contribuição.

### Configurações

```json
{
  "contributes": {
    "settings": {
      "outputDir": { "type": "path", "description": "Where exports go", "scope": "project", "mustBeWritable": true },
      "quality": { "type": "string", "enum": ["draft", "final"], "default": "draft", "description": "Export quality" },
      "cachePath": { "type": "path", "description": "A cache on this computer", "userLevelOnly": true }
    }
  }
}
```

- `scope: "machine"` (o padrão) grava no nível do usuário; `scope: "project"` grava no nível do projeto, que é versionado e compartilhado com a equipe.
- Um valor é lido do nível local, depois do projeto, depois do nível do usuário, e por fim do padrão do manifesto.
- `type: "path"` recebe um caminho absoluto; `directories: false` pede um arquivo, e `mustBeWritable` e `showFreeSpace` adicionam verificações ao formulário.
- `userLevelOnly: true` (com `scope: "machine"`) torna uma chave global para a máquina: valores de projeto e locais são ignorados.
- `enum` oferece escolhas fixas; `options: { "provider": "<id>" }` as obtém de um provedor em tempo de execução (apenas os provedores do próprio app, por enquanto).

### Eventos de ativação

A maioria dos pacotes não precisa de nenhum: cada comando contribuído, slash command, view, editor personalizado, capacidade com estado, tutorial em webview e motor de jogo inicia o código por conta própria. Liste eventos extras em `activationEvents` quando o código precisar rodar em outro momento:

| Evento | Quando |
| --- | --- |
| `onStartupFinished` | Depois da primeira renderização do app, ou do primeiro prompt da CLI (o padrão para um pacote com `main` e nenhum outro evento) |
| `onCommand:<id>`, `onSlashCommand:/<name>` | Antes de o comando rodar |
| `onView:<viewId>`, `onCustomEditor:<viewType>` | Quando a view é exibida pela primeira vez, quando um arquivo correspondente é aberto |
| `onFileType:.<ext>` | Quando um arquivo com essa extensão é aberto em qualquer painel |
| `onCapability:<id>`, `onAgentProvider:<id>` | Quando uma capacidade ou provedor é necessário pela primeira vez |
| `onTutorial:<id>`, `onWebviewPanel:<viewType>` | Antes de um tutorial em webview ser exibido, quando um painel salvo é restaurado |
| `onGameEngine:<id>` | Quando a pasta aberta contém um projeto desse motor |
| `*` | Na inicialização do host (desencorajado) |

## Dependências e plugins do Claude

```json
{
  "dependencies": { "acme.core-3d": "^1.0.0" },
  "claudePlugins": { "level-design@acme-marketplace": "*" },
  "claudeMarketplaces": { "acme-marketplace": { "source": "github", "repo": "acme/claude-plugins" } }
}
```

- Um projeto executa uma versão de cada pacote: a versão mais alta que satisfaz todos os intervalos, aceita pelo app. As dependências são ativadas antes das que dependem delas. Um conflito, um ciclo ou uma dependência excluída é mostrado no pacote que precisa dela.
- Os plugins do Claude são instalados por projeto no cache próprio do app, fixados a um commit no arquivo de lock do projeto e entregues aos chats desse projeto. Eles nunca tocam no seu próprio `~/.claude`. As fontes de marketplace são `github`, `git`, `git-subdir` e `url`.

## Páginas relacionadas

- [API de pacotes](https://ai-game.dev/pt-br/docs/wiki/app/package-api) para o código por trás dessas contribuições.
- [Ciclo de vida, hosts e permissões](https://ai-game.dev/pt-br/docs/wiki/app/package-lifecycle) para ativação, estado e versionamento.
- [Regras e verificações do registro](https://ai-game.dev/pt-br/docs/wiki/app/package-registry) para o que o registro aceita.

---

Source (HTML): https://ai-game.dev/pt-br/docs/wiki/app/package-manifest

Machine-translated (pt-BR) from the English page: https://ai-game.dev/docs/wiki/app/package-manifest
