이 페이지는 영어에서 기계 번역되었습니다. 영어 원문 읽기.

패키지 API

AI Game Dev 패키지의 ctx.aigd API: 모든 네임스페이스, 안정 멤버와 제안 멤버, 데스크톱 전용 호출, 그리고 도구·UI·상태에 대한 실제 예제.

2026년 11월 19일 업데이트 Markdown으로 보기

패키지의 코드는 activate(ctx)에 전달되는 하나의 객체인 ctx.aigd를 통해 앱에 접근합니다. 이 페이지는 그 네임스페이스를 나열하고, 어떤 멤버가 안정(stable)이고 어떤 멤버가 제안(proposed)인지 설명하며, 대부분의 패키지가 사용하는 호출의 실제 예제를 보여줍니다: 명령, 슬래시 명령, 에이전트 도구, 설정, 메시지, 웹뷰, 트리 뷰, 사용자 지정 편집기, 튜토리얼, 저장된 상태. 패키지 API의 버전은 0.4.0입니다.

타입

gamedev pkg init은 전체 API를 자체 포함된 하나의 파일인 src/types/aigd.d.ts로 작성합니다. 이 파일은 앱 자체의 계약에서 생성되며, 이를 작성한 앱 버전과 일치합니다. TypeScript는 이 파일을 import하고, JavaScript는 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) { /* … */ };

임시 폴더에서 최신 gamedev pkg init을 실행하면 더 새로운 버전의 타입 복사본을 얻을 수 있습니다. npm 타입 패키지(@ai-game-dev/package-api)는 준비되었지만 아직 게시되지 않았습니다.

모든 호출은 프로세스 경계를 넘습니다(코드는 앱의 Extension Host에서 실행됩니다). 따라서 인수와 결과는 JSON 값이어야 하며, 앱과 통신하는 모든 메서드는 비동기입니다. 몇 안 되는 동기 멤버(env, project.path, settings.get)는 패키지가 시작될 때 앱이 전달한 상태를 읽습니다.

컨텍스트

멤버설명
ctx.aigdAPI(아래 참조)
ctx.package이 패키지: id, publisher, name, version, displayName, dir, manifest
ctx.subscriptions모든 Disposable을 여기에 추가하세요. 패키지가 중지되면 앱이 이를 정리합니다
ctx.globalState, ctx.projectState이 컴퓨터용, 그리고 이 컴퓨터의 이 프로젝트용 소형 키-값 저장소
ctx.globalStoragePath, ctx.projectStoragePath패키지가 쓸 수 있는 폴더
ctx.logdebug, info, warn, error: 앱 로그에 pkg:<id> 태그로 기록되는 줄
ctx.asAbsolutePath(rel)패키지 폴더 내부의 경로
ctx.reportError(err, subject?)Packages 창의 Errors 목록에 오류를 기록합니다

네임스페이스

네임스페이스설명상태
env호스트(desktop 또는 cli), 앱 버전, 플랫폼, nodeCommand, 시스템 프록시를 통한 fetch, openExternal, 클립보드(데스크톱)안정
commands명령과 슬래시 명령을 등록하고 실행하며, when 컨텍스트 키를 설정합니다안정
capabilitiesTools 스위치의 상태, 활성화 및 채팅별 연결안정
mcp이 프로젝트용 MCP 서버를 등록합니다안정
agent메모리 내에서 에이전트 도구를 제공합니다(registerProvider)안정
gameEngines게임 엔진을 구현합니다(registerEngine, host)0.4.0부터 안정
settings설정을 읽고 쓰며 변경 사항을 감시합니다안정
project프로젝트 경로와 getInfo()(엔진, 엔진 버전, 폴더 내 엔진 프로젝트)안정
packages다른 패키지와 그 export(all, get, getExports)안정
claude이 프로젝트의 채팅에 Claude Code 플러그인 폴더를 추가합니다(registerPlugin)안정
editor연결된 엔진 편집기의 도구로, 프로바이더가 연결된 채팅에서 사용합니다안정
account로그인한 계정의 기능 카탈로그(getSnapshot)안정
mediacontributes.mediaProviders에 선언된 로컬 미디어 생성기를 등록합니다(registerProvider)안정
window메시지, 빠른 선택, 입력 상자, 진행률, 상태 표시줄, 웹뷰, 트리 뷰, 사용자 지정 편집기안정, 데스크톱
tutorials앱 내 팁을 요청하고 추적합니다안정, 데스크톱
sessionslist(), active() 및 라이브 이벤트는 안정이며, 트랜스크립트·프롬프트·채팅별 구성은 제안입니다혼합
storage, downloads, hardware앱의 blob 저장소, 검증된 다운로드, 하드웨어 프로브제안
tasks, subscriptions, work백그라운드 작업 관찰, 장기 실행 작업, 작업 홀드제안

