# 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**: 0
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-02-04

## 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 将自动识别目标并控制角色前往。
- **模拟交互 (New!)**：目前已集成前端模拟 Agent，支持通过自然语言指令（如“去找狗哥”）自动控制角色导航至目标。

---

## 🛠️ 技术栈 (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, Lights)
│   │   │   └── ui/     # 2D UI 组件 (ChatInterface)
│   │   ├── stores/     # 状态管理 (Input, GameState, AgentStore)
│   │   ├── services/   # 外部服务 (MockAgent)
│   │   ├── systems/    # 逻辑系统 (AgentController)
│   │   └── hooks/      # 游戏逻辑 Hooks
│   └── public/         # 静态资源 (Models, Textures)
└── README.md           # 项目说明书
```

## 🚀 快速开始

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

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

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

4. **体验**
   打开浏览器访问 `http://localhost:5173`。
   - 使用 **WASD** 移动，**Space** 跳跃，**Shift** 加速。
   - 在底部输入框输入 **“去找狗哥”**，体验 AI 自动寻路。

---

## 📅 开发路线图 (Roadmap)

- [x] **Phase 1: 基础世界构建**
  - [x] 搭建 R3F 场景与光照
  - [x] 实现物理胶囊体角色控制器 (WASD 移动)
  - [x] 实现相机跟随逻辑

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

- [ ] **Phase 3: 赋予智能**
  - [x] UI 对话交互界面
  - [x] 前端模拟 Agent (Mock Service)
  - [x] AI 指令执行器 (Navigate Command)
  - [ ] 接入真实后端 AI 决策接口

---

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