spardanviro/Godot_AI

Godot 에디터 내부에서 네이티브 ai_assistant 모듈로서 작동하는 AI 어시스턴트 지원 기능을 제공하며, Godot 4.7+ (godot-master)와 호환됩니다.

이 프로젝트는 에디터에 도킹 가능한 AI 패널을 추가하고, 여러 LLM (Large Language Model) 제공업체를 지원하며, EditorScript 워크플로우를 통해 AI가 생성한 에디터 액션(action)을 실행할 수 있습니다. 이는 Godot 내부에서 직접적인 씬(scene) 편집, 스크립트 생성, 프로젝트 설정, 파일 인지 프롬프팅 (file-aware prompting), 에셋 생성 및 디버깅 지원을 위해 구축되었습니다.

ai_assistant는 네이티브 C++ Godot 모듈입니다. 이는 GDExtension이 아니며 프로젝트 파일로 배포되는 일반적인 애드온(addon)도 아닙니다. Godot 엔진 소스 트리 아래에 위치하며 에디터 빌드에 컴파일되어 포함되도록 설계되었습니다.

모듈이 활성화되면 다음 항목들을 등록합니다:

• 에디터 플러그인으로서의 AIAssistantPlugin
• 메인 도크(dock) UI로서의 AIAssistantPanel
• Anthropic, OpenAI 호환 API, Gemini, DeepSeek 및 GLM을 위한 제공업체 통합
• 응답 파싱, 스크립트 실행, 컨텍스트 수집, 권한, 체크포인트, 오류 모니터링, 웹 검색, 에셋 생성 및 멘션 인지 입력(mention-aware input)을 위한 헬퍼 시스템
• 온디맨드(On-demand) API 문서 및 주의사항(gotchas) 주입 (관련 없는 주제에 대한 정적 오버헤드 제로)

패널은 에디터의 오른쪽 도크 영역에 장착됩니다.

• Godot 에디터 내부의 도킹된 AI 패널
• 지속적인 대화 기록을 포함한 채팅 스타일 상호작용 UI
• New, History, Settings, 파일 첨부, 멘션, 전송 및 중지 제어
• 부분 취소를 위한 Stop 버튼이 있는 스트리밍 응답
• 자동 크기 조절 멀티라인 입력 필드
• 고빈도 프리셋 액션 (preset actions):
  • Fix Errors (오류 수정)
  • Performance (성능)
  • ASK: 코드 실행이 없는 대화 모드
  • AGENT: 실행 흐름이 있는 액션 중심 모드
  • PLAN: 실행 전 계획 우선 모드
• 입력창에 @를 입력하여 씬 노드(scene-node) 자동 완성 실행
• 씬 노드를 입력 필드로 드래그하여 멘션 칩(mention chips) 삽입
• @ 사용

현재 선택된 씬을 멘션하기 위한 툴바 버튼 - 멘션 칩(Mention chips)은 인라인으로 렌더링되며, 요청이 전송되기 전에 구조화된 노드 컨텍스트(node context)로 확장됩니다.

• 멘션 플레이스홀더(Mention placeholders)는 원자적 단일 문자 토큰이므로, 백스페이스로 깔끔하게 삭제할 수 있습니다.

• 에디터 파일 피커(file picker)를 통해 다음 요청에 사용할 프로젝트 파일을 첨부합니다.

• 첨부된 파일 내용은 명시적인 컨텍스트(context)로서 전송되는 프롬프트에 추가됩니다.

• 지원되는 첨부 파일 필터:

• Markdown / 다이어그램 (diagram):
  *.md
  , *.mmd
  , *.mermaid

• 텍스트 / 데이터 (data):
  *.txt
  , *.json
  , *.yaml
  , *.yml
  , *.toml
  , *.csv

• GDScript:
  *.gd
  , *.gdscript

• Markdown / 다이어그램 (diagram):

• Anthropic (Claude)

• OpenAI

• Gemini

• DeepSeek

