Update 'Editing Map' manual pages

docsrc/manual/editing-map-connections.rst

@@ -8,6 +8,7 @@ Maps can be connected together so that the player can seamlessly walk between th
 
 .. figure:: images/editing-map-connections/map-connections.png
     :alt: Map Connections View
+    :align: center
 
     Map Connections View
 
@@ -40,4 +41,4 @@ You can select the ``Show Emerge/Dive Maps`` checkbox to view your connected div
 Mirror Connections
 ------------------
 
-An extremely useful feature is the *Mirror to Connecting Maps* checkbox in the top-right corner.  Connections are one-way, which means that you must keep the two connections in sync between the two maps.  For example, Petalburg City has a west connection to Route 104, and Route 104 has an east connection to Petalburg City.  If *Mirror to Connecting Maps* is enabled, then Porymap will automatically update both sides of the connection.  Be sure to *File -> Save All* (``Ctrl+Shift+S``) when saving, since you will need to save both maps' connections.
+An extremely useful feature is the *Mirror to Connecting Maps* checkbox in the top-right corner.  Connections are one-way, which means that you must keep the two connections in sync between the two maps.  For example, Petalburg City has a west connection to Route 104, and Route 104 has an east connection to Petalburg City.  If *Mirror to Connecting Maps* is enabled, then Porymap will automatically update both sides of the connection.  Be sure to ``File > Save All`` (``Ctrl+Shift+S``) when saving, since you will need to save both maps' connections.

docsrc/manual/editing-map-events.rst

@@ -8,28 +8,35 @@ Events are what bring your maps to life.  They include NPCs, signposts, warps, s
 
 .. figure:: images/editing-map-events/map-events.png
     :alt: Map Events View
+    :align: center
 
     Map Events View
 
-All of the events are visible on the map.  The Event Details window on the right displays the properties of the currently-selected event.  If you look closely, you'll see that the woman NPC near the Pokémon Center has a pink border around it because it's selected.  To select a different event, simply click on an event in the map area.  Alternatively, you can use the spinner at the top of the event properties window.  Multiple events can be selected at the same time by holding ``Ctrl`` and clicking another event.
+All of the events are visible on the map.  The Event Details window on the right displays the properties of the currently-selected event.  If you look closely, you'll see that the woman NPC near the Pokémon Center has a pink border around it because it's selected.  To select a different event, simply click on an event in the map area. Multiple events can be selected at the same time by holding ``Ctrl`` (``Cmd`` on macOS) and clicking another event. Alternatively, you can use the spinner at the top of the event properties window to cycle through events. 
 
 .. figure:: images/editing-map-events/event-id-spinner.png
     :alt: Event Id Spinner
+    :width: 75%
+    :align: center
 
     Event Id Spinner
 
 .. warning::
-    There is currently no undo/redo functionality when editing events!  Use Git version control!
+    There is currently no undo/redo functionality when editing information in the Event Details window!  Use Git version control!
 
 Adding & Deleting Events
 ------------------------
 
-To add a new event, press the green plus button. |add-event-button|  You can choose between the different types of events by clicking the small arrow on the right. You can also duplicate any currently selected events with ``Ctrl+D``.
+To add a new event, press the green plus button. You can choose between the different types of events by clicking the small arrow on the right side of the button. You can also duplicate any currently selected events with ``Ctrl+D``.
 
-.. |add-event-button|
-   image:: images/editing-map-events/add-event-button.png
+.. figure:: images/editing-map-events/add-event.png
+    :alt: Add Event Button
+    :width: 75%
+    :align: center
 
-To delete the selected event, press the delete button. |delete-event-button|
+    Add Event Button
+
+To delete the selected event, press the |delete-event-button| button.
 
 .. |delete-event-button|
    image:: images/editing-map-events/delete-event-button.png
@@ -41,6 +48,8 @@ All events have X/Y coordinates.  To move an Event, click and drag it to a new p
 
 .. figure:: images/editing-map-events/event-coords-spinners.png
     :alt: Event Coordinates Spinners
+    :width: 75%
+    :align: center
 
     Event Coordinates Spinners
 
@@ -48,21 +57,40 @@ Events also have an elevation, also known as Z coordinates (see image above).  E
 
 Next, we'll cover each type of event in detail.
 
+.. |field-frlg-exclusive|
+    replace:: Exclusive to pokefirered projects. Can be enabled under the ``Events`` tab of ``Options > Project Settings...``.
+
+.. |event-frlg-exclusive|
+    replace:: This event type is exclusive to pokefirered projects. If you have modified your pokeemerald/pokeruby project to support this event type, you can enable them under the ``Events`` tab of ``Options > Project Settings...``.
+
+.. |event-rse-exclusive|
+    replace:: This event type is exclusive to pokeemerald/pokeruby projects. If you have modified your pokefirered project to support this event type, you can enable them under the ``Events`` tab of ``Options > Project Settings...``.
+
+.. |id-description|
+    replace:: This is an optional field. Here you can give a *unique* name to your event so that you can refer to it elsewhere. If the event has no ID name, you can still refer to it using its number ID instead (the number next to the spinner at the top of the window).
+
+.. |script-description|
+    replace:: The script that executes when the player interacts with the event. The dropdown for this field contains all the scripts from the current map and any scripts already in-use by the map's events. You can enter the name of any script even if it doesn't appear in the dropdown.
+
 Object Events
 -------------
 
