Item Ball Refactor - PokemonSanFran/pokeemerald GitHub Wiki

Item Ball Script Refactor

Introduction

Brendan picking up an item ball

Pokémon Emerald's item balls each have an associated script for them, but they are all identical in form and function. Rather than an individual script for each item, this branch replaces all of the scripts with Common_EventScript_FindItem, which behaves identically, and allows for multiple items to be gained at once. The messages that play when the player receives multiple of the same item have been updated to support multiplies of any item.

Thank you very much to Deokishisu, ShinyDragonHunter, ghoulslash, and Jaizu. Please read more about their contributions and support their projects!

Installation

These instructions assume that you can build pokeemerald, have a basic understanding of C, and are familiar with using the in-game scripting language. If you do not, please watch the tutorials series from Team Aqua's Hideout.

git merge (recommended)

From the root directory of your project, run the following commands in your terminal program of choice:

git remote add psf-emerald https://github.com/PokemonSanFran/pokeemerald/ # This adds our team's pokeemerald branch as a remote repo.
git pull psf-emerald item_ball_refactor #This pulls in the item_ball_refactor feature branch

Manual merge

If your project is:

  • Too far behind pokeemerald
  • Using a different base (pokeemerald-expansion or pokefirered)
  • Some other reason that I can't think of

You can manually implement the features using the diff between this branch and vanilla pokeemerald as a guide. You will need to manually edit or create each of these files in your own project to recreate the feature properly.

Warnings

VAR_0x8009

After the player interacts with an item ball, VAR_0x8009 will contain the amount of the last picked up item. If a developer was previously using VAR_0x8009 to restore something else, it will be overwritten.

ITEMS_COUNT and MAX_BAG_ITEM_CAPACITY

  • If the developer tries to use Common_EventScript_FindItem to give the player an item with an ID greater than ITEMS_COUNT or more than MAX_BAG_ITEM_CAPACITY of an item, the value will default to the defined maximum, respectively.
  • Due to the bitfield on the Movement Radius X member of the ObjectEventTemplate struct, any quantity values over 255 will rollback over to 0.
  • A quantity of 0 that is given to Common_EventScript_FindItem will default to 1.

Usage

Existing Items

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

data/scripts/item_ball_scripts.inc (Old)

Route102_EventScript_ItemPotion::
	finditem ITEM_POTION
	end

data/scripts/item_ball_scripts.inc (New)

Common_EventScript_FindItem::
    callnative GetItemBallIdAndAmountFromTemplate
    finditem VAR_RESULT VAR_0x8009
    end

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",
    },

Examples

giveitem

Route102_EventScript_RouteSignPetalburg::
+    giveitem ITEM_MAX_POTION,1
+    giveitem ITEM_MASTER_BALL,2
+    giveitem ITEM_TM_PSYCHIC,3
+    giveitem ITEM_SALAC_BERRY,4
+    giveitem ITEM_RED_ORB,5
    msgbox Route102_Text_RouteSignPetalburg, MSGBOX_SIGN
    end

https://github.com/PokemonSanFran/pokeemerald/assets/77138753/6a4464af-f160-48fb-87b2-cfb6865573f2

finditem

"object_events": [
+    {
+      "graphics_id": "OBJ_EVENT_GFX_ITEM_BALL",
+      "x": 11,
+      "y": 15,
+      "elevation": 3,
+      "movement_type": "MOVEMENT_TYPE_FACE_DOWN",
+      "movement_range_x": 255,
+      "movement_range_y": 0,
+      "trainer_type": "TRAINER_TYPE_NONE",
+      "trainer_sight_or_berry_tree_id": "ITEM_POTION",
+      "script": "Common_EventScript_FindItem",
+      "flag": "FLAG_ITEM_ROUTE_102_POTION"
+    },
+    {
+      "graphics_id": "OBJ_EVENT_GFX_ITEM_BALL",
+      "x": 11,
+      "y": 15,
+      "elevation": 3,
+      "movement_type": "MOVEMENT_TYPE_FACE_DOWN",
+      "movement_range_x": 4,
+      "movement_range_y": 0,
+      "trainer_type": "TRAINER_TYPE_NONE",
+      "trainer_sight_or_berry_tree_id": "ITEM_ULTRA_BALL",
+      "script": "Common_EventScript_FindItem",
+      "flag": "FLAG_UNUSED_0x020"
+    },
+    {
+      "graphics_id": "OBJ_EVENT_GFX_ITEM_BALL",
+      "x": 11,
+      "y": 15,
+      "elevation": 3,
+      "movement_type": "MOVEMENT_TYPE_FACE_DOWN",
+      "movement_range_x": 3,
+      "movement_range_y": 0,
+      "trainer_type": "TRAINER_TYPE_NONE",
+      "trainer_sight_or_berry_tree_id": "ITEM_TM_FLAMETHROWER",
+      "script": "Common_EventScript_FindItem",
+      "flag": "FLAG_ITEM_ROUTE_102_POTION"
+    },
+    {
+      "graphics_id": "OBJ_EVENT_GFX_ITEM_BALL",
+      "x": 11,
+      "y": 15,
+      "elevation": 3,
+      "movement_type": "MOVEMENT_TYPE_FACE_DOWN",
+      "movement_range_x": 2,
+      "movement_range_y": 0,
+      "trainer_type": "TRAINER_TYPE_NONE",
+      "trainer_sight_or_berry_tree_id": "ITEM_LIECHI_BERRY",
+      "script": "Common_EventScript_FindItem",
+      "flag": "FLAG_ITEM_ROUTE_102_POTION"
+    },
+    {
+      "graphics_id": "OBJ_EVENT_GFX_ITEM_BALL",
+      "x": 11,
+      "y": 15,
+      "elevation": 3,
+      "movement_type": "MOVEMENT_TYPE_FACE_DOWN",
+      "movement_range_x": 0,
+      "movement_range_y": 0,
+      "trainer_type": "TRAINER_TYPE_NONE",
+      "trainer_sight_or_berry_tree_id": "ITEM_RED_ORB",
+      "script": "Common_EventScript_FindItem",
+      "flag": "FLAG_ITEM_ROUTE_102_POTION"
+    },
     {

https://github.com/PokemonSanFran/pokeemerald/assets/77138753/94f2b14e-dfdf-473e-a8c0-4886cd03a47a

Support

If you have read all of the documentation here and still have questions, please ask a good question in the pokeemerald channel of the pret Discord server. You can tag psf or deokishisu and we will try to help if we can.

Donations

If you got some use out of this feature, please consider donating.

Contributors

deokishisu

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

Jaizu

missiri

  • Asked me to make this branch

CHANGELOG

All changes to this project will be documented in this section. The format is based on Keep a Changelog, and this project tries to adhere to Semantic Versioning.

Unreleased

  • n/a

[1.0.1] - 2024-??-??