Battle Item Refactor

[AgustinGDLV]

Description

This PR refactors all battle item usage into battle scripts completely divorced from their other effects. Usable battle items are now almost identical to moves, with script IDs in constants/items.h that correspond to a table in battle_scripts_2.s. There's a lot of cool functionality this opens up, as well as making it way easier to understand and add items in general.

Included: Max Mushrooms item effect, item test compatibility!

Showcases

Single Battle Showcase

Double Battle Showcase

Trainer Battle Showcase

Out of Battle Showcase

What's left?

Nothing!

What's been explicitly tested?

• Max Mushrooms raise all stats!
• X-Items don't raise a stat "sharply" if one stage below max.
• Revives will send out an fainted and revived absent partner during the turn.
• Revives will wait to send out a revived battler until the end of the turn if there is an absent partner that wasn't revived.
• AI will use stat-increasing items at the beginning of a turn (if they don't know they will be fainted).
• AI will use a Revive if there is a fainted party member for them to revive, and select the first fainted party member.
• Switching out before an opponent uses a Revive will not bug out the selected party index (yes, this was a bug).
• The selected party index is not messed up with shuffled orders or Multi Battles.

What does the code do?

General

Items that can be used in battle now call battle scripts. The functionality is split between items that are used directly in the bag (X-Items, Poké Dolls, Poké Balls), items that are used in the party menu (Potions, Revives, etc.), and items that are used in the party menu on a specific move (Leppa Berries and Ethers). These categories are set and checked in the .type field of an item. Party menu items store the selected party index in gBattleStruct->itemPartyIndex[gActiveBattler], and the chosen move index (for PP items) in gChosenMovePos.

The gBattlescriptsForUsingItem table in battle_scripts_2.s has been expanded and now looks much like the move equivalent in battle_scripts_1.s. The .battleUsage field now corresponds to an EFFECT constant, which corresponds to an index in this script table. The constants start at 1 so that possible usage can be checked by just seeing if the field is non-zero.

AI

Trainer AI will use the same items in the exact same way as the player! This means they are now able to use Revives, the new Max Mushrooms, and even PP-items with some logic added (and perhaps a change to the current use of gChosenMovePos, as this could change between the AI choosing an item and executing it). The AI checks remain identical, but instead of checking AI_itemType, they simply check the item script ID just like they do for moves. Realistically, this could be converted to a viability system of sorts. The selected party ID is set to the active battler by default, meaning the AI will always use party menu items on the active battler unless otherwise specified. The only case where this occurs is Revives, where the AI chooses the first fainted party index like Revival Blessing.

Tests

Adds a new USE_ITEM(battler, itemId) macro. This works exactly how you'd expect! To facilitate this, some behavior needed to be added to the recorded player/opponent battle controllers and new constant RECORDED_ITEM_ID was added. The technical details probably aren't important.

Similar to how moves work, you will need to specify party index and move slot if necessary. These are checked for items that require those inputs and are checked for validity. For example, using Leppa Berry might look like USE_ITEM(player, ITEM_LEPPA_BERRY, partyIndex: 0, move: MOVE_TACKLE).

Clean-up

The party menu's helper ExecuteTableBasedItemEffect_ function is gone, as it is no longer necessary to check battle behavior. Similarly, PokemonUseItemEffects has had a lot of code wiped that was meant for item usage in battle, as this function will never be called in battle.

Everything related to AI_itemType and AI_itemField is gone, including the enums, functions, and all the AI behavior that used this.

The .battleUseFunc field for items has been removed, as the proper function is called using their .type field. The ItemUseInBattle_Medicine and similar functions have been consolidated into three functions for these .type categories. The ITEM_B_USE_MEDICINE and ITEM_B_USE_OTHER constants are gone now, too, as these were redundant.

[AgustinGDLV]

Ready for review!

[mrgriffin]

This is very exciting! Thanks for all the hard work :)

EDIT: Don't worry about the outdated things, I couldn't work out how to delete them before submitting my review!

[SBird1337]

I think this might be one of those PRs where it is cleaner if you rebase / squash your commits before we merge them :)