Add a new map

7 files changed, 414 insertions, 0 deletions

diff --git a/Add-a-new-map.md b/Add-a-new-map.md
new file mode 100644
index 0000000..c05ceb5
--- /dev/null
+++ b/Add-a-new-map.md
@@ -0,0 +1,413 @@
+This tutorial is for how to add a new map. As an example, we'll add *two* maps: the outdoor and indoor maps of the Global Terminal building west of Goldenrod City, from HGSS.
+
+
+## Contents
+
+1. [Plan the map's role in the game](#1-plan-the-maps-role-in-the-game)
+2. [Design the map with Polished Map](#1-design-the-map-with-polished-map)
+3. [Define a map constant](#2-define-a-map-constant)
+4. [Define its group data](#3-define-its-group-data)
+   - [Roof type](#roof-type)
+   - [Roof palette](#roof-palette)
+   - [Outdoor sprite set](#outdoor-sprite-set)
+5. [Define its properties](#4-define-its-properties)
+6. [Define its attributes](#5-define-its-attributes)
+7. [Write its event scripts](#6-write-its-event-scripts)
+8. [Include the block and script data](#11-include-the-block-and-script-data)
+
+
+
+## 1. Plan the map's role in the game
+
+The Global Terminal in HGSS was a tall building west of Goldenrod City, made for interaction with other players via DS Wi-Fi. That's not possible with the GameBoy Color, but a "global terminal" would also make sense as an inter-regional rest stop for travelers and tourists in a port town. Here's a mockup of what it will look like:
+
+![Screenshot](screenshots/global-terminal-draft.png)
+
+Microsoft Paint is fine for making mockups and plans; [paint.net](https://www.getpaint.net/) is also a good choice, with more features like layers and an undo/redo history.
+
+
+## 2. Design the map with Polished Map
+
+The maps/\*.blk files that define map layouts can't be edited as text, and hex editing them is inconvenient. So we'll use [Polished Map](https://github.com/Rangi42/polished-map), a program for Windows or Linux that can edit map layouts as well as tilesets. (Editing tilesets is beyond the scope of this tutorial.)
+
+To install Polished Map, just follow the instructions in its [INSTALL.md](https://github.com/Rangi42/polished-map/blob/master/INSTALL.md): download install.bat and polishedmap.exe from the latest release; run install.bat with admin privileges; and delete the downloaded files, since a shortcut to the installed copy of Polished Map should now exist on your Desktop. If you need help using it, read the documentation in the Help menu.
+
+Anyway, create a new map, choosing **pokecrystal** as the project directory (or whatever your pokecrystal-based project happens to be named). Make the new map 10 blocks wide and 18 blocks high, using the `johto_modern` tileset. Then draw its blocks like this:
+
+![maps/GlobalTerminalOutside.blk](screenshots/polished-map-global-terminal-outside.png)
+
+Save that as **maps/GlobalTerminalOutside.blk**.
+
+Next, open **maps/GoldenrodCity.blk**; its 20x18 size should be filled in automatically, but you'll need to manually pick the `johto_modern` tileset. Edit its west side to neatly connect with the Global Terminal:
+
+![maps/GoldenrodCity.blk](screenshots/polished-map-goldenrod-city.png)
+
+Be sure to save your changes.
+
+(Notice that the roofs appear cyan and with the wrong pattern. That's because roofs are given special treatment depending on which group a map is in, and Polished Map just shows a default roof style. We'll see how roofs work later.)
+
+Now create another new map, 9 blocks wide and 6 blocks high, using the `radio_tower` tileset. Then draw its blocks like this:
+
+![maps/GlobalTerminal1F.blk](screenshots/polished-map-global-terminal-1f.png)
+
+Save that as **maps/GlobalTerminal1F.blk**.
+
+
+## 3. Define a map constant
+
+Edit [constants/map_constants.asm](../blob/master/constants/map_constants.asm):
+
+```diff
+ ; map group ids
+ ; `newgroup` indexes are for:
+ ; - MapGroupPointers (see data/maps/maps.asm)
+ ; - MapGroupRoofs (see data/maps/roofs.asm)
+ ; - OutdoorSprites (see data/maps/outdoor_sprites.asm)
+ ; - RoofPals (see gfx/tilesets/roofs.pal)
+ ; `map_const` indexes are for the sub-tables of MapGroupPointers (see data/maps/maps.asm)
+ ; Each map also has associated data:
+ ; - attributes (see data/maps/attributes.asm)
+ ; - blocks (see data/maps/blocks.asm)
+ ; - scripts and events (see data/maps/scripts.asm)
+ 	const_def
+
+ 	newgroup                                                      ;  1
+
+ 	map_const OLIVINE_POKECENTER_1F,                        5,  4 ;  1
+ 	...
+
+ 	...
+
+ 	newgroup                                                      ; 26
+
+ 	map_const ROUTE_30,                                    10, 27 ;  1
+ 	...
+
++	newgroup
+
++	map_const GLOBAL_TERMINAL_OUTSIDE, 10, 18
++	map_const GLOBAL_TERMINAL_1F,       9,  6
+```
+
+Map constants have two parts: the group ID and the map ID. Groups are significant for outdoor maps because they share a roof palette and an outdoor sprite set (more on those later). For indoor maps, groups don't really matter, but they're usually grouped with their corresponding outdoor maps for the sake of organization.
+
+The line `map_const GLOBAL_TERMINAL_OUTSIDE, 10, 18` defines four constants at once:
+
+- `GROUP_GLOBAL_TERMINAL_OUTSIDE` is 27, since that's the current group ID
+- `MAP_GLOBAL_TERMINAL_OUTSIDE` is 3, since that's the current map ID
+- `GLOBAL_TERMINAL_OUTSIDE_WIDTH` is 10
+- `GLOBAL_TERMINAL_OUTSIDE_HEIGHT` is 18
+
+The width and height are the size of the map we designed earlier. Now if you open maps/GlobalTerminalOutside.blk in Polished Map, the TitleCase filename "GlobalTerminalOutside" will get matched with the UPPER_CASE constant prefix "GLOBAL_TERMINAL_OUTSIDE", and the 10x18 size will be automatically filled in.
+
+Note that there is no constant named just `GLOBAL_TERMINAL_OUTSIDE`! This can confuse people because there *are* constants simply named `GOLDENROD_CITY`, `NEW_BARK_TOWN`, etc. Those are landmark constants, unrelated to map constants. We'll see what those are used for later.
+
+
+## 3. Define its group data
+
+Every map in a group shares three things: a roof type, roof palette, and outdoor sprite set. We made a new group for the Global Terminal, so we have to define all of those.
+
+If you're adding a map to an existing group, you can skip this step! Just be aware of what those values already are for that group, since they limit your options for designing outdoor maps.
+
+
+### Roof type
+
+The roof type controls which nine roof tiles get used. This only applies to maps with the `TILESET_JOHTO`, `TILESET_JOHTO_MODERN`, or `TILESET_BATTLE_TOWER_OUTSIDE` tileset, since they have placeholder roof tiles in the right spot. (Those particular tilesets are [hard-coded](Hard-coded-logic#tilesets-that-have-per-mapgroup-roofs) by `LoadTilesetGFX` in [home/map.asm](../blob/master/home/map.asm).)
+
+Edit [data/maps/roofs.asm](../blob/master/data/maps/roofs.asm):
+
+```diff
+ MapGroupRoofs: ; 1c021i
+ ; entries correspond to map groups
+ ; values are indexes for Roofs (see below)
+ 	db -1             ;  0
+ 	db ROOF_OLIVINE   ;  1 (Olivine)
+ 	...
+ 	db ROOF_NEW_BARK  ; 26 (Cherrygrove)
++	db ROOF_GOLDENROD ; 27 (Global Terminal)
+ ; 1c03c
+```
+
+Roof tiles, like all graphics, are only loaded when you warp to a map. Walking across map connections, like from Route 34 to Goldenrod City, will not reload graphics. So if two maps are connected, even if they're in different groups, their roof types have to match. We're going to connect the Global Terminal to Goldenrod City's west edge later, so it has to use the same roof type.
+
+
+### Roof palette
+
+The roof palette affects tiles that use the `ROOF` palette. It only applies to "outdoor" maps: those with the `TOWN` or `ROUTE` environment. (We'll go over environments later.)
+
+Edit [gfx/tilesets/roofs.pal](../blob/master/gfx/tilesets/roofs.pal):
+
+```diff
+ ; group 0 (unused)
+ 	RGB 21,21,21, 11,11,11 ; morn/day
+ 	RGB 21,21,21, 11,11,11 ; nite
+
+ ...
+
+ ; group 26 (Cherrygrove)
+ 	RGB 31,14,28, 31,05,21 ; morn/day
+ 	RGB 14,07,17, 13,00,08 ; nite
+
++; group 27 (Global Terminal)
++	RGB 16,23,28, 03,15,21 ; morn/day
++	RGB 08,11,21, 02,08,16 ; nite
+```
+
+Maps get most of their palettes from [gfx/tilesets/bg_tiles.pal](../blob/master/gfx/tilesets/bg_tiles.pal), but outdoor maps load their `ROOF` palettes from roofs.pal. Only the middle two colors are specified; the lightest and darkest, usually off-white and gray/black, are unchanged from their bg_tiles.pal values.
+
+Unlike tiles, palettes *are* reloaded when you cross a map connection, so the Global Terminal can have a unique roof color.
+
+If you're using a desktop graphics program like Paint, it will show red, green, and blue color channel values from 0 to 255. Color channels on the GameBoy Color range from 0 to 31, so just divide the Paint values by 8 to get the right ones.
+
+To derive "nite" colors from "morn/day" colors, you can divide the red and green values by 2, and multiply the blue value by 3/4.
+
+
+### Outdoor sprite set
+
+The outdoor sprite set is the set of sprites it's possible to use in outdoor maps. Indoor maps are all independent, so they load graphics for whichever sprites happen to be used on each map; but outdoor maps can be connected to each other, so it's necessary to define a set of usable sprites that covers all the connected maps.
+
+Edit [data/maps/outdoor_sprites.asm](../blob/master/data/maps/outdoor_sprites.asm):
+
+```diff
+ OutdoorSprites: ; 144b8
+ ; entries correspond to map groups
+ 	dw OlivineGroupSprites
+ 	...
+ 	dw CherrygroveGroupSprites
++	dw GlobalTerminalSprites
+ ; 144ec
+
+ ...
+
++GlobalTerminalSprites:
+ GoldenrodGroupSprites: ; 14673
+ 	db SPRITE_SUICUNE
+ 	db SPRITE_SILVER_TROPHY
+ 	db SPRITE_POKE_BALL
+ 	db SPRITE_POKEDEX
+ 	db SPRITE_WILL
+ 	db SPRITE_KAREN
+ 	db SPRITE_NURSE
+ 	db SPRITE_OLD_LINK_RECEPTIONIST
+ 	db SPRITE_BIG_LAPRAS
+ 	db SPRITE_BIG_ONIX
+ 	db SPRITE_SUDOWOODO
+ 	db SPRITE_BIG_SNORLAX
+ 	db SPRITE_GRAMPS
+ 	db SPRITE_YOUNGSTER
+ 	db SPRITE_OFFICER
+ 	db SPRITE_POKEFAN_M
+ 	db SPRITE_DAY_CARE_MON_1
+ 	db SPRITE_COOLTRAINER_F
+ 	db SPRITE_ROCKET
+ 	db SPRITE_LASS
+ 	db SPRITE_DAY_CARE_MON_2
+ 	db SPRITE_FRUIT_TREE
+ 	db SPRITE_SLOWPOKE
+ ; 1468a
+```
+
+The Global Terminal is going to be connected to the west edge of Goldenrod City, so they'll have to have identical sprite sets; to save space, they can literally use the same data. Note that, for instance, `OlivineGroupSprites` and `CianwoodGroupSprites` are two different sets but have identical contents, since you can Surf from Olivine City to Cianwood City.
+
+In general you can use this template for defining new sprite sets:
+
+```
+	; 12 non-walking filler sprites
+	db SPRITE_SUICUNE
+	db SPRITE_SILVER_TROPHY
+	db SPRITE_FAMICOM
+	db SPRITE_POKEDEX
+	db SPRITE_WILL
+	db SPRITE_KAREN
+	db SPRITE_NURSE
+	db SPRITE_OLD_LINK_RECEPTIONIST
+	db SPRITE_BIG_LAPRAS
+	db SPRITE_BIG_ONIX
+	db SPRITE_SUDOWOODO
+	db SPRITE_BIG_SNORLAX
+	; 9 walking sprites
+	db SPRITE_COOLTRAINER_M
+	db SPRITE_COOLTRAINER_F
+	db SPRITE_BUG_CATCHER
+	db SPRITE_TWIN
+	db SPRITE_YOUNGSTER
+	db SPRITE_LASS
+	db SPRITE_TEACHER
+	db SPRITE_BUENA
+	db SPRITE_SUPER_NERD
+	; 2 non-walking sprites
+	db SPRITE_POKE_BALL
+	db SPRITE_FRUIT_TREE
+```
+
+A sprite set has 23 sprites, but only nine of them can have walking frames. (Replace those nine with whichever ones your particular maps need.) Examining the VRAM in [BGB](http://bgb.bircd.org/) reveals why they're like this:
+
+![VRAM](screenshots/192-tiles-vram.png)
+
+VRAM is divided into six areas, each 128 tiles large. The middle-right area is for sprites' walking frames. 3 frames per sprite (up/down/side) × 4 tiles per frame = 12 tiles per sprite. 9 NPC sprites + the player sprite = 10 sprites = 120 walking frame tiles. (The remaining 8 are used for special effects like emotes, ledge-hopping shadows, rustling grass, fishing rods, etc.)
+
+Notice how text characters are in the middle-left area. This is why, if an NPC is using a sprite from the top-left area that doesn't have walking frames, it will glitch and appear as text when it takes a step.
+
+
+## 4. Define its properties
+
+Edit [data/maps/maps.asm](../blob/master/data/maps/maps.asm):
+
+```diff
+ MapGroupPointers::
+ ; pointers to the first map of each map group
+ 	dw MapGroup_Olivine     ;  1
+ 	...
+ 	dw MapGroup_Cherrygrove ; 26
++	dw MapGroup_GlobalTerminal ; 27
+
+ ...
+
++MapGroup_GlobalTerminal:
++	map GlobalTerminalOutside, TILESET_JOHTO_MODERN, ROUTE, GOLDENROD_CITY, MUSIC_GOLDENROD_CITY, FALSE, PALETTE_AUTO, FISHGROUP_SHORE
++	map GlobalTerminal1F, TILESET_RADIO_TOWER, INDOOR, GOLDENROD_CITY, MUSIC_GOLDENROD_CITY, FALSE, PALETTE_DAY, FISHGROUP_SHORE
+```
+
+The `map` macro defines these different properties:
+
+- **map name:** The name of the map. For consistency the same name should be used in every label or filename related to a map.
+- **tileset:** The tileset used by the map. The tileset constants are defined in [constants/tileset_constants.asm](../blob/master/constants/tileset_constants.asm). `GlobalTerminalOutside` has to use `TILESET_JOHTO_MODERN`, the same tileset as `GoldenrodCity`, because they'll be connected.
+- **environment:** The map environment. Environments have various effects; a subtle one is that the graphics for rustling tall grass are only loaded outdoors, and the graphics for pushing Strength boulders are only loaded indoors (so don't place any Strength boulders outdoors). Valid environments are defined in [constants/map_data_constants.asm](../blob/master/constants/map_data_constants.asm):
+   - `TOWN`: Outdoors. Can use Fly or Teleport.
+   - `ROUTE`: Outdoors. Can use Fly or Teleport.
+   - `INDOOR`: Indoors. Can't use the Bicycle.
+   - `CAVE`: Indoors. Can use Dig or Escape Rope out to the last outdoor map (with [some hard-coded exceptions](Hard-coded-logic#outdoor-maps-within-indoor-maps-dont-confuse-dig-or-escape-rope)).
+   - `ENVIRONMENT_5`: Neither outdoors nor indoors. Can't use the Bicycle.
+   - `GATE`: Indoors. Won't show pop-up location name signs.
+   - `DUNGEON`: Indoors. Can't use the Bicycle. Can use Dig or Escape Rope just like `CAVE`.
+- **location:** Which landmark corresponds to the map. This affects where you appear on the Town Map and what the pop-up location name sign will say.
+- **music:** What music plays on the map.
+- **phone service flag:** `TRUE` if Pokégear phone service is disabled, otherwise `FALSE`.
+- **time of day:** Controls the color palette. One of `PALETTE_AUTO`, `PALETTE_MORN`, `PALETTE_DAY`, `PALETTE_NITE`, or `PALETTE_DARK`. `PALETTE_AUTO` is based on the actual time of day. `PALETTE_DARK` requires Flash.
+- **fishing group:** Controls the group of wild Pokémon available by fishing. Valid fishing groups are defined in [constants/map_data_constants.asm](../blob/master/constants/map_data_constants.asm):
+
+
+## 5. Define its attributes
+
+Edit [data/maps/attributes.asm](../blob/master/data/maps/attributes.asm):
+
+```diff
+-	map_attributes GoldenrodCity, GOLDENROD_CITY, $35, NORTH | SOUTH
++	map_attributes GoldenrodCity, GOLDENROD_CITY, $35, NORTH | SOUTH | WEST
+ 	connection north, Route35, ROUTE_35, 5, 0, 10
+ 	connection south, Route34, ROUTE_34, 5, 0, 10
++	connection west, GlobalTerminalOutside, GLOBAL_TERMINAL_OUTSIDE, 0, 0, 18
++
++	map_attributes GlobalTerminalOutside, GLOBAL_TERMINAL_OUTSIDE, $35, EAST
++	connection east, GoldenrodCity, GOLDENROD_CITY, 0, 0, 18
+
+ ...
+
+ 	...
+ 	map_attributes Route31VioletGate, ROUTE_31_VIOLET_GATE, $00, 0
++	map_attributes GlobalTerminal1F, GLOBAL_TERMINAL_1F, $00, 0
+```
+
+The `map_attributes` macro takes four arguments: the map name, map ID, border block, and connections. The name and ID just identify the map; they aren't defining anything important.
+
+The **border block** is the block ID that fills the map's surroundings when you get too close to the edge. Usually it's trees for an outdoor map, water for the ocean, clifftop for a cave, solid black for a house, etc.
+
+The **connections** value is a combination of `NORTH`, `SOUTH`, `WEST`, or `EAST`, or 0 if the map has no connections. Only outdoor maps have connections; they're what let you walk straight from one map to another, without needing to warp via a door or staircase. Whatever connections a map has, it's followed by a `connection` macro for each of them, in north-south-west-east order.
+
+The `connection` macro takes six arguments: the direction, map name, map ID, X/Y offset, distance offset, and strip length. Again, the direction, map name, and map ID are just for identification, but the other three values are more complicated.
+
+- **X/Y offset:** How many blocks to shift a connection perpendicular to its direction. A north or south connection gets shifted right/east, a west or east connection gets shifted down/south.
+- **distance offset:** I don't fully understand this value. :/ For simple connections it's usually just 0.
+- **strip length:** How many blocks wide the connection is.
+
+Anyway, I can't fully explain how to determine the right values here; try looking at how other maps connect and base your own connections on them. In this case, we made `GLOBAL_TERMINAL_OUTSIDE` the same height as `GOLDENROD_CITY`, 18 blocks, and they'll line up perfectly side by side without any Y offset, so the connection values are easy to set.
+
+
+## 6. Write its event scripts
+
+Create **maps/GlobalTerminalOutside.asm**:
+
+```diff
++	const_def 2 ; object constants
++
++GlobalTerminalOutside_MapScripts:
++	db 0 ; scene scripts
++
++	db 0 ; callbacks
++
++GlobalTerminalOutside_MapEvents:
++	db 0, 0 ; filler
++
++	db 1 ; warp events
++	warp_event  8, 13, GLOBAL_TERMINAL_1F, 1
++
++	db 0 ; coord events
++
++	db 0 ; bg events
++
++	db 0 ; object events
+```
+
+And create **maps/GlobalTerminal1F.asm**:
+
+```diff
++	const_def 2 ; object constants
++
++GlobalTerminal1F_MapScripts:
++	db 0 ; scene scripts
++
++	db 0 ; callbacks
++
++GlobalTerminal1F_MapEvents:
++	db 0, 0 ; filler
++
++	db 2 ; warp events
++	warp_event  8, 11, GLOBAL_TERMINAL_OUTSIDE, 1
++	warp_event  9, 11, GLOBAL_TERMINAL_OUTSIDE, 1
++
++	db 0 ; coord events
++
++	db 0 ; bg events
++
++	db 0 ; object events
+```
+
+The only events defined so far are warps, so you can use the doors into and out of the Global Terminal building. (Their coordinates can be found with Polished Map's "Event Cursor" tool.)
+
+Writing event scripts is beyond the scope of this tutorial, but you can refer to [docs/map_event_scripts.md](..blob/master/docs/map_event_scripts.md) and [docs/event_commands.md](../blob/master/docs/event_commands.md) for help, and of course use existing map scripts for reference.
+
+You'll probably want a variety of NPCs in the Global Terminal, some from regions beyond Johto and Kanto, maybe with unique items and Pokémon to trade. It's a tall building, with room for more floors than just the one in this example.
+
+
+## 8. Include the block and script data
+
+We created some new files in maps/, but they aren't `INCLUDE`d in the project yet.
+
+Edit [data/maps/blocks.asm](../blob/master/data/maps/blocks.asm):
+
+```diff
++SECTION "Map Blocks 4", ROMX
++
++GlobalTerminalOutside_Blocks:
++	INCBIN "maps/GlobalTerminalOutside.blk"
++
++GlobalTerminal1F_Blocks:
++	INCBIN "maps/GlobalTerminal1F.blk"
+```
+
+And edit [data/maps/scripts.asm](../blob/master/data/maps/scripts.asm):
+
+```diff
+ SECTION "Map Scripts 25", ROMX
+ 
+ INCLUDE "maps/SilverCaveOutside.asm"
+ INCLUDE "maps/Route10North.asm"
++INCLUDE "maps/GlobalTerminalOutside.asm"
++INCLUDE "maps/GlobalTerminal1F.asm"
+```
+
+It doesn't really matter which `SECTION` these files go in. You can make new ones to keep them organized, or just keep filling the existing sections until they run out of space. (If `make` gives you a "Section is too big" or "Unable to place section in bank" error, you've overfilled a bank.)
+
+Anyway, we're done!
+
+![Screenshot](screenshots/global-terminal.png)
diff --git a/Tutorials.md b/Tutorials.md
index e3d6b1f..acb1727 100644
--- a/Tutorials.md
+++ b/Tutorials.md
@@ -9,6 +9,7 @@ Tutorials may use diff syntax to show edits:
 
 **How to add a new…**
 
+- [Map](Add-a-new-map)
 - [Pokémon species](Add-a-new-Pokémon)
 - [Trainer class](Add-a-new-trainer-class)
 - [Type (Fairy)](Add-a-new-Fairy-type)
diff --git a/screenshots/global-terminal-draft.png b/screenshots/global-terminal-draft.png
new file mode 100644
index 0000000..6d8f901
--- /dev/null
+++ b/screenshots/global-terminal-draft.png
diff --git a/screenshots/global-terminal.png b/screenshots/global-terminal.png
new file mode 100644
index 0000000..a667141
--- /dev/null
+++ b/screenshots/global-terminal.png
diff --git a/screenshots/polished-map-global-terminal-1f.png b/screenshots/polished-map-global-terminal-1f.png
new file mode 100644
index 0000000..ce126c7
--- /dev/null
+++ b/screenshots/polished-map-global-terminal-1f.png
diff --git a/screenshots/polished-map-global-terminal-outside.png b/screenshots/polished-map-global-terminal-outside.png
new file mode 100644
index 0000000..cf0ae21
--- /dev/null
+++ b/screenshots/polished-map-global-terminal-outside.png
diff --git a/screenshots/polished-map-goldenrod-city.png b/screenshots/polished-map-goldenrod-city.png
new file mode 100644
index 0000000..080dbfb
--- /dev/null
+++ b/screenshots/polished-map-goldenrod-city.png