Tiled: Showing adjacent maps in the same map view

[bjorn]

Introduction

Sometimes a game has a large world which is split up into multiple maps to make the world more digestible by the game (less memory usage) or easier to edit by multiple people (avoiding merge conflicts). For the player, the transition between these maps should generally be seamless. It would be nice if Tiled would able to show also the maps adjacent to the current map, to make it easy to ensure their borders fit together.

To do this, I would introduce the concept of a "world". Each map can be part of a single world, to which it would refer from its map file. And each world can list any number of maps. In addition, each map gains an "x" and "y" attribute to store its location within its world (in tile coordinates).

Additional Features

To make it easier for existing projects to start using this system, the location of a map can also be derived from its file name based on a custom regular expression and a multiplier.

In addition to a location, each map could have a "level" attribute, which determines at what level this map occurs. This way, multiple maps could be stacked on top of each other rather than adjacent to each other. It would similarly help with matching up different maps that represent for example different floors of the same building.

Implementation Details

Example world definition file:

<world>
  <pattern regexp="(%d+).(%d+).tmx" multiplier="100"/>
  <map source="1.1.tmx"/>
  <map source="1.2.tmx"/>
  <map source="2.1.tmx"/>
  <map source="2.2.tmx"/>
</world>

Or potentially in JSON (I'd prefer to avoid two formats...):

{
    "pattern": {
        "regexp": "(%d+).(%d+).tmx",
        "multiplier": 100
    },
    "maps": [
        "1.1.tmx",
        "1.2.tmx",
        "2.1.tmx",
        "2.2.tmx"
    ],
    "type": "world"
}

Map with some new attributes:

<map x="100" y="100" width="100" height="100" level="1" world="outside.world">
  ...
</map>

New classes introduced would be WorldManager, which loads and owns each referenced world, and a World class that keeps the list of maps and their locations.

Part of the logic in MapScene will need to be moved to a new MapItem graphics item, so that multiple of those can be instantiated on-demand. Interaction with items shown in "other maps" should be disabled. The other maps should be clickable so that it is easy to open it for editing.

[Arcanorum]

Sounds cool to me.

This lines up nicely with how I have been handing the space representation in my game.
I think you should consider using "_elevation_" instead of the somewhat ambiguous and commonly used term "_level_" when talking about stacking things on top of each other like floors of a building.

Would a map being a part of a "world" be required?
Would we be able to set world-level properties?
If so, how would this interact with the proposed Project #1665 structure?
_Project < Worlds < Maps < Layers < Objects_ ?

[bjorn]

I think you should consider using "elevation" instead of the somewhat ambiguous and commonly used term "level" when talking about stacking things on top of each other like floors of a building.

Good point.

Would a map being a part of a "world" be required?

No.

Would we be able to set world-level properties?

I see no reason not to allow custom properties on the world, though that means the world file could be interesting for the game, in which case we'll need to support different formats as done for maps / tilesets (JSON, Lua, ...). I think there's probably a better way of doing this...

If so, how would this interact with the proposed Project #1665 structure?
Project < Worlds < Maps < Layers < Objects ?

I'm not sure if any interaction is needed. Both worlds and maps would be part of a project, and maps can in addition be part of a world.

[bjorn]

Just noting here, that the feature was suggested on the forum as well.

[bjorn]

Started work on this on the wip/multi-map-view branch, but it currently doesn't compile and will still need lots of work. Also, I better finish Tiled 1.1 first.

[bjorn]

So, lots of work later, which mostly meant reducing dependencies on the map scene (fd8dee20fe45775a29ef5bd07efc31607ee65348...15e9ee5b07c2a10002bb45210db03bba01d12c2e) and then moving a lot of functionality out of the map scene (aaa2eaaf5701aae99c0eaeb46bdbfd797b461694) and finally enabling the instantiation of multiple map items within the same scene (8522b1b133e7613c2431ee9bfdda414196c6c348), we have the first usable version:

Above you can see three maps displayed, two alongside the 002-1.tmx map that was opened for editing. This is based on the new "world" files, which are currently in JSON format and need to be hand-written for now. Example for the above maps:

{
    "maps": [
        {
            "fileName": "001-1.tmx",
            "x": 0,
            "y": 0
        },
        {
            "fileName": "002-1.tmx",
            "x": 0,
            "y": 3200
        },
        {
            "fileName": "006-1.tmx",
            "x": 3840,
            "y": 4704
        }
    ],
    "type": "world"
}

I've decided to store the position here instead of in the map files. This decouples stuff a bit (so editing the world doesn't mean changing a bunch of map files). Also, the position is in pixels because no assumption can be made about tile size (though we could associate a grid size with the world, and multiply the x/y of the maps with the grid size, for ease of use).

