[$525 Bounty] Add support for tilemaps made in LDtk (build a parser for .ldtk files)

[Silver-Streak]

Description

Currently the Tilemap object in GD5 only supports Tilemap/Tileset JSON files made by Tiled Map Editor.

As discussed elsewhere, The Level Designer's Toolkit (LDtk) is a newer tilemap editor that has a much more user friendly interface, and allows for much faster iteration than what is available in Tiled Map Editor. LDtk is completely free and available at https://ldtk.io. It is developed by deepnight who is a dev at the studio Motion Twin, who have made a ton of retail games. (Dead Cells being a personal favorite of mine)

While LDtk does support exporting to Tiled TMX, this file cannot be consumed by GDevelop's tilemap objects, so it requires opening it in Tiled then exporting it as a JSON. This also strips some of the more advanced features in LDtk that are greatly beneficial for game development.

Solution suggested

Short-term solution :

• Update GDevelop's tilemap object handling to interpret and support LDtk made maps. LDtk can export as JSON, so a new LDtk specific parser would need to be built (or th current one updated to detect which type of JSON and load it accordingly). LDtk's JSON format is documented here: https://ldtk.io/json/
• This would allow users to use LDtk as their primary map editor outside of GDevelop, and skip numerous steps in the current process as LDtk already embeds tilesets into their files.
  • I would probably recommend this support be for files with the .LDtk extension to not get them confused with Tiled Map JSON files. .ldtk files are just JSON files with a custom extension
  • I'm unsure if it will help, but LDtk's json format is fully supported by Quicktype (https://app.quicktype.io), they give some instructions about that here: https://ldtk.io/docs/game-dev/loading-ldtk-in-your-game/. Quicktype can spit out a Javascript (or C++) interpreter for the JSON with a click of the button. Not sure how easily this will help loading it into the Tilemap object parser.

Long-term solution (outside of the scope of this feature request):

• Fully integrate LDtk into GDevelop as the primary Tilemap editor. This has an open bounty and is under conversation here: [$200+ Bounty] Integrate/Bundle Level Designer Toolkit (LDtk) into GDevelop as a tilemap editor #2352
• Additionally, add support for LDtk's more advanced features such as Worlds (Linking multiple tilemaps), IntGrid layers, and Entity/Enum Support would allow for a lot more flexibility for gamedev (especially all of the Entity Support. It would allow for custom paths/points and could be used for things like enemy paths and other things). This would require the Short-term solution to be implemented first.

Alternatives considered

I thought about asking to support TMX Format files since LDtk can export to that format, but those are in XML and would require a completely different interpreter. It also wipes out a lot of the more advanced features LDtk provides.

Bounty

Learn more about the bounty here: https://www.bountysource.com/issues/97132654-feature-request-add-support-for-tilemaps-made-in-ldtk-build-a-parser-for-ldtk-files

[4ian]

Solution suggested

This is indeed the proper solution that should be implemented. I would add:

• Optionally might be a good idea to upgrade to latest version of pixi-tilemap first (verify it works with the tilemap examples).
• Then implement support for parsing .LDtk (json) files in the Tilemap object (pixi-tilemap-helper.js, so that it works both in the IDE and at runtime). This is the important part where good quality code is required to parse both Tiled and LDtk without dirty hacks.
• Finally add a new ".ldtk" resource to the IDE (I can help if needed).

[blurymind]

Thank you for opening a separate issue. I can pick it up if nobody else wants to give it a try. :) This time we have a good starting point with the helper class. As Florian says it would be a good opportunity to update pixi tilemap

…

On Mon, 15 Mar 2021, 09:19 Florian Rival, ***@***.***> wrote: Solution suggested This is indeed the proper solution that should be implemented. I would add: - Optionally might be a good idea to upgrade to latest version of pixi-tilemap first (verify it works with the tilemap examples). - Then implement support for parsing .LDtk (json) files in the Tilemap object (pixi-tilemap-helper.js, so that it works both in the IDE and at runtime). This is the important part where good quality code is required to parse both Tiled and LDtk without dirty hacks. - Finally add a new ".ldtk" resource to the IDE (I can help if needed). — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#2434 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABRRWVM7XSGYRENWOYGQUU3TDXGLBANCNFSM4ZF7OIMA> .