-Object events are typically used for NPCs (non-player-characters).  More technically, it's any event that has a sprite and the ability to move around.  Object events are displayed using their assigned sprite, except for special cases.  Any object event that uses a dynamic sprite will be displayed as a blue square with an `N` |dynamic-sprite|.  Some examples of dynamic sprites are the player's rival and berry trees.
+Object events are typically used for NPCs (non-player-characters).  More technically, it's any event that has a sprite and the ability to move around.  Object events are displayed using their assigned sprite, except for special cases.  Any object event that uses a dynamic sprite (like berry trees) or that Porymap doesn't recognize will be displayed as a blue square with an `N` |dynamic-sprite|.
 
 .. |dynamic-sprite|
    image:: images/editing-map-events/dynamic-sprite.png
 
 .. figure:: images/editing-map-events/event-object.png
     :alt: Object Event Properties
+    :width: 75%
+    :align: center
 
     Object Event Properties
 
-Id
-    This is the local id of the object in the map.  Some script values use this local id to specify an object when using scripting commands such as `applymovement`.
+Local ID
+    |id-description|
+
+    For example, if you give this object event a Local ID name of ``LOCALID_MY_NPC``, you could write in a script ``applymovement LOCALID_MY_NPC, MovementScript``, or ``applymovement 1, MovementScript``, and either one would apply to this event. The benefit of using ``LOCALID_MY_NPC`` over ``1`` is that if the number changes you won't have to update your scripts at all!
 
 Sprite
     The sprite that is used by the object.
@@ -74,34 +102,39 @@ Movement Radius X/Y
     Movement types that involves walking or moving around the map can be bounded by a radius.  The ensures that the object is always within the specified range from its original position.
 
 Script
-    The script that executes when the player interacts with the object.
+    |script-description|
 
 Event Flag
-    The flag value that controls if the object is visible.  If the flag is set (equal to 1), then the object will be invisible.  If the Event Flag is set to `0`, then the object will always be visible because `0` means "no flag".
+    The flag value that controls if the object is visible.  If the flag is set (equal to 1), then the object will be invisible.  If the flag is not set, or ``Event Flag`` is set to ``0`` (i.e., no flag), then the object will be visible.
 
 Trainer Type
-    The trainer type used by the object. If the object is a trainer, `TRAINER_TYPE_NORMAL` means that the trainer will spot the player in the object's line-of-sight.
+    The trainer type used by the object. If the object is a trainer, ``TRAINER_TYPE_NORMAL`` means that the trainer will spot the player in the object's line-of-sight.
 
 Sight Radius or Berry Tree ID
-    If the object is a trainer, this property control how many tiles the trainer can see to spot the player for battle.  If the object is a berry tree, this specifies the global id of the berry tree.  Each berry tree in the game has a unique berry tree id.
+    If the object is a trainer, this property control how many spaces away the trainer can see to spot the player for battle.  If the object is a berry tree, this specifies the global id of the berry tree.  Each berry tree in the game has a unique berry tree id.
 
 Clone Object Events
 -------------------
 
-Clone Object events are a special type of object that inherits its properties from another Object event. They are used in-game to load objects that are visible in the connecting area of adjacent maps. The targeted object to clone is specified by id and map name. If the targeted object does not exist, or it's also a clone, the sprite for graphics id 0 will be displayed instead. Double-clicking on a Clone Object will open the targeted map with the targeted object selected. This event type is exclusive to pokefirered projects; the code to process them does not exist in pokeemerald/pokeruby.
+Clone Object events are a special type of object that inherits its properties from another Object event. They are used in-game to load objects that are visible in the connecting area of adjacent maps. The targeted object to clone is specified by id and map name. If the targeted object does not exist, or it's also a clone, the sprite for graphics id 0 will be displayed instead. Double-clicking on a Clone Object will open the targeted map with the targeted object selected.
+
+.. note::
+    |event-frlg-exclusive|
 
 .. figure:: images/editing-map-events/event-clone-object.png
     :alt: Clone Object Event Properties
+    :width: 75%
+    :align: center
 
     Clone Object Event Properties
 
-Id
-    This is the local id of the object in the map.  Some script values use this local id to specify an object when using scripting commands such as `applymovement`.
+Local ID
+    |id-description|
 
 Sprite
     The sprite that is used by the object. Clone Objects inherit their sprite from the targeted object, so this cannot be edited. This field is not actually read by the game.
 
