Add more tilemap documentation

8 files changed, 72 insertions, 41 deletions

diff --git a/include/area.h b/include/area.h
index ffad51a8..0bfbf919 100644
--- a/include/area.h
+++ b/include/area.h
@@ -22,7 +22,7 @@ typedef struct {
     u16 pixel_height;
     u16 map_x;
     u16 map_y;
-    MapDataDefinition* tileset;
+    MapDataDefinition* tileSet;
     MapDataDefinition* map;
     MapDataDefinition* tiles;
     void* bg_anim;
@@ -82,7 +82,7 @@ typedef struct {
     u16 map_y;
     u16 pixel_width;
     u16 pixel_height;
-    u16 tileset_id;
+    u16 tileSet_id;
 } FORCE_WORD_ALIGNED RoomHeader;
 static_assert(sizeof(RoomHeader) == 0xa);
 extern RoomHeader* gAreaRoomHeaders[];
diff --git a/include/fileselect.h b/include/fileselect.h
index 83b05111..704fb1b1 100644
--- a/include/fileselect.h
+++ b/include/fileselect.h
@@ -49,11 +49,11 @@ typedef struct {
     /*0x0b*/ SaveFile saves[3];
 } struct_02019EE0;
 extern struct_02019EE0 gMapDataBottomSpecial;
-// TODO size: 0x8000 from ClearTilemaps?
+// TODO size: 0x8000 from ClearTileMaps?
 
 extern void sub_08056FEC(u32, struct_020227E8*);
 extern u32 ShowTextBox(u32 textIndexOrPtr, const Font* font);
-extern void ClearTilemaps(void);
+extern void ClearTileMaps(void);
 extern void ResetSaveFile(u32);
 extern WStruct* sub_0805F2C8(void);
 extern u32 sub_0805F7DC(u32, WStruct*);
diff --git a/include/manager.h b/include/manager.h
index f95029b0..c96a1785 100644
--- a/include/manager.h
+++ b/include/manager.h
@@ -96,7 +96,7 @@ extern void MinishPortalManager_Main();
 extern void DiggingCaveEntranceManager_Main();
 extern void BridgeManager_Main();
 extern void SpecialWarpManager_Main();
-extern void MinishVillageTilesetManager_Main();
+extern void MinishVillageTileSetManager_Main();
 extern void HorizontalMinishPathBackgroundManager_Main();
 extern void MinishRaftersBackgroundManager_Main();
 extern void EzloHintManager_Main();
@@ -107,7 +107,7 @@ extern void EntitySpawnManager_Main();
 extern void MiscManager_Main();
 extern void WeatherChangeManager_Main();
 extern void FlagAndOperatorManager_Main();
-extern void HyruleTownTilesetManager_Main();
+extern void HyruleTownTileSetManager_Main();
 extern void HouseSignManager_Main();
 extern void SteamOverlayManager_Main();
 extern void TempleOfDropletsManager_Main();
diff --git a/include/manager/hyruleTownTilesetManager.h b/include/manager/hyruleTownTileSetManager.h
index 8e269355..ee908238 100644
--- a/include/manager/hyruleTownTilesetManager.h
+++ b/include/manager/hyruleTownTileSetManager.h
@@ -8,6 +8,6 @@ typedef struct {
     u8 field_0x20;
     u8 field_0x21;
     u8 field_0x22;
-} HyruleTownTilesetManager;
+} HyruleTownTileSetManager;
 
 #endif // HYRULETOWNTILESETMANAGER_H
diff --git a/include/manager/minishVillageTilesetManager.h b/include/manager/minishVillageTileSetManager.h
index 50c01f54..748be3c5 100644
--- a/include/manager/minishVillageTilesetManager.h
+++ b/include/manager/minishVillageTileSetManager.h
@@ -7,6 +7,6 @@ typedef struct {
     Manager base;
     u8 unk_20;
     u8 unk_21[0x1F];
-} MinishVillageTilesetManager;
+} MinishVillageTileSetManager;
 
 #endif // MINISHVILLAGETILESETMANAGER_H
