Pacotes

Os pacotes estendem o app AI Game Dev com capacidades inteiras: Blender, música com SuperCollider, uma Base de Conhecimento do projeto, geração 3D com Tripo, modelos locais de imagem e vídeo, modelos de vídeo e áudio na nuvem, e qualquer coisa que uma equipe construa para si. Esta página explica o que é um pacote, quais pacotes vêm com o app e como gerenciá-los na janela Packages do desktop e com o comando gamedev pkg.

O que é um pacote#

Um pacote é uma pasta com um manifesto, aigd-package.json, e, opcionalmente, algum JavaScript. O modelo é o mesmo das extensões do VS Code: tudo o que um pacote mostra é declarado em seu manifesto e visível antes de o código rodar, e o código só inicia quando algo precisa dele.

Um pacote pode contribuir com:

• Ferramentas de sessão na linha Tools, muitas vezes com um servidor MCP por trás, para que o agente ganhe novas ferramentas.
• Comandos de barra como /blender ou /kb, que funcionam no chat do desktop e na CLI.
• Comandos para a paleta de comandos, menus e botões da barra do compositor, itens da barra de status.
• Painéis, views do painel lateral, janelas próprias e editores personalizados ou prévias para tipos de arquivo.
• Configurações, tutoriais curtos no app e dependências de outros pacotes ou plugins do Claude.
• Dados puros: os modelos locais de imagem e vídeo são pacotes sem código, que declaram seus arquivos, tamanho de download, licença e o hardware compatível.

Todo pacote tem um id no formato publisher.name. Pacotes de primeira parte usam o publisher aigd, por exemplo aigd.blender.

Pacotes, plugins do Claude, servidores MCP e extensões de engine#

O app tem quatro tipos de extensão. Todos acabam virando ferramentas que o agente pode usar, mas são gerenciados em lugares diferentes:

Um servidor MCP que você adiciona em Settings pertence ao projeto que estava aberto quando você o adicionou e nunca é visível em outros projetos. Um novo plugin ou servidor MCP passa a valer para o chat que já está aberto a partir da mensagem seguinte.

Pacotes que vêm com o app#

Na primeira inicialização, o app instala seus pacotes padrão para você, no nível de usuário, para que fiquem disponíveis em todos os projetos:

Um padrão que você remove nunca é adicionado de novo. Instalar um pacote não significa que todo chat o carrega: você ativa as ferramentas dele por sessão na linha Tools. Os modelos locais de imagem e vídeo, e as famílias de modelos na nuvem, são pacotes separados; veja o catálogo de pacotes para todos eles.

A janela Packages#

Abra-a pelo ícone de pacote na barra de status, no canto inferior direito da janela ("Open Packages"). Ela mostra o projeto e seus níveis no topo, e estas abas:

• Installed: os pacotes ativos neste projeto, com status, versão e nível.
• Browse: pesquise no registro de pacotes do AI Game Dev.
• Claude plugins: os plugins do Claude que os pacotes exigem para este projeto.
• Models: os modelos locais de imagem e vídeo que você pode baixar, exibidos quando o projeto tem o runtime de geração.

O cabeçalho tem Check for updates e Reload, que reinicia os pacotes do projeto. Selecione um pacote para ver seus detalhes, níveis, configurações e erros.

Instalar um pacote#

No app desktop#

1. Abra a janela Packages e selecione Browse.
2. Pesquise, por exemplo, hello, e selecione o pacote.
3. Abaixo do botão de adicionar, escolha o nível: User, Project ou Local (veja níveis).
4. Clique em Add to Project (ou Add to User, Add to Local).

Para adicionar um pacote de fora do registro, digite na caixa de adição. Ela aceita um id de registro (aigd.blender, opcionalmente com um intervalo de versão como aigd.blender@^1.2), um link do GitHub ou owner/repo, um pacote npm (npm:<name> ou seu link do npmjs.com) ou o caminho de uma pasta.

Na CLI#

Execute gamedev pkg na pasta do projeto (ou passe --cwd <path>), ou use /packages na CLI interativa. O nível padrão é --project.

gamedev pkg list                          # the packages in effect for this project
gamedev pkg list --user                   # the user level alone
gamedev pkg add aigd.blender --user       # from the registry, for every project
gamedev pkg add github:owner/repo         # from GitHub, for this project
gamedev pkg add npm:some-package --local  # from npm, this machine only

