# ThreeDRambler

**Repository Path**: masaikk/three-drambler

## Basic Information

- **Project Name**: ThreeDRambler
- **Description**: 三维漫步者
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-02-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ThreeDRambler - 三维漫步者 (Web 3D MMD 智能探索系统)

## 📖 项目简介

**ThreeDRambler** 是一个基于 Web 的沉浸式三维动作探索游戏。在这个项目中，我们结合了**二次元 MMD (MikuMikuDance) 美学**与**前沿的 Web 3D 技术**。

不同于传统游戏直接由按键驱动角色，本项目引入了 **AI Agent (智能代理)** 作为核心大脑。玩家不仅可以直接控制角色，更可以通过自然语言与 AI 交互，让 AI 协助角色进行复杂的环境探索、交互与动作演出。

> **核心理念：** 意图驱动 (Intent-Driven) | 沉浸式交互 | 二次元美学

---

## ✨ 核心特性

### 1. 🎭 沉浸式动作探索
- **物理驱动的角色控制器**：摒弃僵硬的坐标移动，使用 Rapier/Cannon 物理引擎模拟真实的运动惯性、碰撞与重力。
- **相机相关移动 (Camera-Relative)**：符合现代 3A 游戏的操控手感，角色总是相对于镜头方向移动。
- **动作状态机**：智能平滑地在 Idle (待机)、Walk (行走)、Run (奔跑) 之间切换，保证动作的连贯性。

### 2. 💃 MMD 模型深度集成
- **原生 MMD 支持**：直接在网页端加载精美的 PMX/PMD 模型与 VMD 动作文件。
- **二次元渲染风格**：定制的光照方案与后期处理 (Bloom, Outline)，呈现梦幻的动漫风格。
- **物理骨骼优化**：专门处理 MMD 复杂的物理刚体（如飘动的头发、裙摆），在 Web 端保持流畅。

### 3. 🧠 AI Agent 智能驱动
- **意图分离架构**：
  - **大脑 (Backend)**：分析环境上下文，决策"做什么" (例如：走向书架、打招呼)。
  - **身体 (Frontend)**：负责执行"怎么做" (路径规划、动画混合、物理步进)。
- **自然语言指令**：玩家可以说"去看看那边有什么"，AI 将自动识别目标并控制角色前往。
- **双 Agent 系统**：
  - **自机 Agent**：通过页面对话框控制玩家角色（导航、拾取、跳跃等）。
  - **NPC Agent**：通过 NPC 对话框（按 E 打开）控制 NPC 移动与动作，支持独立的 AI 指令。

### 4. 🤖 NPC 智能角色系统
- **MMD NPC 角色**：支持加载多个 MMD NPC（如绛雨），每个 NPC 有独立的模型、动作与移动参数。
- **物理移动**：NPC 使用物理刚体移动，支持待机/行走动画自动切换，朝向跟随移动方向。
- **AI 对话与控制**：玩家可与 NPC 对话（基于角色设定的 AI 对话），并通过 Agent 控制 NPC 执行动作（如"向前走"、"跳跃"）。
- **角色池管理**：通过配置文件轻松添加新 NPC，支持自定义模型、动作、速度等参数。

---

## 🛠️ 技术栈 (Tech Stack)

本项目采用现代化的前端工程化架构，确保高性能与可维护性。

| 模块 | 技术选型 | 说明 |
| :--- | :--- | :--- |
| **核心框架** | **React 18+** | 构建声明式的 UI 与逻辑 |
| **3D 引擎** | **React Three Fiber (R3F)** | Three.js 的 React 封装，提供组件化的 3D 开发体验 |
| **物理引擎** | **Rapier / Cannon** | 处理碰撞检测与刚体动力学 |
| **状态管理** | **Zustand** | 高性能的全局状态管理，连接输入与渲染 |
| **AI 交互** | **REST API / WebSocket** | 前后端通信协议，传输 JSON 格式的决策指令 |

---

## 📂 目录结构

