게임 엔진 패키지
패키지 하나로 AI Game Dev에 게임 엔진 전체를 가르치세요: 프로젝트 감지, 생성 대화상자, Play, 게임 뷰, 라이브 에이전트 도구를 단계별로.
게임 엔진 패키지는 AI Game Dev에 엔진 전체를 가르칩니다: 어떤 폴더가 해당 엔진의 프로젝트인지, 프로젝트를 만드는 방법, 실행하는 방법, 실행 중인 게임을 표시하는 방법, 그리고 실행 중에 에이전트가 사용할 수 있는 라이브 도구까지. 앱 자체의 엔진(Unity, Godot, Unreal Engine, BRUTAL, Bevy, Web)은 앱 내부에서 같은 계약을 구현하고, 패키지는 Extension Host에서 그것을 구현합니다. 엔진 패키지는 AI Game Dev 0.32.0 이상이 필요하며 다른 패키지와 마찬가지로 커뮤니티 레지스트리에 게시됩니다.
템플릿에서 시작하기
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입니다.
{
"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>에서 실행되며 구현을 등록합니다:
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") |
생략한 선택 메서드는 중립적인 응답을 받습니다: 중지 없음, 게임 뷰 없음, 도구 없음.
실행 과정, 단계별로
- 감지. 사용자가 폴더를 열면 스캔이 여러분의 마커와 일치하는지 확인하고, 여러분의 아이콘과 이름으로 프로젝트를 목록에 표시합니다.
- 활성화. 앱이
onGameEngine:<id>를 발생시키고 최대 30초 동안registerEngine을 기다립니다. - 실행. Play가
operationId와 함께editor.launch를 호출합니다.host.progress({ operationId, message })로 진행 상황을 보고하고("Building 40%"같은 메시지는 진행 표시줄을 그립니다) 단계 사이마다await host.cancelled(operationId)를 확인하세요. 호출은 진행이 없는 채로 15분이 지나거나 총 3시간이 지나면 종료됩니다. - 표시.
gameView: "browser"이면 게임 패널이editor.gameView가 반환한 URL을 로드합니다. - 연결. 채팅에서 에이전트의 connect가
tools.list를 프로젝트의 도구로 나열하고, 각 호출은tools.call로 전달됩니다. 도구 이름은A-Z a-z 0-9 _ -중 1~64자이며, 각 도구에inputSchema를 지정하세요. - 중지.
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로 제공됩니다.