Godot Neural Network Framework

Doodle Recognition Demo

소개

이 프로젝트는 순수 GDScript와 GLSL compute shaders만을 사용하여 Godot Engine에서 완전히 독립적으로 구축된 머신러닝 프레임워크입니다. 외부 의존성, Python 바인딩 또는 클라우드 런타임에 의존하지 않고도, 대화형 애플리케이션 내부에서 완전 가속 트레이닝 및 추론이 가능한 경량적이면서도 강력한 신경망 툴킷을 필요로 하는 연구원, 학생 및 개발자를 위해 설계되었습니다.

아키텍처는 순전파(forward pass)와 역전파(backward pass)를 위한 GPU 최적화 파이프라인과 하이브리드 워크로드를 위한 CPU 접근 가능 레이어를 결합하며, 최대 성능과 이식성을 활용하기 위해 저수준 SPIR-V 셰이더를 활용합니다. 이를 통해 신경망을 실시간 시뮬레이션, 게임 및 크리에이티브 도구에 원활하게 통합할 수 있으며, Godot 생태계 내에서 재현성과 결정론적 동작을 유지합니다.

별도의 설정 없이도 프레임워크는 다음 기능을 제공합니다:

• 사용자 정의 가능한 신경망 아키텍처 (밀집 레이어(dense layers), 활성화 함수(activations), 스케줄러(schedulers)).
• 이미지, 수치 데이터 및 절차적 입력을 위한 실시간 데이터셋 처리.
• 트레이닝 시각화 및 실시간 성능 지표.
• 높은 정확도와 서브초 추론 시간을 갖춘 숫자 및 낙서 분류를 포함한 대화형 데모.

신속한 프로토타이핑, 교육 목적 또는 ML을 상용 수준의 대화형 소프트웨어에 임베딩하는 용도로 사용되든, 이 프레임워크는 외부 ML 라이브러리 없이 네이티브 Godot에서 신경 계산이 얼마나 멀리 확장될 수 있는지 보여줍니다.

기능

• 네이티브 신경망 엔진(Native Neural Network Engine) — Godot 내에서 GDScript와 GLSL compute shaders만을 사용하여 완전히 구축되었으며, 외부 의존성 없이 독립적인 ML 런타임을 제공합니다. 모든 핵심 모듈(레이어, 활성화 함수, 손실 함수, 데이터셋 처리, 직렬화)은 게임, 시뮬레이션 및 교육 도구에 원활하게 통합되도록 최적화되었습니다.
• GPU 가속 추론 및 학습(GPU‑Accelerated Inference & Training) — 순전파(Forward pass)와 역전파(Backward pass)는 SPIR‑V 레벨의 compute shaders를 사용하여 GPU에서 병렬 처리되며, 초단위 추론 시간과 훨씬 빠른 학습 주기를 가능하게 합니다. 배치 처리(Batching) 및 메모리 접근 패턴은 CPU와 GPU 간 데이터 전송 오버헤드를 최소화하도록 조정되었습니다.
• 유연한 활성화 함수(Flexible Activation Functions) — Sigmoid, Tanh, ReLU, Leaky ReLU, Softmax 코어를 포함하며, 모두 속도와 안정성을 위해 셰이더 레벨 최적화로 구현되었습니다. 모듈식 셰이더 API를 통해 사용자 정의 활성화 함수를 쉽게 통합할 수 있어 새로운 아키텍처 실험을 가능하게 합니다.
• 종합적인 정규화(Comprehensive Regularization) — L2 가중치 감쇠(weight decay), 셰이더 레벨의 확률적 드롭아웃(stochastic dropout), 조정 가능한 학습률 스케줄(step decay, exponential decay, warm‑up phases)을 포함하여 과적합을 방지하고 일반화 성능을 향상시키는 강력한 도구를 제공합니다.
• 다용도 손실 함수(Versatile Loss Functions) — 평균 제곱 오차(Mean Squared Error, MSE), 이진 교차 엔트로피(Binary Cross‑Entropy), 범주형 교차 엔트로피(Categorical Cross‑Entropy, CCE)의 최적화된 구현을 제공하며, 대규모 데이터셋 처리를 위해 배치 GPU 평가를 지원합니다.
• 안정성을 위한 기울기 클리핑(Gradient Clipping for Stability) — 통합된 클리핑 메커니즘은 역전파 중에도 기울기가 안전한 범위 내에 머물도록 보장하여, 깊거나 높은 학습률의 모델에서 발생할 수 있는 발산 위험을 줄입니다.
• 내장 데모 스위트(Built‑In Demo Suite) — 실제 작업을 시연하는 즉시 실행 가능한 Godot 씬을 포함합니다. 여기에는 9k 이미지에 대한 숫자 분류를 통해 97%의 정확도를 달성한 예제, 9가지 범주에 걸친 낙서 인식, 실시간으로 계산된 신뢰도 점수를 갖는 라이브 예측 디스플레이 등이 포함됩니다.