aigd.d.ts에서 @desktop으로 표시된 멤버는 CLI에서 아무 동작도 하지 않습니다. undefined로 해석되거나 아무 기능도 없는 객체를 반환하며, 호스트가 한 줄을 로그로 남깁니다. 터미널에서 패키지가 다르게 동작해야 한다면 aigd.env.host를 확인하세요.

안정 API와 제안 API

안정 멤버는 모든 앱 릴리스에서 그 의미를 유지합니다. 변경은 추가만 허용되며, 안정 멤버는 최소 두 번의 마이너 앱 릴리스 동안 지원 중단 경고(gamedev pkg logs에서 패키지별 세션당 한 줄)를 낸 뒤에만 제거되며, 이때 앱이 로드하는 가장 오래된 engines.aigd 버전도 함께 올라갑니다.

제안 멤버는 어느 릴리스에서든 변경되거나 사라질 수 있습니다. 이를 호출하려면 해당 제안을 선언해야 하며, 선언 없이 호출하면 제안 이름을 알려주는 메시지와 함께 실패합니다:

{ "enabledApiProposals": ["forms"] }
제안멤버
formswindow.showForm
alertswindow.showAlert
sessionssessions.getTranscript, sendPrompt, create, focusComposer
sessionConfiguration채팅별 패키지 구성 및 Tools 모듈(sessions.getConfiguration, updateConfiguration, registerToolStateProvider, …)
appFocuswindow.keepInFront
storage, downloads, hardwareblob 저장소, 다운로드 관리자, 하드웨어 프로브
backgroundTasks, subscriptions, workHoldstasks.*, subscriptions.open, work.hold
paidOperations, mockJobs유료 서버 작업(AI Game Dev 자체 제공자 패키지에만 해당) 및 해당 개발 시뮬레이션

명령 및 슬래시 명령

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 });

슬래시 명령은 이름 뒤의 텍스트(inv.args), 입력된 채팅(inv.sessionId), 실시간 라인을 위한 say(), 그리고 사용자가 Esc 또는 Stop을 누르면 완료되는 프로미스인 cancelled를 받습니다. 슬래시 명령은 데스크톱 채팅과 CLI에서 동일하게 동작합니다. 패키지가 실행할 수 있는 앱 명령에는 aigd.packages.open, aigd.packages.reload, aigd.packages.checkForUpdates, aigd.session.focus, aigd.settings.open, aigd.tutorials.show가 있습니다.

에이전트에게 도구 제공하기

선언된 MCP 서버. 가장 간단한 방법입니다. 서버와 채팅별로 이를 켜는 기능을 선언하세요. 코드가 필요 없습니다. 서버는 앱의 Node로 시작되는 여러분의 스크립트입니다:

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

런타임에 등록되는 MCP 서버. 무언가가 시작된 후에야 주소를 알 수 있는 서버(외부 앱의 포트)의 경우:

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

코드에서 제공하는 도구. 에이전트 제공자를 사용하면 서버 프로세스 없이 패키지 안에 도구를 둘 수 있습니다. 해당 기능과 함께 선언한 다음 등록하세요:

{
  "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 }] }),
}));

도구의 입력 스키마는 객체 루트를 가져야 하며, 최상위 oneOf, anyOf, allOf가 없어야 합니다. 결과에는 텍스트와 이미지({ type: "image", data, mimeType }, PNG, JPEG 또는 WebP)가 포함될 수 있습니다. 앱의 검사를 통과하지 못한 이미지는 오류가 아니라 안내 문구로 대체됩니다. 기본 도구 제한 시간은 60초입니다(executionTimeoutMs, 최대 1시간).

