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.
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 exemploacme.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-toolspossuiacme--level-toolseacme--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 | 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>.
{
"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: falsepede um arquivo, emustBeWritableeshowFreeSpaceadicionam verificações ao formulário.userLevelOnly: true(comscope: "machine") torna uma chave global para a máquina: valores de projeto e locais são ignorados.enumoferece 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
{
"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ãogithub,git,git-subdireurl.
Páginas relacionadas
- API de pacotes para o código por trás dessas contribuições.
- Ciclo de vida, hosts e permissões para ativação, estado e versionamento.
- Regras e verificações do registro para o que o registro aceita.