使用说明

godot tilemap mcp

为人工智能代理提供眼睛、词汇和Godot 4瓷砖贴图的安全画笔。

godot-tilemap-mcp 是一个专注的TileMapLayer工具包，既作为MCP服务器又作为命令行应用程序公开。它理解二进制 tile_map_data 隐藏在Godot文本场景中，从TileSets构建语义目录，渲染实际的图集纹理，分析地图质量，并通过可审查的事务应用确定性编辑。

它是为代理设计的，但CLI、PNG报告、JSON配方和无损核心在人工编写的管道中同样有用。

v2有什么变化

可视化输出：绘制PNG图、平铺联系人表和前后/差异报告。
语义发现：别名、地形元数据、自定义数据、物理、导航、图集备选方案、动画和场景源。
安全编辑：预览优先、修订锁定、原子写入、外科手术 tile_map_data 补丁，并保护撤销。
确定性创作：形状、路径、散布、戳记、复制/变换、替换、洪水填充和Godot原生地形连接。
嵌入式瓷砖集：外部 .tres 文件和 TileSet 内部子资源 .tscn 两者都是可检查的。
工作树感知路径：显式的项目覆盖和允许列出的根可以防止意外写入错误的签出。
可重用库：解析器、编解码器、目录、呈现器、分析器、配方引擎和事务存储作为类型化模块导出。
v1兼容性：保留所有旧的MCP工具名称；传统的写调用现在创建预览，除非显式启用了直接模式。

需求

Node.js 22或更新版本。
Godot 4项目使用 TileMapLayer 文本中的节点 .tscn 场景。
仅用于地形连接操作的Godot可执行文件。静态检查、普通编辑、分析和图集渲染不会启动Godot。

从源代码安装

git clone https://github.com/Ekaitzsegurola/godot-tilemap-mcp.git
cd godot-tilemap-mcp
npm install
npm run build

包裹暴露 godot-tilemap-mcp和老 node src/index.js 构建后，入口点仍作为兼容性垫片。

MCP配置

{
  "mcpServers": {
    "godot-tilemap": {
      "command": "node",
      "args": [
        "/absolute/path/to/godot-tilemap-mcp/dist/cli.js",
        "mcp",
        "--project",
        "/absolute/path/to/game"
      ]
    }
  }
}

对于具有代理工作树的存储库，允许其公共父级并传递绝对值 project_path 每次通话：

"args": [
  "/absolute/path/to/godot-tilemap-mcp/dist/cli.js",
  "mcp",
  "--project", "/projects/game",
  "--allow-root", "/projects/game-worktrees"
]

服务器拒绝其配置的根之外的项目覆盖。

安全的编辑流程

编辑永远不仅仅是“写入这些字节”。它是一个与精确场景修订相关的配方：

preview_tilemap_edit 验证坐标、图层、TileSet引用、别名、限制和受保护图层。
它计算单元级别差异并存储 before.png, after.png, diff.png，以及 report.html 在项目之外。
apply_tilemap_edit 检查场景是否仍具有相同的SHA-256版本，仅修补受影响的部分 tile_map_data 属性，并以原子方式写入。
undo_tilemap_edit 仅当后续更改未触及场景时，才恢复原始字节。

这使得预览在聊天中很有用，同时避免了过时的代理覆盖。

{
  "recipe": {
    "scenePath": "res://Scenes/World.tscn",
    "seed": "village-square-v1",
    "operations": [
      {
        "op": "path",
        "layer": "World/Ground",
        "points": [{ "x": 4, "y": 9 }, { "x": 18, "y": 9 }, { "x": 24, "y": 14 }],
        "width": 3,
        "tile": { "brush": "dirt_path" }
      },
      {
        "op": "scatter",
        "layer": "World/Details",
        "region": { "x": 2, "y": 5, "width": 28, "height": 16 },
        "density": 0.08,
        "minDistance": 2,
        "tile": { "brush": "wildflowers" }
      }
    ]
  }
}

配方是确定的：相同的起始版本、配方和种子产生相同的字节。

MCP工具

项目和发现

工具	目的
`tilemap_doctor`	诊断项目/配置文件发现、网桥可用性、场景、数据和参考
`list_tilemaps`	查找场景并报告图层、计数、边界和平铺集
`inspect_tilemap`	检查场景修订、图层、单元格和语义TileSet摘要
`inspect_tileset`	对外部或嵌入式TileSet进行编目
`find_tiles`	按文本、源、地形、自定义数据、物理或导航进行搜索；返回联系人表
`read_tiles`	解码单元，具有区域和响应限制

查看和理解地图

工具	目的
`render_tilemap_image`	将图集纹理中的可见层渲染为PNG
`analyze_tilemap`	测量多样性、熵、重复性、运行、拓扑、孤立单元和无效引用
`extract_tilemap_pattern`	将已编写的区域转换为可重复使用的ASCII戳记和调色板

