# 게임 엔진 패키지 — AI Game Dev 앱 & CLI · AI Game Developer Wiki

패키지 하나로 AI Game Dev에 게임 엔진 전체를 가르치세요: 프로젝트 감지, 생성 대화상자, Play, 게임 뷰, 라이브 에이전트 도구를 단계별로.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/app/game-engine-packages).

게임 엔진 패키지는 AI Game Dev에 엔진 전체를 가르칩니다: 어떤 폴더가 해당 엔진의 프로젝트인지, 프로젝트를 만드는 방법, 실행하는 방법, 실행 중인 게임을 표시하는 방법, 그리고 실행 중에 에이전트가 사용할 수 있는 라이브 도구까지. 앱 자체의 엔진(Unity, Godot, Unreal Engine, BRUTAL, Bevy, Web)은 앱 내부에서 같은 계약을 구현하고, 패키지는 Extension Host에서 그것을 구현합니다. 엔진 패키지는 AI Game Dev 0.32.0 이상이 필요하며 다른 패키지와 마찬가지로 커뮤니티 레지스트리에 게시됩니다.

## 템플릿에서 시작하기

```bash
gamedev pkg init forge --engine --id acme.forge
cd ~/projects && gamedev pkg dev ~/src/forge      # then open a folder, or create a Forge project
gamedev pkg logs acme.forge -f
```

템플릿은 예제 엔진 `samples.toy-engine`입니다: `toy-engine.json`이 있는 폴더를 감지하고, 두 가지 스타터로 프로젝트를 만들며, 게임을 `127.0.0.1`에서 실행되는 작은 Node.js 서버로 구동해 게임 패널에 표시하고, 에이전트에 두 개의 라이브 도구를 제공하며, 게임을 중지합니다. 네이티브 바이너리가 필요 없습니다.

## 선언적 절반: contributes.gameEngines

앱은 여러분의 코드를 실행하지 않고 이것을 읽으므로, 패키지가 시작되기 전에 프로젝트가 감지되고, 목록에 오르고, 그려지고, 생성 대화상자에 제안됩니다. 패키지당 하나의 엔진이며, 그 `id`가 패키지 id입니다.

```json
{
  "engines": { "aigd": ">=0.32.0" },
  "contributes": {
    "gameEngines": [{
      "id": "acme.forge",
      "contractVersion": 1,
      "displayName": "Forge",
      "icon": "media/forge.svg",
      "explorerIcons": { "folder": "media/forge.svg", "folderOpen": "media/forge.svg" },
      "detect": [{ "exists": "forge.json", "type": "file" }],
      "ignoreDirs": [".forge"],
      "editor": "none",
      "connection": "package",
      "gameView": "browser",
      "starters": [
        { "id": "empty", "label": "Empty", "description": "A blank canvas", "preview": "media/starter-empty.webp", "blank": true },
        { "id": "platformer", "label": "Platformer", "description": "A small playable level", "preview": "media/starter-platformer.webp", "recommended": true, "game": true }
      ],
      "defaultProjectName": "forgegame",
      "showcase": { "accent": "#ff8a3d", "pitch": "A tiny canvas engine, run by a package", "languages": "JavaScript", "tags": ["JavaScript", "Canvas"] }
    }]
  }
}
```

| 필드 | 하는 일 |
| --- | --- |
| `detect` | 규칙 중 하나라도 일치하면 해당 폴더가 프로젝트로 표시됩니다: `exists`(상대 경로, 최대 3개 세그먼트), `glob`(폴더 내 파일 이름 패턴), `contains`(일치한 파일의 처음 64KB 안에 있는 리터럴), `allOf`(2~4개의 마커). 각 엔진은 스캔당 2초가 주어지므로 마커를 가볍게 유지하세요. |
| `editor` | 엔진에 실행할 편집기 애플리케이션이 있으면 `"app"`, 없으면 `"none"` |
| `connection` | `"package"`: 패키지가 에이전트의 라이브 도구를 제공합니다. `"none"`: 도구 없음 |
| `gameView` | `"browser"`: 실행 중인 게임이 게임 패널에 표시되는 웹 페이지입니다 |
| `starters` | 생성 대화상자에 표시할 스타터 1~8개, `recommended`는 최대 하나, `preview`는 와이드 이미지(약 16:7, 예를 들어 640×280), `blank`와 `game`은 스타터가 어떤 모습인지 대화상자에 알려 줍니다(앱 0.32.0-beta.1 이하를 지원하려면 이들을 생략하세요. 해당 버전은 이들을 거부합니다) |
| `showcase` | 생성 대화상자가 엔진을 보여 주는 방식: `accent`와 `accent2` 색상(`#rrggbb`), `pitch`(80자), `summary`, `languages`, 최대 5개의 `tags`, `shortName` |
| `editorInstall` | `{url, label}`: 프로젝트를 여는 데 필요한 것을 받을 곳 |
| `skills` | 이 엔진의 프로젝트에 대해 에이전트가 로드하는 `<skill>/SKILL.md` 패키지 폴더 |

패키지는 Unity, Godot, Unreal, BRUTAL 프로젝트의 레이블을 바꿀 수 없습니다. 잘못된 필드가 있으면 엔진 항목 전체가 제외되며, `gamedev pkg validate`가 그 필드 이름을 알려 줍니다.

