Esta página foi traduzida automaticamente do inglês. Leia o original em inglês.

Referência do manifesto de pacote

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.

Atualizado em 19 de novembro de 2026 Ver como Markdown

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

CampoObrigatórioO que é
publisherSimSeu id de publisher: 2 a 40 caracteres, começando com uma letra, depois letras minúsculas, dígitos e hífens simples, sem pontos
nameSimO nome do pacote: 2 a 64 caracteres, em minúsculas, começando com uma letra
versionSimSemver MAJOR.MINOR.PATCH (um sufixo de pré-lançamento como 1.3.0-beta.2 é permitido)
engines.aigdSimA versão mais antiga do AI Game Dev de que o pacote precisa, por exemplo ">=0.18.0"
displayName, descriptionNãoExibidos na janela Packages e no catálogo (displayName até 60 caracteres, description até 400)
icon, avatarTextNãoUma imagem relativa ao pacote, ou até 4 caracteres desenhados como o avatar
licenseNãoUm id SPDX (MIT, Apache-2.0) ou SEE LICENSE IN <file>
homepage, repository, keywordsNãoLinks e até 20 palavras-chave
mainNãoA entrada de código (CommonJS ou ESM) que exporta activate; sem ela o pacote é somente contribuições
activationEventsNãoEventos extras que iniciam o código (abaixo)
hostsNão["desktop"], ["cli"] ou ambos (o padrão); um pacote somente desktop é ignorado pela CLI
dependenciesNãoOutros pacotes, { "<publisher.name>": "<range>" }
claudePlugins, claudeMarketplacesNãoPlugins do Claude Code de que o pacote precisa, e onde encontrar seus marketplaces
enabledApiProposalsNãoAPI proposta que o pacote usa; o registro recusa qualquer entrada aqui
dataVersionNãoA versão dos dados que seu código armazena (informativo)
contributesNãoTudo 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

PontoFormatoObservaçõ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
claudePluginuma pasta relativa ao pacoteUm 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)
gameEnginesveja Pacotes de motor de jogoUm motor por pacote
runtimes, imageModels, videoModels, model3dModels, mediaModelsdeclarativo, sem códigoRuntimes 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.

Id do menuO comando recebeChaves de contexto para when
commandPalettenada—
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>.

{
  "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

{
  "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:

EventoQuando
onStartupFinishedDepois 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

{
  "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.