```text
root
├── docs/               # 项目文档
│   ├── drambler.md     # 详细的技术架构与设计文档
│   ├── revise.md       # 项目反思与优化记录
│   └── server.md       # 后端和agent的设计文档
├── drambler/           # 前端工程 (Vite + React)
│   ├── src/
│   │   ├── components/ # 3D 组件 (World, Character, NPC)
│   │   │   └── ui/     # 2D UI 组件 (ChatInterface, NpcDialog)
│   │   ├── stores/     # 状态管理 (Input, GameState, AgentStore, NpcAgentStore)
│   │   ├── services/   # 外部服务 (API)
│   │   ├── systems/    # 逻辑系统 (AgentController, NpcAgentController)
│   │   └── hooks/      # 游戏逻辑 Hooks
│   └── public/         # 静态资源 (MMD Models, Textures)
└── server/             # 后端工程 (FastAPI + Python)
    ├── main.py         # FastAPI 主入口
    ├── agent.py        # AI Agent 逻辑
    └── models.py       # 数据模型
```

## 🚀 快速开始

### 前端启动

1. **进入前端目录**
   ```bash
   cd drambler
   ```

2. **安装依赖**
   ```bash
   pnpm install  # 或 npm install
   ```

3. **启动开发服务器**
   ```bash
   pnpm dev      # 或 npm run dev
   ```

### 后端启动（可选，AI 功能需要）

1. **进入后端目录**
   ```bash
   cd server
   ```

2. **安装依赖**
   ```bash
   pip install -r requirements.txt
   ```

3. **配置环境变量**
   - 复制 `.env.sample` 为 `.env`
   - 填写 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`（或其他大模型 API）

4. **启动后端服务**
   ```bash
   python main.py
   ```

### 体验功能

打开浏览器访问 `http://localhost:5173`：

- **自机控制**：
  - 使用 **WASD** 移动，**Space** 跳跃，**Shift** 加速。
  - 在底部输入框输入 **"去找狗哥"**，体验 AI 自动寻路。
  - 靠近地面上的**灰色小球**会高亮，按 **E** 拾取，小球消失且**分数 +20**。
  - 点击 **Test: 自动拾取** 或输入「自动拾取」：AI 会走向最近的小球并拾取；可开启 **连续自动拾取**。

- **NPC 交互**：
  - 走到 **NPC 绛雨**附近（地图上的 MMD 角色），提示 **[E] 与绛雨对话**。
  - 按 **E** 打开 NPC 对话框：
    - **对话功能**：在输入框输入消息，与绛雨进行基于《少前2：追放》设定的 AI 对话。
    - **Agent 控制**：点击「向前走」或「跳跃」，AI 将控制绛雨执行对应动作（移动时播放行走动画）。

---

## 📅 开发路线图 (Roadmap)

- [x] **Phase 1: 基础世界构建**
  - [x] 搭建 R3F 场景与光照
  - [x] 实现物理胶囊体角色控制器 (WASD 移动)
  - [x] 实现相机跟随逻辑
  - [x] 物品与拾取系统（地面灰球、Sensor 触发器、E 键拾取、分数显示）

- [x] **Phase 2: MMD 接入**
  - [x] 加载 PMX 模型与 VMD 动作
  - [x] 实现动画切换状态机 (Animation Mixer)

- [x] **Phase 3: 赋予智能**
  - [x] UI 对话交互界面
  - [x] 前端模拟 Agent (Mock Service)
  - [x] AI 指令执行器 (Navigate Command)
  - [x] 接入真实后端 AI 决策接口
  - [x] 物品拾取与自动拾取
  - [x] 双 Agent 系统（自机 + NPC 独立控制）

- [x] **Phase 4: NPC 智能角色系统**
  - [x] NPC 角色池管理（配置化）
  - [x] NPC MMD 模型加载与动画切换
  - [x] NPC 物理移动与朝向控制
  - [x] NPC AI 对话系统（角色设定）
  - [x] NPC Agent 控制（移动、跳跃）

---

*更多详细设计细节请阅读 [docs/drambler.md](./docs/drambler.md)*