AI에게 미니게임 개발 요구사항 쓰기: 장면, 노드, 컴포넌트, 인터랙션 설명법

Easton editorial illustration: central game-scene specification blueprint

AI에게 “점프 기능을 만들어 줘”라고 설명했더니, 실행도 되지 않는 조각 코드만 잔뜩 받은 적이 있을 것입니다. 완전한 게임 스테이지를 만들고 싶은데 노드 트리 구조를 어떻게 설명해야 할지 몰라서, AI가 생성한 계층이 엉망이 되는 경우도 있습니다.

문제는 AI의 능력이 아닙니다. 모호한 Prompt는 재료 목록 없이 레시피만 들고 요리하는 것과 비슷합니다. AI는 자유롭게 해석할 수밖에 없고, 결과는 우리가 원한 것과 완전히 달라집니다.

게임 개발 요구사항은 사실 표준화할 수 있습니다. 장면, 노드, 컴포넌트, 인터랙션이라는 네 가지 핵심 개념에는 각각 대응되는 설명 템플릿이 있습니다. 이 글에서는 실전에서 검증한 방법론을 공유합니다. 장면 4요소법, 노드 트리 JSON 형식, 컴포넌트 설명 템플릿, 인터랙션 5요소 공식, 그리고 바로 복사해 쓸 수 있는 Prompt 템플릿 5개입니다.

Cocos Creator로 미니게임을 만들고 있고, AI로 효율을 높이고 싶지만 자꾸 결과가 어긋난다면 여기서 필요한 답을 찾을 수 있을 것입니다.

게임 요구사항에는 왜 표준화된 설명이 필요할까

모호한 요구사항 설명은 AI 게임 개발의 가장 큰 방해 요소입니다. 저도 예전에 “점프 기능을 만들어 줘”라고 바로 말해 본 적이 있는데, AI는 player.y += 10 같은 코드 한 줄을 내놓았습니다. 물리 시스템도 없고, 충돌 감지도 없고, 애니메이션 전환도 없었습니다. 실행해 보니 캐릭터가 그대로 하늘로 순간이동했습니다.

이런 문제에는 전형적인 증상이 세 가지 있습니다.

첫 번째 문제: AI가 노드 계층을 이해하지 못합니다. Cocos Creator에서 Player 노드를 만들고, 그 아래에 HealthBar 자식 노드를 달아 체력바를 표시한다고 해 보겠습니다. 그런데 “플레이어를 하나 만들어 줘”라고만 말하면 AI는 HealthBar가 자식 노드로 존재해야 한다는 사실을 알지 못합니다. HealthBar를 독립 노드로 장면 루트에 둘 수도 있습니다. 코드가 실행되면 체력바가 플레이어를 따라 움직이지 않습니다.

비교해 보면 바로 드러납니다.

❌ "플레이어를 하나 만들어 줘"
✅ "Player 루트 노드를 만들고, Sprite 컴포넌트를 마운트해 캐릭터 텍스처를 표시하며, 자식 노드 HealthBar로 체력바를 표시한다. 상대 위치는 (0, 32)"

두 번째 버전은 부모-자식 관계를 분명히 설명합니다. 그러면 AI가 생성한 코드에서도 계층이 꼬이지 않습니다.

두 번째 문제: 컴포넌트 조합 관계가 뒤섞입니다. Cocos Creator의 핵심 아키텍처는 “노드 + 컴포넌트”입니다. 노드 자체는 빈 껍데기이고, 컴포넌트가 기능을 부여합니다. 하나의 Player 노드에는 Sprite(텍스처 표시), RigidBody2D(물리 강체), Collider(충돌 감지), PlayerScript(사용자 정의 로직) 네 가지 컴포넌트가 붙을 수 있습니다. “캐릭터가 움직이게 해 줘”라고만 말하면 AI는 이동 스크립트만 줄 수 있고, 물리 컴포넌트를 빠뜨릴 수 있습니다. 그러면 캐릭터가 벽을 뚫고 지나가며 충돌 피드백도 없습니다.

올바른 설명은 컴포넌트 목록을 함께 적어야 합니다.

❌ "캐릭터가 움직이게 해 줘"
✅ "Player 노드에 RigidBody2D 컴포넌트(type: dynamic)를 마운트하고, 자식 노드 Collider 컴포넌트(tag: 'player')를 추가한 뒤, PlayerScript로 키보드 입력을 처리한다"

세 번째 문제: 인터랙션 로직이 조각납니다. “버튼을 누르면 한 번 점프하게 해 줘”라고 말하면 AI는 터치 이벤트 리스너 코드를 줄 수 있습니다. 하지만 얼마나 오래 점프하는지, 얼마나 높이 점프하는지, 점프 중 다시 점프할 수 있는지, 점프가 끝난 뒤 상태를 어떻게 복구하는지는 처리하지 않을 수 있습니다. 실행하면 버튼을 누를 때 캐릭터가 움직이기는 하지만, 애니메이션이 끊기고 상태가 잠기며 연속 클릭에서 버그가 납니다.

완전한 인터랙션 설명에는 다섯 가지 요소가 들어가야 합니다. 트리거 조건, 이벤트 타입, 대상 객체, 응답 동작, 상태 변화입니다. 이 내용은 뒤에서 자세히 다루겠습니다. 우선 공식만 기억해 두면 됩니다.

