孙亚健1. 先搞清楚 TileMapLayer 到底是什么
很多刚接触 Godot 4 的朋友，第一次听说 TileMapLayer 时的反应和我当初一样：这名字和以前 Godot 3 里的 TileMap 有什么关系？我是不是学了一个异端版本？
其实没那么复杂。Godot 4 把原来那个一把抓的 TileMap 节点，拆成了一个更干净的 TileMapLayer。它的定位很明确：只负责管理一层瓦片地图。你一个场景里要是有地面、墙壁、装饰、碰撞区域，以前全塞进一个 TileMap 里，现在你直接新建多个 TileMapLayer，各管各的层，逻辑清楚得多，修改哪一层也不会误伤其他内容。
那"在 TileMapLayer 中显示一个瓦块"这个需求，听起来像是个幼儿园级的操作，但实际上它是你整个 Godot 瓦片地图学习路线的第一块基石。我见过太多人卡在"新建完节点之后，底部面板怎么画都画不上东西"这一步，问题十有八九出在 TileSet 资源没配好。你可以把 TileMapLayer 想成一个画框，TileSet 才是真正装着颜料和图样的调色盘，画框本身不存储任何图案，没有调色盘，你在画框上再怎么比划也是白费功夫。
所以当我们讨论"显示一个瓦块"时，其实是在做三件事：先创建 TileSet 瓦片集资源，再把 TileMapLayer 和 TileSet 绑定，最后通过画笔或代码把瓦块放进指定格子。这篇文章我就按这条主线，把这个过程里所有容易踩的坑、容易懵的概念，一次讲清楚。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 为什么新版改用 TileMapLayer，它到底好在哪
2.1 TileMap 到 TileMapLayer 的拆分之争
在 Godot 3.x 时代，TileMap 节点是典型的"我都行"选手。地形画完了，碰撞多边形也画在同一个 TileMap 里，装饰物也放在同一层。一开始做小游戏确实方便，但项目一旦大起来，麻烦就来了：你想单独调试哪一块碰撞区域，或者想让某个装饰层做轻微滚动视差，就得把一层分出去，代码里各种操作自己绕来绕去，费劲且容易出错。
Godot 4 干脆把图层概念从"一个节点内部存储多个图层"改成"一个节点就是一个图层"。你是地面就单独建一个 TileMapLayer，你是墙壁就再建一个，你是道具层就继续叠加。节点的职责单一了，编辑器里也直观了：哪个层有什么东西，点开节点树一目了然，不需要再进属性面板来回切图层索引。
从我做小项目的感觉来说，这个改动最直接的收益是避免数据混乱。以前一个 TileMap 里可能混着不同 TileSet 的图块，至少要管理 layer 之间的依赖关系。现在每个 TileMapLayer 里只有一个 TileSet，独立编辑、独立隐藏、独立做程序化逻辑，心智负担小了很多。
2.2 TileSet、TileSetSource、TileSetAtlasSource 的角色分配
很多人一打开 TileSet 资源编辑器就头晕，因为里面层级比想象中多。我们从头捋一遍：
- TileSet：是整个瓦片资源的总入口，里面可以塞多个瓦片源（Source）。
- TileSetSource：瓦片源的抽象基类，最常用的是从图片图集创建的 TileSetAtlasSource。
- TileSetAtlasSource：负责把一张大图（图集）按网格切成一个个小瓦片，并暴露出具体的瓦片 ID 和坐标。
用一个生活化类比：TileSet 是你的衣柜，TileSetSource 是柜子里不同的收纳盒，TileSetAtlasSource 就是其中一个装了透明小格子的收纳盒，每格里放一种图案。
实际操作中，你通常不会直接和 TileSetSource 打交道，而是直接在 TileSet 里添加一个 Atlas Source，选择一张 PNG 图片，设置好每个瓦片的像素宽高。Godot 会自动把图集按网格切好，你在编辑器底部会看到一排排切好的瓦块。这一步是"显示一个瓦块"的前提：如果这里没切好，后面怎么放都会错位。
2.3 单个瓦块和多个 TileSet 层如何搭配
这里我想额外说一句：虽然 TileMapLayer 建议一层一个 TileSet，但同一个场景里完全可以有多个 TileMapLayer 共用同一个 TileSet 资源。比如你有一个"地面与墙壁"的 TileSet，可以建一个 TileMapLayer 画地面，再建一个 TileMapLayer 画墙壁，两个节点共用同一个调色盘。这在场景里非常常见，既保持了图层分离，又不会每个层都要重新配一遍瓦片集。
如果你的项目