Update project files manual page

docsrc/manual/editing-map-events.rst

@@ -110,7 +110,7 @@ Target Map
 Warp Events
 -----------
 
-Warp events are how the player is able to warp to other maps, such as entering a building.  Double-clicking on a warp will automatically open the destination map and select the destination warp.  This makes it very easy to navigate around in Porymap. Warps need to be on specific metatiles to function as an exit; a warning will appear if the warp event is not on one of these exits.
+Warp events are how the player is able to warp to other maps, such as entering a building.  Double-clicking on a warp will automatically open the destination map and select the destination warp.  This makes it very easy to navigate around in Porymap. Warps need to be on specific metatiles to function as an exit; a warning will appear if the warp event is not on one of these metatiles.
 
 .. figure:: images/editing-map-events/event-warp.png
     :alt: Warp Event Properties

docsrc/manual/project-files.rst

@@ -6,15 +6,16 @@ Porymap relies on the user maintaining a certain level of integrity with their p
 This is a list of files that porymap reads from and writes to. Generally, if porymap writes 
 to a file, it probably is not a good idea to edit yourself unless otherwise noted.
 
-The filepath that Porymap expects for each file can be overridden under the ``Project Files`` section of ``Options -> Project Settings``. A new path can be specified by entering it in the text box or choosing it with the |button-folder| button. Paths are expected to be relative to the root project folder. If no path is specified, or if the file/folder specified does not exist, then the default path will be used instead. The name of each setting in this section is listed in the table below under ``Override``.
+The filepath that Porymap expects for each file can be overridden on the ``Files`` tab of ``Options -> Project Settings``. A new path can be specified by entering it in the text box or choosing it with the |button-folder| button. Paths are expected to be relative to the root project folder. If no path is specified, or if the file/folder specified does not exist, then the default path will be used instead. The name of each setting in this section is listed in the table below under ``Override``.
 
 .. |button-folder| image:: images/scripting-capabilities/folder.png
    :width: 24
    :height: 24
 
-.. figure:: images/settings-and-options/tab-project-files.png
+.. figure:: images/settings-and-options/tab-files.png
-   :alt: Project Files tab
+   :alt: Files tab
 
+.. _files:
 
 .. csv-table::
    :header: File Name,Read,Write,Override,Notes
@@ -43,7 +44,7 @@ The filepath that Porymap expects for each file can be overridden under the ``Pr
    src/data/heal_locations.h, yes, yes, ``data_heal_locations``,
    src/data/region_map/region_map_sections.json, yes, yes, ``json_region_map_entries``,
    src/data/region_map/porymap_config.json, yes, yes, ``json_region_porymap_cfg``,
-   include/constants/global.h, yes, no, ``constants_global``, reads ``OBJECT_EVENT_TEMPLATES_COUNT``
+   include/constants/global.h, yes, no, ``constants_global``, reads ``define_obj_event_count``
    include/constants/map_groups.h, no, yes, ``constants_map_groups``,
    include/constants/items.h, yes, no, ``constants_items``, for Hidden Item events
    include/constants/flags.h, yes, no, ``constants_flags``, for Object and Hidden Item events
@@ -51,7 +52,7 @@ The filepath that Porymap expects for each file can be overridden under the ``Pr
    include/constants/weather.h, yes, no, ``constants_weather``, for map weather and Weather Triggers
    include/constants/songs.h, yes, no, ``constants_songs``, for map music
    include/constants/heal_locations.h, yes, yes, ``constants_heal_locations``,
-   include/constants/pokemon.h, yes, no, ``constants_pokemon``, reads ``MIN_LEVEL`` and ``MAX_LEVEL``
+   include/constants/pokemon.h, yes, no, ``constants_pokemon``, reads ``define_min_level`` and ``define_max_level``
    include/constants/map_types.h, yes, no, ``constants_map_types``,
    include/constants/trainer_types.h, yes, no, ``constants_trainer_types``, for Object events
    include/constants/secret_bases.h, yes, no, ``constants_secret_bases``, pokeemerald and pokeruby only
