Introduction

So, you want to learn how to use TurtleMap in the least amount of time possible. You've come to the right place. However, before you can jump in, you need to know what TurtleMap actually does, and how it does it. You can learn a lot from the code, but this will hopefully ease you into it.

Core Concepts

Pagination

Imagine writing a story, a large one, on a single piece of paper. Some stories could obviously fit onto a single page, but when you get to writing something the size of the Lord of the Rings or Harry Potter, then you can't reasonably fit those onto a single page. Instead, you split the story into several, or many, "pages" of a book. Congratulations, you now understand the basics of pagination.

Pagination (literally "separating into pages") allows a large amount of data to be handled in small pieces, be it pages of a book, episodes of a TV show, or parts of a map. TurtleMap uses pages called "Regions" to handle it's data in small, discrete parts, without having to process the entire map at once.

Scripting

Games, and other software, sometimes expose parts of it's code to the end user. This code is called a script, and can be done for a veriety of reasons. The most common reasons include allowing the end user to modify the program's behaviour, allowing for faster development (scripting is much faster than hard coding), or for allowing new parts to be easily installed at a later date without requiring modifiaction to the core program.

In TurtleMap's case, scripting is used to allow the end user, and users of the TurtleMap library, to quickly and easily alter the behaviour of the generator. Scripting also allows the user to modify the save file format.

Tiles & Tiling

TurtleMap is a tiled map system. What this means is that the actual map data is made up of "Tile Data", where each point on the map is represented by an integer, indicating it's location on the tile sheet. That is to say, if a tile has the value "30", then the tile it represents is the 30th tile on the image file.

Each region holds a matrix of 20*20 tiles, and each tile actually consists of 3 tile layers, plus a fourth "collision" layer. The first layer, the lowest, is intended for basic types of tiles, like land and water. The second layer, which is rendered above it, is intended for decorative pieces that sit on the ground but don't interact with anything, like flowers or tufts of grass. The third layer, the one rendered above the others, is intended for decorations that sit above the characters heads, like hanging tree branches. The fourth layer, the collision layer, is actually a boolean representing if that tile is supposed to be solid or not; internally, this is actually a separate system from the rest.

Tile Sheets

Classes

TurtleMap currently has four classes:

Region
RegionPagerBase
RegionPagerLua
TileSheet

Region

This is a container for the raw map data. The tiles of a map are arranged in a grid pattern along the X & Y axis. In addition, each tile has three layers, which can be accessed independantly, and a flag indicating if they're solid or not.

RegionPagerBase

This is a container for the Region objects. It handles region creation and unloading, as well as iteration. It also has the ability to directly interface with the raw map data. If you don't want to use lua scripting in your game, then you can simply ignore RegionPagerLua and use this class directly.

RegionPagerLua

This inherits from RegionPagerBase, and acts as the interface to a lua state. You can set callbacks in lua, which are triggered whenever a region is loaded, saved, created or unloaded. As it inherits from RegionPagerBase, it also includes everything that that can do.

TileSheet

This is the graphics class, and quite possibly my least favourite component, since it ties TurtleMap to SDL2 and TurtleGUI. If you wish to reimplement this, or ignore it entirely, then you'll be able to ditch those entirely.

TileSheet handles the loading, unloading and rendering of the tile sheet. A "Tile Sheet" is simply a file that contains images of each tile to be used by the Regions, and actually takes regions as a parameter to the rendering functions.

APIs

Each class also has an accompanying lua API. The APIs mimic the class methods as best as they possibly can.

Installation

In order to build the library, simply call make, with the provided makefile. It will create the library "libturtlemap.a" in the directory above it's root directory.

In order to use the lua APIs in your game, the following needs to be included into linit.cpp (see the lua manual for information on linit.cpp).

#include "region_api.hpp"
#include "region_pager_api.hpp"
#include "tile_sheet_api.hpp"

...

//these libs are preloaded and must be required before used
static const luaL_Reg preloadedlibs[] = {
	...
	{TURTLEMAP_REGION_API, openRegionAPI},
	{TURTLEMAP_REGION_PAGER_API, openRegionPagerAPI},
	{TURTLEMAP_TILE_SHEET_API, openTileSheetAPI},
	...
};