인터랙션 설명 = 트리거 조건 + 이벤트 타입 + 대상 객체 + 응답 동작 + 상태 변화

모호한 설명의 근본 원인은 구조화된 사고가 부족하다는 데 있습니다. AI에는 명확한 맥락, 구체적인 지시, 분명한 경계 조건이 필요합니다. Prompt 엔지니어링에는 CREATE 프레임워크가 있습니다. 원래는 범용 프로그래밍의 모범 사례지만, 게임 개발에도 똑같이 효과적입니다.

필드	게임 개발에서의 적용
C - Context	엔진 버전(Cocos Creator 3.8), 프로젝트 구조, 기존 코드 스타일을 제공
R - Role	AI가 “Cocos Creator 개발 전문가”임을 명확히 지정
E - Example	기대하는 노드 트리 JSON 형식 예시 제공
A - Action	해야 할 일(노드 생성, 컴포넌트 마운트, 이벤트 리스닝)을 명확히 지정
T - Tone	코드 스타일(TypeScript + Cocos Creator API)을 지정
E - Edge	제약 조건(FPS ≥ 60, 노드 수 ≤ 50)을 설명

이 프레임워크의 핵심 논리는 “무엇을 할 것인가”를 “어떤 조건에서”, “어떤 도구로”, “어떤 기준을 만족하도록”으로 나누는 것입니다. 아래 네 개 장에서는 장면, 노드, 컴포넌트, 인터랙션이라는 네 가지 차원을 중심으로 CREATE 프레임워크를 복사 가능한 템플릿으로 바꿔 보겠습니다.

장면 설명의 4요소법

장면은 게임 개발의 최상위 개념입니다. 완전한 장면 설명에는 네 가지 요소가 들어갑니다. 타입, 스타일, 요소, 인터랙션 지점입니다. 이 네 항목을 명확히 채우면 AI는 뼈대가 완성된 스테이지를 생성할 수 있습니다.

먼저 4요소의 정의를 보겠습니다.

요소	정의	설명 방법
장면 타입	게임 스테이지 / 화면 / 메뉴	”{요소}를 포함한 {타입} 장면”
비주얼 스타일	2D / 3D, 픽셀 / 사실적	”{스타일} 아트 스타일을 사용하고, {게임명}을 참고”
핵심 요소	플레이어, 적, 아이템, UI	”{수량}개의 {타입} 객체를 포함하고, 위치는 {좌표}“
인터랙션 지점	클릭 가능 / 충돌 가능 영역	”{수량}개의 인터랙션 영역을 정의하고, {이벤트}를 트리거”

이 방법의 핵심은 먼저 장면의 “뼈대”(타입 + 스타일)를 정한 뒤, “내용”(요소 + 인터랙션 지점)을 채우는 것입니다. 집을 지을 때 먼저 설계도를 그리고, 그다음 가구를 배치하는 것과 같습니다.

실전 예시를 하나 보겠습니다. 소코반 게임 스테이지를 만든다면 어떻게 설명해야 할까요?

【장면 설명】

장면 타입: 소코반 게임 스테이지 장면
비주얼 스타일: 미니멀한 기하학 스타일, 배경은 단색, 그리드 크기는 64x64

핵심 요소:
  - Player 노드 1개(위치: 1행 1열)
  - Box 노드 3개(위치: 2행 2열, 3행 4열, 5행 2열)
  - Target 노드 3개(목표 위치, 움푹 들어간 칸으로 표시)
  - Wall 노드(장면 경계를 둘러쌈)

인터랙션 지점:
  - Player가 Box를 밀 수 있고, 충돌 감지로 이동을 트리거
  - Box가 Target에 도달하면 승리 판정을 트리거
  - 장면 경계와 충돌하면 이동 차단을 트리거

【기술 제약】

엔진: Cocos Creator 3.8
언어: TypeScript
성능: FPS ≥ 60, 노드 수 ≤ 50

이 설명은 네 가지 요소를 모두 포함합니다. 타입은 “소코반 스테이지”, 스타일은 “미니멀한 기하학”, 요소에는 Player, Box, Target, Wall 네 객체의 구체적인 위치가 나열되어 있고, 인터랙션 지점에는 박스 밀기, 승리 판정, 경계 차단이라는 세 가지 핵심 로직이 정의되어 있습니다. 기술 제약을 별도로 적어 AI가 생성하는 코드가 성능 요구사항을 만족하도록 합니다.

여기에는 작은 디테일이 있습니다. 핵심 요소의 위치를 픽셀 좌표로 바로 쓰지 않고 “N행 N열”로 설명했다는 점입니다. 이렇게 하면 AI가 그리드 크기(64x64)에 따라 자동으로 픽셀 좌표로 변환할 수 있습니다. 예를 들어 1행 1열은 (64, 64)가 됩니다. 코드가 더 유연해지고, 그리드 크기를 바꿀 때 모든 좌표를 수동으로 수정할 필요가 없습니다.

바로 복사해서 쓸 수 있는 템플릿도 하나 보겠습니다.

## 장면 설명 템플릿

