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

게임 엔진 패키지

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

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

게임 엔진 패키지는 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")

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

실행 과정, 단계별로

  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로 제공됩니다.