# Criando pacotes — App e CLI do AI Game Dev · AI Game Developer Wiki

Crie seu próprio pacote do AI Game Dev: manifesto aigd-package.json, comandos, ferramentas MCP, desenvolvimento local e compartilhamento.

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

Pacotes não servem apenas para recursos oficiais: você pode escrever o seu próprio para compartilhar uma tarefa repetitiva com o seu time, adicionar uma ferramenta para o agente ou visualizar um formato de arquivo personalizado. Esta página mostra a estrutura do pacote, um pacote mínimo funcional, os principais campos do manifesto, como adicionar uma ferramenta MCP, como desenvolver um pacote com o app em execução e como compartilhá-lo.

## O que você precisa

- O app desktop do AI Game Dev ou a CLI `gamedev`, versão 0.18.0 ou mais recente.
- Um editor de texto. JavaScript é opcional: um pacote pode conter apenas o manifesto.

Pacotes seguem o modelo das extensões do VS Code: uma pasta com um manifesto, `aigd-package.json`, e código opcional que exporta `activate(ctx)` e `deactivate()`. Seu código alcança o app apenas por meio de `ctx.aigd`. Ele roda em um processo de host de extensão separado, um por projeto aberto, e inicia de forma tardia quando algo precisa dele.

## Estrutura do pacote

```text
my-first-package/
  aigd-package.json     the manifest (required)
  extension.js          the code named by "main" (optional)
  media/                icons and images (optional)
  LICENSE
```

Um pacote deve ser autossuficiente: o app nunca executa `npm install` para ele. Se o seu código usa bibliotecas, empacote-as no arquivo para o qual `main` aponta.

## Um pacote mínimo

Este pacote adiciona um slash command `/my-first`, uma entrada na paleta de comandos, um botão na barra de ferramentas do composer, um item na barra de status e uma configuração.

```json
{
  "publisher": "you",
  "name": "my-first-package",
  "version": "0.1.0",
  "displayName": "My First Package",
  "description": "A /my-first slash command, a palette command, a toolbar button and a status bar item.",
  "license": "MIT",
  "main": "extension.js",
  "engines": { "aigd": ">=0.18.0" },
  "activationEvents": ["onSlashCommand:/my-first", "onCommand:you.my-first-package.hello"],
  "contributes": {
    "commands": [
      { "command": "you.my-first-package.hello", "title": "Say hello", "category": "My First Package", "icon": "$(smile)" }
    ],
    "slashCommands": [
      { "name": "/my-first", "description": "Say hello from my first package", "argumentHint": "[name]" }
    ],
    "menus": {
      "composer/toolbar": [{ "command": "you.my-first-package.hello", "group": "navigation" }]
    },
    "statusBar": [
      { "id": "you.my-first-package.status", "text": "My package", "command": "you.my-first-package.hello", "alignment": "left" }
    ],
    "settings": {
      "name": { "type": "string", "default": "game dev", "description": "Who /my-first greets", "scope": "project" }
    }
  }
}
```

E o código, `extension.js` (CommonJS):

```text
const ID = "you.my-first-package";

exports.activate = function activate(ctx) {
  const { aigd } = ctx;
  let count = 0;

  ctx.subscriptions.push(
    aigd.commands.registerCommand(`${ID}.hello`, async () => {
      count++;
      await aigd.window.showInformationMessage(`Hello #${count} from my first package!`);
      return count;
    }),
    // Works in the desktop chat and in the CLI.
    aigd.commands.registerSlashCommand("/my-first", (inv) => {
      const who = inv.args.trim() || aigd.settings.get("name") || "game dev";
      inv.say(`Hi ${who}!`);
    }),
  );

  ctx.log.info("activated");
};

