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

패키지 매니페스트 레퍼런스

aigd-package.json의 모든 필드: id와 버전, engines.aigd, 활성화 이벤트, 의존성, 그리고 각 기여 지점의 형태와 규칙.

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

aigd-package.json은 AI Game Dev 패키지의 매니페스트입니다. id, 버전, 호환되는 앱 버전, 그리고 패키지가 기여하는 모든 것이 담겨 있습니다. 앱은 패키지 코드를 실행하지 않고 이 파일을 읽으므로, 모든 메뉴 항목, 슬래시 명령, Tools 스위치, 뷰는 패키지가 활성화되기 전에도 표시됩니다. 이 페이지는 모든 필드와 기여 지점을 규칙과 함께 나열합니다. gamedev pkg init으로 만든 새 패키지에는 이미 유효한 매니페스트와 편집기 자동 완성용 JSON Schema($schema로 지정)가 들어 있습니다.

최상위 필드

필드필수설명
publisher예게시자 id: 2~40자, 문자로 시작하고 그 뒤에는 소문자, 숫자, 단일 하이픈만 가능하며 점은 사용할 수 없습니다
name예패키지 이름: 2~64자, 소문자, 문자로 시작
version예시맨틱 버전 MAJOR.MINOR.PATCH (1.3.0-beta.2 같은 프리릴리스 접미사 허용)
engines.aigd예패키지가 요구하는 가장 오래된 AI Game Dev 버전. 예: ">=0.18.0"
displayName, description아니요Packages 창과 카탈로그에 표시됩니다 (displayName은 최대 60자, description은 최대 400자)
icon, avatarText아니요패키지 상대 경로 이미지, 또는 아바타로 그려질 최대 4자
license아니요SPDX id(MIT, Apache-2.0) 또는 SEE LICENSE IN <file>
homepage, repository, keywords아니요링크와 최대 20개의 키워드
main아니요activate를 내보내는 코드 진입점(CommonJS 또는 ESM). 이것이 없으면 기여 전용 패키지입니다
activationEvents아니요코드를 시작하는 추가 이벤트 (아래 참조)
hosts아니요["desktop"], ["cli"] 또는 둘 다(기본값). 데스크톱 전용 패키지는 CLI에서 건너뜁니다
dependencies아니요다른 패키지들, { "<publisher.name>": "<range>" }
claudePlugins, claudeMarketplaces아니요패키지가 필요로 하는 Claude Code 플러그인과 그 마켓플레이스를 찾을 위치
enabledApiProposals아니요패키지가 사용하는 제안된 API. 레지스트리는 여기에 어떤 항목도 거부합니다
dataVersion아니요코드가 저장하는 데이터의 버전 (정보용)
contributes아니요패키지가 추가하는 모든 것 (아래 참조)

패키지 id는 publisher.name 형식입니다: acme.level-tools. 이 id는 패키지가 설치된 키와 같아야 하며, 그렇지 않으면 아무것도 실행되지 않습니다(id-mismatch). 게시자 aigd는 AI Game Dev 소유이며, 엔진 이름 unity, godot, unreal, brutal, bevy, threejs는 예약되어 있습니다.

앱 버전: engines.aigd

engines.aigd는 최소값입니다. 예: ">=0.18.0". 이보다 오래된 앱은 패키지를 거부하고 필요한 버전을 알려줍니다. 앱의 베타는 그것이 미리 보여주는 릴리스로 간주됩니다: 0.32.0-beta.1은 ">=0.32.0"을 충족합니다. 앱이 여전히 로드하는 가장 오래된 하한은 0.18.0입니다. 테스트한 가장 오래된 앱으로 설정하세요. 게임 엔진 패키지는 ">=0.32.0"이 필요합니다.

설치는 id와 버전으로 캐시됩니다: 게시하는 모든 변경에는 더 높은 version이 필요합니다.

패키지가 소유하는 id

패키지가 기여하는 모든 것은 자체 id 안에서 이름이 정해지므로 두 패키지가 충돌하지 않습니다:

  • 명령, 패널, 뷰, 뷰 컨테이너, 하위 메뉴, 상태 표시줄 항목, 튜토리얼, 사용자 정의 편집기: <package id>.<local>, 예를 들어 acme.level-tools.export
  • 기능: 패키지 id 자체 또는 <package id>.<local>. 기능 id는 채팅별로 저장되므로 절대 이름을 바꾸지 마세요.
  • MCP 서버 이름: <publisher>--<name> 또는 <publisher>--<name>-<suffix>, 최대 96자: acme.level-tools는 acme--level-tools와 acme--level-tools-preview를 소유합니다. 모델은 모든 도구 이름에서 이 이름을 보기 때문에 점 대신 --를 사용합니다. 한정자 없는 이름은 오류입니다.
  • aigd.commands.setContext로 설정하는 컨텍스트 키: <package id>.<key>