【기본 정보】

- 장면 이름: {sceneName}
- 장면 타입: {타입: 전투 장면 / 메뉴 장면 / 결과 장면}
- 비주얼 스타일: {스타일 설명}

【핵심 요소 목록】

1. {노드명}: {수량}개, 초기 위치 ({x}, {y})
2. {노드명}: {수량}개, 기능 설명
3. ...

【인터랙션 지점 정의】

- {인터랙션 지점 이름}: 트리거 조건 {조건}, 응답 동작 {동작}
- {인터랙션 지점 이름}: ...

【기술 요구사항】

- 엔진 버전: {version}
- 언어: {TypeScript / JavaScript}
- 성능 지표: {FPS / 노드 수 / 메모리}

이 템플릿은 대부분의 2D 미니게임 장면에 적합합니다. 네 가지 요소를 채우면 AI는 구조가 완성된 스테이지 뼈대를 생성할 수 있습니다. 세 번째 장에서는 “핵심 요소 목록”을 노드 트리 JSON 형식으로 확장해 AI가 계층 관계를 이해하도록 만드는 방법을 다루겠습니다.

노드 트리의 표준 설명 형식

노드 트리는 Cocos Creator 장면의 핵심 데이터 구조입니다. 각 노드는 자식 노드를 가질 수 있고, 자식 노드는 부모 노드의 위치를 기준으로 상대 좌표를 상속받아 하나의 트리를 형성합니다. AI에게 노드 트리를 설명할 때 가장 명확한 방식은 JSON 형식을 사용하는 것입니다.

왜 JSON일까요? 구조화되어 있고, 파싱 가능하며, AI가 바로 이해할 수 있기 때문입니다. JSON을 주면 AI는 루트 노드가 누구인지, 어떤 자식 노드가 있는지, 각 노드에 어떤 컴포넌트를 붙여야 하는지, 속성이 무엇인지 알 수 있습니다. 코드를 생성할 때 AI는 JSON의 계층 관계에 따라 단계별로 노드를 생성하므로 부모-자식 관계를 망가뜨리지 않습니다.

표준 노드 트리 JSON 구조를 먼저 보겠습니다.

{
  "rootNode": "Scene",
  "tree": {
    "Player": {
      "components": ["Sprite", "RigidBody2D", "PlayerScript"],
      "position": {"x": 100, "y": 200},
      "properties": {
        "size": {"width": 64, "height": 64},
        "anchor": {"x": 0.5, "y": 0.5}
      },
      "children": {
        "HealthBar": {
          "components": ["ProgressBar"],
          "position": {"x": 0, "y": 32}
        },
        "Weapon": {
          "components": ["Sprite"],
          "position": {"x": 48, "y": 0}
        }
      }
    },
    "Enemies": {
      "components": [],
      "children": {
        "Enemy1": {
          "components": ["Sprite", "EnemyScript"],
          "position": {"x": 300, "y": 150}
        },
        "Enemy2": {
          "components": ["Sprite", "EnemyScript"],
          "position": {"x": 400, "y": 250}
        }
      }
    },
    "UI": {
      "components": [],
      "children": {
        "ScoreLabel": {
          "components": ["Label"],
          "content": "Score: 0"
        },
        "PauseButton": {
          "components": ["Button"],
          "onClick": "pauseGame()"
        }
      }
    }
  }
}

이 JSON은 간단한 전투 장면을 설명합니다. 루트 노드는 Scene이고, 그 아래에 Player(플레이어), Enemies(적 컨테이너), UI(인터페이스)라는 세 개의 최상위 노드가 있습니다. Player 아래에는 HealthBar와 Weapon이라는 두 자식 노드가 붙어 있습니다. AI가 이 JSON을 읽으면 HealthBar를 Player의 자식 노드로 생성해야 하고, 위치는 Player 기준 상대 좌표 (0, 32)라는 것을 알 수 있습니다.

노드 트리 설명에서 기억해야 할 핵심은 세 가지입니다.

첫 번째 핵심: 부모-자식 관계는 반드시 명확해야 합니다. 자식 노드의 position은 부모 노드를 기준으로 한 오프셋입니다. 예를 들어 HealthBar의 position이 (0, 32)라면 Player 바로 위 32픽셀 위치에 있다는 뜻입니다. Player가 (200, 300)으로 이동하면 HealthBar도 자동으로 (200, 332)로 따라갑니다. 이 메커니즘이 체력바가 항상 플레이어를 따라다니도록 보장합니다.

HealthBar를 Player의 자식 노드가 아니라 장면 루트 노드에 두면 체력바는 플레이어를 따라가지 않습니다. 저도 이 함정에 빠진 적이 있습니다. AI가 생성한 코드가 UI 요소를 모두 루트 노드에 두었고, 실행해 보니 체력바와 플레이어가 분리되어 플레이어가 움직여도 체력바는 제자리에 있었습니다. 이후 JSON 형식으로 노드 트리를 설명하자 AI가 생성한 코드의 계층 관계가 올바르게 나왔습니다.

