Tiled Projects

[griest024]

Apologies if this is a duplicate issue. It is at least partially duplicated by a number of issues (#945, #233, #70). However many of those issues are quite old and don't pertain to Tiled 1.x. In addition, those issues bring up a number of good ideas but I think it would be good to bring them together in one place and codify them into a concrete proposal.

Proposal

Tiled should have projects.

Data Structure

A project is a data structure that can be dumped to a .json file or an XML-based file similar to .tmx.

A project contains a number of fields including:

"Orphan" Data

Data that doesn't belong to any particular data structure such as

• Commands
• Object types

Note on orphan data merge strategy: I think it still makes sense to have globally defined commands and object types available in projects. In the case where there is a conflict, the project data should take precedence.

Session Data

Edit: After looking at this again, it doesn't make sense for session data to be kept in a project file. It should instead be kept in some kind of workspace file, similar to the behavior of sublime text and other IDEs.

Data that describes the state that the project was last in

• Open files: which files are open as tabs
• Current file: which file is currently being edited
• Current file history: the edit history of the current file (possible performance concerns)
• Currently selected object, tile, map, or tileset whose properties are displayed

Directory Data

Paths relative to the project file that define a number of important directories including

• Image directory: if this is defined, all paths pointing to images (like in tilesets) are relative to this directory.
• Tileset directory: if this is defined, all paths pointing to tilesets (like in maps) are relative to this directory.

File Data

Paths relative to the project file that point to files included in this project.

• Tilesets
• Maps

Miscellaneous Data

• Custom properties: similar to other data structures, a project should allow for custom properties

UI

Along with the project data structure, this proposal includes UI changes. These changes make it easier to interact with the project data structure and its members directly.

Project Properties

A project should enumerate its members in the property browser, similar to other data structures (map, tileset, etc.)

Project Browser

The UI should include a new panel (widget?) called the project browser. This panel is an accordion, and lists the 4 major components of a project: maps, tilesets, commands, and object types. Each accordion section includes a list with multi-select capability.

An asterisk denotes that a file has unsaved changes, like the tab.

Map and tileset list items should have a context menu with the following items whose functions are identical to those in the file submenu:

• Open
• Export (This would effectively close Batch Export #1117)
• Export As...
• Save
• Save As...

In addition to the above options, the context menu should also include:

• Remove from Project: removes the file from the project
• Delete: removes the file from the project and then deletes it.

Project Menu

When a project is open, a project menu section should be present. This would be consistent with the menu design for other top-level data structures.

Behavior

Add Files to Project

There are several important considerations when designing this feature. A user may want to try out an idea in a new map, but doesn't want his/her project polluted with files they don't intend to use. On the other hand, manually adding files to a project may get tedious, and having open files that are not part of the project goes against the philosophy of a project.

Option 1: Automatically Add Files on Open

When a map or tileset file is opened by any means, it is added to the currently open project, if there is one and if it has not already been added. This option will probably include the fewest number of UI changes.

Option 2: Manually Add Files

An option must be manually selected in order to trigger the adding of a file to a map. This will include adding context menu options to the tabs and to the map file browser as well as options to the main menu bar.

Option 3: User Configurable

Whether or not files are automatically added is manually configured by the user.

Option 4: Monitor Directory

Tiled monitors the tileset and map directories (if present) for compatible files. This option seems difficult to implement and prone to bugs. There are also some performance concerns, though they could be remedied by caching files and/or only checking the type field for an appropriate value.

Curating File Data

When project content, such as a map or tileset, is not at its specified location, the user should be given the choice to locate the file or remove the file from the project.

Advantages

• Switching between large batches of related maps and tilesets is as easy as opening a single file.
• Collaboration on games is easier, as commands and object types can be shared and version controlled.
• File size is reduced (especially in collection tilesets) as paths can be shortened.
• Changing directory structure of your tilesets or images does not pwn your files, as the change can be reflected in a single change of the relevant directory data in the project.

[bjorn]

Thanks a lot for opening an issue about this and summarizing in such extensiveness the uses of a project file! Indeed, this is something I've been wanting to add since a long time already and if I don't have time for it for Tiled 1.1 (which is planned to contain all the work from the GSoC students), then it will certainly be part of the plan for Tiled 1.2.

[griest024]

@bjorn I added some UI mockups

[satu0king]

Is this issue still open for GSoC students ?

[ketanhwr]

@satu0king this particular project is a big one! It might take some time, and I'll suggest starting out with some other ones.

Still, it's open to everyone, feel free to give it some time, but this is not as easy as it seems.

[bjorn]

@satu0king I'm still hopeful that there will be time to get at least part of this implemented for Tiled 1.2, which would be before the GSoC 2018 starts. But it may be that I'm too optimistic (since @ketanhwr is right), in which case it could become a GSoC project if we see a strong candidate with a realistic proposal.

[bjorn]

Just an update since I noticed I wrote Tiled 1.2 in earlier comments. Mainly due to fulfilling several priority requests from major patrons, this feature did not make it for Tiled 1.2. It is now part of the roadmap for Tiled 1.3, and I don't plan to shift it again.

[bjorn]

Initial support for projects has been released in today's new development snapshot.

[bjorn]

Sessions have been introduced with the latest snapshot, which should make switching between projects quite comfortable since there will be a separate list of open files, recent files and editor states for each project. The handling of sessions is currently completely hidden from the user.

Things I noticed that need to be improved:

• When using "Save Project As..." for a project that has no file name yet, it would be helpful if the file chooser would start in the directory of the first folder.

• There is a thread for scanning folders for files, but currently scheduled scans are not cancelled when they are removed or when a new project is loaded. When switching between projects with large folders this can make it take a long time before the relevant folders have been scanned.

Of course there are many other things that need to be improved. Feedback is welcome!

[AJenbo]

The current implementation is working really well, one thing I did notice is that Tiled doesn't recognize the project when you drag and drop it:

[bjorn]

The current implementation is working really well, one thing I did notice is that Tiled doesn't recognize the project when you drag and drop it:

Right, that will always try to open the file so it only works with maps or tilesets. It should indeed check for project as well, thanks!

[bjorn]

Alright, a lot has happened to projects and sessions in the past two months. I've gone over the original ideas from @griest024 once again to see if I've missed anything important.

• Allow defining custom commands for the project. I think this ons is quite essential since commands are a bit annoying to set up and pretty much always project-specific. The tricky part is allowing both global and project-specific commands.

• Directory data per asset type. A project currently just stores a list of folders. The folders are not bound to any specific asset type. This means, we can't currently support things like storing file references relative to a specific folder. Since such a feature is not without some open questions (like, should we support both a single "root" directory and per-asset type directories?) and problems (are we fine with storing files that can't be opened without opening the project first?), I would suggest we carefully consider this feature for a future release.

• Custom properties on the project. This is currently not possible, but I somewhat agree it would be useful, especially consider the last point.

This one is new but I think also essential:

• Scripting API to access the current project. Scripts should be able to access the project properties and have an easy way to get the list of files in a project.

So, a few more things to do before we can close this issue!

[bjorn]

I've split off two remaining issues so that this issue can be closed. There's many things that could still be improved in the support for projects of course (like #2901). Long live the projects!