diff --git a/include/map.h b/include/map.h
index c4284b1a..b133c9e4 100644
--- a/include/map.h
+++ b/include/map.h
@@ -4,20 +4,33 @@
 #include "screen.h"
 
 /**
- * @page TileMap TileMap
+ * @page TileMap Tile Map
  * @brief The map consists of tiles to create the world.
  *
- * 16x16 tiles
- * 8x8 subTiles
+ * GBA graphics are made out of tiles with a size of 8px by 8px. We call those tiles *subTiles*.
+ * Four of those subTiles are combined together to form a bigger 16px by 16px tile (usually called metaTile). We call these *tiles*.
  *
- * tileIndex index into the tile set
- *  0 to 0x800, special tiles at 0x4000 to 0x4096
- * tilePos index into the current map
- * tileType
- * collisionData
- * 
+ * Each map can be up to 64 * 64 tiles big. The map consists of two layers of tiles gMapTop and gMapBottom.
+ * To access the map array the tilePos index can be used which goes from 0 to 64 * 64 = 4096.
+ * Each value in the MapLayer.mapData is a tileIndex which defined which tile of the tileSet should be used.
+ * The tileSet contains tiles from 0 to 2048. Special tileIndex from 0x4000 to 0x4096 can be used to denote special tiles.
+ *
+ * A tile is created from four subTiles. The subTiles for each tile in the tileSet are stored in MapLayer.subTiles. This is loaded for the current area from gAreaTileSets_*.
+ * The subTiles can also be flipped or the palette changed. This is stored in bits 0xa to 0xf, see https://www.coranac.com/tonc/text/regbg.htm#sec-map.
+ *
+ * Each tile in the tileSet also has a tileType defined. This is stored in MapLayer.tileTypes and loaded from gAreaTileSetTypes_*.
+ * The inverse dictionary from tileType to tileIndex is stored in MapLayer.tileIndices.
+ *
+ * The map also stores the collision for each tile in the tileMap layer in MapLayer.collisionData. By default this is filled from gMapTileTypeToCollisionData based on the tileType of the tiles.
+ * But it can also be loaded from gRoomCollisionMap_*.
+ * In MapLayer.actTiles some additional type for each tile is stored which is filled from gMapTileTypeToActTile based on the tileType of the tiles.
  */
 
+// Maximum width or height of a map in tiles.
+#define MAX_MAP_SIZE 64
+// Maximum amount of tiles in a tileSet.
+#define TILESET_SIZE 2048
+
 /**
  * @brief Layer of the TileMap.
  * @ingroup TileMap
@@ -27,62 +40,80 @@ typedef struct {
     /**
      * tileIndex for each tile on the current layer.
      */
-    /*0x0004*/ u16 mapData[0x40 * 0x40];
+    /*0x0004*/ u16 mapData[MAX_MAP_SIZE * MAX_MAP_SIZE];
     /**
      * Collision data for each tile on the current layer.
      * @see CollisionData
      */
-    /*0x2004*/ u8 collisionData[0x40 * 0x40];
+    /*0x2004*/ u8 collisionData[MAX_MAP_SIZE * MAX_MAP_SIZE];
     /**
      * Copy of the map data.
      * @see mapData
      */
-    /*0x3004*/ u16 mapDataOriginal[0x40 * 0x40];
+    /*0x3004*/ u16 mapDataOriginal[MAX_MAP_SIZE * MAX_MAP_SIZE];
     /**
      * Maps from the tileIndex to the tileType.
      * @see TileType
      */
-    /*0x5004*/ u16 tileTypes[0x800];
+    /*0x5004*/ u16 tileTypes[TILESET_SIZE];
     /**
      * Maps from a tileType to a tileIndex. Inverse of @see tileTypes.
      * @see TileType
      */
