README.md

metadata

title: Maple Npc Generator
emoji: 🚀
colorFrom: gray
colorTo: blue
sdk: static
pinned: false

🍁 메이플스토리 NPC 성격 대화 생성기

MapleStory NPC Personality Dialogue Generator

Big Five 성격 모델 기반 LLM NPC 대화 생성 시스템
A real-time NPC dialogue generation system powered by Gemini AI and the Big Five personality model.

---

🎮 프로젝트 소개

20년간 게임콘텐츠, 레벨디자인을 담당하며 체감한 문제가 있습니다.
"수개월 공들여 만든 콘텐츠가 단 며칠 만에 고갈된다."

NPC 대화는 게임 몰입감의 핵심이지만, 수백 명의 NPC에게 일일이 개성 있는 대사를 작성하는 것은 막대한 리소스가 필요합니다. 이 프로젝트는 심리학의 Big Five 성격 모델을 게임 NPC에 적용하여, AI가 NPC의 성격에 맞는 자연스러운 대화를 실시간으로 생성하는 시스템입니다.

"이론을 넘어선 실체 — 게임 개발 현장의 문제를 AI로 직접 해결합니다."

---

🚀 Live Demo

👉 https://maple-npc-generator.vercel.app/

슬라이더로 NPC의 Big Five 성격 수치를 조정하고,
실시간으로 달라지는 대화 스타일을 직접 체험해보세요.

---

🧠 Big Five 성격 모델 (OCEAN)

심리학의 표준 성격 모델을 NPC 대화 생성에 적용했습니다.

특성	영문	낮을 때	높을 때
개방성	Openness	전통적, 현실적	창의적, 호기심 많음
성실성	Conscientiousness	즉흥적, 유연함	체계적, 책임감 강함
외향성	Extraversion	조용함, 내성적	활발함, 사교적
친화성	Agreeableness	직설적, 경쟁적	공감적, 협력적
신경성	Neuroticism	안정적, 침착함	감정적, 예민함

각 수치는 LLM 프롬프트의 personality 파라미터로 변환되어 Gemini에 전달됩니다.
신경성(Neuroticism) 수치는 모델의 temperature 값에도 직접 반영됩니다.

temperature = 0.7 + (neuroticism / 200)

---

🏗️ 시스템 아키텍처

[사용자 브라우저]
      │
      │  POST /api/chat (NPC 설정 + Big Five 수치 + 대화 히스토리)
      ▼
[Vercel Edge Function]  ← GEMINI_API_KEY (서버에만 존재, 외부 노출 없음)
      │
      │  Streaming SSE
      ▼
[Gemini 3 Flash Preview]
      │
      │  실시간 스트리밍 응답
      ▼
[사용자 화면에 타이핑 효과로 출력]

API 키 보안: 클라이언트 번들에 키를 포함하지 않고, Vercel 서버사이드 환경변수로만 관리합니다.

---

🛠️ 기술 스택

분류	기술
Frontend	React 18, TypeScript, Vite, Tailwind CSS
AI	Google Gemini 3 Flash Preview (gemini-3-flash-preview)
배포	Vercel (Edge Functions)
애니메이션	Motion (Framer Motion)
아이콘	Lucide React

---

📦 설치 및 실행

1. 레포지토리 클론

git clone https://github.com/Taewan627/maple-npc-generator.git
cd maple-npc-generator

2. 패키지 설치

npm install

3. 환경변수 설정

cp .env.example .env

.env 파일을 열고 Gemini API 키 입력:

GEMINI_API_KEY=AIza...

API 키 발급: Google AI Studio → Get API key

4. 로컬 실행

npm run dev

http://localhost:5173 접속

---

📁 프로젝트 구조

├── api/
│   └── chat.ts              # Vercel Edge Function (Gemini API 호출, 키 보호)
├── src/
│   ├── App.tsx              # 메인 UI 컴포넌트
│   ├── types.ts             # Big Five 타입 정의
│   ├── services/
│   │   └── geminiService.ts # API Route 호출 및 SSE 스트림 파싱
│   └── data/
│       └── maple_knowledge.json  # 메이플스토리 세계관 지식베이스
├── vercel.json              # Vercel 라우팅 설정
└── vite.config.ts           # Vite 빌드 설정

---

🔬 논문 연구 연계

이 프로젝트는 다음 연구의 실증 시스템(Proof of Concept) 으로 개발되었습니다.

"LLM 기반 게임 NPC 페르소나의 성격 차별성 및 일관성 검증을 위한 정량적 프레임워크 연구: Big Five 모델을 중심으로"
KCI 등재지| 한국 디지털콘텐츠 학회

연구 핵심 질문:

• Big Five 수치 변화가 LLM 출력의 성격 차별성에 유의미한 영향을 주는가?
• 동일 NPC에 대한 반복 생성 시 성격 일관성이 유지되는가?
• 게임 개발 파이프라인에서 AI 기반 NPC 대화 생성이 제작 효율을 개선하는가?

이 시스템은 위 연구 가설을 검증하기 위한 A/B 테스트 및 사용자 실험 플랫폼으로 활용됩니다.

---

👤 개발자

김태완 (Taewan Kim)
서강대학교 가상융합 테크놀로지 박사과정

• 🤗 HuggingFace: huggingface.co/devmeta
• 🐙 GitHub: github.com/Taewan627

---

📄 License

MIT License