AI 어시스턴트

MCP 지원 AI 클라이언트는 사용자가 지켜보는 동안 에디터에 열린 레벨을 편집할 수 있습니다. AI 작업 묶음 하나는 실행 취소 한 단계이며, AI 쪽에서는 게시, 파일 삭제, 다른 레벨 덮어쓰기를 할 수 없습니다

Windows, Linux, Mac용 게임에는 이를 위한 MCP 서버가 들어 있습니다. AI 어시스턴트는 사용자와 같은 작업을 통해 편집하므로, 모든 변경이 뷰포트에 즉시 나타나고 직접 한 편집처럼 기록에 남습니다

MCP 지원 클라이언트라면 무엇이든 됩니다. 예를 들어 채팅 앱이나 코딩 어시스턴트. 게임의 어떤 부분도 특정 AI에 묶여 있지 않습니다

클라이언트 연결

1. 설정 → 에디터 → AI 에이전트(MCP) 항목을 엽니다
2. AI 연결 허용에 체크합니다. 설정 아래 상태 줄에 에디터가 수신 대기하는 포트가 표시됩니다
3. 클라이언트 설정 복사 버튼을 누릅니다. 이제 클립보드에 두 경로가 채워진 클라이언트 설정이 들어 있습니다
4. 클라이언트의 MCP 서버 설정에 붙여넣습니다
5. 에디터에서 레벨을 열거나, AI에게 에디터나 레벨을 직접 열어 달라고 요청합니다

복사된 설정은 다음과 같습니다:

{ "mcpServers": { "bullet-hero": { "command": "<path to BH.MCP>", "args": ["--endpoint", "<path to endpoint.json>"] } } }

BH.MCP 서버 파일은 게임 옆에 있습니다:

이 컴퓨터만 연결할 수 있으며, 한 번에 클라이언트 하나만 연결됩니다. 휴대폰과 태블릿에는 MCP 섹션이 없습니다: 어시스턴트는 데스크톱 전용입니다

게임 사본 여러 개를 동시에 실행할 수 있습니다. 전환을 요청할 때까지 AI 어시스턴트는 가장 마지막에 시작한 사본에서 작업하며, 모든 사본을 나열할 수도 있습니다. 각 사본은 여전히 클라이언트 하나만 받습니다. 사본이 여러 개라면 포트 값을 0 그대로 두십시오. 두 사본이 한 포트에서 수신 대기할 수는 없기 때문입니다

AI 어시스턴트가 할 수 있는 것과 할 수 없는 것

AI 어시스턴트는 사용자가 할 수 있는 거의 모든 것을 할 수 있습니다:

• 레벨 읽기: 계층 구조, 오브젝트, 키프레임, 이벤트, 리소스
• 오브젝트, 키프레임, 마커, 체크포인트, 오디오 트랙, 비트 그리드의 생성, 변경, 삭제
• 생성기 실행, 프리팹 묶기와 배치, 프리팹 모드 안에서 작업
• 텍스처, 폰트, 오디오 파일을 레벨로 가져오기
• 텍스처, 폰트, 오디오 파일을 가져온 뒤 저작자 표시 기록 채우기: 제목, 설명, 링크, 출처, 제작자 - 리소스 기록
• 게임 자체의 프리셋 테마, 폰트, 인터페이스 사운드 사용. resources_list 결과에서 이것들은 게임의 것으로 표시되며, 가져올 필요가 없습니다. 게임에는 프리셋 이펙트가 없습니다: AI 어시스턴트가 배치하는 이펙트는 레벨에 이미 있는 것이거나 새로 만든 것입니다
• 꼭짓점으로 어떤 윤곽이든 레벨 도형으로 그리기, 도형에 그레이디언트로 색 입히기, 텍스트의 폰트와 정렬 설정, 레벨 테마 생성과 편집
• 실행 취소와 다시 실행, 열린 레벨 저장, 다른 레벨 열기, 새 레벨 만들기
• 재생 버튼처럼 재생 시작과 일시 정지
• 실행할 때와 같은 인수로 게임을 다른 화면(에디터, 레벨, 설정 등)으로 이동 - 실행 인수
• 게임이 실행 중이 아닐 때 게임 시작. 서버가 설치된 게임 옆에 있고 MCP 기능이 이미 켜져 있는 경우

이렇게 시작한 플레이는 다른 플레이와 똑같이 통계에 집계되므로, AI 어시스턴트는 요청받았을 때만 플레이를 시작합니다

할 수 없는 것:

