内容
# godot-map-cli
**用于 AI 驱动的 Godot 4 TileMap 编辑的 CLI 和 MCP 服务器**
[](https://nodejs.org/)
[](LICENSE)
[](https://www.typescriptlang.org/)
创建、检查和程序化编辑 Godot 4 TileMap 场景。支持 CLI 和 MCP 协议，以便与 Claude Code 和其他 AI 代理集成。
## 功能
- 创建具有标准 RPG 结构的 Godot 4 项目
- 从具有物理层、 terrain 和碰撞支持的 PNG 图像生成 TileSets
- 创建具有多个 TileMapLayers 的场景
- 使用二进制 PackedByteArray 格式放置、填充、擦除和读取图块
- 在终端中直接以 ASCII 渲染 tilemap
- 具有种子 RNG 的程序生成器：村庄、森林、路径
- 用于地形自动拼接和截图的无头 Godot 集成
- 具有 24 个工具的 MCP 服务器，用于 Claude Code 集成
- 除了 MCP SDK 和 Commander 之外，没有运行时依赖
## 安装
### 全局
```bash
npm install -g godot-map-cli
godot-map-cli --help
```
### 作为 npx
```bash
npx godot-map-cli --help
```
## 快速入门
### 创建项目
```bash
godot-map-cli init my-rpg --name "My RPG"
cd my-rpg
```
### 从 PNG 创建 tileset
```bash
godot-map-cli tileset create overworld \
--image assets/tileset.png \
--tile-size 16 \
--project .
```
### 创建具有层的场景
```bash
godot-map-cli map create scenes/world.tscn \
--tileset res://tilesets/overworld.tres \
--layers Ground,Buildings,Details
```
### 放置图块
```bash
godot-map-cli map place scenes/world.tscn \
--layer Ground \
--at 5,5 \
--tile 0,0
```
### 填充区域
```bash
godot-map-cli map fill scenes/world.tscn \
--layer Ground \
--rect 0,0,20,20 \
--tile 0,0
```
### 渲染到终端
```bash
godot-map-cli map render scenes/world.tscn --layer Ground
```
### 生成村庄
```bash
godot-map-cli generate village scenes/world.tscn \
--center 10,10 \
--size 20,20 \
--houses 5 \
--seed 42
```
## CLI 参考
### 项目管理
| 命令 | 描述 |
|---------|-------------|
| `init <path>` | 创建具有 RPG 结构的 Godot 4 项目 |
| `info [path]` | 显示项目元数据（场景数量、脚本、资产） |
| `godot-version` | 显示检测到的 Godot 安装和版本 |
### TileSet 管理
| 命令 | 描述 |
|---------|-------------|
| `tileset create <name>` | 从 PNG 图像创建 TileSet |
| `tileset inspect <path>` | 解析和显示 TileSet 结构 |
| `tileset register-tiles <path>` | 在 TileSet 中注册图块定义 |
| `tileset set-collision <path>` | 为图块添加碰撞多边形 |
| `tileset add-terrain <path>` | 添加具有命名地形的地形集 |
### 地图编辑
| 命令 | 描述 |
|---------|-------------|
| `map create <scene>` | 创建具有 TileMapLayers 的场景 |
| `map list [project]` | 列出项目中的所有 tilemap |
| `map info <scene>` | 获取 tilemap 层元数据 |
| `map place <scene>` | 放置单个图块 |
| `map fill <scene>` | 用图块填充矩形 |
| `map read <scene>` | 从层中读取图块 |
| `map render <scene>` | 将层以 ASCII 渲染到终端 |
| `map erase <scene>` | 按位置或矩形擦除图块 |
| `map remove-layer <scene>` | 从场景中删除 TileMapLayer |
### 程序生成
| 命令 | 描述 |
|---------|-------------|
| `generate village <scene>` | 生成具有房屋和路径的村庄 |
| `generate forest <scene>` | 生成具有集群树木的森林 |
| `generate path <scene>` | 生成两个点之间的路径 |
### 无头 Godot（需要安装）
| 命令 | 描述 |
|---------|-------------|
| `render <scene>` | 使用无头 Godot 将场景渲染为 PNG |
| `terrain-resolve` | 使用无头 Godot 解析地形自动拼接 |
### MCP 服务器
| 命令 | 描述 |
|---------|-------------|
| `mcp` | 作为 MCP 服务器运行，用于 Claude Code 集成 |
## 架构
```mermaid
graph TD
A[Claude Code / AI 代理] -->|MCP 协议| B[MCP 服务器<br/>tools.ts + handlers.ts]
C[用户 / 终端] -->|CLI 命令| D[Commander<br/>cli.ts]
B --> E[核心模块]
D --> E
E --> F[project.ts<br/>init, info]
E --> G[scene-parser.ts<br/>scene-writer.ts]
E --> H[resource-parser.ts<br/>tileset-writer.ts]
E --> I[tile-data.ts<br/>PackedByteArray 编码]
E --> J[tilemap-editor.ts<br/>place, fill, erase, read]
E --> K[generators/<br/>village, forest, path]
E --> L[godot-runner.ts<br/>无头 GDScript]
G --> M[.tscn 文件]
H --> N[.tres 文件]
F --> O[project.godot]
L -->|可选| P[Godot 4 二进制]
```
CLI 和 MCP 服务器共享相同的核心模块。MCP 服务器将操作作为工具暴露给 AI 代理，而 CLI 为终端用户提供相同的功能。
## MCP 服务器设置
### 构建
```bash
npm run build
```
### 配置 Claude Code
在项目根目录中添加一个 `.mcp.json` 文件（或全局访问 `~/.mcp.json`）：
```json
{
"mcpServers": {
"godot-map-cli": {
"command": "node",
"args": ["/path/to/godot-map-cli/dist/mcp-server.js"]
}
}
}
```
设置 `GODOT_PROJECT_PATH` 环境变量以默认为特定项目目录。
### 可用工具
| 工具 | 描述 |
|------|-------------|
| `godot_project_init` | 创建具有标准目录结构的 Godot 4 项目 |
| `godot_project_info` | 获取项目元数据（名称、场景数量、脚本数量） |
| `godot_tileset_create` | 从 PNG 创建 TileSet，具有可选物理层 |
| `godot_tileset_inspect` | 解析 TileSet .tres 并返回完整结构 |
| `godot_tileset_register_tiles` | 在 TileSet 中注册图块定义 |
| `godot_tileset_set_collision` | 为图块添加碰撞多边形 |
| `godot_tileset_add_terrain` | 添加具有命名地形的地形集 |
| `godot_scene_create` | 创建具有 TileMapLayer 节点的场景 |
| `godot_layer_add` | 向现有场景添加 TileMapLayer |
| `godot_layer_remove` | 从场景中删除 TileMapLayer |
| `godot_tilemap_list` | 扫描项目中的所有 TileMapLayer 节点 |
| `godot_tilemap_info` | 获取 TileMapLayer 元数据（边界、图块数量、z-index） |
| `godot_tilemap_read` | 读取具有可选区域筛选器的层中的图块 |
| `godot_tilemap_render` | 将层（源或图集模式）以 ASCII 渲染 |
| `godot_tilemap_set_tiles` | 在层上放置/覆盖图块 |
| `godot_tilemap_fill_rect` | 用图块填充矩形区域 |
| `godot_tilemap_erase_tiles` | 删除特定位置的图块 |
| `godot_tilemap_erase_rect` | 清除矩形区域中的所有图块 |
| `godot_generate_village` | 生成具有房屋和路径的村庄布局 |
| `godot_generate_forest` | 生成具有集群树木的森林 |
| `godot_generate_path` | 生成两个点之间的路径 |
| `godot_terrain_resolve` | 解析地形自动拼接（需要 Godot） |
| `godot_render_screenshot` | 将场景渲染为 PNG（需要 Godot） |
## 开发
### 设置
```bash
git clone https://github.com/yourusername/godot-map-cli
cd godot-map-cli
npm install
```
### 构建
```bash
npm run build
```
### 监视模式
```bash
npm run dev
```
### 测试
```bash
npm test
npm run test:watch
```
### 启动 MCP 服务器
```bash
npm run start:mcp
```
### 启动 CLI
```bash
npm run start:cli -- --help
```
## 工作原理
### 文件格式处理
- 直接读取和写入 Godot 4 `.tscn`（文本场景）文件
- 解析和生成 `.tres`（资源）文件用于 TileSets
- 编码/解码 Godot 的 `PackedByteArray` 二进制格式用于图块数据
- 无 AST 转换 - 保留格式和注释
### Godot 集成
- 90% 的操作不需要 Godot 安装
- 无头 Godot 仅用于：
- 地形自动拼接解析
- 截图渲染
- 通过 `GODOT_PATH` 环境变量或系统路径检测 Godot
### 程序生成
- 所有生成器都使用种子 RNG 进行可重复性
- 相同的种子始终产生相同的布局
- 支持可变密度和大小参数
### 二进制数据
- 图块存储为 Godot 格式的 `PackedByteArray`
- 每个单元格编码为：source_id（8 位），atlas_x（16 位），atlas_y（16 位），alt（4 位）
- 自动打包/解包 - 对用户透明
## 示例
### 创建完整的 RPG 世界
```bash
# 初始化项目
godot-map-cli init my-game --name "My RPG"
cd my-game
# 创建 tileset
godot-map-cli tileset create terrain --image ../assets/terrain.png --tile-size 16
# 创建世界场景
godot-map-cli map create scenes/world.tscn \
--tileset res://tilesets/terrain.tres \
--layers Ground,Obstacles,Decoration
# 生成基本地形
godot-map-cli map fill scenes/world.tscn \
--layer Ground \
--rect 0,0,100,100 \
--tile 0,0
# 添加村庄
godot-map-cli generate village scenes/world.tscn \
--center 50,50 --size 30,30 --houses 8
# 添加森林
godot-map-cli generate forest scenes/world.tscn \
--rect 70,20,20,20 --density 0.7
```
### 与 Claude Code 一起使用
```
用户：”创建一个具有通过走廊连接的房间的地下城布局“
Claude Code：
1. godot_scene_create 具有 Ground、Walls、Decoration 层
2. godot_tilemap_fill_rect 创建房间区域
3. godot_generate_path 连接房间与走廊
4. godot_tilemap_read 检查布局
5. godot_render_screenshot 可视化
```
## 要求
- Node.js >= 20
- 可选：Godot 4.x（用于地形自动拼接和截图）
## 许可证
MIT
## 贡献
欢迎贡献！请：
1. 测试所有代码更改
2. 保持 TypeScript 严格模式
3. 保持函数在 20 行以内
4. 为新功能添加测试
5. 更新文档
## 支持
- 在 GitHub 上报告问题
- 首先检查现有问题
- 包括您的 Godot 版本和项目结构