아키텍처 개요

프레임워크는 모듈식 레이어와 실행 파이프라인으로 구성되어 있어 데이터 처리(data handling), 모델 정의(model definition), 그리고 연산 실행(compute execution) 간의 명확한 분리를 가능하게 합니다. 이러한 설계 덕분에 각 컴포넌트는 시스템의 다른 부분에 영향을 주지 않으면서 확장하거나 교체할 수 있습니다.

핵심 컴포넌트 (Core Components)

• 데이터 레이어 (/scripts/neural_network/data) — 학습 및 추론을 위해 데이터셋을 가져오고(Imports), 전처리하며, 배치화합니다. 이미지, 수치 데이터, 절차적 입력(procedural inputs)을 처리합니다.
• CPU 레이어 (/scripts/neural_network/core) — 폴백(fallback) 또는 하이브리드 실행 모드를 위해 순수 GDScript로 신경 연산 및 유틸리티 로직을 구현합니다.
• GPU 레이어 (/scripts/neural_network/gpu) — 셰이더 로딩, SPIR‑V 파이프라인, 그리고 컴퓨트 커널(compute kernels)을 관리합니다. 최적화된 병렬성을 통해 순전파(forward pass)와 역전파(backward pass)를 실행합니다.
• 학습 엔진 (Training Engine) (/scripts/neural_network/training) — 학습 루프, 손실 계산(loss calculations), 정규화(regularization), 기울기 클리핑(gradient clipping), 그리고 학습률 스케줄(learning‑rate schedules)을 조정합니다.
• 직렬화기 (Serializer) (/scripts/neural_network/serializer) — 재현 가능한 설정 상태를 가진 훈련된 모델을 저장하고 불러옵니다.
• 시각화 (Visuals) (/scripts/visuals) — 에포크별 손실 그래프(Loss over Epoch graph), 성능 모니터, 그리고 모델 학습 피드백을 위한 UI 컴포넌트와 같은 대화형 및 실시간 시각화 도구를 제공합니다.
• 예제 및 데모 (Examples & Demos) (/examples) — 훈련 워크플로우, 추론(inference), 그리고 시각화 도구가 작동하는 모습을 보여주는 즉시 실행 가능한 Godot 씬을 제공합니다.

데이터 흐름 (Data Flow)

1. 데이터 로드 및 전처리 → 데이터셋 관리자가 배치를 준비합니다.
2. 순전파 (Forward Pass) → 입력이 CPU 폴백 또는 GPU 최적화 컴퓨트 셰이더를 통해 흐릅니다.
3. 손실 계산 (Loss Calculation) → 출력값이 GPU 최적화 손실 함수(loss functions)를 사용하여 목표 레이블과 비교됩니다.
4. 역전파 (Backward Pass) → 기울기(Gradients)가 GPU에서 계산되며, 안정성을 위해 선택적으로 클리핑됩니다.
5. 가중치 업데이트 (Weight Updates) → 정규화가 적용되고 학습률 스케줄이 조정됩니다.

설치 (Installation)

이 프레임워크는 Godot Engine을 위한 완전 독립적인 ML 모듈로, 외부 종속성이 필요 없습니다. 실험용 별도 작업 공간으로 사용하거나 자체 게임/애플리케이션에 직접 임베드할 수 있습니다.

필수 조건 (Prerequisites)

• Godot Engine 4.x 이상 (컴퓨트 셰이더 지원을 위해 Vulkan 필요)
• Vulkan 호환 드라이버가 있는 GPU
• 선택 사항: 네트워크 또는 러너를 확장하기 위한 GDScript 및 GLSL에 대한 숙련도

빠른 설치 (Quick Install)

1. 저장소 복제 (Clone the Repository)

   git clone https://github.com/SinaMajdieh/godot-neural-network.git

2. Godot에서 열기 (Open in Godot)

• Godot을 실행합니다.
• '프로젝트 가져오기(Import Project)'를 클릭합니다.
• 복제된 저장소로 이동하여 project.godot을 선택합니다.