• Steam 창작마당에 게시
• 레벨이나 파일 삭제
• 다른 레벨이나 다른 파일 덮어쓰기. 파일 이름이 이미 사용 중인 가져오기는 거부됩니다
• 읽기 전용 레벨, 또는 이번 세션에서 비밀번호를 입력하지 않은 보호된 레벨 열기
• 열린 레벨에 저장되지 않은 변경이 있는 동안 다른 레벨 열기

AI 작업 묶음 하나는 기록의 한 단계입니다. 기록 탭에는 AI 일괄 작업 항목으로, AI 어시스턴트가 붙인 설명과 함께 표시됩니다. Ctrl+Z 키 한 번이면 묶음 전체가 제거됩니다. 기록에 대해 자세히 - 레벨 설정 › 기록

AI는 동시에 재생되는 두 오브젝트를 같은 레이어에 두지 않습니다. 배치가 그렇게 될 경우, 같은 단계 안에서 나중 오브젝트를 다음 빈 레이어로 올리고 그 사실을 알립니다. 예외는 프리팹의 내용으로, 레벨의 나머지 부분과 레이어를 공유할 수 있습니다

레벨을 바꾸는 첫 AI 작업 묶음은 같은 단계 안에서 레벨의 AI 생성 항목을 AI 생성 값으로 설정합니다. 묶음을 실행 취소하면 이 값도 되돌아갑니다. 자세히 - 메타데이터와 레벨 공유 › AI 생성

사용자가 우선입니다

AI 어시스턴트는 에디터를 두고 사용자와 다투지 않습니다:

• 기즈모 핸들을 드래그하거나 타임라인을 스크럽하는 동안에는 AI 편집이 거부되며, AI 어시스턴트는 기다렸다가 다시 시도합니다
• AI 어시스턴트는 사용자가 아무것도 하지 않을 때만 재생 헤드를 가져갑니다: 재생, 드래그, 입력, 저장 중이 아닐 때
• 에디터는 레벨을 열면 재생을 시작하므로, AI 어시스턴트가 프레임을 보려고 일시 정지할 수 있습니다. AI 어시스턴트가 직접 열거나 만든 레벨은 일시 정지 상태로 유지됩니다. 일부러 재생을 보고 있다면 AI 어시스턴트는 일시 정지 전에 묻습니다
• AI 어시스턴트가 프레임을 보는 동안 에디터를 건드리면 AI 어시스턴트는 즉시 멈춥니다. 재생 헤드는 사용자가 둔 곳에 머뭅니다
• 기록 탐색이 진행되는 동안에도 AI 어시스턴트는 편집할 수 없습니다

클라이언트가 연결되어 있는 동안 뷰포트 오른쪽 위 모서리, 검색 버튼 아래에 AI 배지가 나타납니다. 색이 상태를 나타냅니다: 초록 - 연결됨, 주황 - AI 어시스턴트가 작업 중, 빨강 - AI의 마지막 호출이 오류로 끝남. 클라이언트 연결이 끊긴 뒤에도 배지는 30초 동안 남으므로, 단계마다 다시 연결하는 AI 어시스턴트라도 깜빡이지 않습니다. 배지는 뷰포트 도구와 함께 숨겨집니다. 마우스를 올리면 상태를 글로 읽을 수 있습니다: AI 연결됨, 그리고 AI 어시스턴트가 작업하는 동안에는 지금 하는 작업의 설명. 옆의 X 표시는 클라이언트 연결을 끊고 거부하며, 배지가 사라집니다

중지는 저장되지 않습니다. AI 연결 허용 설정을 껐다 켜거나 게임을 다시 시작하면 해제됩니다

AI 어시스턴트가 보는 것

AI 어시스턴트는 레벨을 두 가지 방법으로 봅니다:

• 도식. 어떤 프레임이든 화면 밖에서 계산한 그림입니다. 재생 헤드를 움직이지 않습니다. 도형과 히트박스는 보여 주지만 텍스트와 이펙트는 없습니다
• 캡처. 레벨이 그리는 그대로의 실제 픽셀이며, 재생 헤드를 통해 찍습니다. 잠시 재생 헤드가 그 프레임으로 이동하고 에디터 오버레이가 숨겨집니다. 그다음 재생 헤드 AI 추적 설정이 켜져 있지 않다면 재생 헤드는 원래 자리로 돌아갑니다. 그림은 에디터 카메라가 아니라 레벨 카메라 기준으로 잡힙니다. 세부를 가까이 보려면 AI 어시스턴트는 대신 월드의 직사각형 영역을 잡을 수 있습니다. 레벨은 바뀌지 않습니다

