Cocos TiledMap入门：从TMX地图制作到对象层与坐标转换实战

如果你做过2D游戏大概率经历过这种场景美术给你一张4000×3000像素的整图你把它拖进场景然后围着它摆几十个碰撞矩形还要在脚本里记录一堆“出生点”“NPC位置”“传送门坐标”。地图稍微大一点或者策划想调整关卡节奏你就得跟美术反复对坐标一天时间就这么没了。后来我改用Tiled编辑器配合Cocos的TiledMap组件彻底把“地图”这件事从代码里拆出去了。TiledMap不是让Cocos帮你画地图而是让关卡设计和程序共用同一份地图数据地图的格子、图块ID、图层、对象、碰撞区域全部存成TMX文件Cocos运行时解析并渲染。这篇文章是“Cocos使用TiledMap总结”系列的第一篇偏基础和整体流程适合刚接触TiledMap、或者已经用但总在图层和坐标上栽跟头的朋友。1. 我为什么放弃手动拼图改用TiledMap1.1 手动拼图的痛只有踩过才懂以我自己的项目为例最早做横版关卡时地图是美术出一张长图我再用编辑器把障碍物、平台一个个拖到对应位置。当时遇到三个问题第一改图成本极高。策划说“把第三块平台往右挪两格”如果美术只改图片我就要重新对坐标如果我在场景里挪节点又要跟美术确认图片是不是“锁死”的。反复几次之后版本里全是“最终版_v7_reallyFinal”。第二碰撞体全靠手摆。一张图几十个碰撞矩形手摆不仅慢还容易漏。特别是平台边缘稍微斜一点矩形和画面之间总有缝隙玩家跳过去时明显感觉“空气墙”。第三逻辑数据没地方放。出生点、怪物刷新点、传送点、可交互物体位置我一般是写死在一个配置表里坐标是像素值。地图一换配置表全作废。TiledMap解决的就是这三个问题地图是“数据”不是“图片”。你在Tiled里看到的每一个格子本质是一个数值也就是GID每块砖、每个碰撞体、每个NPC出生点都是可以被程序读取的对象。改地图只需要改TMX文件代码逻辑不用跟着坐标变。1.2 TiledMap的核心概念地图、图块、图块集、图层、对象第一次接触TiledMap的人容易被一堆术语绕晕。我用一个Excel表格的类比来说地图Map就是整个TMX文件相当于一个Excel工作簿。地图有总尺寸单位是“格子数”比如宽100格、高50格。如果你一定要知道有多少像素用格子数乘以单个格子的像素数就行。图块Tile一个格子里显示的最小单位相当于Excel里的一个单元格。图块集Tileset一组砖块的集合通常来自一张PNG图集。每个图块有一个IDCocos渲染时拿着ID去图集上找对应的图片区域。这相当于Excel里的“颜色编号”单元格里填的是编号显示成什么颜色由编号对应关系决定。图层Layer地图里的层叠关系相当于多个Sheet。一般至少分地面层、墙体层、装饰层。对象层Object Layer不画格子放矩形、多边形、折线、椭圆和图块对象专门用来存逻辑数据比如碰撞区域、出生点、事件触发区域。理解这个划分很重要因为后续所有代码都是围绕“图层”和“对象”来操作的。1.3 Cocos里Tiled的三种接入方式先知道有这些路在不同项目里我见过TiledMap的三种接入方式直接拖场景在Cocos Creator里把TMX资源拖到场景节点上自动生成TiledMap组件。适合关卡固定、量少的小游戏。代码动态加载用resources.load加载TMX资源运行时创建TiledMap组件。适合多关卡、AB包、远程更新场景。远程加载直接从服务器加载TMX。我实际试过并不推荐因为TMX文件内部引用图块集图片时默认是相对路径远程加载后贴图路径对不上经常图片加载不出来。除非你自己封装一套资源重映射否则得不偿失。后面我会重点展开第二种方式因为大部分商业项目不会把地图写死在场景里。2. 在Tiled编辑器里把地图源文件做对后面能省70%时间很多Cocos新手在代码里反复调试最后发现罪魁祸首是Tiled编辑器里的TMX文件本身有问题。地图源文件如果从一开始就配置错Cocos加载后要么黑屏要么碰撞体错位要么图层顺序古怪。这一节说清楚制作阶段的细节。2.1 新建地图这几个参数先想清楚再点确定打开Tiled点“新建地图”时首先要面对四个选项地图方向Orientation、地图尺寸、块大小、图层格式。地图方向直接决定你用哪种美术风格方向类型适用场景Cocos兼容性要注意的问题正交横版、俯视角最好格子是正的坐标计算最简单等角2.5D斜45度视角支持图块遮挡关系复杂坐标换算麻烦六边形战棋、策略兼容性一般格子坐标算法特殊建议谨慎交错很少见兼容性一般不常用我基本没用过我个人90%的项目都用正交地图。不是说等角不好而是Cocos对等角地图的层级排序、遮挡关系处理需要自己多做不少工作尤其在角色从地图下方走到上方时要动态调整节点的渲染顺序这部分不在这篇基础里展开。地图尺寸单位是格子数。比如一张100×50的地图块大小为32像素那么实际像素尺寸就是3200×1600。别把格子数当成像素值去填这是很多人第一次接触时最容易搞混的。块大小Tile Width / Tile Height也很有讲究。常见的是16、32、48、64。块越小美术表现越精细但Cocos渲染时需要的格子数量越多性能压力越大块越大格子数量少但地图看起来粗糙碰到斜坡、圆角时表现力受限。我通常是32或64起步如果一个地块需要更细的局部表现就在装饰层叠加更小的图块而不是把整张地图的块大小调成8。2.2 图块集导入的两种方式内嵌与外链的区别Tiled里导入图块集时会问你是“新建图块集”还是“基于图块集图像创建”。这里有个细节图块集文件可以内嵌到地图里Embed in Map也可以保存成外部TSX文件。Cocos加载TMX时如果图块集是外链的它还要去解析对应的TSX文件。由于Cocos Creator对TSX的支持在不同版本之间有差异我在项目里推荐一个最稳的做法在图块集编辑里勾选“嵌入地图”让图块集数据直接写进TMX文件。这样Cocos只需读一个TMX文件内部引用图片也只剩下相对路径这一层关系大大减少解析出错的可能。同时要注意图块集图片不要用中文名、不要带空格。Cocos在部分安卓真机上对中文路径的资源加载支持不好模拟器正常、真机报错很多时候就是这个原因。2.3 图层规划怎么排决定你后续代码好不好写我见过很多新手在Tiled里建一个图层把所有东西全画上去然后在Cocos里想“怎么让角色走到树后面”——这时候发现自己根本没法把树单独分离出来。在Tiled里建图层时建议按这个顺序从上到下交互层/遮挡层树冠、屋檐、透明墙体等角色在这层下面。装饰层小花、石头装饰不参与碰撞只提升表现。地面层玩家实际行走的地面。碰撞层/对象层通常不画可见图块而是用对象层放矩形或多边形碰撞区。层叠顺序是从上到下显示的最上面的图层渲染时在最前面。Cocos加载TiledMap后图层顺序就是TMX里的顺序你不用自己在代码里重新折腾zIndex但前提是你在Tiled里就规划清楚。另外建议把碰撞信息放在对象层而不是图块层。因为对象层里可以直接画矩形、多边形还能给每个对象加自定义属性。如果你直接把碰撞画成普通图块程序读取时还要判断“哪些GID是障碍”维护成本高很多。2.4 保存和导出TMX前检查这四件事保存TMX之前我习惯过一遍这四项检查基本能避开大部分坑检查图层数确认地面层、装饰层、对象层都在且命名没有大小写差异。Cocos的getLayer是严格按名字匹配的Ground和ground完全不是一回事。检查图块集确认已经勾选“嵌入地图”。如果没勾选把TSX拷进项目时容易漏。检查贴图路径图片和TMX文件的相对路径是否正确。最好让TMX和PNG放在同一个美术素材目录下。检查图层格式Tiled保存时可以选择“CSV”、“Base64”、“zlib压缩”。Cocos对CSV支持最稳定我项目里统一用CSV。Base64或zlib在某些旧版本Cocos上解析会出问题虽然新版本修了不少但没必要冒这个险。3. Cocos加载并正确显示Tiled地图地图在Tiled里做完了接下来就是Cocos侧的事。先说明一下Cocos Creator 2.x和3.x在TiledMap的API上略有差异但整体思路一致。下面以Creator 3.x为主遇到2.x的差异我会单独标注。3.1 资源放置与导入流程拖进编辑器 vs 代码加载在Cocos Creator里最简单的方式是把TMX文件直接拖到场景层级面板。这时会自动创建一个携带TiledMap组件的节点。适合测试界面时快速查看。但真实项目建议用代码加载思路是把TMX文件放到resources目录下的子文件夹里比如resources/maps/。TMX引用的PNG图集也必须一起导入同一个资源系统。在脚本里resources.load拿到TiledMapAsset后动态创建节点并挂TiledMap组件。用代码加载的好处是关卡的入口、卸载、切换都在代码里可控方便做多关卡和AB包管理。3.2 动态加载TMX的具体做法与完整代码下面是一段我在项目中常用的动态加载代码注释写得很细import { _decorator, Component, Node, resources, TiledMapAsset, TiledMap } from cc; const { ccclass } _decorator; ccclass(MapLoader) export class MapLoader extends Component { loadMap(url: string) { resources.load(url, TiledMapAsset, (err, asset) { if (err) { console.error(加载地图失败, err); return; } // 动态创建一个节点用来承载TiledMap组件 const mapNode new Node(Map); this.node.addChild(mapNode); // 挂组件并赋值 const tiledMap mapNode.addComponent(TiledMap); tiledMap.asset asset; }); } }调用时这样写this.loadMap(maps/level1);注意路径不要写.tmx后缀Cocos的resources.load会自动匹配资源类型。Creator 2.x里需要把TiledMapAsset换成cc.TiledMapAsset组件名是cc.TiledMap但整体流程一样。我在迁移项目时基本只改了import的路径和类型名其它逻辑没变。3.3 图层对象访问拿到Layer之后做什么地图加载完成后我们最常做的是拿图层const tiledMap mapNode.getComponent(TiledMap); // 按名字拿图层 const groundLayer tiledMap.getLayer(ground); if (!groundLayer) { console.warn(找不到ground图层); return; } // 拿到图层后可以控制显示/隐藏 groundLayer.node.active false;拿到TiledLayer做什么读取某个格子的GIDgetTileAt(tileX, tileY)判断当前格子是什么砖块。动态改格子setTileGIDAt(gid, tileX, tileY)可以实现挖坑、铺路、机关变化。但是频繁动态改格子会导致地图的批次重建性能下降所以我会避免每帧改一堆格子。控制图层整体颜色/透明度直接改groundLayer.node上的UIRenderer相关属性即可。对象层的获取方式类似const objectGroup tiledMap.getObjectGroup(collision); const objects objectGroup.getObjects();拿到objects后就能遍历出矩形、多边形等数据。这部分是下个章节的重点。3.4 锚点、坐标系和地图对齐最容易翻车的点这里我要专门划一个重点Tiled坐标系的原点在地图左上角Cocos节点坐标的原点在左下角。在Cocos Creator中新建节点的锚点是(0.5, 0.5)这个对普通Sprite没问题。但TiledMap组件加载出来的是一整张“逻辑地图”每个图块的位置都是基于地图左上角计算出来的。如果你把地图节点锚点设在(0.5, 0.5)地图内容会向你意想不到的方向偏移。我的做法是把承载TiledMap的节点锚点设为(0, 0)。将地图节点放在父节点左下角position设为(0, 0, 0)。如果地图要配合摄像机滚动滚动的是这个节点或它的父节点而不是某一层。这样做的好处是地图的左上角正好落在节点原点上后续做像素坐标跟格子坐标的换算是直觉性的不需要反复减宽高。3.5 地图在屏幕上的移动改父节点而不是改层很多新手拿到TiledMap后想实现地图滚动就去移动groundLayer.node的位置。这不是不行但会把事情弄复杂。你要知道TiledMap组件本身不是一张图片而是由多个TiledLayer组成的。移动其中一层会导致层与层之间错位。正确做法是把地图看成一个整体节点移动它的父节点或它自己// 例如让地图向右移动 mapNode.setPosition(mapNode.position.x speed * dt, mapNode.position.y, 0);这样地面、墙体、装饰层一起动碰撞体位置也不用单独修正。后面做坐标换算时只需要把屏幕坐标先转成地图节点的局部坐标再反推格子坐标即可。4. 对象层才是TiledMap最强的隐藏技能很多教程讲完图层就结束了我偏偏要把对象层单开一章。因为在我做过的大部分Cocos 2D项目里对象层承担了至少50%的玩法逻辑——碰撞体、出生点、触发器、传送门都从对象层读取。4.1 对象层的四种对象分别用在什么场景Tiled对象层不是只能画矩形它有这几种常用对象对象类型对应玩法在Cocos里的落地方式矩形碰撞盒、区域触发生成PhysicsBoxCollider或用于矩形重叠检测椭圆圆形碰撞、球形范围生成PhysicsCircleCollider多边形斜坡、不规则碰撞生成多边形碰撞体或用于寻路障碍多边形折线路径点、移动轨迹生成点序列用于敌人巡逻路线图块对象摆放一个图块作为对象一般用于装饰或特殊道具我实际项目里用得最多的是矩形和多边形。矩形用来做墙体、平台碰撞多边形用来做斜坡、河流弯道等不规则边界。如果你在Tiled对象层里画了很多矩形Cocos读取后生成物理体就能免去手动摆碰撞体的痛苦。4.2 从对象层读取出生点和事件区域假设我在Tiled对象层里放了一个矩形对象名字叫spawnPoint并加了一个自定义属性bossId类型是int值是101。Cocos里这样读const group tiledMap.getObjectGroup(objects); const objects group.getObjects(); for (const obj of objects) { if (obj.name spawnPoint) { // obj.x, obj.y 是像素坐标 // obj.width, obj.height 是矩形宽高 // 自定义属性在 obj.properties 或 obj.props 里 const bossId obj.properties ? obj.properties.bossId : 0; console.log(出生点坐标和bossId, obj.x, obj.y, bossId); } }注意不同版本Tiled导出的对象属性存储形式有差别有的版本properties是数组而不是字典。稳妥做法是拿到后先判断类型再取值。如果你用的Cocos版本里obj.properties是数组可以自己封装一个getProp(object, key)函数遍历取出对应键的值。4.3 把矩形对象变成真正能用的碰撞体我最常做的操作就是遍历一个叫collision的对象层把所有矩形对象自动生成为物理碰撞体。这样策划在Tiled里画好关卡边界程序一行都不用改。代码思路const mapSize tiledMap.getMapSize(); // 格子数 const tileSize tiledMap.getTileSize(); // 每格像素 const mapWidthPx mapSize.width * tileSize.width; const mapHeightPx mapSize.height * tileSize.height; const collisionGroup tiledMap.getObjectGroup(collision); if (!collisionGroup) return; const colliderRootNode new Node(Colliders); this.node.addChild(colliderRootNode); for (const obj of collisionGroup.getObjects()) { const colliderNode new Node(obj.name || collider); colliderRootNode.addChild(colliderNode); // 生成矩形碰撞体 const collider colliderNode.addComponent(PhysicsBoxCollider); collider.size new Size(obj.width, obj.height); // Tiled对象坐标以左上角为原点Cocos物理体中心点需要修正 const centerX obj.x obj.width / 2; const centerY mapHeightPx - obj.y - obj.height / 2; colliderNode.setPosition(centerX, centerY, 0); }上面这段代码最关键的就是最后几行。如果不做Y轴修正碰撞体会整体上下颠倒这也是很多新手说“TiledMap碰撞体对不上”的根源。4.4 注意Tiled的Y轴和Cocos是反的我再把坐标翻转这件事强调一次因为它在对象层和网格计算里反复出现Tiled里Y轴向下增长。地图左上角是(0,0)往右x增加往下y增加。Cocos Creator的节点坐标Y轴向上增长。地图左下角是(0,0)往上y增加。所以从Tiled对象层读出来的obj.y指的是“离地图顶部有多少像素”。要转成Cocos里的坐标必须用cocosY mapHeightPx - obj.y - obj.height为什么还要减obj.height因为obj.y是矩形左上角的Y而Cocos里我们通常用节点左下角或中心点来定位。如果碰撞体中心点定位就用上面的centerY公式。记住一个口诀读到Tiled的Y先想清楚你要的是哪个角再减。不然怎么调都不对。5. 坐标换算实战点击地图高亮格子TiledMap项目里坐标换算是高频操作。比如玩家点击地图某个位置角色跑过去比如你在编辑器里策划定的坐标要摆一个宝箱在某个格子上。这里给出几个可复用的公式和代码。5.1 像素坐标与格子坐标的关系像素坐标转格子坐标的公式很简单tileX floor(px / tileWidth) tileY floor((mapHeightPx - py) / tileHeight)其中px, py是地图局部坐标即相对于地图节点左下角的坐标。mapHeightPx是整个地图的高度像素值。为什么要mapHeightPx - py就是因为Cocos的Y向上而地图逻辑格子的Y从顶部往下数。这一步不做你点击最上面的格子会算成最下面。5.2 世界坐标转格子坐标代码实现如果点击的是屏幕你需要先把屏幕坐标转成地图节点局部坐标再转格子坐标// 伪代码按实际版本调整 worldPos event.getUILocation(); localPos mapNode.getComponent(UITransform).convertToNodeSpaceAR(new Vec3(worldPos.x, worldPos.y, 0)); tileX Math.floor(localPos.x / tileSize.width); tileY Math.floor((mapHeightPx - localPos.y) / tileSize.height);这里最大的坑在于localPos是节点左下角为原点的坐标而convertToNodeSpaceAR在某些版本下返回的是以节点锚点为原点的坐标。如果你的地图节点锚点设为了(0,0)那两者一致如果锚点不是(0,0)记得做锚点偏移修正。这也是我前面坚持把地图节点锚点设成(0,0)的原因——它能帮你省掉一系列莫名其妙的偏移。5.3 格子坐标转世界坐标摆宝箱和NPC反过来从格子坐标拿到屏幕位置比如在格子(3,5)上生成一个NPCconst tileW tileSize.width; const tileH tileSize.height; const px tileX * tileW tileW / 2; const py mapHeightPx - (tileY * tileH tileH / 2); const localPos new Vec3(px, py, 0); const worldPos mapNode.getComponent(UITransform).convertToWorldSpaceAR(localPos);加宽高一半是为了把目标点定位到格子中心否则物体摆到格子左下角看起来很别扭。5.4 地图滚动、缩放以后坐标怎么算地图一旦发生滚动或缩放计算顺序就变成屏幕坐标 - 世界坐标event.getUILocation()回来通常已经是UI坐标需要按项目情况转换。世界坐标 - 地图节点局部坐标convertToNodeSpaceAR。局部坐标 - 格子坐标。关键就是第二步只要地图节点不是静止在原点就必须经过convertToNodeSpaceAR转换。我曾经在项目里图省事直接拿屏幕坐标减去地图坐标去算结果地图一切换就全部错位排查了很久。5.5 一个完整的点击高亮格子Demo下面是个常见的实现思路用于点击地图时高亮被点的格子private onMapTouch(event: EventTouch) { const uiPos event.getUILocation(); const local this.mapNode.getComponent(UITransform) .convertToNodeSpaceAR(new Vec3(uiPos.x, uiPos.y, 0)); const tileX Math.floor(local.x / this.tileSize.width); const tileY Math.floor((this.mapHeightPx - local.y) / this.tileSize.height); if (tileX 0 || tileX this.mapWidth || tileY 0 || tileY this.mapHeight) { return; } // 把高亮sprite放到格子中心 const centerPx tileX * this.tileSize.width this.tileSize.width / 2; const centerPy this.mapHeightPx - (tileY * this.tileSize.height this.tileSize.height / 2); this.highlightNode.setPosition(centerPx, centerPy, 0); }注意高亮节点不要直接挂到TiledLayer上最好单独建一个Node放在地图节点上层否则高亮会导致地图渲染批次变更DC上涨得不值得。6. 我从项目里挑出的6个高频问题和排查思路最后这部分是用真金白银换来的。下面这些问题我都在不同版本、不同设备上遇到过据我所知也是TiledMap讨论区里的常客。6.1 地图出现在模拟器上一切正常真机直接白屏真机白屏优先怀疑资源路径。检查三件事TMX文件的路径是否全部小写。Cocos在iOS/Android上对大小写敏感模拟器里不敏感。两个文件名只有大小写不同模拟器能过真机就是找不到。是否有中文名或空格。老实说Cocos对中文路径的兼容性在不同版本之间一言难尽我的经验是素材和代码里一概不用中文避免在打包APK时才暴露问题。地图引用的PNG图集是否已经被打进资源包。如果TMX在resources下但PNG放在resources外打包时PNG可能没进去导致纹理加载失败。真机调试时用resources.load的失败回调查看报错内容十有八九是“Can not find the file”那就是路径对不上。6.2 动态加载之后getLayer一直拿到Null这是新手最常见的报错之一。原因很简单地图还没加载完成就调用了getLayer。resources.load是异步的必须等回调里拿到TiledMapAsset、赋值给组件之后才能获取图层。正确顺序是resources.load(url, TiledMapAsset, (err, asset) { const mapNode new Node(map); this.node.addChild(mapNode); const tiledMap mapNode.addComponent(TiledMap); tiledMap.asset asset; // 到这里之后再getLayer才是安全的 const layer tiledMap.getLayer(ground); });另外检查一下Tiled里图层的名字跟代码里是否完全一致包括空格、下划线、大小写。layer. nameIve never collides? Dont trust. 我在排查时习惯先打印所有图层名const names tiledMap.getLayers().map(l l.name); console.log(names);一眼就能看出是名字问题还是时序问题。6.3 Tiled里看地图好好的Cocos里颜色发黑/发暗通常原因是图块集纹理没有被Cocos正确解析。可能情况PNG图集颜色格式不是常规RGBA部分真机不支持特殊编码。图片路径丢失TMX能找到但图片找不到渲染出来的Tile就是黑色块。图集尺寸过大超出了某些低端设备的纹理上限。Cocos虽然会做压缩但建议图块集单张控制在2048×2048以内不要一张图集上万像素。排查方法在Cocos资源管理器里检查PNG是否成功生成SpriteFrame再检查TMX引用的图片文件名字是否和资源管理器里的名字一致。如果资源导入后名字变了Cocos可能匹配不上。6.4 碰撞体位置和地图画面完全错位这个问题90%是Y轴翻转处理不对另外10%是锚点设错了。排查步骤打印地图实际像素尺寸mapSize.width * tileSize.width和mapSize.height * tileSize.height。先确认地图节点显示尺寸和你以为的尺寸一致。打印对象层里某个矩形的obj.x, obj.y, obj.width, obj.height。核对你的中心点公式是否减掉了宽高。我给自己的检查顺序永远是坐标 - 尺寸 - 中心点修正。如果先用1分钟打日志就能少花一晚上猜错因。6.5 地图节点一滚动格子点击错位滚动地图后点击错位先不要怀疑格子公式先怀疑你是否把地图节点的位移考虑进去了。记住这条铁律所有坐标转换都先经过convertToNodeSpaceAR再做格子计算。如果你发现convertToNodeSpaceAR算出来的局部坐标还是不太对检查地图节点所在的Canvas或UI组件是不是也参与了缩放。有些项目为了适配不同分辨率会在Canvas上加缩放这时候地图节点局部坐标会受UITransform影响需要在转换时传入正确的世界坐标。6.6 大图块集内存占用异常高TiledMap加载后Cocos通常会把图块集整张PNG作为一张纹理加载进显存。如果你的图块集是4096×4096哪怕只用到其中一小块砖内存占用也非常大。解决办法将图块集拆成多张较小的PNG按主题分组。在Tiled里为不同区域建多个图块集减少单张纹理尺寸。配合图集压缩和纹理压缩在原生包发布前检查每种机型的内存占用。如果你做的是大地图、多关卡游戏这一项可以在性能优化阶段重点处理系列后续我会专门写一篇地图性能优化。我个人在实际项目中的体会是TiledMap真正难的部分并不是API怎么调而是地图数据结构的规划——图层顺序、对象层命名、坐标转换约定必须在做第一张地图之前就定下来。很多人用TiledMap觉得坑多往往不是Cocos的问题而是地图源文件从一开始就没有按工程规范来管理。接下来系列的第二篇我会重点写碰撞体自动生成、多关卡无缝切换、原地形动态修改以及TiledMap在大世界项目里的性能优化。如果你也在用Cocos配合Tiled做关卡设计可以先把这篇里的坐标和图层基础消化掉再去碰高级玩法会顺手很多。