3. GPU 호환성 확인 (Verify GPU Compatibility)

• GPU가 Vulkan 및 컴퓨트 셰이더를 지원하는지 확인합니다.
• Godot에서 '프로젝트 설정(Project Settings)' → '렌더링(Rendering)' → '품질(Quality)' → '컴퓨트 셰이더 활성화(Compute Shaders Enabled)'를 확인합니다.

4. 데모 장면 실행 (Run a Demo Scene)

• 파일 시스템 독(FileSystem dock)에서 /examples/classifier/digit_classier.tscn 또는 다른 데모를 엽니다.
• '재생(Play)'을 눌러 프레임워크가 올바르게 실행되는지 확인합니다.

기존 프로젝트에 임베드하기 (Embedding in an Existing Project)

1. /scripts/neural_network를 프로젝트 디렉토리로 복사합니다.
2. 필요한 경우 스크립트 내 리소스 경로를 조정합니다.
3. 스크립트에서 직접 네트워크와 트레이너 생성을 시작합니다.

사용법 (Usage)

이 프레임워크는 빠른 프로토타이핑과 쉬운 통합을 위해 구축되었습니다. GDScript만으로 네트워크 생성, GPU 러너 설정, 모델 훈련, 학습 시각화, 그리고 내보내기/가져오기를 모두 수행할 수 있습니다.

예시: 네트워크 생성 (Example: Creating a network)

# --- GPU 러너 생성 ---
var forward_runner: ForwardPassRunner = ForwardPassRunner.new()

...

예시: 네트워크 훈련 (Example: Training a Network)

# --- GPU 러너 생성 ---
var backward_runner: BackwardPassRunner = BackwardPassRunner.new()

...

예시: 모델 내보내기 (Example: Exporting a Model)

# 훈련된 네트워크를 디스크에 저장합니다.
NeuralNetworkSerializer.export(network, export_path)

예시: 저장된 모델 가져오기 (Example: Importing a Saved Model)

# 추론을 위한 순방향 실행기(forward runner) 생성
var forward_runner: ForwardPassRunner = ForwardPassRunner.new()

...

예시: 씬에 LossGraphPanel 추가하기