• GLM (Zhipu AI)

OpenAI 프로바이더(provider) 경로는 엔드포인트(endpoint) 설정을 통해 호환 가능한 커스텀 엔드포인트로 지정할 수도 있습니다.

설정 대화 상자(settings dialog)는 프로바이더 API로부터 모델 목록을 자동으로 가져오고(auto-fetch), 가져온 모델 중에서 선택할 수 있습니다. 프로바이더별로 별도의 API 키를 저장하며, 프로바이더를 변경할 때 자동으로 교체합니다.

시스템 프롬프트(system prompt)는 가볍게 유지됩니다. 모든 Godot API 문서를 정적으로 포함하는 대신, AIAPIDocLoader가 사용자의 메시지에서 언급된 Godot 클래스 이름(단어 경계 매칭)을 감지하여 해당 클래스에 대한 압축된 API 참조(API references)만을 주입합니다. CharacterBody3D, NavigationAgent3D, AnimationPlayer, RigidBody3D 등을 포함한 50개 이상의 자주 사용되는 클래스를 지원합니다.

401개의 Godot 특화 주의사항(gotchas) 및 함정(pitfalls)이 키워드 인덱스 테이블에 저장되어 있습니다. 요청 시점에 사용자의 메시지와 키워드가 일치하는 항목만 주입됩니다(약 3,000자 제한). 이는 관련성 여부와 관계없이 모든 요청에 주입되던 기존의 3,100라인 분량의 정적 섹션을 대체합니다.

요청당 토큰 절감 효과: 주의사항(gotcha) 관련 컨텍스트 오버헤드 약 90% 감소.

도메인 중심 요청(UI/Control 레이아웃, 물리(physics), 내비게이션(navigation), 셰이더(shaders) 등)을 위한 특화된 시스템 프롬프트 조각(fragments)이 기본 시스템 프롬프트와 함께 필요에 따라 주입됩니다.

• AI 응답을 파싱하고 실행 가능한 GDScript 블록을 추출합니다.

• 생성된 코드를 EditorScript로 래핑(wrap)합니다.

• 에디터 컨텍스트(editor context) 내에서 코드를 실행합니다.

• 실행 전 컴파일 전용 검증(compile-only validation)을 지원합니다.

• 실행 전 기본적인 위험 호출 차단 목록(dangerous-call blocklist)을 사용합니다.

• 민감한 작업에 대한 권한 확인(permission checks)을 통합합니다.

• ASK 모드에서는 코드 실행을 건너뜁니다. 스트리밍 응답이 수동으로 중단된 경우, 부분적인 코드는 히스토리에 보존되지만 실행되지는 않습니다.

차단된 API 패턴:

OS.execute

OS.shell_open

OS.kill

OS.create_process

.shell_execute

실행 권한은 카테고리별로 분류되며 작업 유형별로 설정 가능합니다:

• 노드 생성 (Create nodes)
• 노드 삭제 (Delete nodes)
• 속성 수정 (Modify properties)
• 스크립트 수정 (Modify scripts)
• 프로젝트 설정 변경 (Change project settings)
• 파일 쓰기 (Write files)
• 파일 삭제 (Delete files)

각 카테고리는 Allow(허용), Ask(확인), 또는 Deny(거부)를 지원합니다. 파일 삭제는 기본적으로 거부(deny)로 설정되어 있습니다.

어시스턴트는 다음을 통해 에디터 인지 컨텍스트(editor-aware context)를 구축할 수 있습니다:

• 현재 씬 트리 (current scene tree)
• 선택된 노드 (selected nodes)
• 프로젝트 구조 (project structure)
• 현재 열려 있는 스크립트 (currently open script)
• 인라인 씬-노드 언급 (inline scene-node mentions)
• 첨부된 파일 내용 (attached file contents)