-Target Local Id
+Target Local ID
     The local id of the object to be cloned.
 
 Target Map
@@ -116,33 +149,36 @@ Warp events are how the player is able to warp to other maps, such as entering a
 
 .. figure:: images/editing-map-events/event-warp.png
     :alt: Warp Event Properties
+    :width: 75%
+    :align: center
 
     Warp Event Properties
 
-Id
-    This is the local id of the warp in the map.  This is used when setting the Destination Warp property for another warp.
+ID
+    |id-description|
+
+    This is used when setting the Destination Warp property for another warp.
 
 Destination Map
-    The destination map name.
+    The name of the map to travel to.
 
 Destination Warp
-    The Id of the warp in the destination map.
+    The ID of the warp to travel to.
 
 Trigger Events
 --------------
 
-Trigger events are scripts that execute when the player walks over them.  However, they only execute when a variable is equal some value.  Typically, they execute once, set the variable's value to something else, and then never execute again because the variable's value no longer matches.
+Trigger events are scripts that execute when the player walks over them.  However, they only execute when a variable is equal to some value.  Typically, they execute once, set the variable's value to something else, and then never execute again because the variable's value no longer matches.
 
 .. figure:: images/editing-map-events/event-trigger.png
     :alt: Trigger Event Properties
+    :width: 75%
+    :align: center
 
     Trigger Event Properties
 
-Id
-    The local id of the trigger in the map.  This value is not used for anything.
-
 Script
-    The script that executes when the player walks over the trigger AND when the `Var` equals the `Var Value`.
+    The script that executes when the player walks over the trigger AND when the value of ``Var`` equals ``Var Value``.
 
 Var
     The variable used to determine if the trigger's Script should execute.
@@ -153,16 +189,18 @@ Var Value
 Weather Trigger Events
 ----------------------
 
-Weather trigger events are a very specific type of trigger.  When the player walks over a weather trigger, the overworld's weather will transition to the specified weather type. This event type is unavailable for pokefirered projects; the functions to trigger weather changes were dummied out.
+Weather trigger events are a very specific type of trigger.  When the player walks over a weather trigger, the overworld's weather will transition to the specified weather type.
+
+.. note::
+    |event-rse-exclusive|
 
 .. figure:: images/editing-map-events/event-weather-trigger.png
     :alt: Weather Trigger Event Properties
+    :width: 75%
+    :align: center
 
     Weather Trigger Event Properties
 
-Id
-    The local id of the trigger in the map.  This value is not used for anything.
-
 Weather
     The type of weather to transition to.
 
@@ -173,17 +211,16 @@ Sign events, or signposts, are simple interactable scripts.  They are typically
 
 .. figure:: images/editing-map-events/event-sign.png
     :alt: Sign Event Properties
+    :width: 75%
+    :align: center
 
     Sign Event Properties
 
-Id
-    The local id of the BG event in the map.  This value is not used for anything.
-
 Player Facing Direction
     The direction the player must be facing in order to execute the sign's script.
 
 Script
-    The script that executes when the player interacts with the sign.
+    |script-description|
 
 Hidden Item Event
 -----------------
@@ -192,12 +229,11 @@ Hidden items are invisible items that can be picked up by the player. They each
 
 .. figure:: images/editing-map-events/event-hidden-item.png
     :alt: Hidden Item Event Properties
+    :width: 75%
+    :align: center
 
     Hidden Item Event Properties
 
-Id
-    The local id of the BG event in the map.  This value is not used for anything.
-
 Item
     The item the player will receive when interacting with this hidden item.
 
@@ -205,50 +241,84 @@ Flag
     This flag is set when the player receives the hidden item.
 
 Quantity
-    Exclusive to pokefirered. The number of items received when the item is picked up.
+    The number of items received when the item is picked up.
+
+    |field-frlg-exclusive|
 
 Requires Itemfinder
-    Exclusive to pokefirered. When checked, the hidden item can only be received by standing on it and using the Itemfinder.
+    When checked, the hidden item can only be received by standing on it and using the Itemfinder.
+
+    |field-frlg-exclusive|
 
 Secret Base Event
 -----------------
 
-This is the event used to mark entrances to secret bases.  This event will only be functional on certain metatiles.  Unfortunately, they are hardcoded into the game's engine (see ``sSecretBaseEntranceMetatiles`` in ``src/secret_base.c``).
-This event type is unavailable for pokefirered projects; secret bases do not exist there.
+This is the event used to mark entrances to secret bases.  This event will only be functional on certain metatiles.  Unfortunately, they are hardcoded into the game's engine (see ``sSecretBaseEntranceMetatiles`` in ``src/secret_base.c``). Double-clicking on a secret base will open the secret base's map (assuming Porymap is able to infer which map that is by looking at the ``Secret Base`` field).
+
+.. note::
+    |event-rse-exclusive|
 
 .. figure:: images/editing-map-events/event-secret-base.png
     :alt: Secret Base Event Properties