事务性创作

工具	目的
`preview_tilemap_edit`	验证配方并返回一个可视化的、版本锁定的差异
`apply_tilemap_edit`	以原子方式应用现有预览
`undo_tilemap_edit`	当应用后的修订仍然匹配时撤消
`discard_tilemap_edit`	删除未应用/未完成工作的缓存工件

支持的操作包括 set, erase, fill, flood_fill, path, scatter, replace, stamp, copy, terrain_connect，以及 terrain_path.

v1工具 get_tilemap_info, render_tilemap, analyze_tilemap_patterns, set_tiles, fill_rect, paint_path, stamp_pattern, erase_tiles，以及 erase_rect 也注册了。默认情况下，旧的写入工具只能预览。 --legacy-direct-writes 为受控迁移恢复即时应用程序。

命令行界面

godot-tilemap-mcp doctor --project /path/to/game
godot-tilemap-mcp list --project /path/to/game
godot-tilemap-mcp inspect res://Scenes/World.tscn --layer World/Ground
godot-tilemap-mcp catalog res://Tiles/world.tres --text grass --out /tmp/grass.png
godot-tilemap-mcp render res://Scenes/World.tscn --layer World/Ground --out /tmp/world.png --grid
godot-tilemap-mcp analyze res://Scenes/World.tscn --layer World/Ground
godot-tilemap-mcp plan recipes/new-grove.json
godot-tilemap-mcp apply tx_...
godot-tilemap-mcp undo tx_...

跑 godot-tilemap-mcp help 对于所有选项。

可选项目简介

语义目录自动工作。A. .godot-tilemap-mcp.json profile添加了项目语言和护栏：

{
  "$schema": "https://raw.githubusercontent.com/Ekaitzsegurola/godot-tilemap-mcp/main/schemas/project-profile.schema.json",
  "version": 1,
  "layer_roles": {
    "ground": ["*/Ground", "*/Base"],
    "details": ["*/Details", "*/Overlay"]
  },
  "protected_layers": ["*/RuntimeMarkers"],
  "tilesets": {
    "res://Tiles/world.tres": {
      "aliases": {
        "grass_base": { "source_id": 0, "atlas_x": 2, "atlas_y": 4, "alternative_id": 0 }
      },
      "brushes": {
        "wildflowers": {
          "tiles": [
            { "tile": { "alias": "flower_blue" }, "weight": 3 },
            { "tile": { "alias": "flower_white" }, "weight": 1 }
          ]
        }
      }
    }
  },
  "limits": {
    "max_cells_per_edit": 50000,
    "max_render_pixels": 16777216
  }
}

使用以下内容创建初学者配置文件 godot-tilemap-mcp config init。参见食谱和简介完整的工作流程。

无损编辑和二进制格式

核心使用字节偏移量解析Godot文本资源，并保留每个未触及的字符，包括行尾和UTF-8 BOM。应用事务只会替换完整的 tile_map_data 物业线。

Godot 4将此布局的字段存储为base64：

uint16 LE format version
repeat:
  int16  LE cell x
  int16  LE cell y
  uint16 LE source id
  uint16 LE atlas x
  uint16 LE atlas y
  uint16 LE alternative/transform flags

格式错误的base64、截断的有效载荷、无效的范围、模糊的层名称、未知的图块引用、过时的修订、受保护的层和过大的编辑在场景写入之前失败。

库API

import {
  ProjectPaths,
  TransactionStore,
  inspectTileSet,
  loadSceneSnapshot,
  renderSceneImage,
} from "godot-tilemap-mcp/core";

核心不依赖于MCP传输。看建筑学用于模块边界和扩展点。

安全和隐私

运行时不调用云服务。它只读取允许列出的本地Godot项目，渲染本地资源，将预览存储在操作系统缓存中，并仅对需要引擎语义的操作调用本地Godot可执行文件。回顾安全.md 在将其暴露在本地stdio客户端之外之前。

贡献

欢迎提供Bug报告、TileSet夹具、平台反馈和有针对性的拉取请求。阅读贡献.md.

许可证

麻省理工学院——见许可证.

使用说明

godot tilemap mcp

v2有什么变化

需求

从源代码安装

MCP配置

安全的编辑流程

MCP工具

项目和发现

查看和理解地图

事务性创作

命令行界面

可选项目简介

无损编辑和二进制格式

库API

安全和隐私

贡献

许可证

相关 MCP

Unity MCP AI游戏开发工具

Unity编辑器MCP服务器

Excel SQL查询服务器

游戏脚本与存储管理工具集

Godot引擎交互协议

虚幻引擎模型上下文协议