AI Micro Town — 브라우저 자율 마을 시뮬레이션 상세 설계서
상태: CURATED · ACTIVE (엔진 코어 구현 · 브라우저 실험 검증 전) 기술 스택: C++ (ECS), Emscripten/WebAssembly, Wllama(Llama.cpp Wasm), Canvas 2D, TypeScript, Vite 카테고리: Web & AI Lab
1. 문제와 대상 사용자
에이전트 시뮬레이션은 보통 주민 수가 늘어날수록 서버 추론 비용이 함께 늘어나, 개인 개발자가 지속적으로 운영하기 어렵습니다. AI Micro Town은 연산과 추론을 모두 사용자 기기로 옮기면 어디까지 가능한지를 확인하는 기술 실험입니다. 대상은 관찰형 시뮬레이션을 좋아하는 사용자와, 브라우저 내 로컬 추론의 실제 한계를 알고 싶은 개발자입니다.
2. 핵심 구조
| 계층 | 설명 |
|---|---|
| ECS 코어 | 주민·사물·환경을 Entity/Component/System으로 분리한 C++ 시뮬레이션 루프 |
| 로컬 LLM | 주민 성격과 단기 기억을 프롬프트로 변환해 브라우저 안에서 대사·행동을 생성 |
| 렌더러 | ECS가 계산한 상태를 Canvas 2D로 매핑 (배경 타일은 오프스크린 캔버스에 1회 렌더 후 캐싱) |
3. 기술 선택 이유
- C++ + Data-Oriented Design: 메모리 레이아웃을 직접 제어해 다수 개체를 한 프레임 안에 갱신하기 위해 선택했습니다.
- WebAssembly: 설치 없이 브라우저에서 네이티브에 가까운 속도로 시뮬레이션을 돌리기 위한 배포 수단입니다.
- 로컬 LLM(경량 모델): 서버 추론 비용을 0으로 두고, 사용자 데이터를 외부로 보내지 않기 위한 선택입니다.
4. 현재 범위
- 엔진 코어(entity manager, 3개 시스템, world, Emscripten 바인딩)와 웹 프런트엔드가 구현되어 있습니다. 타일맵·주민 렌더링, 대화 버블, 마을 이벤트 5종, HUD, 화면 공유까지 브라우저에서 동작하는 루프가 완성돼 있습니다.
- 대사 생성은 규칙 기반(Track 1)이 기본이고, 버튼으로 켜는 로컬 LLM(Track 2)이 실패하면 규칙 기반으로 폴백합니다.
- 저장소에 커밋된 Wasm 바이너리가 Phase 1 시점 빌드라 확장 API(World_GetTask 등)를 포함하지 않습니다. 브릿지가 이를 감지해 JS Mock 시뮬레이터로 폴백하므로, 현재 커밋 상태에서는 C++ 엔진이 아니라 Mock이 구동됩니다. Emscripten 재빌드가 선행 과제입니다.
- 결제는 연동돼 있지 않습니다. 프리미엄 이벤트 UI는 이메일 사전 신청만 수집합니다.
- 브라우저 공개 실험은 아직 제공하지 않습니다. 이 카드는 구조 기록을 우선 제공합니다.
5. 알려진 한계
- 로컬 LLM은 최초 진입 시 자동으로 받는 것이 아니라 사용자가 버튼으로 켜는 옵트인 방식이며, 켜는 순간 모델 가중치를 내려받습니다. 기기 성능에 따라 응답 지연이 크게 달라집니다.
- 현재 연결된 모델은 약 1MB 데모급 GGUF(stories260K)라 한국어 대사 품질이 보장되지 않고, 생성 결과가 짧으면 규칙 기반 대사로 되돌립니다.
- 주민 수가 엔진에 5명으로 고정돼 있고 최대 엔티티가 256으로 상한이 걸려 있습니다.
- 멀티스레드 Wasm은 크로스오리진 격리(COOP/COEP) 헤더가 필요해 배포 환경 제약을 받습니다.
- 저사양 기기와 일부 모바일 브라우저에서는 목표 프레임을 유지하지 못할 수 있습니다.
6. 다음 검증
- Emscripten으로 엔진을 재빌드해 확장 API(World_GetTask/GetVelocityX/GetVelocityY)를 포함한 Wasm 바이너리를 갱신하고, 브릿지가 Mock이 아닌 실제 Wasm 모드로 진입하는지 확인
- 대상 브라우저·기기별 WebAssembly 및 모델 호환성 측정
- 호환성 확인 후에만 제한된 브라우저 실험을 공개하고, 미지원 환경에는 요구사항을 먼저 노출