cs-roam-mcp
README.md
# cs-roam-mcp
真人 CS 第一人称漫游 MCP(Model Context Protocol)服务 —— 一句话:让任何基于 Three.js / React Three Fiber 的数字孪生、园区、楼宇可视化项目,**一行工具调用就拿到一套国产 3A 级 FPS 手感的第一人称漫游控制器源码**。
参数逆向整理自国产 3A 级 FPS 游戏的漫游控制器(移动 / 形体 / 视觉全套配置),已在数字孪生 Web 工程中以 TypeScript 复刻并通过 `tsc` 类型检查与线上验证。
## 特性
- **真·FPS 手感**:走 / 冲刺 / 下蹲 / 瞄准(ADS)四档速度,地面四档加速度逼近与衰减,空中操控衰减
- **跳跃系统**:`jumpVelocity = √(2·g·h)` 精确起跳、土狼时间(coyote 0.12s)、跳跃缓冲(0.13s)、落地下沉弹簧 + 镜头震动衰减
- **镜头表现**:步伐相位 bob(Y/X 双轴)、冲刺 FOV +6°、ADS FOV 52°、侧移滚转、鼠标尖峰过滤(>400px 剔除)
- **碰撞**:多边形足迹(footprint polygon)分轴滑动碰撞,建筑轮廓直接投影即可用
- **零依赖 MCP**:仅 Node 内置模块,stdio JSON-RPC 2.0,无需 `npm install`
- **可移植组件**:`FirstPersonWalk.portable.tsx` 无任何项目数据依赖,碰撞体 / 出生点 / 灵敏度全部走 props
## 快速开始
```bash
git clone https://github.com/dashizhihuan2018-source/cs-roam-mcp.git
```
### 注册到 WorkBuddy / Claude 等 MCP 宿主
在 MCP 配置(如 `~/.workbuddy/mcp.json` 或 `claude_desktop_config.json`)中添加:
```json
{
"mcpServers": {
"cs-roam": {
"command": "node",
"args": ["/你的路径/cs-roam-mcp/index.js"]
}
}
}
```
重启宿主后即可使用(WorkBuddy 用户需在连接器管理页对新服务点 Trust 启用)。
## 提供的工具
| 工具 | 用途 |
|------|------|
| `cs_roam_component` | 返回可移植组件 `FirstPersonWalk.portable.tsx` 完整源码(直接落盘即用) |
| `cs_roam_config` | 返回全套手感参数表(速度 / 加速度 / 重力跳跃 / 镜头 / 碰撞),含单位与出处说明 |
| `cs_roam_integrate` | 返回接入指南:Canvas 接线、OrbitControls 让位与恢复、指针锁定、HUD 提示样式 |
| `cs_roam_customize` | 按你的项目定制参数(身高 / 速度 / 灵敏度等),跳跃速度自动按 `√(2gh)` 推导 |
典型对话用法:
> 帮我把第一人称漫游加到这个 Three.js 场景里,建筑碰撞体用这几个多边形。
宿主会自动调用上述工具拿到源码与接线说明,直接写入你的工程。
## 组件依赖
`FirstPersonWalk.portable.tsx` 需要:
- React 18+
- `@react-three/fiber`(组件挂在 `<Canvas>` 内)
- three.js(r150+)
## 技术栈
Node.js ≥ 16(MCP 服务);TypeScript + React Three Fiber(漫游组件)。
## License
MIT