AI导哈

Godot 4 TileMap编辑工具

一款用于创建、检查和程序化编辑Godot 4 TileMap场景的CLI和MCP服务器工具，支持AI驱动的地图生成和终端渲染。

  • by DjinnFoundry
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 DjinnFoundry/godot-map-cli

使用说明

godot地图cli

用于AI驱动的Godot 4 TileMap编辑的CLI+MCP服务器

创建、检查和以编程方式编辑Godot 4 TileMap场景。支持CLI和MCP协议，以便与Claude Code和其他AI代理集成。

特性

  • 使用标准RPG结构创建和检查Godot 4项目
  • 从具有物理层、地形和碰撞支持的PNG图像生成平铺集
  • 使用多个TileMapLayer创建场景
  • 使用二进制PackedByteArray格式放置、填充、擦除和读取磁贴
  • ASCII渲染图直接在终端中显示
  • 带有种子RNG的程序生成器：村庄、森林、路径
  • 用于地形自动绘制和屏幕截图的无头Godot集成
  • MCP服务器，配备24个克劳德代码集成工具
  • 除了MCP SDK和Commander之外，零运行时依赖性

安装

全球

npm install -g godot-map-cli
godot-map-cli --help

作为npx

npx godot-map-cli --help

快速开始

创建一个项目

godot-map-cli init my-rpg --name "My RPG"
cd my-rpg

从PNG创建波浪集

godot-map-cli tileset create overworld \
  --image assets/tileset.png \
  --tile-size 16 \
  --project .

创建具有图层的场景

godot-map-cli map create scenes/world.tscn \
  --tileset res://tilesets/overworld.tres \
  --layers Ground,Buildings,Details

放置瓷砖

godot-map-cli map place scenes/world.tscn \
  --layer Ground \
  --at 5,5 \
  --tile 0,0

填充一个区域

godot-map-cli map fill scenes/world.tscn \
  --layer Ground \
  --rect 0,0,20,20 \
  --tile 0,0

渲染到终端

godot-map-cli map render scenes/world.tscn --layer Ground

创建一个村庄

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] 列出项目中的所有波浪图
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集成

建筑

graph TD
    A[Claude Code / AI Agent] -->|MCP protocol| B[MCP Server<br/>tools.ts + handlers.ts]
    C[User / Terminal] -->|CLI commands| D[Commander<br/>cli.ts]

    B --> E[Core Modules]
    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 codec]
    E --> J[tilemap-editor.ts<br/>place, fill, erase, read]
    E --> K[generators/<br/>village, forest, path]
    E --> L[godot-runner.ts<br/>headless GDScript]

    G --> M[.tscn files]
    H --> N[.tres files]
    F --> O[project.godot]
    L -->|optional| P[Godot 4 binary]

CLI和MCP服务器共享相同的核心模块。MCP服务器将操作作为AI代理的工具公开，而CLI为终端用户提供相同的功能。

MCP服务器设置

构建

npm run build

配置Claude代码

添加a .mcp.json 将文件保存到项目根目录（或 ~/.mcp.json 全球访问）：

{
  "mcpServers": {
    "godot-map-cli": {
      "command": "node",
      "args": ["/path/to/godot-map-cli/dist/mcp-server.js"]
    }
  }
}

集 GODOT_PROJECT_PATH env-var默认为特定的项目目录。

可用工具

工具 说明
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）

发展

设置

git clone https://github.com/yourusername/godot-map-cli
cd godot-map-cli
npm install

构建

npm run build

观看模式

npm run dev

测试

npm test
npm run test:watch

启动MCP服务器

npm run start:mcp

启动CLI

npm run start:cli -- --help

运作原理

文件格式处理

  • 读写Godot 4 .tscn （文本场景）文件直接
  • 解析并生成 .tres TileSets的（资源）文件
  • 编码/解码Godot的 PackedByteArray 平铺数据的二进制格式
  • 无AST转换-保留格式和注释

Godot集成

  • 90%的操作不需要安装Godot
  • 无头Godot仅用于：
    • 地形自动操纵分辨率
    • 屏幕截图渲染
  • Godot检测通过 GODOT_PATH 环境变量或系统路径

过程生成

  • 所有发生器都使用种子RNG进行再现
  • 具有相同种子的确定性输出总是产生相同的布局
  • 支持可变密度和尺寸参数

二进制数据

  • 瓷砖储存方式 PackedByteArray Godot格式
  • 每个单元格编码为：source_id（8位）、atlas_x（16位）、atlas_y（16位”）、alt（4位”）
  • 自动包装/拆包-对用户透明

例子

创造一个完整的RPG世界

# Initialize project
godot-map-cli init my-game --name "My RPG"
cd my-game

# Create tileset
godot-map-cli tileset create terrain --image ../assets/terrain.png --tile-size 16

# Create world scene
godot-map-cli map create scenes/world.tscn \
  --tileset res://tilesets/terrain.tres \
  --layers Ground,Obstacles,Decoration

# Generate base terrain
godot-map-cli map fill scenes/world.tscn \
  --layer Ground \
  --rect 0,0,100,100 \
  --tile 0,0

# Add village
godot-map-cli generate village scenes/world.tscn \
  --center 50,50 --size 30,30 --houses 8

# Add forest
godot-map-cli generate forest scenes/world.tscn \
  --rect 70,20,20,20 --density 0.7

与Claude Code一起使用

User: "Create a dungeon layout with rooms connected by corridors"

Claude Code:
  1. godot_scene_create with Ground, Walls, Decoration layers
  2. godot_tilemap_fill_rect to create room areas
  3. godot_generate_path to connect rooms with corridors
  4. godot_tilemap_read to inspect layout
  5. godot_render_screenshot to visualize

需求

  • Node.js>=20
  • 可选：Godot 4.x（用于地形自动绘制和屏幕截图）

许可证

麻省理工学院

贡献

欢迎投稿！拜托：

  1. 测试所有代码更改
  2. 保持TypeScript严格模式
  3. 将功能保持在20行以内
  4. 为新功能添加测试
  5. 更新文档

支持

  • 在GitHub上报告问题
  • 先检查现有问题
  • 包括您的Godot版本和项目结构

相关 MCP