# 비전
다중 입력 소스를 지원하는 실시간 상호작용형 AI 엔진입니다.
실시간으로 다양한 입력(사용자 입력, 환경 변화, 다른 AI의 출력 등)을 처리하고,
시각/청각/물리적 피드백을 생성할 수 있는 통합 AI 엔진을 목표로 합니다.
## 장기 목표
- **다중 입력 처리**
- 사용자 직접 입력 (키보드, 마우스, 터치 등)
- 환경 센서 입력 (카메라, 마이크, 가속도계 등)
- AI 모델 출력의 재입력
- **다중 출력 생성**
- 시각 (2D/3D 렌더링)
- 청각 (음성, 음향 효과, 음악)
- 물리 (충돌 감지, 힘 피드백)
- **AI 모델 연계**
- 모델 간 파이프라인 구성
- 실시간 피드백 루프
- 분산 처리 지원
# 현재 아키텍처
## 모듈 구조 (계층적 아키텍처)
```
src/
├── core/ # 기반 추상화 계층
│ ├── system.rs # System trait (게임 로직 인터페이스)
│ ├── component.rs # Component trait (데이터 인터페이스)
│ └── entity.rs # Entity, EntityId (컴포넌트 컨테이너)
│
├── runtime/ # 실행 인프라 계층
│ ├── engine.rs # Engine (최상위 진입점)
│ ├── world.rs # World (ECS 컨테이너)
│ ├── scheduler.rs # SystemScheduler (시스템 실행 관리)
│ ├── asset/ # AssetManager (텍스처 로딩/캐싱)
│ └── scene/ # SceneManager (YAML 기반 씬 관리)
│
├── systems/ # System 구현체들
│ └── render/ # RenderSystem (화면 렌더링)
│ ├── gpu/ # GPU 추상화 (Device, Queue, Pipeline)
│ ├── resources/ # GPU 리소스 (Vertex, Texture)
│ ├── pipeline/ # 렌더링 로직 (Batch, Commands, Transform)
│ └── shaders/ # WGSL 셰이더
│
├── components/ # Component 구현체들
│ ├── transform.rs # Transform (위치, 회전, 크기)
│ ├── sprite.rs # Sprite (스프라이트 렌더링)
│ └── text.rs # Text (텍스트 렌더링)
│
└── math/ # 수학 유틸리티 (Vec2 등)
```
## 설계 원칙
### 계층적 분리
- **core/**: 확장 가능한 인터페이스 (System, Component trait)
- **runtime/**: 유일 인스턴스 관리자들 (Engine, World, AssetManager, SceneManager)
- **systems/**: System trait 구현체들 (다중 인스턴스 가능)
- **components/**: Component trait 구현체들 (다중 인스턴스 가능)
### 명확한 책임
- **추상화 (core)**: 무엇을 해야 하는가? (trait 정의)
- **실행 (runtime)**: 언제, 어떻게 실행하는가? (생명주기 관리)
- **구현 (systems/components)**: 실제로 무엇을 하는가? (로직 구현)
### 가시성 제어
- `pub(super)`: 부모 모듈에서만 접근 (내부 구현 숨김)
- `pub`: 외부 크레이트에 공개 (공개 API)
- 내부 구조를 숨기고 명확한 인터페이스만 노출
### 핵심 특징
- **ECS 패턴**: Entity-Component-System 아키텍처 적용
- **선언적 구성**: YAML 기반 씬 정의로 코드와 데이터 분리
- **템플릿 재사용**: 엔티티 템플릿 상속 및 오버라이드
- **캐싱 최적화**: 텍스처, 템플릿 등 자동 캐싱
- **크로스 플랫폼**: macOS/Linux 개발 → Windows 배포 지원
- **Rust 네이티브**: 안전성과 성능을 위해 Rust로 구현
# for developers
## 개발 환경 설정
- (window powershell) wsl 설치: `wsl --install -d Ubuntu-24.04`
- (in wsl) rust 설치: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
- (in wsl) build tool 설치:
```bash
sudo apt update && sudo apt install \
build-essential \
clang \
cmake \
ninja-build \
pkg-config \
libx11-dev libxi-dev libgl1-mesa-dev libwayland-dev \
libssl-dev curl git
```
## 로컬 개발
### 프로젝트 빌드
```bash
# 전체 프로젝트 빌드
cargo build
# 테스트 실행
cargo test
```
## MVP (Minimum Viable Product)
간단한 2D 게임을 통해 핵심 기능을 검증합니다.
1. **기본 입력 처리**
- 키보드/마우스 입력
- 간단한 물리 충돌
2. **AI 통합**
- 단일 AI 모델 통합
- 실시간 추론 처리
- 간단한 시각/청각 피드백
3. **출력 생성**
- 2D 그래픽스
- 기본 사운드 재생