Battle Atlas - a tabletop battlemap generator

Battle Atlas is a mod for the game Tabletop Simulator that was released to the Steam Workshop in June 2017. It was written by myself and a friend known as TattleTale.

This page contains the backstory and notes on the development of Battle Atlas. For the project page please use the links below:

BattleAtlas Website BattleAtlas on Steam

The original problem, or how it all began

The idea for Battle Atlas started developing while trying to create a DnD campaign in Tabletop Simulator and found the constant alt-tabing between GIMP, Imgur and TTS too cumbersome.

For those unfamiliar with the game, Tabletop Simulator is a Unity based game that gives you a blank table and the ability to load in a variety of generic game tokens and accessories, as well as custom models and Unity assetbundles. You simply provide a URL to the image or model you want to load in and Tabletop Simulator spawns the asset on your table as a 3D, interactable item.

Unfortunately Tabletop Simulator doesn't easily allow you to create or import your content directly into the game if you wish to share them. Instead, you have to first create your asset in a suitable program such as GIMP or Photoshop, or Blender. Then you upload your images and objects to a third-party hosting service, such as Imgur, SteamCloud or Pastebin. You can then import the assets via an in-game menu and the various parts (model mesh, diffuse image, etc) are loaded in.

The process isn't difficult, but the several steps involved can mount up quickly when you're working on a large project.

Early attempts at a solution

My first experiment was with a jQuery/css powered web-based solution intended to allow me to easily lay out tiles and save the composite image, potentially using the in-game Tablet feature.

This had several bugs and was ultimately never very efficient. I also tested a piece of software called Tiled which was very good, but it consumes RAM like there's no tomorrow. It also still requires you to export the image and upload it to a third party host. This was less than ideal.

I wanted a way to create maps in Tabletop Simulator without having to manually edit and upload them. This was the basic idea for Battle Atlas, however I had never done any modding in Tabletop Simulator nor had I used Lua.

Help arrives!

Luckily for me it was around this time that I met TattleTale. He had already created a number of highly useful and succeful mods for TTS, including one I was using for creating my own campaign. After explaining my idea to him and showing him the crude-but-demonstrative web version I had cobbled together he agreed to help work on the idea.

I'd found a tileable set of RPG map tiles made by MadCowChef on DeviantArt and showed him the idea I'd had so far. He approved of it and encouraged me to keep going with anything that would benefit the RPG community as a whole. I wrote a small module to manage the images via a CMS, and respond to URL calls with a dynamic image.

TattleTale wrote the in-game menu that lists and spawns the images as objects, and got it talking to the website. A week or two of revisions and we had a semi-working system.

Bugs, problems and other unintended features

Despite working reasonably well there were some major problems with the early version of BattleAtlas. It was initially running on a free Amazon EC2 instance with 1GB RAM and a single CPU core. This was often overwhelmed when manipulating large images, and would crash if multiple images were requested at once.

Also, due to unfortunate timing, we were also mistaking a bug in Tabletop Simulator which caused the game to crash if a resource wasnt delivered in a timely manner to be a bug with our code. We spent a bit of timing optimising our codeand eventually moved the service to a larger server. The increase ins performance coincided with a bug-fix for the game and the problems were solved.

Better than expected

Battle Atlas works better than I expected it to, I'll admit. I wasn't sure how the game would deal with the number of tiles available and what kind of resources I was comitting the server to, but after the initial teething problems the site has worked without any need for intervention. TattleTales code works excellently and he continues to provide small updates as he finds things to tinker with. At the time of writing it's been running for over a year without my input.

Plans for the future

I would like to add more tiles to BattleAtlas, but I'm no artist. If anyone knows of a tileable map-set of decent quality, with a suitable license then please let me know.

The current version of BattleAtlas stores the final images on my own server. One day I would like to update this to take advantage of the new WebRequest feature in Tabletop Simulator to push the final image to Imgur and return the URLs to the client. This would mean that BattleAtlas is only repsonsible for generating the images, not storing or serving them.