exports.deactivate = function deactivate() {};
```

O slash command, o botão da barra de ferramentas e o item da barra de status aparecem a partir do manifesto antes de qualquer código rodar; `activate` é chamado na primeira vez que um deles é usado.

## Ids e regras de nomenclatura

- O id do pacote é `publisher.name`, em minúsculas: aqui `you.my-first-package`. O publisher tem de 2 a 40 caracteres (letras, dígitos, hífens únicos). Use o seu próprio nome de publisher; `aigd` é o do AI Game Dev.
- Todo id que um pacote contribui (comandos, views, itens da barra de status, tutoriais) começa com o id do pacote: `you.my-first-package.hello`.
- `engines.aigd` é obrigatório: a versão mais antiga do AI Game Dev de que o pacote precisa, por exemplo `">=0.18.0"`. Um app mais antigo recusa o pacote e informa qual versão ele exige.
- `version` é semver. As instalações são cacheadas por id e versão, então toda mudança que você publicar precisa de uma versão maior.

## Principais campos do manifesto

| Campo | Obrigatório | Finalidade |
| --- | --- | --- |
| `publisher`, `name`, `version` | Sim | O id e a versão |
| `engines.aigd` | Sim | Versão mínima do app |
| `displayName`, `description`, `icon`, `license`, `homepage`, `repository`, `keywords` | Não | O que a janela Packages mostra |
| `main` | Não | O ponto de entrada do código; sem ele, o pacote contém apenas contribuições |
| `activationEvents` | Não | Eventos extras que iniciam o código, como `onStartupFinished` |
| `hosts` | Não | `desktop`, `cli` ou ambos |
| `dependencies` | Não | Outros pacotes, `{ "<id>": "<range>" }` |
| `claudePlugins` | Não | Plugins do Claude de que o pacote precisa, `{ "<plugin>@<marketplace>": "<range>" }` |
| `contributes` | Não | Tudo o que o pacote adiciona (abaixo) |

Os pontos de contribuição em `contributes` incluem `commands`, `slashCommands`, `capabilities` (interruptores na linha Tools da sessão), `mcpServers`, `settings`, `panels`, `viewsContainers` e `views` (views de árvore ou webview nos painéis laterais), `menus` e `submenus`, `keybindings`, `customEditors`, `statusBar` e `tutorials`. Os menus usam ids fixos, como `commandPalette`, `composer/toolbar`, `explorer/context`, `editor/title` e `view/item/context`, cada um com uma cláusula `when` opcional. A CLI mostra slash commands, linhas Tools, mensagens, quick picks, caixas de entrada e formulários; menus e painéis são exclusivos do desktop.

## Dê uma ferramenta ao agente com um servidor MCP

O motivo mais comum para escrever um pacote é dar novas ferramentas ao agente. Declare um servidor MCP e uma capability que o ativa por sessão:

```json
{
  "publisher": "you",
  "name": "level-tools",
  "version": "0.1.0",
  "engines": { "aigd": ">=0.18.0" },
  "contributes": {
    "capabilities": [
      {
        "id": "you.level-tools",
        "label": "Level tools",
        "description": "Counts collectibles in the level files.",
        "defaultEnabled": false,
        "mcpServer": "you--level-tools"
      }
    ],
    "mcpServers": {
      "you--level-tools": {
        "command": "${node}",
        "args": ["${packageDir}/server.js"]
      }
    }
  }
}
```

- O nome do servidor deve ser `<publisher>--<name>` (ou `<publisher>--<name>-<suffix>`) do id do pacote, com no máximo 96 caracteres, para que nomes de autores diferentes nunca colidam. Um nome não qualificado é um erro.
- Variáveis que você pode usar em um servidor stdio: `${node}`, `${packageDir}`, `${projectDir}` e `${globalStorage}`.
- Se um servidor MCP com o mesmo nome já estiver configurado em uma sessão, o servidor do pacote não é adicionado e a sessão exibe um aviso.

## Desenvolva com o app em execução

Aponte um projeto para a sua pasta em vez de uma versão publicada. A pasta é usada no local, recarrega quando um arquivo que ela inclui muda e nunca é atualizada automaticamente. O nível padrão é **Local**, que nunca é commitado.

```bash
cd <your project>
gamedev pkg link <path-to-your-package>      # use the folder (default --local)
gamedev pkg list                             # shows "(local dev)" and which level it overrides
gamedev pkg unlink you.my-first-package      # back to the published version
```

Se o seu pacote tem uma etapa de build (`src/` compilado em `dist/`), use `gamedev pkg dev` em vez disso. Ele executa o script `dev` do pacote, ou reexecuta `build` após cada mudança no código-fonte, vincula a pasta após o primeiro build bem-sucedido e encerra todos os processos que iniciou quando você pressiona Ctrl+C:

```bash
gamedev pkg dev <path-to-your-package>
```

No app desktop, o mesmo recurso fica na janela Packages: selecione o pacote e escolha **Use a local folder…**, depois **Stop using local folder** para voltar. Uma pasta cujo manifesto declara outro id é recusada.

**Dica**

Os logs do seu pacote (`ctx.log`, `console.*`) aparecem no log do app marcados com `pkg:<your id>`, e um pacote com falha lista seus erros na aba **Errors** da janela Packages.

## Compartilhe seu pacote

O registro do AI Game Dev contém os pacotes oficiais. Para compartilhar o seu, publique-o no GitHub ou no npm; assim qualquer pessoa pode adicioná-lo por link:

```bash
gamedev pkg add github:you/my-first-package           # not pinned: receives updates
gamedev pkg add github:you/my-first-package@v0.1.0    # a tag (never auto-updated)
gamedev pkg add npm:my-first-package                  # an npm package
gamedev pkg add npm:my-first-package@^0.1.0           # with a version range
```

Para um time, adicione-o no nível **Project** para que ele seja commitado em `.ai-game-dev/packages.json` e todo colega o receba, fixado pelo arquivo de lock do projeto.

Antes de publicar uma nova versão, aumente `version` em `aigd-package.json`. Um arquivo alterado sob uma versão inalterada nunca chega a uma instalação que já tem essa versão.

## Boas práticas

- Mantenha as ferramentas focadas. Toda ferramenta que o agente vê ocupa contexto; uma ferramenta pequena e bem descrita é usada corretamente com mais frequência.
- Declare o máximo que puder no manifesto, para que a interface fique visível antes de o seu código iniciar.
- Use `scope: "project"` para configurações que o time deve compartilhar e `scope: "machine"` para caminhos em um único computador.
- Pacotes rodam com as permissões do seu usuário e sem sandbox. Não inclua segredos em um pacote e explique aos usuários o que o seu pacote faz.

## Saiba mais

- [Pacotes](https://ai-game.dev/pt-br/docs/wiki/app/packages) para níveis, atualizações e configurações.
- [Catálogo de pacotes](https://ai-game.dev/pt-br/docs/wiki/app/packages-catalog) para saber o que os pacotes oficiais fazem.
- O post [pacotes, plugins do Claude e servidores MCP](https://ai-game.dev/pt-br/blog/ai-game-dev-packages-plugins-mcp) sobre um servidor MCP adicionado a um chat em tempo real.

---

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

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