gamedev pkg validate는 내 것이 아닌 모든 id를 해당 필드와 함께 알려줍니다.

기여 지점

지점형태참고
commands{command, title, shortTitle?, category?, icon?, palette?, hosts?, enablement?}팔레트 항목. enablement는 when 절입니다
slashCommands{name, description, argumentHint?, hosts?}name은 입력 그대로, /export. 이름이 충돌하면 내장 명령이 우선하고, 그다음에는 id 순서상 첫 번째 패키지가 우선합니다
capabilities{id, label, description, defaultEnabled?, mcpServer?, gatesClaudePlugin?, statusful?, hidden?, icon?}채팅의 Tools 행에 있는 스위치. mcpServer는 이 스위치가 켜는 서버를 지정합니다
mcpServers{ "<server name>": {command, args?, env?} or {type: "http" or "sse", url, headers?} }Stdio 서버는 ${node}, ${packageDir}, ${projectDir}, ${globalStorage}를 사용할 수 있습니다
agentProviders{id, serverName, capabilityId, sessionToolViewId?}코드가 aigd.agent.registerProvider를 통해 메모리에서 제공하는 도구
settings{ "<key>": {type, default?, description, enum?, scope?, …} }타입: string, number, boolean, string[], path
menus{ "<menu id>": [{command or submenu, group?, when?, alt?}] }고정 메뉴 id (아래)
submenus{id, label, icon?}서브메뉴 id는 메뉴 키이기도 합니다
keybindings{command, key, mac?, win?, linux?, when?, args?}데스크톱; mac이 지정되지 않으면 ctrl은 macOS에서 Cmd를 의미합니다
statusBar{id, text, tooltip?, command?, alignment?, priority?, when?}데스크톱
panels{viewType, title, icon?}코드가 여는 웹뷰 패널
viewsContainers{left?: [{id, title, icon}], right?: [...]}새 사이드 패널 탭
views{ "left" or "right" or "<container id>": [{id, name, type: "tree" or "webview", icon?, when?, welcome?, titleBar?}] }사이드 패널의 트리 뷰와 웹뷰 뷰
customEditors{viewType, displayName, selector: [{filenamePattern}], priority?}priority가 default(기본값)이면 일치하는 파일의 기본 제공 미리보기를 대체하고, option이면 Open With에 표시됩니다
tutorials{id, title, anchor, markdown? and media? or webview?, size?, trigger?, when?, after?, priority?}사용자당 한 번 표시되는 짧은 인앱 팁
claudePlugin패키지 기준 상대 폴더패키지에 포함되어 배포되는 Claude Code 플러그인
mediaProviders{id, capabilityId, execution: "local"}코드가 aigd.media.registerProvider로 등록하는 로컬 미디어 생성기
sessionTools{id, capabilityId, title, modules?}채팅의 Tools에서 특정 기능(capability)을 위한 설정 화면(코드가 resolve하는 웹뷰 뷰)
gameEngines게임 엔진 패키지 참조패키지당 엔진 하나
runtimes, imageModels, videoModels, model3dModels, mediaModels선언형, 코드 없음로컬 생성 런타임과 그 런타임이 실행하는 모델, 그리고 클라우드 모델 제품군

아이콘은 $(name)(앱 아이콘 세트의 아이콘) 또는 패키지 내부 경로입니다. composerButtons는 여전히 로드되지만 더 이상 사용되지 않습니다(deprecated): composer/toolbar 메뉴 항목을 사용하세요.

메뉴 id명령이 받는 값when용 컨텍스트 키
commandPalette없음—
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}리소스 키들, activeCustomEditor, previewKind
preview/<kind>/toolbar{path}리소스 키들, previewKind
view/title{viewId}view
view/item/context{viewId, itemId}view, viewItem
packages/item/context{packageId}packageId, packageLevel, packageState
statusBar/item/context{itemId}statusBarItem

