Item Ball refactor / Pluralize item names for giveitem and finditem

[pkmnsnfrn]

Description

• Refactors item ball scripts to unify them all under Common_EventScript_FindItem , using trainerRange_berryTreeId to define item and movementRangeX to define quantity
• Converts all existing item balls scripts to use Common_EventScript_FindItem
• Implicitly allows for multiple items to be picked up in the field
• Pluralizes the names of any and all items (in English) for when the player gets or finds multiple items

Usage

Existing Items

This branch will convert all the existing scripts in vanilla pokeemerald to use Common_EventScript_FindItem. No quantity is defined for these items, which defaults to 1.

If developers would like to convert item ball scripts that they have added to their repo, @Bassoonian has written a python script capable of doing so. Developers will need to run some version of the following command in their repo:

wget https://raw.githubusercontent.com/rh-hideout/pokeemerald-expansion/f7bf1f4e320ce00d3434f337aaf796b2489e6ced/item_ball_refactor_helper.py -O item_ball_refactor_helper.py && chmod +x item_ball_refactor_helper.py && python3 item_ball_refactor_helper.py && rm item_ball_refactor_helper.py

New Items

When a developer wants to add a new item ball to the overworld of their game, they can do so either via json or Porymap. Regardless of the method, the result will be the same - if the player has room in their bag, the item will be picked up, added to the inventory, and the flag for that item will be set.

Porymap (reccomended)

When adding a new object to a map, the object's fields must be set as follows:

• Script: Common_EventScript_FindItem (the script used for all item balls)
• Event Flag: FLAG_ITEM_HAMMERLOCKE_GREAT_BALL (the flag used for the item in question, needs to be manually created by the developer and assigned)
• Sight Radius / Berry Tree ID: ITEM_GREAT_BALL (the constant for the item the player should receive)
• Movement Radius X: 10 (the amount of the item the player should receive. if this is 0, the player will receive 1.)

json

For the new object, add the following element to the object_events of the map.json for the map being edited.

    {
      "graphics_id": "OBJ_EVENT_GFX_ITEM_BALL",
      "trainer_sight_or_berry_tree_id": "ITEM_GREAT_BALL", // the constant for the item the player should receive
      "script": "Common_EventScript_FindItem", // the script used for all item balls
      "flag": "FLAG_ITEM_HAMMERLOCKE_GREAT_BALL", // the flag used for the item in question, needs to be manually created by the developer and assigned
      "movement_range_x": 10, // the amount of the item the player should receive. if this is 0, the player will receive 1.

// all elements below this line can be freely changed by the developer.
      "x": 41,
      "y": 4,
      "elevation": 3,
      "movement_type": "MOVEMENT_TYPE_LOOK_AROUND",
      "movement_range_y": 0,
      "trainer_type": "TRAINER_TYPE_NONE",
    },

Testing

Clean Branch

You can recreate this branch by applying a patch or pulling the repo. From a clean version of expansion's upcoming, you can either:

### Patch
wget https://github.com/rh-hideout/pokeemerald-expansion/files/13856855/patch-item_ball_refactor_testing.patch -O item.patch ; git apply item.patch ; rm item.patch
Patches are only cool when its a single commmit or a string of commits. Now that I've merged with upcoming, the patches broken and I can't be arsed to fix it.

Repo

git remote add psf-expansion https://github.com/PokemonSanFran/pokeemerald-expansion/ ; git pull psf-expansion item_ball_refactor

Manual Tests

To recreate my testing environment, you can either:

Download

wget https://github.com/PokemonSanFran/pokeemerald-expansion/raw/025c822c3b003b568d14f68e8ee3abc87969cf42/pokeemerald.sav -O pokeemerald.sav ; wget https://raw.githubusercontent.com/PokemonSanFran/pokeemerald-expansion/025c822c3b003b568d14f68e8ee3abc87969cf42/data/scripts/debug.inc -O data/scripts/debug.inc ; wget https://raw.githubusercontent.com/PokemonSanFran/pokeemerald-expansion/025c822c3b003b568d14f68e8ee3abc87969cf42/data/maps/Route102/map.json -O data/maps/Route102/map.json

Manually Apply

• data/scripts/debug.inc
• data/maps/Route102/map.json
• pokeemerald.sav

Verified Scenarios

Each item in the following lists goes to a timestamped YouTube link with each specific scenario being tested.

• Pick up 6 Potions
• Pick up 1 Great Ball
• Pick up 12 Cheri Berry
• Pick up 2 Storage Key
• Pick up 11 TM35

- Pick up an item ball where movementRangeX is defined as 255

• Pick up an item ball where movementRangeX is defined as 15

• Pick up an item ball where movementRangeX is defined as 0

• Pick up an item ball where trainerRange_berryTreeId is defined as ITEMS_COUNT + 1

• Pick up an existing item ball

• Given 2 Max Potion

• Given 4 Master Ball

• Given 1 Cheri Berry

• Given 99 TM42

• Given 3 Basement Key

Features this PR does NOT handle:

• Item Balls with TMs inside are colored gold #3944
• Receiving a Mega Stone via giveitem or finditem plays a special this sound effect #3943
• Item Balls with Mega Stones inside use a different OW sprite #3947

Credits

Please credit these people instead of me.

deokishisu

• Wrote the original implementation of Set Up Item Balls on a Map Without Needing New Scripts

ShinyDragonHunter

• Wrote the original tutorial for Set Up Item Balls on a Map Without Needing New Scripts
• Provided the original code for CopyItemNameHandlePlural
• Pointed out an issue where ObjectEventTemplate needed to have a bitfield adjusted to allow for more than 15 items to be given

ghoulslash

• Wrote the original implementation of gText_ObtainedTheItems, EventScript_ObtainedItemMessage, and EventScript_ObtainedItem.

Jaizu

• Wrote the original implementation of gText_PlayerFoundItems, EventScript_FoundItemMessage, and EventScript_FoundItem.

Discord Contact Info

I am pkmnsnfrn. I have already started a discussion thread.

[Bassoonian]

Wrote a Python script to convert your repo's finditems to the new format (and also cleans up the now unused finditem scripts, both in inc files and pory files): https://hastebin.com/share/epepoworow.python

This means that this should now qualify for merging.

[pkmnsnfrn]

• Pushed option 2 as discussed
• Updated Manual Tests section (RIP patches) with new json / save / debug files
• Retested Verified Scenarios and updated YouTube link

taken care of