## 코드 절반: registerEngine

`activate`는 앱이 엔진을 처음 필요로 할 때 `onGameEngine:<id>`에서 실행되며 구현을 등록합니다:

```typescript
import type { PackageContext, GameEngineImplementation } from "./types/aigd";

export async function activate(ctx: PackageContext): Promise<void> {
  if (!ctx.aigd.gameEngines) return;                 // an app older than 0.32.0
  const host = ctx.aigd.gameEngines.host;            // the app's services, scoped to this package
  const engine: GameEngineImplementation = { project: { /* … */ }, plugin: { /* … */ }, editor: { /* … */ }, tools: { /* … */ } };
  ctx.subscriptions.push(await ctx.aigd.gameEngines.registerEngine("acme.forge", engine));
}
```

앱이 여러분의 메서드를 호출합니다. 모든 메서드는 비동기이고, 순수 JSON을 받고 반환하며, **절대 예외를 던지지 않습니다**: 실패도 결과입니다(예: `{ success: false, errorMessage }`).

| 메서드 | 호출 시점 |
| --- | --- |
| `project.validate(path)` | 감지된 폴더가 프로젝트인지 확인할 때 |
| `project.create({ projectPath, name, starter?, force? })` | 생성 대화상자에서 |
| `plugin.status`, `install`, `update(projectPath)` | 프로젝트 내부에 필요한 것을 설정할 때 |
| `editor.availability()` | 실행 전: 이 컴퓨터에서 엔진을 실행할 수 있는지 |
| `editor.launch(projectPath, { operationId? })` | Play 시, 그리고 에이전트가 연결할 때 |
| `editor.diagnose(projectPath)` | Projects 패널의 상태 표시용 |
| `editor.health?`, `editor.stop?`, `editor.gameView?`, `editor.runIdentity?`, `editor.prepare?` | 선택 사항: 실패 설명, 게임 중지, 게임 뷰 URL, 실행 구분, 필요 시 준비 |
| `tools.list(projectPath)`, `tools.call(projectPath, call)` | 에이전트의 라이브 도구(`connection: "package"`) |

생략한 선택 메서드는 중립적인 응답을 받습니다: 중지 없음, 게임 뷰 없음, 도구 없음.

## 실행 과정, 단계별로

1. **감지.** 사용자가 폴더를 열면 스캔이 여러분의 마커와 일치하는지 확인하고, 여러분의 아이콘과 이름으로 프로젝트를 목록에 표시합니다.
2. **활성화.** 앱이 `onGameEngine:<id>`를 발생시키고 최대 30초 동안 `registerEngine`을 기다립니다.
3. **실행.** Play가 `operationId`와 함께 `editor.launch`를 호출합니다. `host.progress({ operationId, message })`로 진행 상황을 보고하고(`"Building 40%"` 같은 메시지는 진행 표시줄을 그립니다) 단계 사이마다 `await host.cancelled(operationId)`를 확인하세요. 호출은 진행이 없는 채로 15분이 지나거나 총 3시간이 지나면 종료됩니다.
4. **표시.** `gameView: "browser"`이면 게임 패널이 `editor.gameView`가 반환한 URL을 로드합니다.
5. **연결.** 채팅에서 에이전트의 connect가 `tools.list`를 프로젝트의 도구로 나열하고, 각 호출은 `tools.call`로 전달됩니다. 도구 이름은 `A-Z a-z 0-9 _ -` 중 1~64자이며, 각 도구에 `inputSchema`를 지정하세요.
6. **중지.** `editor.stop`은 `launch`가 시작한 것을 종료하며, 오직 그것만 종료합니다.

호스트 서비스는 `logger(scope)`, `progress`, `cancelled`, `compareVersions(a, b)`, 그리고 자신의 저장소 폴더 안 경로에 대한 파일 잠금과 macOS 격리 제거입니다. 한 번의 호출보다 오래 유지되는 상태(실행 기록, 다운로드한 런타임)는 `ctx.globalStoragePath` 또는 `ctx.projectStoragePath`에 보관하세요.

## 테스트하기

- `gamedev pkg validate`: 매니페스트와 매니페스트가 지정한 파일들을 검사합니다.
- 스크래치 폴더에 링크하고, 대화상자에서 프로젝트를 만들고, Play를 누르고, 채팅에서 연결하고, 각 도구를 호출한 뒤 중지하세요. 그런 다음 `gamedev pkg logs <id>`로 전체 실행 로그를 읽어보세요.
- `contractVersion`은 구현하는 엔진 계약의 이름입니다(현재는 `1`만 존재). 추가 사항은 버전을 유지하며, 호환되지 않는 변경은 1 옆에 버전 2로 제공됩니다.

## 관련 페이지

- [프로젝트와 엔진](https://ai-game.dev/ko/docs/wiki/app/projects-and-engines)에서 사용자가 엔진 프로젝트를 어떻게 다루는지 확인하세요.
- [패키지 API](https://ai-game.dev/ko/docs/wiki/app/package-api)에서 `ctx.aigd`의 나머지 부분을 확인하세요.
- [패키지 게시](https://ai-game.dev/ko/docs/wiki/app/publishing-packages)에서 엔진을 공유하는 방법을 확인하세요.

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/app/game-engine-packages

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/app/game-engine-packages
