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

API de pacotes

A API ctx.aigd dos pacotes do AI Game Developer: namespaces, membros estáveis e propostos, chamadas exclusivas do desktop e exemplos de uso.

Atualizado em 19 de novembro de 2026 Ver como Markdown

O código do seu pacote chega ao app por meio de um único objeto, ctx.aigd, entregue a activate(ctx). Esta página lista seus namespaces, informa quais membros são estáveis e quais são propostos, e mostra exemplos funcionais das chamadas que a maioria dos pacotes faz: comandos, slash commands, ferramentas de agente, configurações, mensagens, webviews, tree views, editores customizados, tutoriais e estado armazenado. A API de pacotes está na versão 0.4.0.

Tipos

gamedev pkg init grava toda a API em um único arquivo autocontido, src/types/aigd.d.ts, gerado a partir do contrato do próprio app e correspondente à versão do app que o gerou. O TypeScript o importa; o JavaScript o usa a partir do JSDoc:

import type { PackageContext } from "./types/aigd";

export async function activate(ctx: PackageContext): Promise<void> {
  ctx.subscriptions.push(ctx.aigd.commands.registerCommand("acme.level-tools.hello", () => "hi"));
}

export function deactivate(): void {}
/** @param {import("./types/aigd").PackageContext} ctx */
exports.activate = function activate(ctx) { /* … */ };

Um gamedev pkg init mais recente em uma pasta de rascunho fornece uma cópia mais nova dos tipos. Um pacote npm de tipos (@ai-game-dev/package-api) está preparado, mas ainda não foi publicado.

Toda chamada atravessa uma fronteira de processo (seu código roda no Extension Host do app), então argumentos e resultados devem ser valores JSON, e todo método que conversa com o app é assíncrono. Os poucos membros síncronos (env, project.path, settings.get) leem o estado que o app enviou quando o pacote iniciou.

O contexto

MembroO que é
ctx.aigdA API (abaixo)
ctx.packageEste pacote: id, publisher, name, version, displayName, dir, manifest
ctx.subscriptionsColoque todo Disposable aqui; o app os descarta quando o pacote para
ctx.globalState, ctx.projectStatePequenos armazenamentos chave-valor para este computador e para este projeto neste computador
ctx.globalStoragePath, ctx.projectStoragePathPastas nas quais seu pacote pode gravar
ctx.logdebug, info, warn, error: linhas marcadas com pkg:<id> no log do app
ctx.asAbsolutePath(rel)Um caminho dentro da pasta do pacote
ctx.reportError(err, subject?)Registra um erro na lista de Erros da janela Packages

Namespaces

NamespaceO que fazStatus
envHost (desktop ou cli), versão do app, plataforma, nodeCommand, fetch através do proxy do sistema, openExternal, área de transferência (desktop)Estável
commandsRegistrar e executar comandos e slash commands, definir chaves de contexto whenEstável
capabilitiesStatus, ativação e anexação por chat dos seus switches de FerramentasEstável
mcpRegistrar servidores MCP para este projetoEstável
agentServir ferramentas de agente em memória (registerProvider)Estável
gameEnginesImplementar uma engine de jogo (registerEngine, host)Estável desde 0.4.0
settingsLer e gravar suas configurações, observar alteraçõesEstável
projectO caminho do projeto e getInfo() (engine, versão da engine, os projetos de engine na pasta)Estável
packagesOutros pacotes e suas exportações (all, get, getExports)Estável
claudeAdicionar uma pasta de plugin do Claude Code aos chats deste projeto (registerPlugin)Estável
editorAs ferramentas do editor de engine conectado, para chats aos quais seu provider está anexadoEstável
accountO catálogo de capacidades da conta conectada (getSnapshot)Estável
mediaRegistrar um gerador de mídia local declarado em contributes.mediaProviders (registerProvider)Estável
windowMensagens, quick picks, caixas de entrada, progresso, barra de status, webviews, tree views, editores customizadosEstável, desktop
tutorialsSolicitar e acompanhar dicas no appEstável, desktop
sessionslist(), active() e eventos ao vivo são estáveis; transcrições, prompts e configuração por chat são propostosMisto
storage, downloads, hardwareO armazenamento de blobs do app, downloads verificados e sondagem de hardwareProposto
tasks, subscriptions, workObservação de tarefas em segundo plano, trabalho de longa duração, retenções de trabalhoProposto