[Silver-Streak]

Thank you for opening a separate issue. I can pick it up if nobody else wants to give it a try. :) This time we have a good starting point with the helper class. As Florian says it would be a good opportunity to update pixi tilemap

No concerns from me, although I'm not an approver for work on this, so we'll wait on @4ian to chime in.

[4ian]

Feel free to go ahead!

[4ian]

Note though as this will create more maintenance in the future, I expect properly organized and clear code so that it's easy to update in the future. We could also integrate unit test (with .spec.js files)

[blurymind]

So on the topic of file types, I want my extension to take in both a json and an ldtk file as tilemap resource.

Option 1
Now doing that means adding the "ldtk" extension to the json resource type.
There is a downside to that - when you select json files, now the ldtk extension is added to them.
The ldtk file is technically a json file yes,but the extension should let the user filter it out as a tilemap specifically and sepparate it from other json files.

Option 2:
Adding a new resource kind - a tilemap resource, which allows for both json and ldtk files. That way when we open json files we wont be getting ldtk files also displayed in the file chooser.

So for option 2 - do I need to recompile the c++ GD to work? I notice that the 'json' kind is in the source code.
If so I might need help to get that in order to have something working with it. Didnt we have instructions somewhere on how to edit the c++engine and recompile it? If not couldnt you push a change to it to allow for a timemap resource or something - it wont affect the users since it wont yet be exposed to the frontend

I can go with Option 1 for now and we can sort it out later if its more complicated than it seems - since it seems like a polish thing to do anyways.

If I can at least get to properly open ldtk and json files from one field in my extension, I can then focus on the actual parsing.
Btw Option 1 seems easy to do for me without much help, but I'm not sure if its what we want

[4ian]

@Bouh added a "bitmapFont" in the upcoming BitmapText PR so yeah that's the way to go here too: create a "tilemap" resource (that can be a .json or .ldtk).
I.e: option 2

But you can go for option 1 and I can rework the core to have a "tilemap" resource. Then we'll update the extension to have a "tilemap" resource property instead of a resource of type "json".

We should do this btw for yarn json files too. We should rework the actions so that they don't use a "jsonResource" but a "yarnResource" :)

[blurymind]

I really want to go with option 2, but have no idea how to recompile and use the c++part of GD. The bitmapFont commit could inform me how to do the code part, but not the update gd.js part.

I am now developing it on linux, so in theory at least compiling c++ should be easier, right?

is that the pr?
https://github.com/4ian/GDevelop/pull/2432/files

in my case it should be easier since they are all technically a jsonResource

[4ian]

Yes. It's a massive one but you can search for "bitmapFont" everywhere to see.

Anyway, maybe you can concentrate on coming up with a clean and nice parser that adapts well in what we have now, and we can solve this "json" => "tilemap" resource latter :)

I am now developing it on linux, so in theory at least compiling c++ should be easier, right?

Yes, follow the README in the GDevelop.js folder and let me know :)

[Bouh]

is that the pr?
https://github.com/4ian/GDevelop/pull/2432/files

Yes.
I can compile gd.js if needed. Just tag me in the PR i copy the branch and compile and share with you the compiled file.

[blurymind]

no worries, I got it to compile now :) I copy and pasted some boilerplate c++ code to create a TilemapResource, but am yet to see if that did the trick

[blurymind]

Some progress report today:

• I successfully added a new tilemap resource that recognises both ldtk and json file extensions and loads the json data from them.
• added a new levelIndex parameter, since the ldtk file allows for several levels to be stored in a single file. Using levelIndex we can tell GD to only render one level at a time in a tilemap object

