深入解析LDtk项目JSON结构(1.5.3版本)

深入解析LDtk项目JSON结构(1.5.3版本)

ldtk Modern, lightweight and efficient 2D level editor 项目地址: https://gitcode.com/gh_mirrors/ld/ldtk

项目概述

LDtk是一款优秀的2D关卡编辑器，其项目数据采用JSON格式存储。本文将详细解析LDtk 1.5.3版本的JSON数据结构，帮助开发者更好地理解和处理LDtk项目文件。

1. 项目根结构(ProjectJson)

项目JSON文件的根结构包含以下核心内容：

1.1 基础信息

• bgColor：项目背景色，使用十六进制颜色码表示(如"#rrggbb")
• jsonVersion：文件格式版本号
• iid：项目的唯一标识符

1.2 关卡与定义

• levels：包含所有关卡的数组，顺序在"LinearHorizontal"和"LinearVertical"布局中才有意义
• defs：项目定义集合(大多数用户可忽略)
• externalLevels：若为true，项目将保存为主文件+各关卡子文件的形式

1.3 世界布局

• worldLayout：关卡组织方式枚举值，包括：
  • Free：自由布局
  • GridVania：网格布局
  • LinearHorizontal：水平线性布局
  • LinearVertical：垂直线性布局
• worldGridWidth/worldGridHeight：网格布局下的世界网格尺寸(像素)

注意：这些布局相关字段将在"多世界"更新后移至worlds数组中

1.4 多世界支持

• worlds：启用"多世界"功能后，此数组包含所有世界数据
  • 每个世界有自己的关卡数组和布局设置
  • 目前版本默认只包含一个世界

2. 世界结构(WorldJson)

世界结构是1.0.0版本新增的预览功能，包含：

• identifier：用户定义的世界唯一标识
• iid：世界实例唯一ID
• levels：该世界包含的所有关卡
• 布局相关设置：
  • worldLayout：世界布局类型
  • worldGridWidth/worldGridHeight：网格尺寸
  • defaultLevelWidth/defaultLevelHeight：默认关卡尺寸

3. 关卡结构(LevelJson)

关卡数据有两种存储方式：

1. 嵌入主项目JSON文件(默认)
2. 单独保存在.ldtkl文件中(启用"Separate level files"时)

3.1 基础属性

• identifier：关卡唯一标识
• iid：关卡实例唯一ID
• __bgColor：关卡背景色
• bgRelPath：背景图片相对路径(可选)

3.2 相邻关卡

• __neighbours：相邻关卡数组，包含：
  • dir：相对位置(n/s/w/e等)
  • levelIid：相邻关卡实例ID

3.3 实例数据

• fieldInstances：关卡自定义字段值数组
• layerInstances：所有图层实例数组
  • 当使用单独关卡文件时，此字段为null

4. 编辑器专用字段

这些字段仅供LDtk编辑器使用，包括：

• 备份设置：backupOnSave, backupLimit
• 导出设置：exportTiled, imageExportMode
• 默认值：defaultGridSize, defaultEntityWidth等
• 项目标识：appBuildId(生成项目的LDtk版本)

最佳实践建议

1. 多世界兼容性：即使当前不使用多世界功能，也应考虑未来兼容性，正确处理worlds数组

2. 关卡加载：检查externalRelPath判断是否需要加载单独关卡文件

3. 相邻关卡：利用__neighbours实现游戏场景导航或关卡切换

4. 自定义字段：通过fieldInstances访问关卡特定数据

5. 版本控制：关注jsonVersion确保兼容性

通过深入理解LDtk的JSON结构，开发者可以更好地集成LDtk项目到游戏引擎中，实现高效的关卡加载和数据处理。

ldtk Modern, lightweight and efficient 2D level editor 项目地址: https://gitcode.com/gh_mirrors/ld/ldtk