Membros marcados com @desktop em aigd.d.ts não fazem nada na CLI: eles resolvem para undefined ou retornam um objeto inerte, e o host registra uma linha. Verifique aigd.env.host quando seu pacote precisar se comportar de forma diferente no terminal.

API estável e proposta

Um membro estável mantém seu significado em todas as versões do app. As mudanças são apenas aditivas; um membro estável só é removido depois de pelo menos duas versões menores do app com avisos de depreciação (uma linha por pacote por sessão em gamedev pkg logs), junto com um aumento da versão mais antiga de engines.aigd que o app carrega.

Um membro proposto pode mudar ou desaparecer em qualquer versão. Para chamar um, declare sua proposta; uma chamada sem a declaração falha com uma mensagem que nomeia a proposta:

{ "enabledApiProposals": ["forms"] }
PropostaMembros
formswindow.showForm
alertswindow.showAlert
sessionssessions.getTranscript, sendPrompt, create, focusComposer
sessionConfigurationconfiguração de pacote por chat e módulos de Tools (sessions.getConfiguration, updateConfiguration, registerToolStateProvider, …)
appFocuswindow.keepInFront
storage, downloads, hardwareo armazenamento de blobs, o gerenciador de downloads, a sondagem de hardware
backgroundTasks, subscriptions, workHoldstasks.*, subscriptions.open, work.hold
paidOperations, mockJobsjobs pagos no servidor (apenas os pacotes de provedor do próprio AI Game Dev) e sua simulação de desenvolvimento

Comandos e comandos de barra

const ID = "acme.level-tools";

ctx.subscriptions.push(
  aigd.commands.registerCommand(`${ID}.count`, async (...args) => {
    const n = await countCollectibles();
    await aigd.window.showInformationMessage(`${n} collectibles in this level`);
    return n;
  }),
  aigd.commands.registerSlashCommand("/collectibles", async (inv) => {
    inv.say("Counting…");                       // a system line in the chat, live
    const n = await countCollectibles(inv.args.trim());
    inv.say(`${n} collectibles.`);
  }),
);

await aigd.commands.setContext(`${ID}.hasLevel`, true);   // usable in when clauses
await aigd.commands.executeCommand("aigd.packages.open", { packageId: ID });

Um comando de barra recebe o texto depois do nome (inv.args), o chat em que foi digitado (inv.sessionId), say() para linhas ao vivo e cancelled, uma promise que é resolvida quando o usuário pressiona Esc ou Stop. Os comandos de barra funcionam do mesmo jeito no chat do desktop e na CLI. Entre os comandos do app que seu pacote pode executar estão aigd.packages.open, aigd.packages.reload, aigd.packages.checkForUpdates, aigd.session.focus, aigd.settings.open e aigd.tutorials.show.

Dê ferramentas ao agente

Um servidor MCP, declarado. O jeito mais simples: declare o servidor e uma capacidade que o ativa por chat. Nenhum código é necessário; o servidor é seu próprio script iniciado com o Node do app:

{
  "contributes": {
    "capabilities": [
      { "id": "acme.level-tools", "label": "Level tools", "description": "Counts collectibles in level files.", "mcpServer": "acme--level-tools" }
    ],
    "mcpServers": {
      "acme--level-tools": { "command": "${node}", "args": ["${packageDir}/server.js"] }
    }
  }
}

Um servidor MCP, registrado em tempo de execução. Para um servidor cujo endereço você só descobre depois que algo foi iniciado (a porta de um app externo):

await aigd.mcp.registerServer("acme--level-tools", { type: "http", url: `http://127.0.0.1:${port}/mcp` });

Ferramentas servidas pelo seu código. Um provedor de agente mantém as ferramentas no seu pacote, sem processo de servidor. Declare-o com sua capacidade e depois registre-o:

{
  "contributes": {
    "capabilities": [{ "id": "acme.helper", "label": "Helper", "description": "Helper tools", "defaultEnabled": true }],
    "agentProviders": [{ "id": "acme.helper.agent", "serverName": "acme--helper", "capabilityId": "acme.helper" }]
  }
}
ctx.subscriptions.push(await aigd.agent.registerProvider("acme.helper.agent", {
  getTools: () => [{
    name: "status",
    description: "Read the helper's status",
    inputSchema: { type: "object", properties: {}, additionalProperties: false },
  }],
  getInstructions: () => "Use the helper's status tool when working in this project.",
  invokeTool: async (name, args, context) => ({ content: [{ type: "text", text: context.project.path }] }),
}));

O schema de entrada de uma ferramenta precisa ter uma raiz do tipo objeto, sem oneOf, anyOf ou allOf no nível superior. Os resultados podem conter texto e imagens ({ type: "image", data, mimeType }, PNG, JPEG ou WebP); uma imagem que não passa nas verificações do app é substituída por uma nota, nunca por um erro. O prazo padrão da ferramenta é de 60 segundos (executionTimeoutMs, até uma hora).

Uma capacidade com status. Defina statusful: true na capacidade quando ativá-la exigir trabalho (iniciar um app externo). O app então mostra seu status no interruptor e chama seu handler de ativação:

ctx.subscriptions.push(
  aigd.capabilities.registerStatusProvider("acme.level-tools", async () =>
    (await isRunning()) ? { phase: "connected", detail: "Editor 4.2" } : { phase: "idle" }),
  aigd.capabilities.registerActivationHandler("acme.level-tools", async (req) => {
    req.progress("Starting the level server…");
    try { await start(); return { ok: true }; }
    catch (e) { return { ok: false, failure: { code: "start-failed", text: String(e) } }; }
  }),
);

Configurações

const quality = aigd.settings.get<string>("quality") ?? "draft";
await aigd.settings.update("quality", "final", "project");   // user, project or local
ctx.subscriptions.push(aigd.settings.onDidChange((e) => ctx.log.info(`${e.key} is now ${String(e.value)}`)));

As chaves são suas (sem o prefixo do pacote) e precisam ser declaradas em contributes.settings. Toda gravação é validada conforme a declaração.

Mensagens, seletores e progresso

const choice = await aigd.window.showWarningMessage("Overwrite the export?", { modal: true }, "Overwrite", "Keep");
const level = await aigd.window.showQuickPick(["forest", "cave", "castle"], { title: "Export which level?" });
const name = await aigd.window.showInputBox({ prompt: "File name", value: "level-1" });

await aigd.window.withProgress({ title: "Exporting", cancellable: true }, async (progress, cancelled) => {
  progress.report({ message: "Meshes", increment: 50 });
  progress.report({ message: "Textures", increment: 50 });
});

const item = aigd.window.createStatusBarItem("acme.level-tools.status", { alignment: "left" });
item.text = "3 levels";
item.command = "acme.level-tools.count";
item.show();
ctx.subscriptions.push(item);

Na CLI, as mensagens são impressas como linhas de sistema; uma mensagem modal, um quick pick ou uma caixa de entrada viram um prompt de terminal enquanto seu comando de barra é executado. Fora de um comando de barra, a CLI recusa prompts com um PromptRefusedError (código prompt_refused), então um pacote que faz perguntas deve fazê-las a partir de um comando de barra ou verificar aigd.env.host.

Webviews: painéis, visões laterais e janelas

Uma webview é sua própria página HTML dentro do app (desktop). A mesma página funciona em um painel, em uma aba do painel lateral ou em sua própria janela:

const panel = aigd.window.createWebviewPanel("acme.level-tools.map", "Level map");
const script = panel.webview.asWebviewUri(ctx.asAbsolutePath("dist/map.js"));
panel.webview.html = `<!doctype html><html><body><canvas id="map"></canvas>
  <script type="module" src="${script}"></script></body></html>`;
