moltrun 1.7.0

High-performance game engine library with AI capabilities, built on wgpu for modern 3D graphics and physics simulation
Documentation

비전

다중 입력 소스를 지원하는 실시간 상호작용형 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 설치: 
    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

로컬 개발

프로젝트 빌드

# 전체 프로젝트 빌드
cargo build

# 테스트 실행
cargo test

MVP (Minimum Viable Product)

간단한 2D 게임을 통해 핵심 기능을 검증합니다.

  1. 기본 입력 처리
  • 키보드/마우스 입력
  • 간단한 물리 충돌
  1. AI 통합
  • 단일 AI 모델 통합
  • 실시간 추론 처리
  • 간단한 시각/청각 피드백
  1. 출력 생성
  • 2D 그래픽스
  • 기본 사운드 재생