[4ian]

Nice! :)

[blurymind]

Some progress today - I got the conditional splitting to two different methods to create the generic tilemapData- based on the file header's key telling GD what application was used to create it.
I am using Ldtk's official examples for testing.

There is still a lot to do before it can get a basic render, but its interesting how the automatically generated tiles are just generated in each tilemap level's layer.

A tilemap layer in it can have a different atlas from the other layers and stores a relative path to that atlas - so I will for sure need to get it to automatically add these image resources in the extension's helper module somehow and not the IDE - that is if we want to be able to render all layers of a tilemap at once- which we most definitely do. For now I am just trying to get it to work with a single one, but will try to tackle that later on.
I wonder if I can pass to it Gd's resources manager and just auto-add these relative path atlases when looping through each layer.

[blurymind]

Some progress today:

I came up with a way to automatically load atlas image resources on a per layer basis - if they are not identified by GD as an existing image resource - they will get added via the resource manager.

Started figuring out how to slice up the tileset for ldtk's tilemap, managed to cache some tileset textures, but I am yet to find out if they are the right rects

[blurymind]

Some progress today, I got it to render LDTK layer! Yay :)

Still lots to do before this can be a pr - there are different types, flipped tiles, etc etc. Thankfully the data structure is kind of nice when compared to tiled's.I had to jump through less hoops to identify the position of tiles because led spells out their position in px - unlike tiled which makes us manually do the math. Same for the slicing of the tileset.
https://ldtk.io/json/
It is kind of competing with tiled really well here - simply because it gives us easier to use data.

Why in the name of crazy bats doesn't tiled do that too? @bjorn ?
I can get rid of a lot of the code for the tiled parsing if we simply had the damned tile src and px coordinates in the exported file.
pixi-tilemap requires these absolute x,y coordinates - both for the tile positions in the tileset atlas and the tile x/y coordinates on the tilemap.

[Silver-Streak]

Yes, looking at the LDtk json format made a ton of sense to me, and I haven't dealt with JSON/Javascript for work in like 4 years. Deepknight did really good work designing it.

Excited to see the continued progress.

[blurymind]

I must say removing all this complexity also results in less fragile code - less things can break. Its just those two values that make a huge difference.

If @bjorn adds them to the output of tiled data - I will be able to remove the nested for loops and all the math expressions to compute where the tile is on the atlas and on the tilemap. That stuff is what makes it fragile

[bjorn]

Why in the name of crazy bats doesn't tiled do that too? @bjorn ?

I think the clear redundancy of the information was the main reason not to include it, especially 17 years ago when the TMX format was introduced. I could certainly consider adding this information, and had actually opened issue mapeditor/tiled#2863 about this last year, which is about including the tile rectangle on the tileset image in the tileset definition.

The same applies to the information storing the location of each tile on a tile layer, which can be almost trivially derived from its index and the grid size. It wasn't "crazy bats" to not include that information, it made perfect sense because including that would have made the files that much bigger and we could no longer just use an array of numbers to store a tile layer (nor compress it). Actually, when exported like this a tile layer would look exactly like an object layer, so maybe we could add an option to export tile layers as object layers?

[blurymind]

@bjorn please consider adding it even if optionally - I dont think it will make it that much bigger. The tiled parser on gdevelop is more prone to break because of all these manual expressions just to evaluate the tile's x,y on the tilemap and on the tileset.

Having it will allow me to remove these nested for loops and expressions - ultimately resulting in much cleaner code and less computation needed for gdevelop to do when parsing the data. I didn't realise what a huge difference this makes until writing a parser for ldtk.

You are sort of adding tons of complexity to the engine's parser by omitting that data from the export just to save a few bites.
You are correct that it made more sense 17 years ago, but today even a simple smartphone with bad internet connection will have no problem with it

[4ian]