navigation 그룹은 인라인 툴바 버튼을 만들고, 다른 그룹은 "…" 오버플로 메뉴로 들어가며, group@order는 그룹 내에서 정렬 순서를 지정합니다. 미리보기 종류는 code diff image svg texture audio video model font markdown table binary입니다. 알 수 없는 메뉴 id는 오류가 아니라 경고이므로, 더 새로운 앱을 위해 작성된 패키지도 여전히 로드됩니다.

when 절

메뉴, enablement, 키 바인딩, 뷰, 상태 표시줄 항목, 튜토리얼은 VS Code 문법의 when 절을 사용합니다: ! && || == != < <= > >= =~ /regex/ in 및 not in, 괄호를 지원합니다. 전역 키로는 host, platform, projectOpen, projectEngine, activePane, activeFilePath, activeFileExtname, sessionActive, sessionRunning, attachedCapabilities, activePackages, installedPackages, workspaceEngines와 열린 폴더의 엔진마다 하나씩 있는 workspaceHasEngine:<engine>이 있습니다. 설정은 config.<package id>.<key>로, 자체 키는 <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" }]
    }
  }
}

파싱할 수 없는 절은 매니페스트 오류이며 해당 기여 항목이 제외됩니다.

설정

{
  "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"(기본값)은 사용자 레벨에 기록하고, scope: "project"는 프로젝트 레벨에 기록하며 이는 커밋되어 팀과 공유됩니다.
  • 값은 로컬 레벨, 그다음 프로젝트, 그다음 사용자 레벨, 마지막으로 매니페스트 기본값 순서로 읽습니다.
  • type: "path"는 절대 경로를 받습니다. directories: false는 파일을 요청하며, mustBeWritable과 showFreeSpace는 양식에 검사를 추가합니다.
  • userLevelOnly: true(scope: "machine"과 함께)는 키를 머신 전체 범위로 만들어 프로젝트 및 로컬 값이 무시됩니다.
  • enum은 고정된 선택지를 제공하고, options: { "provider": "<id>" }는 런타임에 provider로부터 선택지를 가져옵니다(현재로서는 앱 자체 provider만 해당).

활성화 이벤트

대부분의 패키지는 아무것도 필요하지 않습니다. 기여된 모든 명령, 슬래시 명령, 뷰, 사용자 지정 편집기, 상태를 가진 기능, 웹뷰 튜토리얼, 게임 엔진이 코드를 스스로 시작하기 때문입니다. 코드가 다른 시점에 실행되어야 한다면 activationEvents에 추가 이벤트를 나열하세요:

이벤트시점
onStartupFinished앱의 첫 렌더링 이후, 또는 CLI의 첫 프롬프트 이후 (main이 있고 다른 이벤트가 없는 패키지의 기본값)
onCommand:<id>, onSlashCommand:/<name>명령이 실행되기 전
onView:<viewId>, onCustomEditor:<viewType>뷰가 처음 표시될 때, 일치하는 파일이 열릴 때
onFileType:.<ext>해당 확장자를 가진 파일이 어느 패널에서든 열릴 때
onCapability:<id>, onAgentProvider:<id>기능이나 provider가 처음 필요할 때
onTutorial:<id>, onWebviewPanel:<viewType>웹뷰 튜토리얼이 표시되기 전, 저장된 패널이 복원될 때
onGameEngine:<id>열린 폴더에 해당 엔진의 프로젝트가 있을 때
*호스트 시작 시 (권장하지 않음)

종속성과 Claude 플러그인

{
  "dependencies": { "acme.core-3d": "^1.0.0" },
  "claudePlugins": { "level-design@acme-marketplace": "*" },
  "claudeMarketplaces": { "acme-marketplace": { "source": "github", "repo": "acme/claude-plugins" } }
}
  • 프로젝트는 각 패키지의 한 버전만 실행합니다. 모든 범위를 만족하고 앱이 허용하는 가장 높은 버전입니다. 종속성은 이를 필요로 하는 패키지보다 먼저 활성화됩니다. 충돌, 순환, 제외된 종속성은 이를 필요로 하는 패키지에 표시됩니다.
  • Claude 플러그인은 프로젝트별로 앱 자체 캐시에 설치되고, 프로젝트의 lock 파일에 있는 커밋에 고정되며, 해당 프로젝트의 채팅에 전달됩니다. 사용자의 ~/.claude는 절대 건드리지 않습니다. 마켓플레이스 소스는 github, git, git-subdir, url입니다.