+    :width: 75%
+    :align: center
 
     Secret Base Event Properties
 
-Id
-    The local id of the BG event in the map.  This value is not used for anything.
-
-Secret Base Id
+Secret Base
     The id of the destination secret base.
 
-Heal Location / Healspots
--------------------------
+Heal Locations
+--------------
 
 This event is used to control where a player will arrive when they white out or fly to the map. The white out functions a little differently between game versions. For pokeemerald and pokeruby players will arrive at the event's coordinates after a white out, while in pokefirered they will arrive on the map set in ``Respawn Map`` and at hardcoded coordinates (see ``SetWhiteoutRespawnWarpAndHealerNpc`` in ``src/heal_location.c``).
 
 .. figure:: images/editing-map-events/event-heal-location.png
     :alt: Heal Location Properties
+    :width: 75%
+    :align: center
 
     Heal Location Properties
+ID
+    The unique ID name of this Heal Location Event. This is the name you'll use to refer to this heal location in scripts (e.g. ``setrespawn HEAL_LOCATION_MY_MAP``) or elsewhere in your project. Unlike other ID name fields, this name is required and cannot be substituted with the ID number at the top of the window.
 
 Respawn Map
-    Exclusive to pokefirered. The map where the player will arrive when they white out (e.g. inside the PokéCenter that the heal location is in front of).
+    The map where the player will arrive when they white out (e.g. inside the PokéCenter that the heal location is in front of).
+
+    |field-frlg-exclusive|
 
 Respawn NPC
-    Exclusive to pokefirered. The local id of the NPC the player will interact with when they white out.
+    The local id of the NPC the player will interact with when they white out.
+
+    |field-frlg-exclusive|
+
+.. _custom-attributes:
+
+Custom Attributes
+-----------------
+
+Under each event you'll also find the ``Custom Attributes`` table. This lets you add new data to any event. By default it is empty, and only the ``Add`` button is enabled.
+
+.. figure:: images/editing-map-events/custom-attributes.png
+    :alt: Custom Attributes
+    :width: 35%
+    :align: center
+
+When you click ``Add`` you will be prompted to enter the name of your new data field, what type of data it is, and the value. Once added you can edit their values in the table, or select an entry and click ``Delete`` to remove it.
+
+.. figure:: images/editing-map-events/custom-attributes-table.png
+    :alt: Custom Attributes Table
+    :width: 75%
+    :align: center
+
+At the moment our new data has no impact on the game, but we can write code in our project to do whatever we want with it! The new data can be found in the ``map.json`` file of whatever map it was added to. Normally these ``map.json`` files are handled by a tool in your project called ``mapjson``, so to use your new data you may need to modify this tool.
 
 Open Map Scripts
 ----------------
 
-Clicking the ``Open Map Scripts`` button |open-map-scripts-button| will open the map's scripts file in your default text editor.  If nothing happens when this button is clicked, you may need to associate a text editor with the `.inc` file extension (or `.pory` if you're using Porycript).
+Clicking the |open-map-scripts-button| button will open the map's scripts file in your default text editor.  If nothing happens when this button is clicked, you may need to associate a text editor with the ``.inc`` file extension (or ``.pory`` if you're using Porycript).
 
-Additionally, if you specify a ``Goto Line Command`` in *Options -> Edit Preferences* then a tool-button will appear next to the `Script` combo-box in the *Events* tab. Clicking this button will open the file that contains the script directly to the line number of that script. If the script cannot be found in the project then the current map's scripts file is opened.
+Additionally, if you specify a ``Goto Line Command`` in ``Preferences...`` then a tool-button will appear next to the ``Script`` combo-box in the ``Events`` tab. Clicking this button will open the file that contains the script directly to the line number of that script. If the script cannot be found in the project then the current map's scripts file is opened.
 |go-to-script-button|
 
 .. |open-map-scripts-button|
@@ -261,13 +331,13 @@ Tool Buttons
 ------------
 
 The event editing tab also extends functionality to a few of the tool buttons described in :ref:`Editing Map Tiles <editing-map-tiles>`.
-A brief description and animation is listed for each of the available tools below:
 
 Pencil
-    When clicking on an existing event, the pencil tool will behave normally (as the standard cursor). It can also be used to "draw" events in a certain location. The event created will be a default-valued event of the same type as the currently selected event. Right-clicking with the Pencil Tool will return to the Pointer tool.
+    Clicking on an empty space will create a new event of the same type as your currently-selected event. This is the same as clicking the New Event button except that the new event will be positioned under your cursor. Right-clicking with the Pencil Tool will return to the Pointer tool.
 
 .. figure:: images/editing-map-events/event-tool-pencil.gif
     :alt: Drawing Object Events with the Pencil Tool
+    :align: center
 
     Drawing Object Events with the Pencil Tool
 
