# 비전
다중 입력 소스를 지원하는 실시간 상호작용형 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 그래픽스
  - 기본 사운드 재생
