From RPTools Wiki
Jump to navigation Jump to search

What is a 'Framework'?

MapTool Campaign Frameworks are usually Campaign Files configured to support a particular game system with additional features. They are not features of MapTool itself so much as a feature of the MapTool community. As such, frameworks are optional; you do not need one to play your games, though a great framework may make your game easier to run or more fun to play.

Campaign Frameworks range from simple, such as a blank campaign file with a few pre-built custom properties and campaign macros, to complex campaign files with totally customized campaign properties and hundreds of macros providing advanced functionality such as character sheets, dice rolling boxes, calculators, combat systems, and more.

The term 'Framework' is sometimes used more broadly to refer to any user-contributed work providing additional MapTool features, either for a specific game system or for general use. Such features might be character sheet panels, a campaign calendar system, a dice roller, or even a simple calculator. These can be delivered in a Campaign File, as a standalone token or macro set, or a collection of files and instructions on how to include the feature(s) in your own game.

Where can I find frameworks for my game system?

The MapTool community has built numerous frameworks to support all kinds of game systems and extra MapTool features over the years. A sample list is at the bottom of this article, and searching the RPTools Forum is a great place to start.

Wolph42's Loading & Updating Frameworks forum post is an excellent starting point if you haven't used a framework before. If you have any trouble, the framework's author or and the MapTool community are usually able to help.

How can I create my own framework?

Do you have a campaign file with some custom properties and a few macros you've built for your game system?

  • Save a copy of your game.
  • Strip out all the content of your own game, leaving only the 'bones' - campaign properties, library tokens, tables, macros, and some sample character and monster tokens.
  • Polish up any sloppy macros, perhaps make them more generic and flexible to fit more situations. Collect all the resources on a single map in the campaign file.
  • Share it online with some information on how to use it and bam! You have just made your first framework!

Just like you, framework authors generally built their first frameworks out of necessity for their own games. Of course, as you run more games, you may want to be more thoughtful in planning the framework before playing your game. You may want to list out features you'll need and make a plan on how your game system will function. Download any popular framework and tinker around to see how they work - you will learn a lot about how others have built great frameworks and you'll get ideas for improving your own.

Here are a few select wiki resources helpful for understanding frameworks and creating your own. You'll notice most of these have to do with MapTool's macro language - good framework authors are often macro writing experts, since macros are the only way to extend MapTool's core functionality:

  • Introduction to Properties: The basis for many framework are the custom Campaign Properties to define token properties, states, sight & light types and more to match the game system.
  • Introduction to Macro Writing: MapTool's macro language is incredibly powerful. Create attack buttons for your players, custom character sheet panels, and so much more. Frameworks depend heavily on macros to add features and functionality.
  • Library Tokens: Instead of writing an 'attack' macro for every token in your game, a common approach is to write just one and 'link' to it on every token. This way, if you have to fix or improve the attack macro, you only have to do it once. Library tokens are the key feature to make a single macro available to all tokens across your whole campaign.
  • Introduction to Macro Branching: Your framework will almost certainly have some conditional logic, such as displaying a message to chat when a character is dropped to zero hit points. Learning if/then conditional logic is a core macro writing skill you'll want.
  • Introduction to Macro Loops: Frameworks often handle lists of data, such as showing a list of equipment in a character sheet panel. Looping through lists is an important skill.
  • Introduction_to_JSON_Datatypes: Most advanced frameworks use something called 'JSON' in macros and token properties. Learning about this will make looking at other people's frameworks and macros more intelligible, and can open up new horizons for your own framework.

Sample List of Frameworks

Below are just some frameworks created by MapTool users over the years. This is in no way complete, and if you are serious about finding a framework for your game it is recommended to visit the RPTools User Creations board.

The year of the last update is listed for each framework. Note that very old frameworks may not work properly on modern versions of MapTool.

Call of Cthulhu



As D&D 5e is very popular, their are numerous current frameworks available, and they are frequently changing.


3.5 / Pathfinder 1e

Warhammer 40k

Dragon Age


First edition Pathfinder frameworks can be found with D&D 3.5 above.