@@ -279,6 +349,7 @@ Shift
 
 .. figure:: images/editing-map-events/event-tool-shift.gif
     :alt: Moving Events with the Shift Tool
+    :align: center
 
     Moving Events with the Shift Tool
 
@@ -291,5 +362,9 @@ The Ruler Tool provides a convenient way to measure distance on the map. This is
 
 .. figure:: images/editing-map-events/event-tool-ruler.gif
     :alt: Measuring metatile distance with the Ruler Tool
+    :align: center
 
     Measuring metatile distance with the Ruler Tool
+
+.. tip::
+    If you'd like to see your events while editing the map, select ``View > Show Events in Map View``.

docsrc/manual/editing-map-header.rst

@@ -8,6 +8,8 @@ The map header is a collection of miscellaneous properties that belong to a map.
 
 .. figure:: images/editing-map-header/map-header.png
     :alt: Map Header View
+    :width: 80%
+    :align: center
 
     Map Header View
 
@@ -17,6 +19,9 @@ Song
 Location
     The region map section to which the map belongs.
 
+Location Name
+    The in-game name that can appear for this map. This name is shared with all maps that use the same ``Location``.
+
 Requires Flash
     Whether or not the map has limited vision which the HM move Flash can expand.
 
@@ -42,7 +47,11 @@ Allow Dig & Escape Rope
     Controls whether the Dig field move or the Escape Rope item can be used.
 
 Floor Number
-    Exclusive to pokefirered. Used to append a number to the map name popup. Negative values are prefixed with "B" for basement, and floor 127 is "Rooftop".
+    Used to append a number to the map name popup. Negative values are prefixed with "B" for basement, and floor 127 is "Rooftop".
 
-Custom Fields
-    You can enter custom fields if you need support for additional fields in your project.  They can also be useful for keeping notes.
+Custom Attributes
+    You can enter new data if you need support for additional fields in your project.  They can also be useful for keeping notes. See :ref:`Custom Attributes <custom-attributes>`
+
+
+.. note::
+    ``Allow Running``, ``Allow Biking``, and ``Allow Dig & Escape Rope`` are disabled by default for pokeruby projects. ``Floor Number`` is disabled by default for pokeruby and pokeemerald projects. Their behavior is normally handled some other way, or doesn't exist. If you have modified your pokeruby/pokeemerald project to use one of these disabled fields, they can be enabled on the ``Maps`` tab of ``Options > Project Settings...``.

docsrc/manual/editing-map-tiles.rst

@@ -4,17 +4,19 @@
 Editing Map Tiles
 *****************
 
-Editing map tiles takes place in Porymap's Main Window.  The map is laid out in a grid of what are called "metatiles".  The editing basic flow is to make a metatile selection, and then paint that metatile selection onto the map.
+Editing map tiles takes place in Porymap's Main Window.  The map is laid out in a grid of what are called "metatiles".  The basic editing flow is to make a metatile selection, and then paint that metatile selection onto the map.
 
 Visual Options
 --------------
 
 Before getting into the details of editing map tiles, you should be aware of some settings that make your life easier.
 
-A grid can be displayed over the editable map area by using the ``Grid`` checkbox, which is located in the toolbar above the map area.
+A grid can be displayed over the editable map area by using the ``Grid`` checkbox, which is located in the toolbar above the map area. The appearance of the grid can be changed with ``View > Grid Settings...``.
 
 .. figure:: images/editing-map-tiles/map-grid.png
     :alt: Map Grid
+    :width: 70%
+    :align: center
 
     Map Grid
 
@@ -22,19 +24,23 @@ The border's visibility, including the surrounding map connections, can be toggl
 
 .. figure:: images/editing-map-tiles/map-border-off.png
     :alt: Map Border Toggled Off
+    :width: 70%
+    :align: center
 
     Map Border Toggled Off
 
-You can zoom in and out on the map with *View -> Zoom In* (``Ctrl++`` or ``Ctrl+Mouse Wheel Scroll Up``) and *View -> Zoom Out* (``Ctrl+-`` or ``Ctrl+Mouse Wheel Scroll Down``).
+You can zoom in and out on the map with ``View > Zoom In`` (``Ctrl++`` or ``Ctrl+Mouse Wheel Scroll Up``) and ``View > Zoom Out`` (``Ctrl+-`` or ``Ctrl+Mouse Wheel Scroll Down``).
 
-By default, the mouse cursor will show a white indicator outline of the currently-hovered tile(s) of what will be painted.  You can disable this outline with *View -> Cursor Tile Outline* (``C``).  Additionally, the cursor changes its appearance depending on which tool you currently have selected in the toolbar.  You can disable this with *View -> Cursor Icons*.
+By default, the mouse cursor will show a white indicator outline of the currently-hovered tile(s) of what will be painted.  You can disable this outline with ``View > Cursor Tile Outline`` (``C``).  Additionally, the cursor changes its appearance depending on which tool you currently have selected in the toolbar.  You can disable this with ``View > Cursor Icons``.
 
