libgamemaps provides a standard interface to access different game levels regardless of their file format.


The main interface to the library is the getManager() function, which returns an instance of the Manager class. The Manager is used to query supported map formats, and for each supported file format it returns an instance of the MapType class.

The MapType class can be used to examine files and check what file format they are in, and if they are in the correct format, to open them. Successfully opening a map produces an instance of the Map class. The MapType class can also be used to create new maps from scratch, which will again return a Map instance.

The Map class is used to directly manipulate map files, changing the level as it appears in-game. The Map class itself is a base class, and is extended in the form of the Map2D class for editing maps from platform-style games. There are currently no plans to implement a Map3D class (e.g. for Build games) however should someone be dedicated enough the library can support this.


The libgamemaps distribution comes with example code in the form of the gamemap utility, which provides a simple command-line interface to the full functionality of the library.

For a small "hello world" example, try this:

#include <camoto/stream_file.hpp>
#include <iostream>
using namespace camoto;
using namespace camoto::gamemaps;
int main(void)
// Get hold of the Manager class
ManagerPtr manager = getManager();
// Use the manager to look up a particular map format
MapTypePtr mapType = manager->getMapTypeByCode("map-xargon");
// Open a map file on disk
// We cheat here - we should check and load any supplementary files, but
// for the sake of keeping this example simple we know this format doesn't
// need any supps.
// Use the map format handler to read in the file we opened as a map
MapPtr map;
try {
map = mapType->open(file, supps);
} catch (const stream::open_error& e) {
std::cerr << "Error opening map: " << e.what() << std::endl;
return 1;
// See if the map is a 2D grid-based one
Map2DPtr map2d = boost::dynamic_pointer_cast<Map2D>(map);
if (map2d) {
// It is, print the number of layers
std::cout << "This map has " << map2d->getLayerCount() << " layers."
<< std::endl;
} else {
std::cout << "This map was not a 2D map." << std::endl;
// No cleanup required because all the Ptr variables are shared pointers,
// which get destroyed automatically when they go out of scope (if nobody
// else is using them!)
return 0;

When run, this program produces output similar to the following:

This map has 2 layers.

More information

Additional information is available from the Camoto homepage