In the screenshot you can also see the new menu items, that allow you to load and unload any number of worlds. Of course when you reopen Tiled, any previously loaded worlds are also reopened.

So, a lot of work was done (spent about 4 days on this so far), but there still remain a few things to be done (which I'll have to work on later due to other commitments):

• [x] Add a quick way to switch from one map to another map in the same world. Based on double-click for example, we could either switch tab or change the "active" map within the same view. I would probably prefer the latter, but this does open up a lot more edge cases.
• [x] Add a way to manage a world file within Tiled, so no manual editing is needed. That's a bunch of UI work of course (done for Tiled 1.4).
• [x] Add support for pattern-matching, as described in the first post. The pattern is supposed to capture two values from any matching files, which get multiplied by the multiplier to form the position of the map.
• [ ] There is no support for "level" or "elevation" yet.

I've opened a pull request with the changes (#1836), so that there is a consistent place for downloading a build (Windows builds available on AppVeyor, Linux builds available via a link to transfer.sh found in Travis CI logs). For the current version, builds are available here:

https://ci.appveyor.com/project/bjorn/tiled/build/1.0.2918 (click a job, then click ARTIFACTS)
https://transfer.sh/x6s4L/Tiled.AppImage (available for two weeks)

Once Tiled 1.1 is branched, this change could be merged into master quite soon, so that it will be available in the development snapshots.

[HeadClot]

This is really cool!

[NazdarGit]

Agreed! Very nice!

[bjorn]

A new build is available that adds support for defining the maps using pattern matching:

https://ci.appveyor.com/project/bjorn/tiled/build/1.1.3155
https://transfer.sh/dh3ss/Tiled.AppImage

Example of a world defined by pattern matching:

{
    "patterns": [
        {
            "regexp": "ow-p0*(\\d+)-p0*(\\d+)-o0000\\.tmx",
            "multiplierX": 6400,
            "multiplierY": -6400,
            "offsetX": -6400
        },
        {
            "regexp": "ow-p0*(\\d+)-n0*(\\d+)-o0000\\.tmx",
            "multiplierX": 6400,
            "multiplierY": 6400,
            "offsetX": -6400,
            "offsetY": -6400
        },
        {
            "regexp": "ow-n0*(\\d+)-p0*(\\d+)-o0000\\.tmx",
            "multiplierX": -6400,
            "multiplierY": -6400
        },
        {
            "regexp": "ow-n0*(\\d+)-n0*(\\d+)-o0000\\.tmx",
            "multiplierX": -6400,
            "multiplierY": 6400,
            "offsetY": -6400
        }
    ],
    "type": "world"
}

The "regexp" should have two captures, the first is taken to be the X and the second the Y coordinate (we can enhance this to allow named captures like (?<x>\d) and (?<y>\d)). The resulting values are then multiplied by multiplierX and multiplierY respectively, after which the offsetX and offsetY are added to make up the final pixel position of the map.

The pattern matches against all files in the same folder as the world file. If it's preferable to put the world files somewhere else, we can allow a base directory to be configured.

I've written the above world file for the Invertika maps. However, its outside world contains no less than 2500 maps (50x50 maps, each 200x200 tiles), and initially Tiled was quickly running out of memory. Then I implemented an image cache (9202e252ccc5b6817a86d911dc5edd247a140495), which helped and allowed Tiled to display the whole world while consuming about 10 GB of RAM:

However, for this kind of scale there would be a number of other changes necessary, for example to make the loading asynchronous and the rendering asynchronous and cached when zoomed out. Alternatively, we'd load only the direct neighbors of the current map.

[bjorn]

There is a new build available now, that adds the ability to click on a neighboring map to make that the active map being edited:

https://ci.appveyor.com/project/bjorn/tiled/build/1.1.3216 (click a job, then click ARTIFACTS)
https://transfer.sh/rnMpV/Tiled.AppImage (available for two weeks)

It also includes a memory management cleanup that fixes a crash in the Tile Collision Editor (0971ade98d0d19a20a1d5c68f08027168e5fe368) and an option to show only adjacent maps (dbefe488523ff2ee678d7b471913c44556cfd983), as well as all the latest fixes and changes made on the 1.1 and master branches.

I'm confident that I can merge this branch to master soon, latest next week.

[HeadClot]

Super happy this is being worked on :)