상태가 있는 기능. 켜는 데 작업이 필요한 경우(외부 앱 시작) 기능에 statusful: true를 설정하세요. 그러면 앱이 스위치에 상태를 표시하고 활성화 핸들러를 호출합니다:

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) } }; }
  }),
);

설정

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)}`)));

키는 여러분의 것이며(패키지 접두사 제외) contributes.settings에 선언해야 합니다. 모든 쓰기는 선언에 대해 검증됩니다.

메시지, 선택기, 진행률

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);

CLI에서는 메시지가 시스템 라인으로 출력됩니다. 모달 메시지, 빠른 선택, 입력 상자는 슬래시 명령이 실행되는 동안 터미널 프롬프트가 됩니다. 슬래시 명령 외부에서 CLI는 PromptRefusedError(코드 prompt_refused)와 함께 프롬프트를 거부하므로, 질문을 하는 패키지는 슬래시 명령에서 질문하거나 aigd.env.host를 확인해야 합니다.

웹뷰: 패널, 사이드 뷰, 창

웹뷰는 앱(데스크톱) 내부의 여러분의 HTML 페이지입니다. 동일한 페이지가 팬, 사이드 패널 탭 또는 자체 창에서 동작합니다:

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
  • 사이드 패널 탭: contributes.views.right 아래에 { "id": "acme.level-tools.side", "name": "Levels", "type": "webview" }를 선언하고 aigd.window.registerWebviewViewProvider("acme.level-tools.side", { resolveWebviewView(view) { view.webview.html = page(); } })를 등록하세요. "titleBar": "hidden"을 사용하면 페이지가 자체 헤더를 그릴 수 있습니다.
  • 자체 창: aigd.window.createWebviewWindow(viewType, title)는 크기 조절이 가능한 네이티브 창을 엽니다(프로젝트당 뷰 타입별로 하나). 이 페이지는 엄격한 콘텐츠 보안 정책 아래에서 실행됩니다. 패키지 자체 파일만 사용하고, 네트워크와 eval은 허용되지 않습니다.
  • 테마: 페이지는 <html data-theme="light|dark">와 앱의 팔레트를 --aigd-* CSS 변수(--aigd-bg, --aigd-surface, --aigd-text, --aigd-primary, …)로 받으며, 테마가 바뀔 때마다 다시 전송됩니다.
  • 페이지 API: acquireAigdApi()는 postMessage, getState, setState, executeCommand(자체 명령 및 앱 명령), getContext(), close()를 제공합니다.

트리 뷰

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);

뷰는 contributes.views에서 "type": "tree"로 선언합니다. contextValue는 view/item/context 메뉴에서 viewItem이 됩니다. 항목에는 체크박스, 배지, 클릭 명령을 붙일 수 있습니다.

사용자 지정 편집기

{ "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"));
  },
}));

default 편집기는 일치하는 파일에 대해 앱 자체의 미리보기를 대체합니다. option 편집기는 Open With 아래에 표시됩니다. 문서는 앱 쪽에서 읽기 전용입니다. 패키지가 직접 파일을 쓰며, 파일이 디스크에서 변경되면 팬이 다시 로드됩니다. aigd.window.openPreview(path)는 탐색기에서 클릭한 것처럼 프로젝트 파일을 미리보기에 표시합니다.

튜토리얼

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

팁은 사용자마다 한 번, 조용한 시점에 표시되며, 앵커를 가리킵니다: capability:, statusBar:, view:, slashCommand:, command: 또는 menu: 뒤에 id가 오거나, composer, none입니다. markdown은 최대 8개의 media 파일과 함께, 또는 풍부한 콘텐츠용 webview 페이지와 함께 사용합니다. request(id, { force: true })는 팁을 다시 표시하고, isSeen과 setSeen은 확인 상태를 읽고 설정합니다.

저장된 상태

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는 이 컴퓨터의 모든 프로젝트가 공유하며, projectState는 이 컴퓨터의 이 프로젝트에 속합니다. 둘 다 업데이트와 제거 후에도 유지되며(패키지를 다시 추가하면 복원됩니다), Packages 창의 Remove data가 이들을 삭제합니다. 앱은 데이터를 절대 마이그레이션하지 않으므로, dataVersion은 직접 비교하고 올려야 합니다.