@blurymind Please be careful about your wording and the way you address people on what is technical considerations. It is poor form to tag multiple times someone that has been making what is a great product for years just to hit on a way some data is formatted.
I know it's not your intent, but this can really be lived as a micro agression for someone to be tagged on some other project just to read that the way your project formats data has some "crazy" and "damned" choices. These things can cause severe burn out, especially in the open-source world.

As with every product, technical decisions and choices, there are advantages and disadvantages. Not only 17 years ago it was a right decision, it was also a very clever one and probably helped a lot of games perform correctly and save memory.
It's certainly now less usual to store flags like this in bits of an integer, and it's certainly a good idea to suggest an alternative way that make the parsing less painful :)

But it's our decision and responsibility to own this parsing in GDevelop:

• Either we decide we can support it, as we already do. It's a bit painful but ok once you understand bitwise operators in JS.
  • We can always add unit tests to make sure it's robust.
  • And we can open or vote on the Tiled GitHub issues to advocate for a format that would avoid this complexity.
• Or we decide it's too complex and don't support Tiled format.
  • We can make the feedback on the Tiled GitHub issue of course.

But remember that you may not have the full picture behind a choice, the legacy/technical considerations at the time or now, or missed an actual advantage of a specific format. So let's refrain from tagging and being too harsh at people especially at contributors from other projects :)
The proper etiquette would be to say in an issue "We've identified things are more painful than what they could, so I suggest this approach instead. It may have drawbacks (more bytes, redundancy of information, etc...), but also some advantages (easier parsing). It would be helpful for us (GDevelop) but also surely for other games".

Again I know the intent was not bad, but still, these things are important :) We're the one choosing to support Tiled format, so we must own it.

[blurymind]

ah sorry, there was no bad feelings,I was trying to say it jokingly but it came out bad. I shouldn't have tagged Bjorn here, just wanted to bring it up because some bugs cropping out can be fixed in theory in a better way if we can get the coordinates directly.
My current tilemap bugfix pr for example can really work much better with that data available

Yes indeed tiled is a fantastic editor and it is still the most popular out there, just bringing this up with hope to put some light into how this data can improve its adoption even more.

I love the both tiled and ldtk and supporting both is important to me

[blurymind]

Just to be more specific,this PR here
#2296

Its not fixing the problem completely and the tilemap still has corner cases where rendering has issues. If we can get the x,y values - this will let me fix it in a much better way with no corner case issues.

Just out of the box Ldtk will not have these problems with pixi-tilemap because of that. Complicated code leads to higher chance of corner case bugs and having these x,y values will lead to much cleaner and bug free parsing for pixi-tilemap. Tiled parsing can also benefit from this when x,y values are included in the json file

[Silver-Streak]

Just out of the box Ldtk will not have these problems with pixi-tilemap because of that. Complicated code leads to higher chance of corner case bugs and having these x,y values will lead to much cleaner and bug free parsing for pixi-tilemap. Tiled parsing can also benefit from this when x,y values are included in the json file

If LDtk doesn't have the issue OOTB, and your PR fixes most use cases, along with the eventual goal of integrating LDtk as a native editor, I think the edge cases could be reasonable, to the point where we can just document it and treat it as a minor compatibility issue rather than having it continue to take more and more of your available hours trying to fix.

Obviously, I have no say in any of the above, it just seems like the best path forward as an outside observer.

[blurymind]

Some progress today - I got it to render all ldtk layers,apart of entities, which I am not sure if we will support.

One limitation of pixi-tilemap atm is the inability to render semi-transparent tiles. I might do a PR to pixi-tilemap to add that some time in the week, as the shadow layer of the ldtk example project looks really ugly without it.

There was a pr before, but it was abandoned before it could be merged
pixijs/tilemap#88

I will try to redo it and get it in before we upgrade pixi tilemap.Might as well address more of its limitations while at it. I believe tiled also has opacity on layers, so we do need it for both formats

[blurymind]

