패키지
AI Game Dev 앱에 어떤 패키지가 들어 있는지, Packages 창이나 gamedev pkg로 설치·업데이트·제외·제거하는 방법, 레벨이 동작하는 방식을 설명합니다.
패키지는 AI Game Dev 앱을 통째로 확장합니다. Blender, SuperCollider를 이용한 음악, 프로젝트 Knowledge Base, Tripo 3D 생성, 로컬 이미지·비디오 모델, 클라우드 비디오·오디오 모델, 그리고 팀이 직접 만드는 무엇이든 포함됩니다. 이 페이지에서는 패키지가 무엇인지, 어떤 패키지가 앱에 기본 포함되는지, 데스크톱 Packages 창과 gamedev pkg 명령으로 패키지를 관리하는 방법을 설명합니다.
패키지란 무엇인가
패키지는 매니페스트 aigd-package.json과 선택적인 JavaScript로 이루어진 폴더입니다. 모델은 VS Code 확장과 같습니다. 패키지가 보여 주는 모든 것은 매니페스트에 선언되어 코드가 실행되기 전에 확인할 수 있고, 코드는 무언가 필요로 할 때만 시작됩니다.
패키지는 다음을 제공할 수 있습니다.
- 세션 도구: Tools 행에 표시되며, 대개 MCP 서버를 기반으로 하여 에이전트가 새로운 도구를 얻게 합니다.
- 슬래시 명령:
/blender나/kb처럼 데스크톱 채팅과 CLI에서 모두 동작합니다. - 명령 팔레트용 명령, 메뉴와 컴포저 툴바 버튼, 상태 표시줄 항목.
- 패널, 사이드 패널 뷰, 자체 창, 그리고 파일 형식용 사용자 지정 편집기나 미리보기.
- 설정, 짧은 인앱 튜토리얼, 다른 패키지나 Claude 플러그인에 대한 의존성.
- 순수 데이터: 로컬 이미지·비디오 모델은 코드가 없는 패키지로, 파일, 다운로드 크기, 라이선스, 적합한 하드웨어를 선언합니다.
모든 패키지는 publisher.name 형식의 id를 가집니다. 자사 패키지는 퍼블리셔 aigd를 사용합니다(예: aigd.blender).
패키지, Claude 플러그인, MCP 서버, 엔진 확장
앱에는 네 종류의 확장이 있습니다. 모두 결국 에이전트가 사용할 수 있는 도구가 되지만, 관리하는 위치는 다릅니다.
| 종류 | 확장 대상 | 관리 위치 |
|---|---|---|
| 패키지 | 앱 자체: 도구, 명령, 패널, 편집기, 모델 | Packages 창, /packages, gamedev pkg |
| Claude 플러그인 | Claude 에이전트: 스킬, 명령, 에이전트, 플러그인 MCP 서버 | Settings, Claude Plugins, 또는 /plugin |
| MCP 서버 | 현재 프로젝트를 위한, 로컬 또는 원격 모든 MCP 서버의 도구 | Settings, MCP servers, 또는 /mcp |
| 엔진 확장 | Unity, Unreal 또는 Godot 플러그인 내부의 추가 도구 | 사이드바 extensions 액션 또는 /install-extension (extensions 참고) |
Settings에서 추가한 MCP 서버는 추가할 당시 열려 있던 프로젝트에 속하며 다른 프로젝트에서는 절대 보이지 않습니다. 새 플러그인이나 MCP 서버는 이미 열려 있는 채팅에 다음 메시지부터 적용됩니다.
앱에 기본 포함된 패키지
앱은 처음 시작할 때 기본 패키지를 사용자 레벨에 설치하므로 모든 프로젝트에서 사용할 수 있습니다.
| 패키지 | 추가하는 기능 |
|---|---|
aigd.blender | Blender: 에이전트가 실제 Blender에서 3D 모델을 만들고 편집합니다 |
aigd.supercollider | 음악: SuperCollider로 게임 음악을 작곡하고 렌더링하고 내보냅니다 |
aigd.knowledge | Knowledge Base: 에이전트가 읽고 갱신하는 프로젝트 내 Markdown 노트 |
aigd.tripo | Tripo: 3D, 텍스처, 메시, 리그, 애니메이션 도구 |
aigd.sdcpp | stable-diffusion.cpp를 사용한 로컬 이미지·비디오 생성 |
제거한 기본 패키지는 다시 추가되지 않습니다. 패키지를 설치했다고 해서 모든 채팅에 적용되는 것은 아닙니다. Tools 행에서 세션별로 해당 도구를 켜야 합니다. 로컬 이미지·비디오 모델과 클라우드 모델 패밀리는 별도 패키지입니다. 전체 목록은 packages catalog를 참고하세요.
Packages 창
창 오른쪽 아래 상태 표시줄의 패키지 아이콘에서 열 수 있습니다("Open Packages"). 상단에 프로젝트와 그 레벨이 표시되고, 다음 탭이 있습니다.
- Installed: 이 프로젝트에서 활성화된 패키지와 각각의 상태, 버전, 레벨.
- Browse: AI Game Dev 패키지 레지스트리를 검색합니다.
- Claude plugins: 이 프로젝트에서 패키지가 필요로 하는 Claude 플러그인.
- Models: 다운로드할 수 있는 로컬 이미지·비디오 모델로, 프로젝트에 생성 런타임이 있을 때 표시됩니다.
헤더에는 Check for updates와 Reload가 있으며, Reload는 프로젝트의 패키지를 다시 시작합니다. 패키지를 선택하면 세부 정보, 레벨, 설정, 오류를 볼 수 있습니다.
패키지 설치
데스크톱 앱에서
- Packages 창을 열고 Browse를 선택합니다.
- 예를 들어
hello를 검색하고 해당 패키지를 선택합니다. - 추가 버튼 아래에서 레벨을 선택합니다: User, Project, Local (levels 참고).
- Add to Project(또는 Add to User, Add to Local)를 클릭합니다.
레지스트리 외부의 패키지를 추가하려면 추가 상자에 입력합니다. 레지스트리 id(aigd.blender, 선택적으로 aigd.blender@^1.2 같은 버전 범위), GitHub 링크 또는 owner/repo, npm 패키지(npm:<name> 또는 해당 npmjs.com 링크), 폴더 경로를 받습니다.
CLI에서
프로젝트 폴더에서 gamedev pkg를 실행하거나(--cwd <path> 전달), 대화형 CLI에서 /packages를 사용하세요. 기본 레벨은 --project입니다.
gamedev pkg list # the packages in effect for this project
gamedev pkg list --user # the user level alone
gamedev pkg add aigd.blender --user # from the registry, for every project
gamedev pkg add github:owner/repo # from GitHub, for this project
gamedev pkg add npm:some-package --local # from npm, this machine only범위 없이 추가된 레지스트리 패키지는 ^<installed version>으로 기록되어 호환되는 업데이트를 받습니다.
레벨: user, project, local
패키지와 그 설정은 세 레벨에서 선언됩니다. 상위 레벨이 하위 레벨을 재정의합니다: local이 project를, project가 user를 이깁니다.
| 레벨 | 적용 대상 | 선언 위치 | Git에 커밋 |
|---|---|---|---|
| User | 이 컴퓨터의 모든 프로젝트 | ~/.ai-game-dev/packages.json | 아니요 |
| Project | 프로젝트를 여는 모든 사람 | <project>/.ai-game-dev/packages.json | 예 |
| Local | 이 컴퓨터의 이 프로젝트에만 | <project>/.ai-game-dev/packages.local.json | 아니요(앱이 .ai-game-dev/.gitignore에 추가합니다) |
각 레벨 옆에는 정확한 버전을 고정하는 잠금 파일(packages-lock.json, packages-lock.local.json)도 있어, 프로젝트를 공유하는 팀원이 동일한 바이트를 설치합니다.
팀 전체가 필요한 패키지에는 Project를, 개인 도구에는 User를, 컴퓨터에 설치된 도구 경로처럼 머신별 선택에는 Local을 사용하세요.
한 프로젝트에서 패키지 제외
사용자 레벨 패키지를 한 프로젝트에서 끄려면 해당 패키지를 선택하고 레벨 행에서 Exclude를 선택하거나 다음을 실행하세요.
gamedev pkg exclude aigd.blender # off in this project (written to the project file)
gamedev pkg include aigd.blender # undo그러면 프로젝트 파일에 "aigd.blender": false가 저장되며 다른 프로젝트에는 영향을 주지 않습니다.
패키지 업데이트
자동 업데이트는 기본적으로 켜져 있습니다. 앱은 시작 직후, 4시간마다, 그리고 Check for updates를 클릭할 때 확인합니다. 각 레벨이 선언한 범위 안에서 앱과 호환되는 최신 버전을 설치하고, 실행마다 알림을 하나씩 표시합니다. 예를 들어 "Updating 1 package… (1/1)" 다음에 "Updated 1 package"가 표시됩니다.
- Packages 창에서 해당 패키지의 Auto-update 스위치로, 또는
gamedev pkg auto-update off <id>로 한 패키지의 자동 업데이트를 끌 수 있습니다. 이 선택은 컴퓨터별로 적용됩니다. gamedev pkg update(전체) 또는gamedev pkg update <id>로 지금 업데이트합니다.- 로컬 폴더에서 온 패키지와 태그에 고정된 GitHub 소스는 자동으로 업데이트되지 않습니다.
더 새로운 앱이 필요한 패키지는 그 사실을 알립니다("requires AI Game Dev >=X, you have Y"); 앱을 먼저 업데이트하세요.
패키지 제거
해당 패키지를 선택하고 Remove를 선택하거나 다음을 실행하세요.
gamedev pkg remove <id> # remove it from the project level
gamedev pkg remove <id> --user # remove it from the user level다른 패키지의 의존성으로만 설치된 패키지에는 Remove가 없고 Exclude만 있으며, 아무도 필요로 하지 않으면 저절로 사라집니다.
패키지 설정
패키지를 선택하고 Settings를 엽니다. 각 설정 옆에서 값을 기록할 레벨을 선택하며, 칩은 현재 값의 출처를 보여 줍니다. 일부 설정은 **Browse…**와 여유 공간 확인이 있는 폴더 선택기이고, 일부는 앱에서 제공하는 선택지를 제공합니다.
CLI에서:
gamedev pkg settings aigd.blender # every key, its value and level
gamedev pkg settings <id> <key> <value> --local # write a value at a level
gamedev pkg settings <id> <key> --unset --project # clear the value at a level값은 저장되기 전에 선언된 타입과 검사됩니다. 거부된 값은 아무것도 바꾸지 않고 코드 1로 종료합니다.
의존성
패키지는 다른 패키지와 Claude 플러그인에 의존할 수 있습니다. 앱이 이를 대신 설치하고 프로젝트마다 패키지당 하나의 버전을 유지합니다. Packages 창은 의존성을 "<id>에 대해 설치됨"과 그 레벨로 표시합니다. 패키지가 필요로 하는 Claude 플러그인은 프로젝트별로 앱 소유 캐시에 설치되며 해당 프로젝트의 세션에서만 로드되고, 사용자의 Claude Code에는 절대 로드되지 않습니다.
안전과 오류
패키지는 VS Code 확장처럼 사용자 권한으로 실행됩니다. 샌드박스는 없습니다. 신뢰할 수 있는 출처의 패키지만 설치하세요. AI Game Dev 레지스트리의 패키지는 압축을 풀기 전에 게시된 체크섬과 검증됩니다.
패키지가 실패하면 카드에 경고 개수가 표시되고 Errors 탭에 세부 정보가 나열됩니다. 타사 패키지의 오류는 어디에도 전송되지 않으며, 자사 레지스트리의 aigd 패키지 오류는 충돌 보고에 동의한 경우에만 저희에게 보고됩니다. 설치된 패키지는 네트워크 연결 없이도 시작됩니다.
다음 단계
- packages catalog에서 사용 가능한 모든 패키지를 확인하세요.
- Creating packages에서 직접 만들어 보세요.
- packages, Claude plugins and MCP servers 글에서 Packages 창과 프로젝트 MCP 서버가 동작하는 모습을 볼 수 있습니다.