How to contribute?

I’m interested in contributing a feature to Tiled QT, though I’m somewhat unfamiliar with how to contribute on Github. How might I set up a basic workspace on a Windows machine to work with the source?

The feature I’d like to implement would be a UI for embedding images. I’m currently working on a TMX editor/engine for Android and I thought improved embedded image support would make resource management easier since file paths are unlikely to be consistent if a user is working on a map between devices.
Would this be an acceptable contribution?

First of all, great to hear you’d like to contribute to TIled!

You would probably do something like:

  • Fork Tiled on GitHub.
  • Clone your fork to your local machine.
  • Install Qt using the online installer from Open Source Development | Open Source License | Qt. In the installer, I recommend choosing Qt 5.6 for MinGW and also installing the matching MinGW version (in the Tools section).
  • Open tiled.qbs in Qt Creator and start hacking.

I think actually being able to control which images get embedded would be great, but I also think this is a very tricky thing to work on regarding usability. You’d have to consider the workflow, how to make an image embedded and how to un-embed it again. Or should this work as an export feature only?

Also, since this involves tilesets you’re likely to make conflicts with the wip/tilesetdocument branch I’m working on. To avoid this you may want to base your code on that branch instead, but some functionality is currently broken on that branch.

Please feel free to elaborate about your plan or to ask further questions as you go along. I’ll try to help where I can.

I’ll be sure to share some mockup sketches once I’ve done a bit more brainstorming :slight_smile:

If it would be something you are open to, part of my current plan would involve making a small change in the TMX format to allow image elements within the map tag, though I hope to find a solution that would avoid that once I get a bit more familiar with the source.

Regarding the changelog:

Tiled 0.9

Added initial (non-GUI) support for individual and/or embedded tile images (since there is no way to set this up in Tiled Qt but only in Tiled Java or with pytmxlib, this is not very important to support at the moment)

Has there been any further work on the feature since version 0.9, and should I pay more attention to a particular version or branch for reference?

It’s not immediately clear to me what would be the advantage of doing that. What problem are you having that this would solve?

No further work has so far been done on supporting embedded image data.

One thing to note regarding the UI for this. I think it makes little sense to support maps having partially embedded and partially external images, just like it makes no sense to support tile layers having different compression formats within one map. Both of these are supported in the TMX format, but I think there needs to be no way to set this up in the UI.

I’m just partly concerned with how well some mobile devices would handle larger map files; I was thinking that by only embedding images within the map tag it might help avoid duplicate embedded images. Though the more I think about it, I feel like it would just make the format confusing so I’ll avoid it.

Perhaps the Tile Layer Encoding map option could be split into Tile Layer Encoding and Compression to ensure layers and images are compressed the same when saved?

Well, the compression doesn’t apply to image data, since images are stored as PNG or possibly other image-specific formats.

Huh, good to know. I guess that makes sense though since some things may directly be able to handle encoded images.

If I go with the export-only approach, do you think it would also be reasonable to look into adding an export option to bundle external images and tilesets into a .zip or similar archive with the map?

I’m not sure, that depends on whether this would be useful for anybody. I’m having a bit of trouble thinking of a use-case for such functionality. Usually a game already has its own way of shipping the data.

Do you think it would be appropriate to add a security alert when opening a map with embedded content before trying to decode the resources? I kinda just realized the possibility that someone might misuse being able to embed resources…

It might also help if embedded resources are converted to a specific image format and stripped of any metadata before embedding them/after decoding them. If the file can’t be converted then cancel the operation and alert the user - I really need to look more into validating files at the very least.

Edit: Alternatively, validate embedded content on load and only warn the user if there was an error reading the image. I’m not sure which method would be better security wise.

I think there is no point to worry about this specifically in the case of embedded images, because it does not open up additional security problems compared to reading plain image files. Users opening untrusted files should keep their version of Tiled up-to-date with related security fixes, as well as checking the files before opening them. It it usually a pretty rare case.

Well, from a security point of view the risk is in trying to read the image, right? However, the user should obviously be made aware of any problems with reading the image regardless.

The risk I’m mostly concerned with would be users extracting the embedded data and saving it to their drive and the content ends up being malicious, though there’s the option to simply not allow extracting data once it’s embedded if you think that would be reasonable.

I think Tiled only needs to provide an option to save the image to a file again, but then the user gets to choose the format at that point and it is stored based on the raw image data.