@@ -62,9 +63,74 @@ The filepath that Porymap expects for each file can be overridden under the ``Pr
    include/constants/metatile_labels.h, yes, yes, ``constants_metatile_labels``,
    include/constants/metatile_behaviors.h, yes, no, ``constants_metatile_behaviors``,
    include/constants/species.h, yes, no, ``constants_metatile_behaviors``, for the Wild Pokémon tab
+   include/global.fieldmap.h, yes, no, ``global_fieldmap``, reads map and tileset data masks
    include/fieldmap.h, yes, no, ``constants_fieldmap``, reads tileset related constants
-   src/event_object_movement.c, yes, no, ``initial_facing_table``, reads ``gInitialMovementTypeFacingDirections``
+   src/fieldmap.c, yes, no, ``fieldmap``, reads ``symbol_attribute_table``
-   src/pokemon_icon.c, yes, no, ``pokemon_icon_table``, reads files in ``gMonIconTable``
+   src/event_object_movement.c, yes, no, ``initial_facing_table``, reads ``symbol_facing_directions``
-   graphics/pokemon/*/icon.png, yes, no, ``pokemon_gfx``, to search for Pokémon icons if they aren't found in ``gMonIconTable``
+   src/pokemon_icon.c, yes, no, ``pokemon_icon_table``, reads files in ``symbol_pokemon_icon_table``
+   graphics/pokemon/\*/icon.png, yes, no, ``pokemon_gfx``, to search for Pokémon icons if they aren't found in ``symbol_pokemon_icon_table``
 
 
+In addition to these files, there are some specific symbol and macro names that Porymap expects to find in your project. These can be overridden on the ``Identifiers`` tab of ``Options -> Project Settings``. The name of each setting in this section is listed in the table below under ``Override``. Overrides with ``regex`` in the name support the `regular expression syntax <https://perldoc.perl.org/perlre>`_ used by Qt.
+
+.. figure:: images/settings-and-options/tab-identifiers.png
+   :alt: Files tab
+
+.. _identifiers:
+
+.. csv-table::
+   :header: Override,Default,Notes
+   :widths: 20, 20, 30
+
+   ``symbol_facing_directions``, ``gInitialMovementTypeFacingDirections``, to set sprite frame for Object Events based on movement type
+   ``symbol_obj_event_gfx_pointers``, ``gObjectEventGraphicsInfoPointers``, to map Object Event graphics IDs to graphics data
+   ``symbol_pokemon_icon_table``, ``gMonIconTable``, to map species constants to icon images
+   ``symbol_wild_encounters``, ``gWildMonHeaders``, output as the ``label`` property for the top-level wild ecounters JSON object
+   ``symbol_heal_locations``, ``sHealLocations``, only if ``Respawn Map/NPC`` is disabled
+   ``symbol_spawn_points``, ``sSpawnPoints``, only if ``Respawn Map/NPC`` is enabled
+   ``symbol_spawn_maps``, ``sWhiteoutRespawnHealCenterMapIdxs``, values for Heal Locations ``Respawn Map`` field
+   ``symbol_spawn_npcs``, ``sWhiteoutRespawnHealerNpcIds``, values for Heal Locations ``Respawn NPC`` field
+   ``symbol_attribute_table``, ``sMetatileAttrMasks``, optionally read to get settings on ``Tilesets`` tab
+   ``symbol_tilesets_prefix``, ``gTileset_``, for new tileset names and to extract base tileset names
+   ``define_obj_event_count``, ``OBJECT_EVENT_TEMPLATES_COUNT``, to limit total Object Events
+   ``define_min_level``, ``MIN_LEVEL``, minimum wild encounters level
+   ``define_max_level``, ``MAX_LEVEL``, maximum wild encounters level
+   ``define_tiles_primary``, ``NUM_TILES_IN_PRIMARY``, 
+   ``define_tiles_total``, ``NUM_TILES_TOTAL``,
+   ``define_metatiles_primary``, ``NUM_METATILES_IN_PRIMARY``, total metatiles are calculated using metatile ID mask
+   ``define_pals_primary``, ``NUM_PALS_IN_PRIMARY``,
+   ``define_pals_total``, ``NUM_PALS_TOTAL``, 
+   ``define_map_size``, ``MAX_MAP_DATA_SIZE``, to limit map dimensions
+   ``define_mask_metatile``, ``MAPGRID_METATILE_ID_MASK``, optionally read to get settings on ``Maps`` tab
+   ``define_mask_collision``, ``MAPGRID_COLLISION_MASK``, optionally read to get settings on ``Maps`` tab
+   ``define_mask_elevation``, ``MAPGRID_ELEVATION_MASK``, optionally read to get settings on ``Maps`` tab
+   ``define_mask_behavior``, ``METATILE_ATTR_BEHAVIOR_MASK``, optionally read to get settings on ``Tilesets`` tab
+   ``define_mask_layer``, ``METATILE_ATTR_LAYER_MASK``, optionally read to get settings on ``Tilesets`` tab
+   ``define_attribute_behavior``, ``METATILE_ATTRIBUTE_BEHAVIOR``, name used to extract setting from ``symbol_attribute_table``
+   ``define_attribute_layer``, ``METATILE_ATTRIBUTE_LAYER_TYPE``, name used to extract setting from ``symbol_attribute_table``
+   ``define_attribute_terrain``, ``METATILE_ATTRIBUTE_TERRAIN``, name used to extract setting from ``symbol_attribute_table``
+   ``define_attribute_encounter``, ``METATILE_ATTRIBUTE_ENCOUNTER_TYPE``, name used to extract setting from ``symbol_attribute_table``
+   ``define_metatile_label_prefix``, ``METATILE_``, expected prefix for metatile label macro names
+   ``define_heal_locations_prefix``, ``HEAL_LOCATION_``, output as prefix for Heal Location IDs if ``Respawn Map/NPC`` is disabled
+   ``define_spawn_prefix``, ``SPAWN_``, output as prefix for Heal Location IDs if ``Respawn Map/NPC`` is enabled
+   ``define_map_prefix``, ``MAP_``, expected prefix for map macro names
+   ``define_map_dynamic``, ``DYNAMIC``, macro name after prefix for Dynamic maps
+   ``define_map_empty``, ``UNDEFINED``, macro name after prefix for empty maps
+   ``define_map_section_prefix``, ``MAPSEC_``, expected prefix for location macro names
+   ``define_map_section_empty``, ``NONE``, macro name after prefix for empty region map sections
+   ``define_map_section_count``, ``COUNT``, macro name after prefix for total number of region map sections
+   ``regex_behaviors``, ``\bMB_``, regex to find metatile behavior macro names
+   ``regex_obj_event_gfx``, ``\bOBJ_EVENT_GFX_``, regex to find Object Event graphics ID macro names
+   ``regex_items``, ``\bITEM_(?!(B_)?USE_)``, regex to find item macro names
+   ``regex_flags``, ``\bFLAG_``, regex to find flag macro names
+   ``regex_vars``, ``\bVAR_``, regex to find var macro names
+   ``regex_movement_types``, ``\bMOVEMENT_TYPE_``, regex to find movement type macro names
+   ``regex_map_types``, ``\bMAP_TYPE_``, regex to find map type macro names
+   ``regex_battle_scenes``, ``\bMAP_BATTLE_SCENE_``, regex to find battle scene macro names
+   ``regex_weather``, ``\bWEATHER_``, regex to find map weather macro names
+   ``regex_coord_event_weather``, ``\bCOORD_EVENT_WEATHER_``, regex to find weather trigger macro names
+   ``regex_secret_bases``, ``\bSECRET_BASE_[A-Za-z0-9_]*_[0-9]+``, regex to find secret base ID macro names
+   ``regex_sign_facing_directions``, ``\bBG_EVENT_PLAYER_FACING_``, regex to find sign facing direction macro names
+   ``regex_trainer_types``, ``\bTRAINER_TYPE_``, regex to find trainer type macro names
+   ``regex_music``, ``\b(SE|MUS)_``, regex to find music macro names
+   ``regex_species``, ``\bSPECIES_``, regex to find species macro names

