最后同步日期：2026-04-15 | Godot 官方原文 — TileMap

TileMap

节点继承关系

继承链：Node -> Node2D -> TileMap

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

瓦片地图——用"瓦片印章"在网格上盖出 2D 关卡。

生活比喻：想象一个印章垫。你有一个印章板（TileSet），上面刻着不同的图案（草地、石头、水）。TileMap 就是一张盖了章的纸——你选好印章，在网格的某个格子里"啪"一下盖上去，这块瓦片就放好了。整张地图就是一格一格盖出来的。

TileMap 是一个多层容器，一个 TileMap 节点内部可以包含多个图层（比如地面层、装饰层、碰撞层），每个图层都是一张独立的瓦片网格。

节点用途

用瓦片拼出 2D 关卡，支持多个图层。内存省、编辑快、支持碰撞和导航。

具体来说，TileMap 能做这些事：

• 摆放瓦片：在网格的指定坐标放上你选好的瓦片
• 多层管理：地面放一层、树和花放一层、碰撞信息放一层，互不干扰
• 碰撞检测：瓦片本身可以携带碰撞形状，角色走上去会自动碰撞
• 导航网格：瓦片可以自动生成导航区域，敌人 AI 能沿路径行走

使用场景

• 2D 平台跳跃游戏的关卡（如《超级马里奥》的地图）
• RPG 世界地图（如《宝可梦》的城镇和草丛）
• 策略游戏的地形网格（如《文明》的六角格地图）
• 塔防游戏的地图布局
• 像素风格的室内场景

常用节点搭配

节点	用途	是否必需
TileSet	瓦片集合资源（定义每块瓦片的图片、碰撞等）	是
TileSetAtlasSource	瓦片图集源（把一张大图切割成多块瓦片）	可选
TileSetScenesCollectionSource	用场景做瓦片（比如一整棵树作为一个瓦片）	可选
CollisionShape2D	给瓦片地图整体加碰撞形状（通常不需要，瓦片自带碰撞）	很少需要

生效必备素材/资源

资源	类型	说明
TileSet	TileSet	瓦片集合——定义每块瓦片长什么样、有没有碰撞、能不能走
瓦片图集图片	Texture2D	一张大图，里面画好了所有瓦片图案，引擎会自动切割

注意

没有 TileSet 资源的 TileMap 就像一个没有印章的印章垫——什么也盖不出来。你必须先创建一个 TileSet 资源，把瓦片图片添加进去，然后赋给 TileMap 节点。

节点属性与信号

瓦片属性

属性	类型	默认值	继承自	说明
tile_set	TileSet	null	—	使用的瓦片集合资源（核心属性，必须设置）
rendering_quadrant_size	int	16	—	渲染分块大小，值越大渲染批次越少但精度越低
collision_visibility_mode	int	0	—	编辑器中碰撞形状的显示模式
navigation_visibility_mode	int	0	—	编辑器中导航区域的显示模式

变换属性

属性	类型	默认值	继承自	说明
position	Vector2	(0,0)	Node2D	相对父节点位置
rotation	float	0.0	Node2D	旋转角度（弧度）
scale	Vector2	(1,1)	Node2D	缩放

常用信号

信号	参数	说明
changed	—	瓦片地图内容发生变化时触发

常用方法

方法	返回值	说明
SetCell(layer, coords, sourceId, atlasCoords)	void	在指定图层的指定坐标放置瓦片
GetCellTileData(layer, coords)	TileData	获取指定坐标的瓦片数据（包含碰撞、自定义属性等）
EraseCell(layer, coords)	void	擦除指定坐标的瓦片
GetUsedCells(layer)	Array	获取指定图层上所有已放置瓦片的格子坐标
GetUsedCellsById(layer, sourceId)	Array	获取指定图层上使用了某个瓦片源的所有坐标

代码示例

C#

using Godot;

public partial class MyTileMap : TileMap
{
    public override void _Ready()
    {
        // 在第 0 层的坐标 (3, 5) 放置瓦片
        // sourceId = 0 表示第一个瓦片源
        // atlasCoords = (1, 0) 表示图集中的第 2 列第 1 行
        SetCell(0, new Vector2I(3, 5), 0, new Vector2I(1, 0));

        // 读取这个位置的瓦片数据
        TileData data = GetCellTileData(0, new Vector2I(3, 5));
        if (data != null)
        {
            // 读取自定义属性 "walkable"（是否可行走）
            Variant isWalkable = data.GetCustomData("walkable");
            GD.Print($"位置(3,5)是否可行走: {isWalkable}");
        }

        // 擦除这个位置的瓦片
        EraseCell(0, new Vector2I(3, 5));
    }
}

GDScript

extends TileMap

func _ready():
    # 在第 0 层的坐标 (3, 5) 放置瓦片
    # source_id = 0 表示第一个瓦片源
    # atlas_coords = (1, 0) 表示图集中的第 2 列第 1 行
    set_cell(0, Vector2i(3, 5), 0, Vector2i(1, 0))

    # 读取这个位置的瓦片数据
    var data = get_cell_tile_data(0, Vector2i(3, 5))
    if data:
        # 读取自定义属性 "walkable"（是否可行走）
        var is_walkable = data.get_custom_data("walkable")
        print("位置(3,5)是否可行走: ", is_walkable)

    # 擦除这个位置的瓦片
    erase_cell(0, Vector2i(3, 5))

新手建议

在实际开发中，瓦片通常是在编辑器里用鼠标画的，而不是用代码一个个摆。代码方式适合做程序化生成（随机地图）或者运行时动态修改（比如炸药炸开一堵墙）。