두 번째 핵심: 상속이 아니라 컴포넌트 조합입니다. Cocos Creator의 설계 철학은 “노드는 엔티티이고, 컴포넌트가 기능을 부여한다”입니다. 노드 자체에는 아무 동작도 없습니다. Sprite 컴포넌트를 붙여야 이미지를 표시할 수 있고, RigidBody2D를 붙여야 물리 속성을 가질 수 있으며, Script를 붙여야 사용자 정의 로직이 생깁니다. 이런 조합식 설계는 상속식 설계보다 유연합니다. Player에는 Sprite + RigidBody + Script를 붙이고, Enemy에는 Sprite + RigidBody + EnemyScript를 붙일 수 있습니다. 두 노드는 일부 컴포넌트를 공유하지만 각자 독립적인 스크립트를 가집니다.

JSON에서는 components 배열로 컴포넌트 목록을 설명합니다. AI는 배열 순서에 따라 컴포넌트를 하나씩 마운트하고, 각 컴포넌트의 속성은 properties에 보충할 수 있습니다.

세 번째 핵심: 노드 이름은 규칙적으로 지어야 합니다. 카멜 케이스(Player, Enemy, HealthBar)를 따르고, 기능성 노드는 밑줄(bg_sprite, ui_canvas)을 사용할 수 있습니다. 이름이 명확하면 AI가 생성하는 코드의 변수명도 일관되고, 나중에 코드를 유지보수할 때 노드의 용도를 한눈에 파악할 수 있습니다.

실전 사례를 하나 더 보겠습니다. 슈팅 게임의 노드 트리입니다. 이 JSON을 그대로 AI에게 보내면 완전한 장면 코드를 생성하게 할 수 있습니다.

{
  "rootNode": "GameScene",
  "tree": {
    "Player": {
      "components": [
        "Sprite(텍스처 경로: assets/player.png)",
        "RigidBody2D(type: dynamic, gravityScale: 0)",
        "Collider(tag: 'player')",
        "PlayerScript"
      ],
      "position": {"x": 200, "y": 400},
      "properties": {"size": {"width": 64, "height": 64}},
      "children": {
        "BulletSpawnPoint": {"position": {"x": 32, "y": 0}}
      }
    },
    "Enemies": {
      "children": [
        {
          "Enemy1": {
            "components": ["Sprite", "Collider(tag: 'enemy')"],
            "position": {"x": 600, "y": 200}
          }
        },
        {
          "Enemy2": {
            "components": ["Sprite", "Collider(tag: 'enemy')"],
            "position": {"x": 700, "y": 300}
          }
        }
      ]
    },
    "Bullets": {
      "components": [],
      "description": "총알 풀 컨테이너, Bullet 노드를 동적으로 생성"
    },
    "UI": {
      "children": {
        "ScoreLabel": {"components": ["Label"], "content": "Score: 0"},
        "RestartButton": {"components": ["Button"], "onClick": "restartGame()"}
      }
    }
  }
}

이 JSON에는 주목할 만한 디테일이 몇 가지 있습니다.

Player 아래에는 BulletSpawnPoint 자식 노드가 있고, 위치는 (32, 0)입니다. 이 노드는 총알 발사 지점이며 플레이어 기준 32픽셀만큼 오프셋됩니다.
Enemies는 컨테이너 노드이며, 그 아래에 여러 Enemy 자식 노드를 배열 형태로 나열합니다.
Bullets는 총알 풀 컨테이너이고, description 필드로 동적으로 Bullet 노드를 생성하는 부모 노드임을 설명합니다.
UI 아래의 RestartButton에는 onClick 속성이 있어 콜백 함수 이름을 직접 바인딩합니다.

AI에게 보낼 때는 기술 제약도 함께 붙입니다.

위 노드 트리 JSON을 바탕으로 Cocos Creator 장면을 생성해 주세요.

요구사항:
1. Cocos Creator 3.8 API 사용
2. TypeScript 코드, 타입 어노테이션 포함
3. 스크립트 컴포넌트는 @ccclass 데코레이터 사용
4. 이벤트 리스닝은 node.on() 메서드 사용

AI는 JSON의 계층 관계에 따라 완전한 장면 생성 코드를 만듭니다. 노드 생성, 컴포넌트 마운트, 속성 설정의 세 단계가 포함됩니다. 코드를 받은 뒤에는 스크립트 컴포넌트의 구체적인 로직만 보충하면 장면 뼈대가 완성됩니다.

컴포넌트 설명 템플릿

컴포넌트는 노드 기능의 운반체입니다. AI에게 컴포넌트를 설명할 때 핵심은 네 가지 필드를 명확히 하는 것입니다. 기능, 속성, 의존성, 예시 설정입니다. 이 템플릿은 모든 Cocos Creator 내장 컴포넌트와 사용자 정의 스크립트 컴포넌트에 적합합니다.

먼저 네 필드의 정의를 보겠습니다.

필드	필수 여부	설명
기능	필수	컴포넌트가 무엇을 하는지 한 문장으로 설명
속성	필수	설정 파라미터(타입 + 설명)
의존성	선택	노드에 필요한 속성 / 다른 컴포넌트
예시 설정	권장	대표 설정값