docsrc/manual/settings-and-options.rst

@@ -269,7 +269,7 @@ Files & Identifiers
 
 These two tabs provide a way to override the filepaths and symbol/macro names Porymap expects to find in your project.
 
-For ``Files``, each can be overridden by typing a new path or selecting a file/folder with the |button-folder| button. If the file/folder doesn't exist when the project is loaded then the default path will be used instead.
+For ``Files``, each can be overridden by typing a new path or selecting a file/folder with the |button-folder| button. Paths are expected to be relative to the root project folder. If no path is specified, or if the file/folder specified does not exist, then the default path will be used instead.
 
 For ``Identifiers``, each can be overridden by typing a new name in the line edit. Overrides with ``regex`` in the name support the `regular expression syntax <https://perldoc.perl.org/perlre>`_ used by Qt.
 

forms/customscriptseditor.ui

@@ -6,7 +6,7 @@
    <rect>
     <x>0</x>
     <y>0</y>
-    <width>535</width>
+    <width>540</width>
     <height>355</height>
    </rect>
   </property>
@@ -109,7 +109,7 @@
        <item>
         <widget class="QLabel" name="label_Manual">
          <property name="text">
-          <string>&lt;html&gt;&lt;head/&gt;&lt;body&gt;&lt;p&gt;&lt;a href=&quot;https://huderlem.github.io/porymap/manual/scripting-capabilities.html&quot;&gt;&lt;span style=&quot; text-decoration: underline;&quot;&gt;What are custom scripts?&lt;/span&gt;&lt;/a&gt;&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</string>
+          <string>&lt;html&gt;&lt;head/&gt;&lt;body&gt;&lt;p&gt;&lt;a href=&quot;https://huderlem.github.io/porymap/manual/scripting-capabilities.html&quot;&gt;&lt;span style=&quot; text-decoration: underline;&quot;&gt;Help&lt;/span&gt;&lt;/a&gt;&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</string>
          </property>
          <property name="openExternalLinks">
           <bool>true</bool>

