直接挂载运行，自动校验4大核心兼容点，报错直接给解决方案，新手秒懂
import { _decorator, Component, Node, TiledMap, resources, error, log } from 'cc';
const { ccclass, property } = _decorator;
@ccclass('MapCheck')
export class MapCheck extends Component {
@property({tooltip: "填resources下tmx路径，无后缀（例：map/test）"})
mapPath: string = "";
start() {
this.checkMapCompatibility();
}
// 一键校验核心逻辑
async checkMapCompatibility() {
log("开始校验Tiled地图兼容性（适配Cocos3.8.0+Tiled1.4.x）");
if(!this.mapPath) {error("请填写mapPath路径！"); return;}
try {
// 1. 加载地图资源校验
const tmxRes = await resources.load<TiledMap>(this.mapPath);
log("✅ 地图资源加载成功");
// 2. 校验核心兼容项（4大必过项）
this.checkFormat(tmxRes);
this.checkLayer(tmxRes);
this.checkTileSet(tmxRes);
this.checkPath();
log("🎉 所有兼容项校验通过，可正常使用");
} catch (e) {
error(`❌ 地图加载失败：${e}`);
log("💡 大概率原因：路径错误/资源不在resources/格式不兼容");
}
}
// 校验1：地图格式（必为XML，禁用二进制）
checkFormat(tiledMap: TiledMap) {
const tmxAsset = tiledMap.tmxAsset;
if(tmxAsset && tmxAsset.rawXml) {
log("✅ 地图格式为XML，符合兼容要求");
} else {
error("❌ 地图格式错误！需在Tiled导出XML格式，禁用二进制/CSV");
}
}
// 校验2：图层（禁用高版本图层，无中文名称）
checkLayer(tiledMap: TiledMap) {
const layers = tiledMap.getLayers();
const invalidLayers = layers.filter(layer =>
layer.name.includes(" ") || /\\u4e00-\\u9fa5/.test(layer.name)
);
if(invalidLayers.length > 0) {
error(`❌ 图层名非法：${invalidLayers.map(l=>l.name)}，需改英文无空格`);
} else {
log("✅ 图层名称+类型符合兼容要求");
}
}
// 校验3：瓦片集（外部引用，无缺失）
checkTileSet(tiledMap: TiledMap) {
const tileSets = tiledMap.getTileSets();
if(tileSets.length === 0) {
error("❌ 瓦片集缺失！Tiled需导出外部tsx，且tmx/tsx/png同目录");
} else {
log(`✅ 瓦片集加载正常，共${tileSets.length}个`);
}
}
// 校验4：路径合法性（无中文）
checkPath() {
if(/\\u4e00-\\u9fa5/.test(this.mapPath)) {
error("❌ 地图路径含中文！需改为纯英文路径");
} else {
log("✅ 地图路径合法");
}
}
}
使用步骤（3步搞定）
-
挂载到Canvas节点，无需额外配置
-
在编辑器属性面板，填地图resources下路径（例map/test，无.tmx）
-
运行项目，控制台直接看结果（红叉报错/绿勾通过）
额外提示
• 报错直接看控制台提示，对应FAQ秒解
• 无需改任何代码，直接用就行