이 템플릿의 논리는 먼저 AI에게 컴포넌트의 용도(기능)를 알려 주고, 조정 가능한 파라미터(속성)를 나열한 뒤, 마지막으로 전제 조건(의존성)을 설명하는 것입니다. AI는 이 구조에 따라 컴포넌트 마운트 코드를 생성하고, 속성값은 예시 설정에 맞춰 채웁니다.

실전 예시로 Sprite 컴포넌트 설명을 보겠습니다.

## 컴포넌트 이름: Sprite

**기능**: 이미지 텍스처를 표시하는 2D 게임에서 가장 자주 쓰이는 렌더링 컴포넌트

**속성**:

- spriteFrame: SpriteFrame - 이미지 리소스 | 기본값: null
- sizeMode: SizeMode - 크기 모드(CUSTOM / RAW / TRIMMED) | 기본값: TRIMMED
- type: SpriteType - 렌더링 타입(SIMPLE / SLICED / TILED / FILLED) | 기본값: SIMPLE

**의존성**:

- 노드에 필요한 속성: size 속성(sizeMode = CUSTOM일 때)

**예시 설정**:

spriteFrame: assets/player.png
sizeMode: RAW

이 설명은 Sprite 컴포넌트의 핵심 속성을 모두 나열합니다. AI가 이 내용을 읽으면 다음과 비슷한 코드를 생성합니다.

const sprite = node.addComponent(Sprite);
sprite.spriteFrame = assets.player;
sprite.sizeMode = SizeMode.RAW;

물리 컴포넌트 사례도 하나 보겠습니다. RigidBody2D입니다.

## 컴포넌트 이름: RigidBody2D

**기능**: 2D 물리 강체로, 노드에 물리 속성(중력, 충돌)을 부여

**속성**:

- type: RigidBodyType - 강체 타입(STATIC / DYNAMIC / KINEMATIC) | 기본값: STATIC
- gravityScale: number - 중력 계수 | 기본값: 1.0
- linearVelocity: Vec2 - 선형 속도 | 기본값: (0, 0)

**의존성**:

- 필요한 다른 컴포넌트: Collider2D(충돌 감지)

**예시 설정**:

type: DYNAMIC
gravityScale: 0.5
linearVelocity: (100, 0)

여기에는 의존성 필드가 있습니다. RigidBody2D는 Collider2D와 함께 있어야 충돌 감지를 할 수 있습니다. AI가 이 의존성을 읽으면 같은 노드에 Collider2D 컴포넌트를 붙이라고 알려 주거나, 자동으로 추가해 줍니다.

흔한 함정을 하나 이야기해 보겠습니다. 예전에 AI에게 “캐릭터에 물리 속성을 넣어 줘”라고 설명했더니 AI는 RigidBody2D만 붙이고 Collider는 붙이지 않았습니다. 코드를 실행하니 캐릭터는 중력의 영향을 받아 아래로 떨어졌지만, 바닥에 닿으면 그대로 통과했습니다. 충돌 감지가 없었기 때문입니다. 이후 컴포넌트 설명 템플릿을 사용하고 의존성 필드를 추가하자, AI가 생성한 코드에는 RigidBody2D + Collider2D가 함께 붙었습니다.

컴포넌트 설명 템플릿의 표준 형식을 정리하면 다음과 같습니다.

## 컴포넌트 이름: {ComponentType}

**기능**: {컴포넌트 기능을 한 문장으로 설명}

**속성**:

- {속성명}: {타입} - {설명} | 기본값: {default}
- {속성명}: {타입} - {설명} | 기본값: {default}

**의존성**:

- 노드에 필요한 속성: {Node 속성}(예: size, anchor)
- 필요한 다른 컴포넌트: {Component 이름}(예: RigidBody2D)

**예시 설정**:

{property}: {value}
{property}: {value}

**코드 예시**:

```typescript
// 컴포넌트 가져오기
const sprite = this.node.getComponent(Sprite);
sprite.spriteFrame = newSpriteFrame;

이 템플릿은 Cocos Creator의 모든 내장 컴포넌트(Sprite, Label, Button, RigidBody2D, Collider2D 등)에 적합하고, 사용자 정의 스크립트 컴포넌트에도 잘 맞습니다. PlayerScript 컴포넌트를 만들고 싶다면 같은 템플릿으로 설명하면 됩니다.

## 컴포넌트 이름: PlayerScript

**기능**: 플레이어 이동, 점프, 충돌 응답을 처리하는 사용자 정의 로직

**속성**:

- moveSpeed: number - 이동 속도 | 기본값: 200
- jumpHeight: number - 점프 높이 | 기본값: 100
- health: number - 현재 체력 | 기본값: 100

**의존성**:

- 노드에 필요한 속성: RigidBody2D 컴포넌트(물리 이동에 사용)
- 노드에 필요한 속성: Collider2D 컴포넌트(충돌 감지에 사용)

**예시 설정**:

moveSpeed: 300
jumpHeight: 150
health: 100

AI가 이 설명을 읽으면 완전한 PlayerScript TypeScript 클래스를 생성합니다. @property 데코레이터로 정의된 속성, onLoad / start / update 생명주기 메서드, move / jump / takeDamage 같은 사용자 정의 메서드가 포함됩니다. 코드를 받은 뒤에는 구체적인 로직만 채우면 뼈대는 이미 완성된 상태입니다.

인터랙션 설명 공식

인터랙션은 게임 로직의 핵심입니다. 플레이어가 버튼을 누르고, 캐릭터가 적과 충돌하고, 총알이 목표에 맞는 일은 모두 인터랙션입니다. AI에게 인터랙션을 설명할 때 가장 명확한 방식은 5요소 공식을 사용하는 것입니다.

인터랙션 설명 = 트리거 조건 + 이벤트 타입 + 대상 객체 + 응답 동작 + 상태 변화

다섯 요소의 의미는 다음과 같습니다.

트리거 조건: 어떤 상황에서 발생하는가(충돌, 클릭, 키보드 입력)
이벤트 타입: 구체적인 이벤트 이름(TOUCH_START, onCollisionEnter)
대상 객체: 어떤 노드 / 컴포넌트가 이벤트에 응답하는가
응답 동작: 어떤 메서드 / 함수를 실행하는가
상태 변화: 데이터 / 시각 요소가 어떻게 바뀌는가

이 공식은 인터랙션 설명이 완전한 폐쇄 루프가 되도록 보장합니다. 하나라도 빠지면 AI가 생성한 코드에는 버그가 생기기 쉽습니다.

예를 들어 보겠습니다. “버튼을 누르면 한 번 점프하게 해 줘”라고 말하면 AI는 터치 이벤트 리스너 코드만 줄 수 있습니다. 하지만 얼마나 높이 점프하는지, 얼마나 오래 점프하는지, 점프가 끝난 뒤 상태를 어떻게 복구하는지는 설명되지 않습니다. 실행하면 버튼을 눌렀을 때 캐릭터가 움직이기는 하지만, 애니메이션이 끊기고 상태가 잠기며 연속 클릭에서 문제가 생깁니다.

올바른 설명은 다섯 요소를 모두 명확히 써야 합니다.

## 인터랙션 이름: 클릭 점프

【트리거 조건】

- 트리거 방식: 터치 클릭
- 트리거 객체: JumpButton 노드
- 트리거 시점: TOUCH_END(손가락이 화면에서 떨어질 때)

【이벤트 리스닝】

- 리스닝 노드: JumpButton
- 이벤트 타입: Node.EventType.TOUCH_END
- 콜백 함수: onJumpButtonClicked

【응답 동작】

- 실행 메서드: PlayerScript.jump()
- 파라미터 전달: height = 100, duration = 0.3

【상태 변화】

- 데이터 변화: Player.position.y += 100
- 시각 변화: Player 노드가 jump 애니메이션 재생(scale: 1.0 → 1.2 → 1.0)
- 상태 변화: Player.isJumping = true(0.3초 동안 유지)

【코드 구현】

```typescript
jumpButton.on(Node.EventType.TOUCH_END, (event) => {
  const playerScript = player.getComponent(PlayerScript);
  playerScript.jump({ height: 100, duration: 0.3 });
}, this);


이 설명은 다섯 요소를 모두 포함합니다. AI가 읽으면 콜백 함수, 파라미터 전달, 상태 관리까지 포함한 완전한 터치 이벤트 리스너 코드를 생성합니다. 코드를 받은 뒤에는 jump() 메서드의 구체적인 구현만 보충하면 됩니다.

충돌 인터랙션 사례도 보겠습니다.

```markdown
## 인터랙션 이름: 충돌 피해 감지

【트리거 조건】

- 트리거 방식: 충돌 감지
- 트리거 객체: Player 노드 Collider + Enemy 노드 Collider
- 트리거 시점: onCollisionEnter(충돌 시작)

【이벤트 리스닝】

- 리스닝 컴포넌트: Player 노드의 Collider 컴포넌트
- 이벤트 타입: Collider2D.onCollisionEnter
- 콜백 함수: onPlayerHitEnemy

【응답 동작】

- 실행 메서드: PlayerScript.takeDamage(amount)
- 파라미터 전달: damage = 10

【상태 변화】

- 데이터 변화: Player.health -= 10
- 시각 변화: Player 노드가 흰색 깜빡임 애니메이션 재생(0.1초)
- 상태 변화: Player.isHurt = true(0.2초 동안 유지)

【코드 구현】

```typescript
onCollisionEnter(self: Collider2D, other: Collider2D) {
  if (other.tag === 'enemy') {
    const playerScript = this.node.getComponent(PlayerScript);
    playerScript.takeDamage(10);
    this.flashWhite(0.1);
  }
}


여기서 중요한 디테일은 트리거 객체가 두 노드의 Collider 컴포넌트이고, 트리거 시점이 onCollisionEnter라는 점입니다. AI는 이 설명을 읽고 Player의 Collider 컴포넌트에서 충돌 이벤트를 리스닝해야 하며, 충돌 대상의 tag가 'enemy'일 때 피해 로직을 실행해야 한다는 것을 알 수 있습니다.

인터랙션 설명에서 흔한 함정은 상태 변화를 명확히 말하지 않는 것입니다. 예전에 AI에게 "적과 충돌하면 체력을 깎아 줘"라고 설명했더니 AI는 `health -= 10` 코드만 주었습니다. 시각 피드백(흰색 깜빡임 애니메이션)과 상태 잠금(isHurt)은 없었습니다. 실행해 보니 플레이어가 적과 부딪히면 체력은 줄었지만 아무런 시각 신호가 없어서 플레이어가 다쳤는지 알 수 없었고, 연속 충돌로 체력이 순식간에 모두 깎였습니다.