forms/projectsettingseditor.ui

@@ -1374,7 +1374,7 @@
             <item>
              <widget class="QLabel" name="label_ProjectFilesHelp">
               <property name="text">
-               <string>  &lt;html&gt;&lt;head/&gt;&lt;body&gt;&lt;p&gt;&lt;a href=&quot;https://huderlem.github.io/porymap/manual/project-files.html&quot;&gt;&lt;span style=&quot; text-decoration: underline;&quot;&gt;Help&lt;/span&gt;&lt;/a&gt;&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</string>
+               <string>&lt;html&gt;&lt;head/&gt;&lt;body&gt;&lt;p&gt;&lt;a href=&quot;https://huderlem.github.io/porymap/manual/project-files.html#files&quot;&gt;&lt;span style=&quot; text-decoration: underline; color:#0069d9;&quot;&gt;Help&lt;/span&gt;&lt;/a&gt;&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</string>
               </property>
               <property name="textFormat">
                <enum>Qt::RichText</enum>
@@ -1468,7 +1468,7 @@
             <item>
              <widget class="QLabel" name="label_IdentifiersHelp">
               <property name="text">
-               <string>  &lt;html&gt;&lt;head/&gt;&lt;body&gt;&lt;p&gt;&lt;a href=&quot;https://huderlem.github.io/porymap/manual/project-files.html&quot;&gt;&lt;span style=&quot; text-decoration: underline;&quot;&gt;Help&lt;/span&gt;&lt;/a&gt;&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</string>
+               <string>&lt;html&gt;&lt;head/&gt;&lt;body&gt;&lt;p&gt;&lt;a href=&quot;https://huderlem.github.io/porymap/manual/project-files.html#identifiers&quot;&gt;&lt;span style=&quot; text-decoration: underline; color:#0069d9;&quot;&gt;Help&lt;/span&gt;&lt;/a&gt;&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</string>
               </property>
               <property name="textFormat">
                <enum>Qt::RichText</enum>