대화가 길어져 토큰 사용량이 현재 모델의 컨텍스트 창(context window)을 초과할 정도로 커지면 긴 대화는 자동으로 요약됩니다. 구현 방식은 최근의 대화 내용은 온전하게 유지하고, 오래된 히스토리는 순환 요약(rolling summary) 방식으로 압축합니다.

• AI가 트리거한 실행 창(execution windows) 동안 발생하는 에디터/런타임 에러를 포착합니다.

• AI로 인한 실행 에러를 관련 없는 콘솔 노이즈와 분리합니다.

• 실패 내용을 어시스턴트에게 다시 전달하여 자동 재시도(automatic retry)를 수행합니다.

• 최대 3회의 자동 재시도를 지원합니다.

• 위험한 수정이 이루어지기 전에 씬 체크포인트(scene checkpoints)를 생성합니다.

• 여러 개의 최근 체크포인트를 저장합니다.

• 패널 UI를 통해 되돌리기(reverting)를 허용합니다.

• 채팅 세션을 user://ai_assistant_chats 경로 아래에 JSON 파일로 저장합니다.

• 저장된 채팅의 목록 보기, 불러오기 및 삭제를 지원합니다.

어시스턴트는 모듈에 의해 가로채지는(intercepted) 비코드 마커(non-code markers)를 지원합니다:

• OpenAI 이미지 API를 통한 이미지 생성
• OpenAI TTS API를 통한 오디오 생성

생성된 에셋은 res://ai_generated_image.png와 같은 프로젝트 경로에 저장됩니다.

및 res://ai_generated_audio.mp3

.

• DuckDuckGo HTML 검색 통합
• 직접 URL 가져오기 (Direct URL fetch) 지원
• 프롬프트 증강 (Prompt augmentation)을 위한 HTML-to-text 추출

UI 문자열은 영어와 중국어로 현지화되어 있습니다.

핵심 구성 요소:

파일	역할
ai_assistant_panel.*	메인 에디터 독 (Editor dock), 요청 흐름, 멘션 (Mentions), 첨부 파일, 히스토리, 스트리밍
ai_assistant_plugin.*	에디터 플러그인 진입점
ai_settings_dialog.*	프로바이더 (Provider) 및 동작 설정 UI
ai_mention_text_edit.*	인라인 칩 (Inline chips) 및 드래그 앤 드롭을 지원하는 멘션 가능 채팅 입력창
ai_mention_highlighter.*	멘션 칩을 렌더링하는 구문 강조기 (Syntax highlighter)
ai_provider.*	추상 프로바이더 인터페이스
ai_response_parser.*	모델 응답에서 텍스트 및 코드 블록 추출
ai_script_executor.*	생성된 GDScript를 에디터 컨텍스트에서 래핑 및 실행
ai_context_collector.*	씬 (Scene), 선택 항목, 스크립트 및 프로젝트 정보 수집
ai_error_monitor.*	AI 실행 관련 에디터/런타임 오류 추적
ai_checkpoint_manager.*	체크포인트 및 복구 지원
ai_permission_manager.*	규칙 기반 실행 게이팅 (Execution gating)
ai_web_search.*	검색 및 페이지 텍스트 추출
ai_image_generator.*	이미지 생성 도우미
ai_audio_generator.*	오디오 생성 도우미
ai_ui_agent.*	UI 특화 프롬프팅 도우미
ai_profiler_collector.*	성능 프롬프트를 위한 프로파일러 (Profiler) 데이터 수집
ai_system_prompt.*	기본 시스템 프롬프트 빌더 (~1150 라인, 경량)
ai_api_doc_loader.*	온디맨드 (On-demand) Godot API 레퍼런스 주입
ai_gotchas_index.*	온디맨드 Gotchas 주입 (401개 항목, 키워드 인덱스 방식)
ai_domain_prompts.*	도메인 특화 프롬프트 조각
ai_localization.h	UI 문자열 현지화 테이블

providers/ 디렉토리 내의 프로바이더 구현 사항

:

파일	프로바이더 (Provider)
anthropic_provider.*	Anthropic Claude
openai_provider.*	OpenAI (DeepSeek 호환 포함)
gemini_provider.*	Google Gemini
deepseek_provider.*	DeepSeek
glm_provider.*	Zhipu AI GLM

godot/modules/ai_assistant/

이 저장소는 모듈 디렉토리입니다. modules/ 디렉토리 아래에 직접 클론(Clone)하거나 복사하세요.

scons platform=windows target=editor

사용자의 환경에 맞춰 platform, arch 및 기타 SCons 플래그를 조정하세요. 이 모듈은 TOOLS_ENABLED에 의해 보호되며 에디터 빌드(editor builds)에만 컴파일됩니다.

컴파일 후, 빌드된 에디터 실행 파일을 사용하여 Godot을 실행하세요. AI 패널이 오른쪽 도크(dock)에 나타납니다.

설정은 EditorSettings 내의 ai_assistant/* 네임스페이스(namespace) 아래에 저장됩니다.

키 (Key)	설명
ai_assistant/provider	활성 프로바이더 (anthropic, openai, gemini, deepseek, glm)
ai_assistant/api_key_anthropic	Anthropic API 키
ai_assistant/api_key_openai	OpenAI API 키
ai_assistant/api_key_gemini	Gemini API 키
ai_assistant/api_key_deepseek	DeepSeek API 키
ai_assistant/api_key_glm	GLM API 키
ai_assistant/model	모델 이름
ai_assistant/api_endpoint	커스텀 엔드포인트 (Custom endpoint) 재정의
ai_assistant/max_tokens	최대 응답 토큰 (기본값: 4096)
ai_assistant/temperature	샘플링 온도 (Sampling temperature, 기본값: 0.7)
ai_assistant/send_on_enter	Enter 키로 전송 (기본값: true)
ai_assistant/autorun	생성된 코드 자동 실행 (기본값: true)
ai_assistant/language	UI 언어 (en 또는 zh)
ai_assistant/permissions/*	카테고리별 실행 권한

프로젝트별 지침을 정의하려면 프로젝트 내에 res://godot_ai.md 파일을 생성하세요. 어시스턴트가 이 파일을 로드하여 시스템 프롬프트(system prompt)에 자동으로 추가합니다.

• AI 패널에서 설정(settings) 대화 상자를 엽니다.
• 제공자(provider)를 선택하고 API 키를 입력합니다.
• 선택 사항으로 엔드포인트(endpoint)와 모델(model)을 재정의(override)할 수 있습니다.
• Enter 키를 눌렀을 때 즉시 전송할지 여부와 생성된 코드를 자동으로 실행할지 여부를 선택합니다.
• 민감한 작업에 대한 권한 수준(permission levels)을 구성합니다.
• ASK, AGENT, 또는 PLAN 모드에서 패널 사용을 시작합니다. - 다음과 같은 방법으로 다음 요청을 선택적으로 풍부하게 만들 수 있습니다:
• + 버튼으로 파일 첨부
• @를 사용하여 씬 노드(scene nodes) 언급
• 입력 필드에 씬 노드(scene nodes)를 드래그 앤 드롭
• 파일을 첨부하여

ai_assistant/
|- providers/
| |- anthropic_provider.*
...

• 모든 LLM 제공자에 대해 사용자가 제공한 API 키가 필요합니다.
• 웹 검색은 HTML 스크래핑(scraping)을 통해 구현되었습니다; 제공자 페이지는 유지보수가 필요할 수 있습니다.
• 에셋 생성(Asset generation)은 현재 OpenAI 전용 엔드포인트를 사용합니다.
• 아직 자동화된 CI 또는 크로스 플랫폼 패키징 워크플로우는 지원되지 않습니다.

Apache License 2.0에 따라 라이선스가 부여됩니다. LICENSE를 참조하세요.

이는 이 리포지토리(repository)의 코드에 적용됩니다. Godot 엔진 업스트림(upstream)은 MIT 라이선스를 따릅니다.