Godot LDtk C# Importer

Godot 4 C# LDtk 导入插件

⚠️ 目前该插件仍处于开发阶段，许多特性还处于调整中，请勿将本插件应用于生产环境！在使用本插件前，请确保已经对项目文件进行备份！

📖 安装

1. 使用C#版Godot 4.2+
2. 将addons\LdtkImporter目录放到项目的addons目录下
3. 通过 Project > Project Settings > Plugins开启本插件
4. 此时.ldtk文件可以被Godot识别，并且会自动导入，并生成对应的.tscn场景资源和.tresTileset资源

✨ 特性

🌏 World

• [x].ldtk文件导入后生成同名的.tscn场景，内部包含所有的关卡节点 ⬇️

🏔️ Level

• LDTKLevel导入后，生成同名的关卡场景 ⬇️
• 关卡场景独立导出为.tscn文件

📄 Layer

• AutoLayer、IntGrid类型Layer生成为Godot TileMap，Entity类型Layer生成为Godot Node2D
• 支持将 IntGrid 作为子节点生成 ⬇️

• 支持同一个Layer下多个Tile叠加

🧱 Tilesets

• 为每个 LDTK Tilesets 生成 TileSetAtlasSource 样式的 Godot Tileset
• 支持 Tile X轴/Y轴翻转，并为其生成专门的 AlternativeTile

🐸 Entity

• 为每个Entity生成一个

🚩 导入选项

当在Godot的FileSystem选中一个.ldtk文件时，可以看到如下图所示的导入选项： ⬇️

• General
  • Prefix: 该前缀表示当执行导入时，生成的 Node2D、TileMap等节点的名称前缀（例如：LDTK_World_Level_0）以及导入的元数据的名称前缀
• World
  • Post Processor: 导入后置处理器，可以通过后置处理器对导入后的节点进行自定义处理
  • World Scenes: 表示要生成的世界场景的文件名称
• Tileset
  • Add Tileset Definition to Meta: 将所有 LDTK Tileset definition数据作为元数据存储到Godot tileset中，其中元数据的key为：${Prefix}_tilesetDefinition，例如：LDTK_tilesetDefinition
  • Resources: 根据LDTK中Tilesets的不同，插件自动生成对应的配置
• Entity
  • Post Processor: 导入后置处理器，可以通过后置处理器对导入后的节点进行自定义处理
  • Add Entity Definition to Meta: 将LDTK Entity Definition数据作为元数据存储到导入后的Entity Scene以及节点中，其中元数据的key为：${Prefix} _entityDefinition，例如：LDTK_entityDefinition
  • Add Entity Instance to Meta: 将LDTK Entity Instance数据作为元数据存储到导入后的Entity节点中，其中元数据的key为：${Prefix}_entityInstance，例如：LDTK_entityInstance
  • Scenes: 根据LDTK中Entity的数量，插件自动生成对于的配置
• Level
  • Post Processor: 导入后置处理器，可以通过后置处理器对导入后的节点进行自定义处理
  • Add Level to Meta: 将LDTK Level数据作为元数据存储到导入后的Level节点中，其中元数据的key为：${Prefix}_levelInstance，例如：LDTK_levelInstance
  • Add Layer Instance to Meta: 将LDTK Layer Instance数据作为元数据存储到导入后的Layer节点中，其中其中元数据的key为：${Prefix}_layerInstance，例如：LDTK_layerInstance
  • Add Layer Definition to Meta: 将LDTK Layer Definition数据作为元数据存储到导入后的Layer节点中，其中其中元数据的key为：${Prefix}_layerDefinition，例如：LDTK_layerDefinition
  • Import Int Grid: 是否导入IntGrid，效果参考Layer中动图展示
  • Scenes: 根据LDTK中Level的不同，插件自动生成对应的配置

❓FAQ

LDTK支持在同一个Layer内的同一个位置堆叠多个tile instance，当导入到Godot时，是如何处理的？

Godot TileMap支持创建多个 Layer ，在导入时，插件会算出当前Layer的最大堆叠数量并在TileMap中提前将这些Layer创建出来，同时还会更新每个 tile instance 在TileMap中的Layer图层索引。在真正执行导入时，已经就知道每个LDTK tile instance归属于哪个TileMap Layer。一句话总结：通过Godot TileMap支持多Layer的特性解决堆叠问题。

如果使用该插件作为LDTK和Godot的桥梁，那么工作流应该是怎样的？

本插件作者一直在思考该问题，且还没要找到完美的解决方案。在LDTK和Godot结合的工作流中，LDTK的主要作用地图编辑器，然而并不能在LDTK中完成所有的地图编辑工作，例如需要为TileSet 配置物理碰撞、导航时，也有可能在导入后对tscn场景进行编辑修改。这导致了一个核心矛盾点的产生：如何解决重复导入而不影响在Godot中所做修改。，目前有一个初步想法：

1. 不支持重复导入，每次导入都覆盖原来的资源（Tileset、Scene）
2. 支持重复导入
   1. 在导入时，假如原资源（Tileset、Scene等）已经存在，在原数据的基础上修改
   2. 通过前缀名区分节点是用户节点还是LDTK节点，也用来区分是用户元数据还是LDTK元数据

目前插件选用的是方案1的思路，如果有更好的思路，欢迎一起探讨！

如果需要扩展导入后置处理器，要如何操作？

1. 首先需要实现AbstractPostProcessor，类似如下所示：

   [Tool] //1. 必不可少
   [GlobalClass] //2. 必不可少
   [PostProcessor(ProcessorType.World)] //3. 本后置处理器的类型，可以进行组合，例如：[PostProcessor(ProcessorType.World | ProcessorType.Level)] 
   public partial class MyWorldPostProcessor : AbstractPostProcessor
   {
       public override Node2D PostProcess(LdtkJson ldtkJson, Dictionary options, Node2D baseNode)
       {
           //对baseNode进行处理，可以仍然返回baseNode，也可以返回一个全新的Node2D或其子类
           return baseNode;
       }
   }

2. 需要在FileSystem中新建一个MyWorldPostProcessor类型的资源，并保存扩展名为：.tres，该后置处理器会自动添加到导入选项中

💣 TODO

• 运行时
  • 支持运行动态修改IntGrid，并根据 LDTK Auto-layer rule definition 实时更新并渲染受影响的IntGrid和AutoLayer
• World
  • 导入后处理脚本支持
  • LDTK 默认Level背景色支持
  • LDTK Multi-worlds 支持
• Level
  • 支持Level背景色和背景图的导入
  • LDTK Level fields支持，元数据名称为：$"{prefix}_fieldInstances"
  • Level 导入后处理脚本支持
  • 支持Level配置开关：是否生成独立的Level场景
• Entity
  • Entity视觉显示支持（Sprite2D）
  • Entity导入后处理脚本支持
  • Enum支持
• 文档
  • 增加后置处理器扩展说明

🐞 已知BUG

• 每次重新导入后，需要重新Reload Current Project或重新打开Godot后，导入的.tscn才会生效
• 每次重新导出时，导出的tscn文件都有变化（主要是Level场景的id发生变化）
• 当IntGrid不包含rules时，生成的TileMap节点中没有包含TileSet，并且也没有正确设置tile
• 官方示例：Typical_TopDown_example.ldtk，导入后，某些Tile会缺失
• 目前导入后，没有为Level设置背景色
• 打开某些导入后的场景和Tileset后，会导致Godot闪退（例如：Typical_TopDown_example.ldtk）