-An indicator outline for the player's in-game view radius can be toggled with *View -> Player View Rectangle* (``V``).
+An indicator outline for the player's in-game view radius can be toggled with ``View > Player View Rectangle`` (``V``).
 
 The Metatile Selection Pane can be zoomed in or out using the slider on the bottom.
 
 .. figure:: images/editing-map-tiles/metatile-selection-slider.png
     :alt: Metatile Selection Zoom Slider
+    :width: 40%
+    :align: center
 
     Metatile Selection Zoom Slider
 
@@ -45,76 +51,103 @@ Before you paint onto the map, you need to select which metatiles you will be pa
 
 .. figure:: images/editing-map-tiles/single-metatile-selection.gif
     :alt: Basic Metatile Selection
+    :align: center
 
     Basic Metatile Selection
 
-You can select more than one tile at a time by clicking and dragging the desired region.  For example, it's convenient to select the entire Pokémon Center at once.
+You can select more than one tile at a time by clicking and dragging the desired region.  For example, it's convenient to select the entire Pokémon Center at once. If your selection is too large to see, you can also resize the selection window.
 
 .. figure:: images/editing-map-tiles/multiple-metatile-selection.gif
     :alt: Multiple Metatile Selection
+    :align: center
 
     Multiple Metatile Selection
 
-Metatiles can also be selected from existing metatiles on the map area.  Use the Eyedropper Tool with *Tools -> Eyedropper* (``E``), or simply click the Eyedropper button |eyedropper-tool| in the toolbar above the map area.  A more powerful way to do this is to right-click on the map when using the Pencil Tool or Bucket Fill Tool.  You can even right-click and drag to copy a region from the map.  In this example GIF, we demonstrate how quick and easy it is to use the right-click method to copy and paint metatiles.
+Metatiles can also be selected from existing metatiles on the map area.  Use the Eyedropper Tool with ``Tools > Eyedropper`` (``E``), or simply click the |eyedropper-tool| button in the toolbar above the map area.  A more powerful way to do this is to right-click on the map when using the Pencil Tool or Bucket Fill Tool.  You can even right-click and drag to copy a region from the map.
 
 .. figure:: images/editing-map-tiles/right-click-metatile-selection.gif
     :alt: Right-Click Metatile Selection
+    :align: center
 
     Right-Click Metatile Selection
 
 .. |eyedropper-tool|
    image:: images/editing-map-tiles/eyedropper-tool.png
+   :height: 24
 
 Now, let's learn how to use the various tools to paint your metatile selection onto the map.
 
 Pencil Tool
 -----------
 
-The Pencil Tool |pencil-tool| (*Tools -> Pencil*, or ``N``) is your bread and butter when editing maps.  Simply left-click to paint your current metatile selection onto the map.  You can click and drag to paint a bigger portion of the map.  When clicking and dragging, the metatiles will be painted as if they are snapping to a grid.  This simplifies things like painting large areas of trees.
+The Pencil Tool |pencil-tool| (``Tools > Pencil``, or ``N``) is your bread and butter when editing maps.  Simply left-click to paint your current metatile selection onto the map.  You can click and drag to paint a bigger portion of the map.  When clicking and dragging, the metatiles will be painted as if they are snapping to a grid.  This simplifies things like painting large areas of trees.
 
 .. figure:: images/editing-map-tiles/snapping-painting.gif
     :alt: Painting a Large Metatile Selection
+    :align: center
 
     Painting a Large Metatile Selection
 
 .. |pencil-tool|
    image:: images/editing-map-tiles/pencil-tool.png
+   :height: 24
 
 Pointer Tool
 ------------
 
-The Pointer Tool |pointer-tool| (*Tools -> Pointer*, or ``P``) doesn't do anything.  It just allows you to click on the map without painting anything.
+The Pointer Tool |pointer-tool| (``Tools > Pointer``, or ``P``) doesn't do anything.  It just allows you to click on the map without painting anything.
 
 .. |pointer-tool|
    image:: images/editing-map-tiles/pointer-tool.png
+   :height: 24
 
 Bucket Fill Tool
 ----------------
 
-The Bucket Fill Tool |bucket-fill-tool| (*Tools -> Bucket Fill*, or ``B``) works just like you think it does.  It fills a contiguous region of identical metatiles.  If you have a large metatile selection, it will fill the region with that pattern.  A useful shortcut for the Bucket Fill Tool is to middle-click when using the Pencil Tool.
+The Bucket Fill Tool |bucket-fill-tool| (``Tools > Bucket Fill``, or ``B``) works just like you think it does.  It fills a contiguous region of identical metatiles.  If you have a large metatile selection, it will fill the region with that pattern.
 
 .. figure:: images/editing-map-tiles/bucket-fill-painting.gif
     :alt: Painting with Bucket Fill Tool