# 에포크별 손실(Loss over Epoch) 시각화 패널을 즉시 생성하고 연결합니다.
var loss_panel: EpochMetricGraphPanel = EpochMetricGraphPanel.new_panel(
	"Training Loss",   # 패널 제목
...

이것이 중요한 이유 (Why This Matters)

• 설계상 모듈성(Modular by Design) — 필요한 구성 요소만 사용합니다 (데이터셋, GPU 실행기, 훈련 로직).
• 임베딩 친화적(Embedding-Friendly) — 네트워크, 트레이너, 직렬화기가 모든 Godot 스크립트에서 작동합니다.
• 프로덕션 준비 완료(Production-Ready) — 학습된 모델을 내보내고 재훈련 없이 런타임 환경에서 로드할 수 있습니다.
• 실시간 처리 가능(Real-Time Capable) — 순방향 패스는 GPU 가속되며 인터랙티브 애플리케이션에 최적화되어 있습니다.

데모 쇼케이스 (Demo Showcase)

아래는 /examples 폴더에 포함된 세 가지 예시 데모입니다.
GIF는 Godot 내부에서 실시간 성능을 시연하며, GPU 가속 순방향 패스와 인터랙티브 도구로 작동합니다.

숫자 인식 데모 (Digit Recognition Demo)

9,000개의 숫자 이미지(0–9)를 사용하여 신경망을 훈련시키고, 범주형 교차 엔트로피 손실(Categorical Cross-Entropy loss)과 Tanh 활성화 함수를 사용하여 약 97%의 테스트 정확도를 달성합니다.
GIF 미리보기:

낙서 인식 데모 (Doodle Recognition Demo)

9,000개의 이미지에 걸쳐 9가지 낙서 카테고리(예: 등대, 기타, 고양이)로 훈련하여, 다양한 데이터셋과 입력 유형을 다루는 프레임워크의 유연성을 보여줍니다.
GIF 미리보기:

에포크별 손실 시각화 도구 (Loss over Epoch Visualization Tool)

에포크별 훈련 손실의 실시간 인터랙티브 그래프를 제공하며, 부드러운 보간(interpolation), 정확한 손실 값을 보여주는 호버 툴팁, 테마 기반 스타일링 기능을 갖추고 있습니다.
훈련 중 수렴 안정성을 시각적으로 모니터링하는 데 도움이 됩니다.
GIF 미리보기:

나선형 이진 분류 데모 (Spiral Two-Class Classification Demo)

두 개의 교차하는 클래스를 가진 **합성 나선형 데이터셋(synthetic spiral dataset)**을 생성하고, 점들을 분류하기 위해 완전 연결 신경망(fully-connected neural network)을 훈련하며, 학습된 **결정 경계(decision boundary)**를 플롯에 직접 시각화하면서 훈련합니다. 비선형 분리 능력과 실시간 GPU 가속 렌더링을 보여줍니다. GIF 미리보기:

동기 (Motivation)

머신러닝 프레임워크는 풍부하지만, 거의 모두 무거운 외부 종속성(heavy external dependencies), Python 바인딩 또는 별도의 런타임 환경이 필요합니다. Godot과 같은 게임 엔진의 실시간 애플리케이션에서는 이것이 마찰을 일으킵니다: 추가적인 툴체인, 제한된 인-엔진 GPU 가속화, 그리고 라이브 상호작용 기회가 적습니다.

이 프로젝트는 개인적인 도전으로 시작되었습니다: 신경망이 핵심적으로 어떻게 작동하는지 실험하고 이해하며, 처음부터 강력한 무언가를 구축하기 위해서입니다. 이는 도구를 만들고, 문제를 테스트하고 수정하며, 기술적 한계를 밀어붙이는 것에 대한 열정을 반영하며—학습과 헌신을 통해 한 사람이 무엇을 성취할 수 있는지 보여줍니다.

또한 신경망이 외부 종속성 없이 원활하게, 네이티브하게, 실시간으로 실행될 수 있는 곳, 즉 라이브 시뮬레이션, 훈련 데모 및 대화형 AI 경험을 위한 **게임 엔진의 활용되지 않은 잠재력(untapped potential)**에 대한 증거로도 자리매김합니다.

비전 (Vision)

저는 Godot에서 머신러닝이 다른 내장 시스템을 사용하는 것만큼 자연스럽고 접근하기 쉬워지기를 목표로 합니다:

• 통합 워크플로우(Unified Workflow) — Godot 씬 내부에서 네트워크를 구축, 훈련 및 배포합니다.
• 실시간 AI(Real-Time AI) — 게임플레이, VR, 교육 및 시뮬레이션을 위한 즉각적인 추론을 제공하는 GPU 컴퓨트 셰이더(GPU compute shaders).
• 모듈식 확장성(Modular Extensibility) — 사용자 정의 레이어, 활성화 함수(activations), 손실 지표(loss metrics) 및 스케줄러를 쉽게 추가할 수 있습니다.
• 교육적 접근성(Educational Accessibility) — 빠른 학습을 위한 명확한 데모, 시각화 및 이해하기 쉬운 코드.
• 개방 혁신(Open Innovation) — 가볍고, 오픈 소스이며, 커뮤니티 주도 방식입니다.

향후 목표에는 다음이 포함됩니다:

• 고급 아키텍처 지원 (CNNs, RNNs, attention/transformers).
• 디버깅 및 이해를 위한 확장된 시각화 도구.
• 창의적이고 합성 데이터를 위한 데이터셋 생성 유틸리티.
• 게임 및 시뮬레이션에서 인터랙티브하고 GPU 구동되는 AI의 전체 성능을 보여줌.

기술 스택 (Tech Stack)

이 프레임워크는 Godot Engine 생태계 내부에만 완전히 구축되었으며, 네이티브 스크립팅 및 셰이더 기술만을 사용합니다. 외부 종속성이 전혀 없어(no external dependencies) 이식성이 뛰어나고 가벼우며 모든 Godot 프로젝트에 쉽게 임베드할 수 있습니다.

핵심 기술 (Core Technologies)

• Godot Engine 4.x — 게임 엔진 플랫폼 및 런타임 환경.
• GDScript — 네트워크 로직, 데이터 처리 및 오케스트레이션의 주요 언어.
• GLSL Compute Shaders — 순전파/역전파 신경망 패스를 위한 GPU 가속화.
• SPIR‑V — 최적화된 GPU 워크로드를 위한 저수준 셰이더 중간 표현(intermediate representation).
• Godot 리소스 시스템 (Godot Resource System) — 데이터셋, 모델 직렬화 및 설정 저장에 사용됨.

ML 컴포넌트