이후 5요소 공식을 사용해 상태 변화를 보충하자, AI가 생성한 코드에는 흰색 깜빡임 애니메이션과 상태 잠금이 포함되어 인터랙션 경험이 완성되었습니다.

표준 인터랙션 설명 템플릿은 다음과 같습니다.

```markdown
## 인터랙션 이름: {인터랙션 설명}

【트리거 조건】

- 트리거 방식: {터치 / 키보드 / 충돌}
- 트리거 객체: {노드명}
- 트리거 시점: {TOUCH_START / TOUCH_END / onCollisionEnter}

【이벤트 리스닝】

- 리스닝 노드: {노드명}
- 이벤트 타입: Node.EventType.{이벤트 타입}
- 콜백 함수: {함수명}

【응답 동작】

- 실행 메서드: {스크립트명}.{메서드명}
- 파라미터 전달: {파라미터 목록}

【상태 변화】

- 데이터 변화: {변수명} = {새 값}
- 시각 변화: {애니메이션 / 색상 / 위치 변화}

이 템플릿은 터치 인터랙션(버튼 클릭, 화면 스와이프), 충돌 인터랙션(캐릭터가 적과 충돌, 총알이 목표에 적중), 키보드 인터랙션(방향키 이동, 스페이스바 점프)에 모두 적합합니다. 다섯 요소를 채우면 AI는 완전한 이벤트 리스너 코드를 생성할 수 있습니다.

Cocos Creator의 터치 이벤트에는 네 가지 타입이 있습니다. 참고용으로 정리하면 다음과 같습니다.

이벤트 타입	트리거 시점
TOUCH_START	손가락이 화면을 누를 때
TOUCH_MOVE	손가락이 화면 위에서 움직일 때
TOUCH_END	손가락이 화면에서 떨어질 때
TOUCH_CANCEL	터치가 시스템에 의해 취소될 때(예: 전화 수신으로 중단)

리스닝 방식은 node.on(Node.EventType.{이벤트 타입}, callback, target)입니다. 소멸 시에는 node.off()로 리스너를 해제해 메모리 누수를 피해야 합니다. 이런 디테일은 템플릿에도 반영되어 있으므로 AI가 규칙에 맞게 코드를 생성합니다.

실전 Prompt 템플릿 5개

앞에서는 장면 4요소, 노드 트리 JSON, 컴포넌트 설명 템플릿, 인터랙션 5요소 공식을 다뤘습니다. 이 네 가지 방법론을 Prompt로 옮기려면 표준 형식이 필요합니다. 여기서는 바로 복사해서 쓸 수 있는 템플릿 5개를 제공합니다. 장면 만들기, 노드 만들기, 인터랙션 구현, 스크립트 만들기, 성능 최적화라는 다섯 상황을 포괄합니다.

템플릿 1: 완전한 장면 만들기

【역할】당신은 Cocos Creator 개발 전문가이며 TypeScript와 노드-컴포넌트 아키텍처에 능숙합니다.

【작업】아래 게임 장면의 완전한 코드를 작성해 주세요.

【장면 설명】

장면 타입: {타입}
비주얼 스타일: {스타일}
핵심 요소: {노드 목록}
인터랙션 지점: {인터랙션 목록}

【노드 트리 구조】

```json
{노드 트리 JSON}

【기술 요구사항】

엔진: Cocos Creator 3.8
언어: TypeScript, @ccclass 데코레이터 사용
API: Cocos Creator 공식 API 사용(node.getComponent, node.on 등)

【출력 요구사항】

장면 코드(완전한 노드 생성 로직)
스크립트 코드(타입 어노테이션과 주석 포함)
이벤트 리스닝 코드(인터랙션 로직)


### 템플릿 2: 노드를 만들고 컴포넌트 마운트하기

【역할】Cocos Creator TypeScript 개발자

【작업】{노드명} 노드를 만들고 {컴포넌트 목록} 컴포넌트를 마운트해 주세요.

【노드 속성】

이름: {nodeName}
위치: ({x}, {y})
크기: {width}x{height}
앵커: ({anchorX}, {anchorY})

【컴포넌트 설정】

{컴포넌트명}:
- {속성}: {값}
{컴포넌트명}:
- {속성}: {값}

【출력 요구사항】

TypeScript 코드, 타입 어노테이션 포함
Cocos Creator 3.8 API 사용
각 코드 줄을 설명하는 한국어 주석 추가


### 템플릿 3: 인터랙션 로직 구현하기

【역할】Cocos Creator 이벤트 시스템 전문가

【작업】아래 인터랙션 로직을 구현해 주세요.

【인터랙션 설명】

트리거 조건: {트리거 조건}
이벤트 타입: {이벤트 타입}
대상 객체: {노드명}
응답 동작: {메서드명}
상태 변화: {변화 설명}

【기술 제약】