Um pacote do registro adicionado sem intervalo é gravado como ^<installed version>, para que receba atualizações compatíveis.

Níveis: user, project, local#

Os pacotes e suas configurações são declarados em três níveis. Um nível mais alto substitui um mais baixo: local vence project, project vence user.

Cada nível também tem um arquivo de lock ao lado (packages-lock.json, packages-lock.local.json) que fixa as versões exatas, para que colegas de equipe que compartilham o lock do projeto instalem os mesmos bytes.

Use Project para pacotes de que toda a equipe precisa, User para suas ferramentas pessoais e Local para escolhas específicas da máquina, como o caminho de uma ferramenta instalada no seu computador.

Excluir um pacote em um projeto#

Para desativar um pacote de nível user em um projeto, selecione-o e escolha Exclude na linha do nível, ou:

gamedev pkg exclude aigd.blender            # off in this project (written to the project file)
gamedev pkg include aigd.blender            # undo

O arquivo do projeto passa então a conter "aigd.blender": false; os outros projetos não são afetados.

Atualizar pacotes#

As atualizações automáticas ficam ativadas por padrão. O aplicativo verifica logo após a inicialização, a cada quatro horas e quando você clica em Check for updates. Ele instala a versão mais recente dentro do intervalo que cada nível declara e que seja compatível com o seu aplicativo, e mostra uma notificação por execução, como "Atualizando 1 pacote… (1/1)" seguida de "1 pacote atualizado".

• Desative as atualizações automáticas de um pacote com sua chave Auto-update na janela Packages, ou com gamedev pkg auto-update off <id>. A escolha é por computador.
• Atualize agora com gamedev pkg update (todos) ou gamedev pkg update <id>.
• Pacotes de uma pasta local, e fontes do GitHub fixadas em uma tag, nunca são atualizados automaticamente.

Um pacote que precisa de um aplicativo mais novo avisa ("requer AI Game Dev >=X, você tem Y"); atualize o aplicativo primeiro.

Remover um pacote#

Selecione-o e escolha Remove, ou:

gamedev pkg remove <id>              # remove it from the project level
gamedev pkg remove <id> --user       # remove it from the user level

Um pacote instalado apenas como dependência de outro não tem Remove, só Exclude; ele desaparece sozinho quando nada precisa dele.

Configurações do pacote#

Selecione um pacote e abra Settings. Ao lado de cada configuração você escolhe o nível em que ela é gravada; a etiqueta mostra de onde vem o valor atual. Algumas configurações são seletores de pasta com Browse… e verificação de espaço livre; outras oferecem opções que vêm do aplicativo.

Na CLI:

gamedev pkg settings aigd.blender                 # every key, its value and level
gamedev pkg settings <id> <key> <value> --local   # write a value at a level
gamedev pkg settings <id> <key> --unset --project # clear the value at a level

Um valor é verificado em relação ao tipo declarado antes de ser salvo; um valor recusado não altera nada e encerra com o código 1.

Dependências#

Um pacote pode depender de outros pacotes e de plugins do Claude. O aplicativo os instala para você e mantém uma versão de cada pacote por projeto. A janela Packages lista uma dependência como "instalado para <id>" com seu nível. Os plugins do Claude de que um pacote precisa são instalados por projeto em um cache do próprio aplicativo e carregados apenas nas sessões daquele projeto, nunca no seu próprio Claude Code.

Segurança e erros#

Os pacotes são executados com as permissões do seu usuário, como extensões do VS Code: não há sandbox. Instale pacotes apenas de fontes confiáveis. Os pacotes do registro do AI Game Dev são verificados em relação aos checksums publicados antes de serem descompactados.

Se um pacote falhar, seu cartão mostra uma contagem de avisos e sua aba Errors lista os detalhes. Erros de pacotes de terceiros nunca são enviados a lugar algum; erros de pacotes aigd de primeira parte do nosso registro são relatados a nós apenas com o seu consentimento de relatório de falhas. Os pacotes instalados são iniciados sem conexão de rede.

Próximos passos#

• Veja todos os pacotes disponíveis no catálogo de pacotes.
• Crie o seu próprio em Criando pacotes.
• O post pacotes, plugins do Claude e servidores MCP mostra a janela Packages e um servidor MCP de projeto em ação.