[hexus]

Yeah, this looks incredible. I was considering using an infinite map, splitting up the regions, and loading them in myself. Now it looks like I won't need to. :)

[bjorn]

Yeah, this looks incredible. I was considering using an infinite map, splitting up the regions, and loading them in myself. Now it looks like I won't need to. :)

It is true that these features have some overlap. It does not really make sense to use this feature in combination with infinite maps, which would lead to a very confusing editing experience.

The main reasons this feature is still interesting even though we have infinite maps are performance (the entire infinite map may slow down Tiled too much) and collaboration (changes to tile layers do not merge very well, and splitting up the world helps to avoid merges or blocking each other).

Actually with the way infinite maps are stored, they should merge quite well provided you don't edit the same 16x16 block as somebody else, but there is no easy way to avoid doing this whereas it is possible to communicate about separate map files.

[bjorn]

This issue will remain open until this feature is more complete, but it is available in today's new development snapshot and added to the documentation!

[HeadClot]

Thank you @bjorn - I am going to contribute to the patreon campaign hopefully at the end of the month.

[bjorn]

@HeadClot Thanks! This feature was put on the priority list by @tomcashman, who is also a major patron. I've just reached my two-days-per-week goal again, but I still need more support to be able to afford the small office room I work in!

Regarding what's next for this feature until the Tiled 1.2 release, he's a short list of things I plan to work on next:

• [x] Darken inactive maps instead of making them transparent, which should make them easier to read since the transparency is causing the various layers to blend into each other.
• [x] Render a border around each map.
• [x] Highlight a hovered inactive map (in addition to the cursor change) to make it clearer that clicking there will select it, and which one (in case of multiple overlapping maps).
• [x] When loading/unloading/reloading a world, update maps shown alongside existing open files.
• [x] Automatically reload a world when its file changes on disk.

Editing the actual world definition in Tiled is probably not worth squeezing into Tiled 1.2, but it can always be worked on for a future release.

[bjorn]

Today's new development snapshot improved the interaction with other maps, implementing all the points I had listed above. I hope it is now ready for the Tiled 1.2 release. Any feedback and help with testing would be really appreciated!

[bjorn]

Closing this since the feature is available in the snapshots now, and doing an editor for the world files is out of scope for Tiled 1.2. An editor can be done in the future, but only if there is demand for it (same for the additional "level" or "elevation" support).

Feedback is still welcome, there should be about two more weeks until the Tiled 1.2.0 release.

[hexus]

I would personally love to see an editor, but until then I'll see what I can get done without one.

Super exciting feature! :tada:

[karai17]

Does this feature have any impact on loading [Lua] maps into a game, or is this purely an editor feature?

[bjorn]

Does this feature have any impact on loading [Lua] maps into a game, or is this purely an editor feature?

It is purely an editor feature, unless you code support for the world file in your game.

Usually, the game somebody is working on already has some kind of mechanism that stitches maps together and setting up the world file is a way to tell Tiled about this.

[karai17]

Cool, thanks. I've updated STI over the past few days to bring it back up
to feature parity with Tiled so I was just making sure I knew what users
would be expecting~

On Sun, Mar 24, 2019, 18:27 Thorbjørn Lindeijer, [e-mail]
wrote:

Does this feature have any impact on loading [Lua] maps into a game, or is
this purely an editor feature?

It is purely an editor feature, unless you code support for the world file
http://doc.mapeditor.org/en/stable/manual/worlds/#defining-a-world in
your game.

Usually, the game somebody is working on already has some kind of
mechanism that stitches maps together and setting up the world file is a
way to tell Tiled about this.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/bjorn/tiled/issues/1669#issuecomment-476001838, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAkB_Cw5E7ZjhBoAlmwlIV643zO94_Feks5vZ-20gaJpZM4OonJu
.

[Beefy-Swain]

Is this feature documented in the TMX format docs? I cannot find it there.

[Beefy-Swain]

I see, it is a separate spec detailed here: https://doc.mapeditor.org/en/stable/manual/worlds/