Ok so there is a huge refactor between pixi-tilemap for pixi v5 and v6 and in order to add opacity to tiles, gdevelop will need to be on pixi v6.

In essence, I cannot upgrade pixi-tilemap in gdevelop until gdevelop is not upgraded to pixi v6.

The commits to pixi-tilemap-v5 seem to have stopped for since almost half a year ago.

I need this to get in before I can work on improving pixi-tilemap to support opacity for opacity on layers in gdevelop
#2447

I guess I can still work on it for v6,it just wont be in GD until we are on v6

[4ian]

Ah nice, is the rotate something built recently in pixi tilemap?

In any case dealing with entities with variables from tiled and ldtk needs its own pr/issue and could be tricky to get right imo.

Yes, entities should be indeed a separate concern.

An action to get entities variables translated into an object is probably a good idea though, but that's for another day.

[Silver-Streak]

Discussion on handling entities created: #2836

[blurymind]

Ah nice, is the rotate something built recently in pixi tilemap?

I believe @ivanpopelyshev added it in the end of 2019
pixijs/tilemap@54ebaa3

Will it be ok if I also add support for varied animation speed in tiles for tiled format in the same pr? I recently added it to pixi-tilemap, so I am a bit eager to get that in the extension. When ldtk gets that at some point, it will also be easy to add.

I want to take advantage of all of pixi-tilemap's options

An action to get entities variables translated into an object is probably a good idea though, but that's for another day.

In any case dealing with entities with variables from tiled and ldtk needs its own pr/issue and could be tricky to get right imo.

Yes, entities should be indeed a separate concern.

Yes absolutely. Its a design task that has lots of caveats which need to be discussed in advance.
@Silver-Streak thanks :) whatever we implement for entities will need to work with both tiled and ldtk in a consistent way- so its good to start thinking about how it would work sooner than later.

I see some overlap of dealing with entities and collisions from both apps, but they are very different in my head

[blurymind]

Some progress today, added ability to render tilemap backgrounds

with that all rendering features from Test_File_For_Api_showing_all_features.ldtk from ldtk's samples now work in the runtime and the IDE. The ide still doesnt render entities - but I think that should be done in the entities task.

The example file has these bits that dont contain any actual textures:

@deepnight are they supposed to render in the runtime of the game? I suppose I can make them only render in the IDE if they are required. I am thinking of doing that for entities - only render entities in the IDE

Btw this is how easy it is to set up switching between levels contained in a single ldtk file

[MorphicDreamer]

still open?

[Silver-Streak]

still open?

Yep! #2828

You can see active/linked pull requests at the bottom of any open issue.

[MorphicDreamer]

still open?

Yep! #2828

You can see active/linked pull requests at the bottom of any open issue.

Upon looking I noticed that another dev is currently writing a fix.

[Silver-Streak]

This has neared another birthday, and people are asking about this again on discord and the forums.

I've bumped up the bounty on this and the ldtk integration/bundling to hopefully renew drive/interest.

[daiyam]

Hello, is the bounty still active?

[Silver-Streak]

It is. The original person working on it has unfortunately gone silent. You can review their incomplete PR here, but you'd likely want to start from scratch as they were running into rodeblocks with the method they were working on.

I'd recommend reviewing and writing up a proposal on how you'd want to proceed, and one of the mainline devs can review and give you a green light. That way you don't waste to much time building something out if it'll just run into the same roadblocks.

[daiyam]

I've made some progress.
Since that PR, the TileMap has been rewritten so I couldn't used it. I had to restart from "scratch". But it is/was still useful.

Here are my 3 main issues:

• How to load the resources? I would like to automatically import the tilemap and all its resources when the tilemap is added. This will avoid the force the user to manually import all the resources.
• LDtk allows for different grid sizes to used in the same scene. For now, should we have only 1 size?
• What about the collision map? Should it be another object or have dropdown to select the collision layer?

[daiyam]

Here what I have so far:

I'm having an issue with the shelfs in background because they are half step (x=8.5, y=10) on the grid. I'm not sure what to do...

[Silver-Streak]

I'd wait for one of the main contributors/devs to chime in, but I don't think Tiled supports floating positions either, so I don't know that there's a hard requirement to have the ldtk file support non-integers even if the base app does.

This is just my opinion on it, though.

[daiyam]

@Silver-Streak I've just tested. When exported from LDtk to Tiled, the shelves are shifted. I can do that.

[4ian]

@daiyam That looks like great progress :)
On your issues, here is my thinking:

How to load the resources? I would like to automatically import the tilemap and all its resources when the tilemap is added. This will avoid the force the user to manually import all the resources.

That's the hard bit. The current resource system is basically one file = one resource (there are no "meta resources" linking to more than one file). How do you work currently? Do you ask for all resources manually by the user? Did you hardcode their loading?

Depending on what it looks like currently (or if we can look at the code directly), we can think of how to make this user friendly.

LDtk allows for different grid sizes to used in the same scene. For now, should we have only 1 size?

I guess so, we can add support for this later?

What about the collision map? Should it be another object or have dropdown to select the collision layer?

@D8H created a "Tilemap collision mask" object - I think ideally we should use it:

This is because this allows to have different objects, one for platforms, one for jump thrus, etc...
For the user, this means they would use their ldtk file for the tilemap object and reuse it again for the "Tilemap collision mask" object.

[daiyam]

How do you work currently?

For I've changed the tilesets.relPath to SunnyLand_by_Ansimuz-extended.png then added a resource with the same name...
I haven't done any work on how to load the resources since I knew you had some reservations to add new way to load resources. I want to validate with you before to make the needed changes.
So I was more thinking that when adding a LDtk map, the editor will parse it and locate all the files and import all those files to the project as resources and then, rewrite the json with the corresponding resource ids.

@D8H created a "Tilemap collision mask" object - I think ideally we should use it:

I will look into that

---

LDtk has floating tiles. Now, they are rounded to the lower integer (like LDtk does when exporting for Tiled).

[daiyam]

All the levels:

[Silver-Streak]

Just to clarify, LDTK doesn't currently natively have a collision layer of any kind. I suppose you could have it pick up x/y point entities (or enums) named in a certain way to have them mapped to collision polygons?

(Deepmind has collision and geometry handling on the roadmap, but I don't think there is any design around it done yet)

[daiyam]

@Silver-Streak true, I was misled by their example (a layer is called Collisions). Some grass and the ladders are that layer...

[Silver-Streak]

Yeah, with no current native collision support, I'd be interested in @D8H 's feelings on whether to map collisions to LDTK files at all before official support.

Even with an x,y (point) entities layer, the layer would have to be a different grid size (likely 1x1) to be used for collisions accurately, which would require supporting different grid sizes.

[daiyam]

which would require supporting different grid sizes.

LDtk does support that. That was one of my question.

I will wait for @D8H's inputs.

---

I was finally able to compile GDevelop.js, GnuWin was messing up the previous attempts... (or I was using Powershell or bash)

[D8H]

If you mean layer grid offsets, the extension doesn't handle it for Tiled. I don't think it's mandatory. It can be done in another PR.

[Silver-Streak]

If you mean layer grid offsets, the extension doesn't handle it for Tiled. I don't think it's mandatory. It can be done in another PR.

To be clear, layer grid offsets and collisions both could be handled in another PR, correct?

[D8H]

To be clear, layer grid offsets and collisions both could be handled in another PR, correct?

Correct

[daiyam]

I'm having an issue with adding a new TilemapResource for supporting .ldtk files.
I can get it working and all but then, the old tilemap resources which are mapped to JsonResource can't be reassigned anymore.
The old tilemap are correctly displayed but if you remove the property from the object and re-add it, you get an error!

What to do? New object type?

[daiyam]

I've pushed my PR. I made some substantial changes so you might have some concerns...