Automapping: Restricting rules.txt rules by map name

[eishiya]

(Reposting this feature suggestion from Discord, where it's been buried by the sands of time chat.)

It would be convenient if rules.txt could have sections in it that limit the automapping rules in them to applying only to some maps, e.g.

globalRules1.tmx
globalRules2.tmx

[town*]
townRules.tmx
townSpecialCases.tmx

[dungeon*]
dungeonRules.tmx
iceDungeonRules.tmx
lavaDungeonRules.tmx

[fakeTownDungeon.tmx]
//a dungeon that has elements of a town in it
dungeonRules.tmx
townRules.tmx

[*]
globalRulesThatRunAfterEverythingElse.tmx

Map names are a pretty simple way to go about this, since most people already name their maps in some systematic way. Map-name based logic is also not new to Tiled, it already appears in World files.

Benefits of limiting rules to a subset of maps within rules.txt:

• Performance. Irrelevant rules don't have to even be read.
• Readability and maintainability. The map-name match strings also serve as section headings and make it clearer what each group of rules does (though comments already achieve that too), and it's easier to see what's going on when everything is in one file than if one uses many rules.txt files in different subdirectories.
• The rule files themselves can be simpler in some cases, as they don't have to check for quite as much context. For example, rules that add jungle-themed details to dungeon walls can be set to apply only to *jungle* maps, instead of requiring the user to use a special "yes, apply jungle details in this area" layer.
• Old rules.txt files will still be compatible, as they'll just lack these restricted sections (through care has to be taken to make sure that weirdly-named files can't be mistaken for section headings, my [sections] above might not be good enough for that, asterisks or semicolons might be better.)

I realise that restricting rules to specific maps or groups of maps can be mostly achieved by putting the different maps in subdirectories and putting different rules.txt in each subdirectory, but this means the user would have to organize their files around their appearance rather than based on whatever other system they may prefer, and special cases like "fakeTownDungeon.tmx" in the example have to be in their own subdirectory.

Although my example above has a single match string for each section, I think multiples should be allowed, e.g. dungeon*, cave*, finalBoss.tmx. It would also be neat to support regex in this, but I don't think it's necessary, as plain names and simple wildcards are enough in most cases for dealing with map names. Unlike in World files, there are no additional parameters here that need to be extracted from the names.

[bjorn]

What about referencing automapping rules from maps instead? A single rule file reference should suffice, which can include other rule files if desired to avoid duplication.

If we do need to extend the rules.txt file, maybe it makes sense to transition to a JSON file instead? It'll be rather more verbose to edit by hand, but it would be easier to read and write the file. Hmm, I guess we should only do this alongside an editor for such files.

[axboureau]

I like specifying rules files from map instead of the other way around.

[eishiya]

Referencing rules from maps would be convenient for projects with only a few maps or situations where each map is unique in its rule set, but when you have many maps split into a few categories, referencing maps from rule files is more convenient, especially since it means that when you create a new map, you don't have to worry about setting up the rules for it, the correct ones will be applied automatically as long as it follows the naming convention you establish in rules.txt. I also think it's annoying to have a bunch of different rules.txts floating around.

And unless the associations are stored in the Project rather than in the maps, it's clutter xP However, if it is done as Project properties, I think that opens up some great possibilities for an editor within Tiled, allowing both per-map associations that can easily be accessed within Tiled, and name-based ones like in my suggestion. Personally, I've never been fond of the fact that we even need a rules.txt and that it can't be edited from within Tiled, and now Projects are a great opportunity to get rid of it as a requirement.

[bjorn]

I've decided to implement the original request. I may implement a way to refer to rule files from maps or from specific layers later, but it seems to me that this is rather independent of this rules.txt feature.

Although my example above has a single match string for each section, I think multiples should be allowed, e.g. dungeon*, cave*, finalBoss.tmx. It would also be neat to support regex in this, but I don't think it's necessary, as plain names and simple wildcards are enough in most cases for dealing with map names.

For now I am just supporting a single glob pattern and no regex, and the matching happens only against the map file name, not the full path. A comma is a valid file name character, though multiple patterns could also be supported using | eventually.

[eishiya]

@bjorn This still needs to be documented, so I think it's a little early to close the issue xP Here's a draft of the first half of the Setting It Up section in the Automapping docs, expanded to describe this feature:

Setting it Up
=============

The Automapping feature looks for a text file called 'rules.txt' in
the folder where the current map is located. If there isn't one,
it uses the Automapping rules file set in your Project. Each line
in this text file is either

-  a path to a **rulefile**
-  or a path to another textfile which has the same syntax (e.g. in
   another directory)
-  or a map filename specifier, enclosed in **[ ]** and using **\*** as a wildcard
-  or is a comment, which is indicated by **#** or **//**

By default, all Automapping rules will run on any map you Automap.
The map filename specifiers let you restrict which maps rules apply to.
For example, any rules after ``[town*]`` will only apply to maps whose
filenames start with "town". To start applying rules to all maps again,
you can use ``[*]``, which will match any map name.

I also took the opportunity to mention Project rule files and when those are used, and corrected an "i.e." to "e.g.", since different rule text files aren't necessarily in different directories.

[bjorn]

@eishiya Thanks for update to this part, I've included it in 9e1c128!

[bjorn]

Btw, I wondered if I should document the behavior of the file name filter in combination with includes, but I considered it a bit too involved and maybe not very relevant. For what it's worth, its behavior is:

The last specified filename filter also applies to rule maps listed in included .txt files, but any changes to the filename filter within included files do not affect the active filter in the including file.

[eishiya]

That is the behaviour I expect :D I agree that it's too involved and not often relevant, so even though ideally I think everything should be documented, maybe it's something better suited to my tip sheet than to the official docs.