node.on으로 이벤트를 리스닝
이벤트 타입은 Node.EventType 열거형 사용
콜백 함수에는 event 파라미터 포함
소멸 시 node.off로 리스너 해제

【출력 요구사항】

TypeScript 코드
리스닝, 콜백, 소멸 로직을 완전하게 포함
오류 처리 추가(노드 없음, 컴포넌트 누락)


### 템플릿 4: 스크립트 컴포넌트 만들기

【역할】Cocos Creator 스크립트 개발 전문가

【작업】{스크립트명} 스크립트 컴포넌트를 만들어 주세요.

【스크립트 기능】

{기능 설명}

【속성 정의】

@property({타입})
{속성명}: {타입} = {기본값}

【메서드 목록】

{메서드명}({파라미터}): {반환 타입}
- 기능: {설명}
{메서드명}({파라미터}): {반환 타입}
- 기능: {설명}

【생명주기】

onLoad: {초기화 로직}
start: {시작 로직}
update(dt): {매 프레임 업데이트 로직}

【출력 요구사항】

TypeScript 코드, @ccclass와 @property 데코레이터 사용
완전한 생명주기 메서드 포함
타입 어노테이션과 한국어 주석 추가


### 템플릿 5: 노드 트리 성능 최적화하기

【역할】Cocos Creator 성능 최적화 전문가

【작업】아래 노드 트리 구조의 성능을 최적화해 주세요.

【현재 노드 트리】

{노드 트리 JSON}

【성능 문제】

노드 수가 너무 많음: {수량}
DrawCall이 너무 높음: {횟수}
메모리 사용량이 너무 큼: {크기}

【최적화 목표】

FPS: ≥ 60
DrawCall: ≤ 20
메모리: ≤ 100MB

【최적화 전략】

노드 병합: {병합 방안}
노드 풀 사용: {재사용 방안}
컴포넌트 최적화: {컴포넌트 최적화 방안}

【출력 요구사항】

최적화된 노드 트리 JSON
TypeScript 최적화 코드
성능 비교 데이터(최적화 전 vs 최적화 후)


이 다섯 템플릿은 AI 게임 개발의 전체 흐름을 포괄합니다. 장면 생성부터 노드 마운트까지, 인터랙션 구현부터 스크립트 작성까지, 마지막으로 성능 최적화까지 이어집니다. 각 템플릿은 CREATE 프레임워크를 따릅니다. Context(역할 설정), Action(작업 설명), Edge(기술 제약, 성능 지표), Example(노드 트리 JSON 예시)이 들어 있습니다.

사용할 때는 템플릿을 그대로 복사하고 `{}` 안의 내용을 바꾸면 됩니다. 예를 들어 템플릿 2에서 Player 노드를 만들고 싶다면 `{nodeName}`을 `Player`로, `{컴포넌트 목록}`을 `Sprite, RigidBody2D, PlayerScript`로 바꾸고, 속성은 실제 요구사항에 맞게 채우면 됩니다. AI는 템플릿에 따라 완전한 코드를 생성하므로, 처음부터 Prompt를 작성하는 시간을 줄일 수 있습니다.

## 정리

이 글에서는 네 가지 방법론과 다섯 개의 실전 템플릿을 다뤘습니다. 핵심을 다시 정리해 보겠습니다.

**장면 설명 4요소**: 타입, 스타일, 요소, 인터랙션 지점. 먼저 장면의 뼈대를 정하고 내용을 채우면 AI가 구조가 완성된 스테이지를 생성합니다.

**노드 트리 JSON 형식**: 루트 노드 → 자식 노드 → 컴포넌트 → 속성 → 위치. 구조화된 형식으로 계층 관계를 설명하면 AI가 트리 구조에 따라 단계별로 노드를 생성하므로 부모-자식 관계가 꼬이지 않습니다.

**컴포넌트 설명 4필드**: 기능, 속성, 의존성, 예시 설정. 먼저 용도를 말하고, 파라미터를 나열한 뒤, 전제 조건을 설명하면 AI가 이 구조에 따라 컴포넌트 마운트 코드를 생성합니다.

**인터랙션 설명 5요소**: 트리거 조건, 이벤트 타입, 대상 객체, 응답 동작, 상태 변화. 다섯 요소가 완전한 폐쇄 루프를 이루면 AI가 생성한 코드에 누락이 줄어듭니다.

이 네 가지 방법론은 다섯 개의 실전 템플릿으로 Prompt에 적용할 수 있습니다. 장면 만들기, 노드 만들기, 인터랙션 구현, 스크립트 만들기, 성능 최적화입니다. 템플릿은 CREATE 프레임워크를 따르므로, `{}` 안의 내용만 바꿔 바로 사용할 수 있습니다.

다음에 AI에게 게임 요구사항을 설명할 때는 JSON 형식으로 노드 트리를 설명하고, 5요소 공식으로 인터랙션 로직을 설명해 보세요. 전후 결과를 비교해 보면 차이가 분명합니다. 모호한 설명은 조각난 코드, 뒤섞인 계층, 빠진 인터랙션을 낳습니다. 표준화된 설명은 구조가 완전하고, 계층이 명확하며, 인터랙션이 닫힌 코드를 만듭니다. 효율 향상은 실제로 체감됩니다.