점프 후 이펙트의 정지 화면은 연속 재생에서 보이는 것과 비슷하지만, 항상 같지는 않습니다

AI 어시스턴트는 음악을 들을 수 없습니다. 트랙을 숫자로 바꿉니다: 템포, 비트, 마디, 섹션, 각 대역의 음량. 이것은 신뢰도가 붙은 추정이며, 틀릴 수 있습니다. 예를 들어 템포가 절반이나 두 배로 잡힐 수 있습니다. 레벨에 설정한 비트 그리드가 AI의 추정보다 우선합니다. AI 어시스턴트가 분석에서 제안하는 비트 그리드는 정수와 0.01 % 이내로 차이 나는 템포를 그 정수로 반올림하며, 오프셋은 항상 한 마디보다 짧습니다. 트랙 일부에 대한 제안은 그 부분의 템포를 쓰므로, 템포가 바뀌는 트랙은 템포마다 세그먼트 하나를 받습니다

그래서 타이밍이 중요할 때 AI 어시스턴트가 직접 들어 보라고 요청할 수 있습니다. 에디터에서 최대 45초 범위를 재생하며, 이때 재생 헤드도 움직입니다. 에디터를 건드리면 재생은 그 자리에서 멈춥니다

에디터 사운드가 음소거된 동안에는 AI 어시스턴트가 아무것도 재생하지 않고 사운드를 켜 달라고 요청합니다

AI 어시스턴트 자신의 동작은 인터페이스 사운드를 내지 않습니다: AI 쪽에서 일으킨 실행 취소, 저장, 거부는 소리가 없습니다. 의도적으로 재생하는 것만 들립니다

ai 폴더

AI 어시스턴트는 레벨에 대한 기억을 레벨 폴더 안의 ai 폴더에 보관합니다. 다음 세션은 어떤 클라이언트든 이 폴더를 먼저 읽고, 지난 세션이 멈춘 곳에서 이어 갑니다

들어 있는 것:

• CONTEXT.md - 브리프, 음악, 섹션 계획, 결정 사항, 사용자의 의견, 열린 질문
• AI 어시스턴트가 보관하기로 한 다른 파일. .md 또는 .json 파일만
• manifest.json - 폴더가 레벨과 함께 이동하는지 여부. AI 어시스턴트는 이 파일을 바꿀 수 없습니다

폴더는 AI 어시스턴트가 처음으로 쓸 내용이 생길 때 나타납니다. 파일 하나는 최대 256 KB, 폴더 전체는 최대 1 MB입니다. 일반 텍스트 파일이므로 직접 읽고, 편집하고, 삭제할 수 있습니다

폴더는 기본적으로 레벨과 함께 이동합니다: 내보낸 아카이브와 Steam 창작마당 업로드에서. 폴더를 이 기기에만 두려면 레벨 설정의 메타데이터 탭에서 이 레벨과 함께 AI 컨텍스트 공유 체크를 해제하십시오. 체크박스는 폴더가 생긴 뒤에 나타납니다. 바로 파일에 저장되므로 Ctrl+Z 키로도 되돌릴 수 없습니다

비밀번호가 있는 내보내기 모드는 체크박스와 상관없이 폴더를 절대 포함하지 않습니다. 자세히 - 내보내기와 보호 › 레벨 내보내기

이 기기에서 만든 레벨 사본은 폴더도 함께 가져갑니다. 사본은 공유가 아니기 때문입니다

설정

모두 설정 → 에디터 → AI 에이전트(MCP)에 있으며, 이 기기에만 저장됩니다:

• AI 연결 허용 - 클라이언트가 연결할 수 있는지 여부. 기본으로 꺼져 있습니다
• 포트 - 에디터가 수신 대기하는 포트. 0 값이면 시작할 때마다 빈 포트를 고릅니다
• 재생 헤드 AI 추적 - 켜면: 캡처 후 재생 헤드가 AI 어시스턴트가 본 프레임에 일시 정지 상태로 머뭅니다
• AI 편집 표시 - AI 편집이 끝날 때마다 만들거나 바꾼 것을 선택하고 위치를 표시합니다
• AI 작업 지연, 초 - 두 AI 작업 사이에 에디터가 기다리는 시간. 사용자가 따라갈 수 있게 해 줍니다. 0 값이면 각 작업을 즉시 적용합니다

모든 설정과 기본값 - 에디터 설정 › AI 에이전트

다음: 작업을 잃지 않기, 내보내기와 보호