+    :align: center
 
     Painting with Bucket Fill Tool
 
 .. |bucket-fill-tool|
    image:: images/editing-map-tiles/bucket-fill-tool.png
+   :height: 24
+
+Holding down the ``Ctrl`` key (or ``Cmd``, on macOS) while using the Bucket Fill Tool will fill *all* matching metatiles on the map, rather that just the contiguous region.
+
+Move Tool
+---------
+
+The Move Tool |move-tool| (``Tools > Move``, or ``M``) lets you pan around the map by clicking and dragging. You can also pan around the map with middle-click or by scrolling.
+
+.. figure:: images/editing-map-tiles/map-pan.gif
+    :alt: Panning with Move Tool
+    :align: center
+
+    Panning with Move Tool
+
+.. |move-tool|
+   image:: images/editing-map-tiles/move-tool.png
+   :height: 24
 
-Holding down the ``Ctrl`` key while using the Bucket Fill Tool will fill *all* matching metatiles on the map, rather that just the contiguous region.
 
 Map Shift Tool
 --------------
 
-The Map Shift Tool |map-shift-tool| (*Tools -> Map Shift*, or ``S``) lets you shift the metatile positions of the entire map at the same time.  This is useful after resizing a map.  (Though, simply right-click copying the entire map is another way of accomplishing the same thing.)  Metatiles are wrapped around to the other side of the map when using the Map Shift Tool.  Simply click and drag on the map to perform the map shift.
+The Map Shift Tool |map-shift-tool| (``Tools > Map Shift``, or ``S``) lets you shift the metatile positions of the entire map at the same time.  This is useful after resizing a map.  (Though, simply right-click copying the entire map is another way of accomplishing the same thing.)  Metatiles are wrapped around to the other side of the map when using the Map Shift Tool.  Simply click and drag on the map to perform the map shift.
 
 .. figure:: images/editing-map-tiles/map-shift-painting.gif
     :alt: Map Shift Tool
+    :align: center
 
     Map Shift Tool
 
 .. |map-shift-tool|
    image:: images/editing-map-tiles/map-shift-tool.png
+   :height: 24
 
 Smart Paths
 -----------
@@ -123,23 +156,76 @@ Smart Paths provide an easy way to paint pathways, ponds, and mountains.  If the
 
 .. figure:: images/editing-map-tiles/smart-paths-1-painting.gif
     :alt: Regular vs. Smart Paths
+    :align: center
 
     Regular vs. Smart Paths
 
 .. figure:: images/editing-map-tiles/smart-paths-2-painting.gif
     :alt: Bucket Fill with Smart Paths
+    :align: center
 
     Bucket Fill with Smart Paths
 
 .. figure:: images/editing-map-tiles/smart-paths-3-painting.gif
     :alt: Smart Paths from Right-Click Selection
+    :align: center
 
     Smart Paths from Right-Click Selection
 
 Straight Paths
 --------------
 
-Straight Paths allows for painting tiles in straight lines by snapping the cursor to that line.  Either the X or Y axis will be locked depending on the direction you start painting in.  To enable straight paths simply hold down ``Ctrl`` when painting tiles.  Straight paths works for both metatiles and collision tiles, and works in conjunction with *Smart Paths*.  It also works with the *Map Shift Tool*.  Straight path painting can be chained together with normal painting to allow you, for example, to paint a straight path, then release ``Ctrl`` to continue the path normally, then press ``Ctrl`` again to continue painting a straight path from that position.
+Straight Paths allows for painting tiles in straight lines by snapping the cursor to that line.  Either the X or Y axis will be locked depending on the direction you start painting in.  To enable straight paths simply hold down ``Ctrl`` (or ``Cmd``, on macOS) when painting tiles.  Straight paths works for both metatiles and collision tiles, and works in conjunction with *Smart Paths*.  It also works with the *Map Shift Tool*.  Straight path painting can be chained together with normal painting to allow you, for example, to paint a straight path, then release ``Ctrl`` to continue the path normally, then press ``Ctrl`` again to continue painting a straight path from that position.
+
+Change Dimensions
+-----------------
+
+The dimensions of the map can be changed with the |change-dimensions| button. Clicking this button will bring up an interactive resizing window. Click and drag the borders around the map image to change the size of the map, or enter a specific size with the number inputs at the top. You can click and drag the map around to reposition it within the new size rectangle. Anything outside the rectangle when you finish will be deleted. If you'd like to undo your changes in this window you can hit |reset| to return to the original size and position.
+
+.. figure:: images/editing-map-tiles/map-resizing.gif
+    :alt: Resizing the map
+    :align: center
+
+    Resizing the map
+
+
+Border Dimensions
+^^^^^^^^^^^^^^^^^
+
+The dimensions of the map's border can also be adjusted on this window for pokefirered projects via the ``Border Width`` and ``Border Height`` number inputs. If you have modified your pokeemerald or pokeruby project to support custom border sizes you can enable this option by checking ``Enable Custom Border Size`` on the ``Maps`` tab of ``Options > Project Settings...``.
+
+.. |change-dimensions|
+   image:: images/editing-map-tiles/change-dimensions.png
+   :height: 24
+
+.. |reset|
+   image:: images/editing-map-tiles/reset.png
+   :height: 24
+
+Change Layout
+-------------
+
+The core visual data of the map is called the "layout". A map's size, which tilesets it uses, its border, metatiles, and collision/elevation are all part of the layout. The layout for the current map can be swapped using the Layout dropdown. This might be useful if you have multiple versions of the same map that you'd like to alternate between.
+
+.. figure:: images/editing-map-tiles/layout-dropdown.png
+    :alt: Layout Dropdown
+    :width: 40%
+    :align: center
+
+    Layout Dropdown
+
+
+Change Map Tilesets
+-------------------
+
+Every map uses exactly two Tilesets--primary and secondary.  These can be changed by choosing a different value from the two Tileset dropdowns.
+
+.. figure:: images/editing-map-tiles/tileset-dropdowns.png
+    :alt: Tileset Dropdowns
+    :width: 40%
+    :align: center
+
+    Tileset Dropdowns
 
 Change Map Border
 -----------------