panel.webview.onDidReceiveMessage((msg) => ctx.log.info(`page says ${JSON.stringify(msg)}`));
await panel.webview.postMessage({ type: "level", tiles });
// dist/map.js, inside the page
const api = acquireAigdApi();
api.postMessage({ type: "ready" });
window.addEventListener("message", (e) => draw(e.data));
api.setState({ zoom: 2 });             // restored with the pane after a relaunch
  • Aba do painel lateral: declare { "id": "acme.level-tools.side", "name": "Levels", "type": "webview" } em contributes.views.right e registre aigd.window.registerWebviewViewProvider("acme.level-tools.side", { resolveWebviewView(view) { view.webview.html = page(); } }). "titleBar": "hidden" permite que sua página desenhe o próprio cabeçalho.
  • Janela própria: aigd.window.createWebviewWindow(viewType, title) abre uma janela nativa redimensionável, uma por tipo de visão por projeto. A página dela roda sob uma política de segurança de conteúdo estrita: apenas os arquivos do próprio pacote, sem rede, sem eval.
  • Tema: a página recebe <html data-theme="light|dark"> e a paleta do app como variáveis CSS --aigd-* (--aigd-bg, --aigd-surface, --aigd-text, --aigd-primary, …), reenviadas a cada troca de tema.
  • API da página: acquireAigdApi() fornece postMessage, getState, setState, executeCommand (seus próprios comandos e comandos do app), getContext() e close().

Visões em árvore

const tree = aigd.window.createTreeView("acme.level-tools.levels", {
  treeDataProvider: {
    getChildren: async (parent) => parent
      ? listObjects(parent.id).map((o) => ({ id: o.id, label: o.name, icon: "$(box)" }))
      : listLevels().map((l) => ({ id: l.id, label: l.name, collapsible: "collapsed", contextValue: "level" })),
  },
});
tree.message = "3 levels";
ctx.subscriptions.push(tree);

A visão é declarada com "type": "tree" em contributes.views. O contextValue se torna viewItem para os menus view/item/context; os itens podem ter checkboxes, badges e um comando de clique.

Editores personalizados

{ "contributes": { "customEditors": [{ "viewType": "acme.level-tools.level", "displayName": "Level preview", "selector": [{ "filenamePattern": "*.level.json" }], "priority": "default" }] } }
ctx.subscriptions.push(aigd.window.registerCustomEditorProvider("acme.level-tools.level", {
  resolveCustomEditor(document, panel) {
    panel.webview.html = renderLevel(fs.readFileSync(document.path, "utf8"));
  },
}));

Um editor default substitui a pré-visualização do próprio app para os arquivos correspondentes; um editor option aparece em Open With. Os documentos são somente leitura do lado do app: seu pacote grava os arquivos por conta própria, e o painel recarrega quando o arquivo muda no disco. aigd.window.openPreview(path) mostra um arquivo do projeto na pré-visualização, como um clique no Explorer faz.

Tutoriais

{ "contributes": { "tutorials": [{ "id": "acme.level-tools.intro", "title": "Count collectibles", "anchor": "slashCommand:/collectibles", "markdown": "tutorials/intro.md" }] } }
ctx.subscriptions.push(aigd.tutorials.request("acme.level-tools.intro"));

Uma dica é exibida uma vez por usuário, em um momento tranquilo, apontando para sua âncora: capability:, statusBar:, view:, slashCommand:, command: ou menu: seguido de um id, composer ou none. markdown com até 8 arquivos media, ou uma página webview para conteúdo rico. request(id, { force: true }) exibe novamente; isSeen e setSeen leem e definem o estado de visualização.

Estado armazenado

const DATA = 2;
if ((ctx.globalState.dataVersion ?? 0) < DATA) {
  await migrate(ctx.globalState);
  await ctx.globalState.setDataVersion(DATA);
}
await ctx.projectState.update("lastExport", new Date().toISOString());
const last = ctx.projectState.get<string>("lastExport");

globalState é compartilhado por todos os projetos neste computador; projectState pertence a este projeto neste computador. Ambos sobrevivem a atualizações e à remoção (readicionar o pacote os restaura); Remove data na janela Packages os exclui. O app nunca migra seus dados: dataVersion é seu para comparar e incrementar.