Update manual

huderlem · Jan 2, 2024 · 697459b · 697459b
1 parent 2088a5e
commit 697459b
Show file tree

Hide file tree

Showing 123 changed files with 23,923 additions and 8,914 deletions.
diff --git a/docs/.buildinfo b/docs/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 84555ec9fefb928fe9970dd525a17df6
+config: 23fd5c9a8562e86bc017afd5666bb426
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/_images/base-game-version.png b/docs/_images/base-game-version.png
diff --git a/docs/_images/button-create.png b/docs/_images/button-create.png
diff --git a/docs/_images/button-load.png b/docs/_images/button-load.png
diff --git a/docs/_images/button-refresh.png b/docs/_images/button-refresh.png
diff --git a/docs/_images/custom-scripts-editor.png b/docs/_images/custom-scripts-editor.png
diff --git a/docs/_images/default-tilesets.png b/docs/_images/default-tilesets.png
diff --git a/docs/_images/delete.png b/docs/_images/delete.png
diff --git a/docs/_images/events.png b/docs/_images/events.png
diff --git a/docs/_images/file_edit.png b/docs/_images/file_edit.png
diff --git a/docs/_images/folder.png b/docs/_images/folder.png
diff --git a/docs/_images/import-defaults.png b/docs/_images/import-defaults.png
diff --git a/docs/_images/import_defaults.png b/docs/_images/import_defaults.png
diff --git a/docs/_images/map-collisions.png b/docs/_images/map-collisions.png
diff --git a/docs/_images/maps.png b/docs/_images/maps.png
diff --git a/docs/_images/new-map-defaults.png b/docs/_images/new-map-defaults.png
diff --git a/docs/_images/new-script.png b/docs/_images/new-script.png
diff --git a/docs/_images/pokemon-icon-placeholder.png b/docs/_images/pokemon-icon-placeholder.png
diff --git a/docs/_images/pokemon_icon_placeholder.png b/docs/_images/pokemon_icon_placeholder.png
diff --git a/docs/_images/prefabs.png b/docs/_images/prefabs.png
diff --git a/docs/_images/preferences.png b/docs/_images/preferences.png
diff --git a/docs/_images/refresh-prompt.png b/docs/_images/refresh-prompt.png
diff --git a/docs/_images/restore-defaults.png b/docs/_images/restore-defaults.png
diff --git a/docs/_images/settings.png b/docs/_images/settings.png
diff --git a/docs/_images/tab-events.png b/docs/_images/tab-events.png
diff --git a/docs/_images/tab-files.png b/docs/_images/tab-files.png
diff --git a/docs/_images/tab-general.png b/docs/_images/tab-general.png
diff --git a/docs/_images/tab-identifiers.png b/docs/_images/tab-identifiers.png
diff --git a/docs/_images/tab-maps.png b/docs/_images/tab-maps.png
diff --git a/docs/_images/tab-project-files.png b/docs/_images/tab-project-files.png
diff --git a/docs/_images/tab-tilesets.png b/docs/_images/tab-tilesets.png
diff --git a/docs/_images/tilesets-metatiles.png b/docs/_images/tilesets-metatiles.png
diff --git a/docs/_sources/manual/editing-map-collisions.rst.txt b/docs/_sources/manual/editing-map-collisions.rst.txt
@@ -9,7 +9,7 @@ Selecting Collision Types
 
 The Collision Type Selector is a tab next to the Metatile Selector.  It features 32 total different collision types.  The left column is for collision types that allow the player to walk through the tiles.  These are denoted by white text.  The right column is for collision types that are impassable by the player.  These are denoted by red text.
 
-The transparency slider above the collision types controls the transparency of the collision properties on the map view.
+The transparency slider above the collision types controls the transparency of the collision properties on the map view. The slider at the bottom of the panel zooms the selector image in and out.
 
 .. figure:: images/editing-map-collisions/map-collisions.png
     :alt: Map Collisions View
@@ -73,3 +73,6 @@ Multi-Level Collision Type |multi-level-collision-type-1| |multi-level-collision
 
 .. |multi-level-collision-type-2|
    image:: images/editing-map-collisions/multi-level-collision-type-2.png
+
+.. note::
+    For advanced usage: Any valid elevation/collision value combination can be selected using the ``Elevation`` and ``Collision`` value spinners, even if it's not represented graphically on the selector image. You may also resize/replace this selector image under ``Options -> Project Settings``.
diff --git a/docs/_sources/manual/editing-map-events.rst.txt b/docs/_sources/manual/editing-map-events.rst.txt
@@ -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.
+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

diff --git a/docs/_sources/manual/project-files.rst.txt b/docs/_sources/manual/project-files.rst.txt
@@ -6,9 +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 with config options. The name of each config override is listed in the table, and should begin with ``path/``.
-For example if you wanted to rename ``include/constants/items.h`` to ``headers/defines/stuff.h``, you would add ``path/constants_items=headers/defines/stuff.h`` to your project's ``porymap.project.cfg`` file.
+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-files.png
+   :alt: Files tab
+
+.. _files:
 
 .. csv-table::
    :header: File Name,Read,Write,Override,Notes
@@ -28,7 +35,7 @@ For example if you wanted to rename ``include/constants/items.h`` to ``headers/d
    data/tilesets/graphics.inc, yes, yes, ``tilesets_graphics_asm``, only if ``tilesets_headers`` can't be found
    data/tilesets/metatiles.inc, yes, yes, ``tilesets_metatiles_asm``, only if ``tilesets_headers`` can't be found
    data/tilesets/[primary|secondary]/\*, yes, yes, ``data_tilesets_folders``, default tileset data location
-   src/data/wild_encounters.json, yes, yes, ``json_wild_encounters``,
+   src/data/wild_encounters.json, yes, yes, ``json_wild_encounters``, optional (only required to use Wild Pokémon tab)
    src/data/object_events/object_event_graphics_info_pointers.h, yes, no, ``data_obj_event_gfx_pointers``,
    src/data/object_events/object_event_graphics_info.h, yes, no, ``data_obj_event_gfx_info``,
    src/data/object_events/object_event_pic_tables.h, yes, no, ``data_obj_event_pic_tables``,
@@ -37,27 +44,93 @@ For example if you wanted to rename ``include/constants/items.h`` to ``headers/d
    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``,
-   include/constants/opponents.h, yes, no, ``constants_opponents``, reads max trainers constant
-   include/constants/flags.h, yes, no, ``constants_flags``,
-   include/constants/vars.h, yes, no, ``constants_vars``,
-   include/constants/weather.h, yes, no, ``constants_weather``,
-   include/constants/songs.h, yes, no, ``constants_songs``,
+   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
+   include/constants/vars.h, yes, no, ``constants_vars``, for Trigger events
+   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 and max level constants
+   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``,
+   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
    include/constants/event_object_movement.h, yes, no, ``constants_obj_event_movement``,
    include/constants/event_objects.h, yes, no, ``constants_obj_events``,
    include/constants/event_bg.h, yes, no, ``constants_event_bg``,
    include/constants/region_map_sections.h, yes, no, ``constants_region_map_sections``,
    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/pokemon_icon.c, yes, no, ``pokemon_icon_table``, reads files in ``gMonIconTable``
+   src/fieldmap.c, yes, no, ``fieldmap``, reads ``symbol_attribute_table``
+   src/event_object_movement.c, yes, no, ``initial_facing_table``, reads ``symbol_facing_directions``
+   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