Finished the draft for dummies-1

Home.md

@@ -1 +1,28 @@
-Welcome to the TurtleMap wiki!
+# Introduction
+
+Hello and welcome to the TurtleMap Wiki. Here, I'll try to explain and document everything there is to know about the TurtleMap Library. If you're reading this, then you should also have the TurtleMap source code readily available as well.
+
+# Crash Course
+
+This is a straight forward way of learning how to use TurtleMap.
+
+* [TurtleMap for Dummies Part 1](turlemap-for-dummies-1) - Cover core concepts, and installation
+
+# Detailed Reference
+
+This is a breakdown of each class, it's methods and it's APIs, for quick lookup.
+
+* Global Variables And Their Uses
+* Region
+* Region API
+* Region Pager Base
+* Region Pager Lua
+* Region Pager API
+* Tile Sheet
+* Tile Sheet API
+
+# Adaptation
+
+This section is for those who wish to adapt or modify TurtleMap. Please know that any modifications are welcome, and if it suits specific a purpose it may be accepted via a pull request on GitHub.
+
+* Disconnecting TurtleGUI - Removing the dependency on SDL2 and TurtleGUI

turtlemap-for-dummies-1.md

@@ -0,0 +1,80 @@
+# 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.
+
+## 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, the following needs to be included into linit.cpp (see the lua manual for information on linit.cpp).
+
+```C++
+#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},
+	...
+};
+```
+