-    /*0x6004*/ u16 tileIndices[0x800];
+    /*0x6004*/ u16 tileIndices[TILESET_SIZE];
     /**
      * Maps from a tile index to the four sub tiles (with attributes) it consists of.
      * @see https://www.coranac.com/tonc/text/regbg.htm#sec-map
      */
-    /*0x7004*/ u16 subTiles[0x800 * 4];
+    /*0x7004*/ u16 subTiles[TILESET_SIZE * 4];
     /**
      * Some sort of special behavior for tiles? Falling into holes or jumping off walls does not work when this is all zero.
      * @see ActTile
      */
-    /*0xb004*/ u8 actTiles[0x40*0x40];
+    /*0xb004*/ u8 actTiles[MAX_MAP_SIZE * MAX_MAP_SIZE];
 } MapLayer;
 
 extern MapLayer gMapTop;
 extern MapLayer gMapBottom;
 
-extern MapLayer* GetLayerByIndex(u32 layer);
+typedef enum {
+    LAYER_BOTTOM = 1,
+    LAYER_TOP = 2,
+} LayerIndex;
 
-/*
-Definition where some map data is found and where it should be copied to.
-Defined using the map_data asm macro, e.g. in map_headers.s
-*/
-typedef struct {
-    u32 src;
-    void* dest;
-    u32 size;
-} MapDataDefinition;
+/**
+ * Returns the MapLayer for a layer of the map.
+ *
+ * @param layer @see LayerIndex
+ */
+extern MapLayer* GetLayerByIndex(u32 layer);
 
 // There is another map data definition following.
 #define MAP_MULTIPLE 0x80000000
 // The src is compressed.
 #define MAP_COMPRESSED 0x80000000
 
-typedef enum {
-    LAYER_BOTTOM = 1,
-    LAYER_TOP = 2,
-} LayerIndex;
+/**
+ * Definition where some map data is found and where it should be copied to.
+ * Defined using the map_data asm macro, e.g. in map_headers.s
+ */
+typedef struct {
+    /**
+     * @brief Source offset from gMapData.
+     *
+     * MAP_MULTIPLE bit is set if there is another MapDataDefinition following.
+     */
+    u32 src;
+    /**
+     * Target pointer where to load or decompress the map data to.
+     */
+    void* dest;
+    /**
+     * @brief Size of the map data in bytes.
+     *
+     * MAP_COMPRESSED bit is set if the map data is compressed.
+     */
+    u32 size;
+} MapDataDefinition;
 
 #endif // MAP_H
diff --git a/include/room.h b/include/room.h
index 80cf8ab5..7348a568 100644
--- a/include/room.h
+++ b/include/room.h
@@ -56,7 +56,7 @@ typedef struct {
     /*0x28*/ union SplitWord bg3OffsetX;
     /*0x2C*/ union SplitWord bg3OffsetY;
     /*0x30*/ Entity* camera_target;
-    /*0x34*/ u32 tileset; // TODO Should be MapDataDefinition*, but then SetupTileSet does not match.
+    /*0x34*/ u32 tileSet; // TODO Should be MapDataDefinition*, but then LoadRoomTileSet does not match.
 } RoomControls;
 extern RoomControls gRoomControls;
 
diff --git a/include/tilemap.h b/include/tileMap.h
index 6017f9bd..fb1fbc2e 100644
--- a/include/tilemap.h
+++ b/include/tileMap.h
@@ -3,10 +3,10 @@
 
 #include "global.h"
 
-// gMapDataTopSpecial and gMapDataBottomSpecial are tilemaps of 8x8 pixels. But they are also reused for other data in
+// gMapDataTopSpecial and gMapDataBottomSpecial are tileMaps of 8x8 pixels. But they are also reused for other data in
 // other parts of the game.
 
-// Rendered tilemaps https://www.coranac.com/tonc/text/regbg.htm#sec-map
+// Rendered tileMaps https://www.coranac.com/tonc/text/regbg.htm#sec-map
 extern u16 gMapDataTopSpecial[0x4000];
 extern u16 gMapDataBottomSpecial[0x4000];