@@ -148,25 +234,15 @@ The map's border can be modified by painting on the Border image, which is locat
 
 .. figure:: images/editing-map-tiles/map-border.png
     :alt: Change Map Border
+    :width: 40%
+    :align: center
 
     Change Map Border
 
-The dimensions of the map's border can also be adjusted for pokefirered projects via the ``Change Dimensions`` button. If you have modified your pokeemerald or pokeruby project to support custom border sizes you can enable this option with the ``use_custom_border_size`` field in your project's ``porymap.project.cfg`` file.
-
-Change Map Tilesets
--------------------
-
-Every map uses exactly two Tilesets--primary and secondary.  These can be changed by choosing a different value from the two Tileset dropdowns.
-
-.. figure:: images/editing-map-tiles/tileset-pickers.png
-    :alt: Tileset Pickers
-
-    Tileset Pickers
-
 Undo & Redo
 -----------
 
-When painting metatiles, you can undo and redo actions you take.  This makes it very easy to fix mistakes or go back in time.  Undo can be performed with ``Ctrl+Z`` or *Edit -> Undo*.  Redo can be performed with ``Ctrl+Y`` or *Edit -> Redo*.
+When painting metatiles, you can undo and redo actions you take.  This makes it very easy to fix mistakes or go back in time.  Undo can be performed with ``Ctrl+Z`` or ``Edit > Undo``.  Redo can be performed with ``Ctrl+Y``/``Ctrl+Shift+Z`` or ``Edit > Redo``.
 
 
 .. _editing-map-tiles-prefabs:
@@ -178,25 +254,29 @@ Prefabs, or "prefabricated selections", are a way to optimize your map-editing w
 
 .. figure:: images/editing-map-tiles/prefab-list.png
     :alt: Prefab Tab
+    :width: 40%
+    :align: center
 
     Prefab Tab
 
-Porymap provides a set of default prefabs for each supported base game version (pokeemerald, pokefirered, and pokeruby). When opening a project for the first time, Porymap will prompt the user for importing those default prefabs.
+Porymap provides a set of default prefabs for each supported base game version (pokeemerald, pokefirered, and pokeruby). When you first open the ``Prefabs`` tab for your project Porymap will prompt you to import those default prefabs.
 
 To create a new prefab, simply select a group of metatiles from the main map view. (See the `Selecting Metatiles`_. section above for how to use right-click-drag to select from the map area.) Then, click the "Create from Selection" button. This will bring up the following window where individual metatiles can be toggled on/off in the prefab. You can also give your prefab a name.
 
 .. figure:: images/editing-map-tiles/prefab-create.png
     :alt: Prefab Creation Window
+    :align: center
 
     Prefab Creation Window
 
-Prefabs are designated for whichever primary and secondary tilesets were used to create them. As such, any prefabs for with tilesets that are incompatible with the currently-opened map will be hidden from the Prefab list.
+Prefabs are designated for whichever primary and secondary tilesets were used to create them. As such, any prefabs using tilesets that are incompatible with the currently-opened map will be hidden from the Prefab list.
 
 To select a prefab to use for painting on the map, simply click on the prefab image in the list view.
 
 .. figure:: images/editing-map-tiles/prefab-demo.gif
     :alt: Painting with a Prefab
+    :align: center
 
     Painting with a Prefab
 
-Prefab data is saved to a JSON file. It defaults to ``<project_root>/prefabs.json``. However, it can be configured in Porymap's project config file using the ``prefabs_filepath`` setting.
+Prefab data is saved to a JSON file. It defaults to ``<project_root>/prefabs.json``. This path can be changed at any time by editing ``Prefabs Path`` on the ``General`` tab of ``Options > Project Settings...``.