[Pokeemerald] "User Manual" for DizzyEggg's battle_engine_v2, pokemon_expansion, and item_expansion

[Ryuhouji]

Welcome! This is a 'User Manual' of sorts for DizzyEggg's "battle engine v2" repo.​

I've been using the battle engine for over a year as the primary base for my game, Emerald Enhanced, and I use a lot of the features quite extensively.
I think it's the best base for any Pokemon Emerald romhack. I highly recommend using it.

I will not be explaining how to start with it, this was covered by TheRisingSean here: (Link)

Let's get started!

I recommend grabbing and merging pokemon_expansion and item_expansion into battle engine, as you get access to all of its features in doing so. There are limitations to /just/ using the battle engine. The information here will assume you have all three merged and compiling successfully. Each section will tell you the required modules to work.

Part 1: Mega Evolution:
Requirements:battle_engine_v2, pokemon_expansion, item_expansion

Mega Evolution has been a part of the repo for a while, but it comes disabled by default. To enable it, we need to go to:

src/data/pokemon/evolution.h

Here, we will have to do some uncommenting to enable mega evolutions. You don't have to enable all of them if, for example, your romhack is using a limited number of species e.g. only gen 4, etc.

There are lines that look like this:

  [SPECIES_BEEDRILL] = {{EVO_MEGA_EVOLUTION, ITEM_NONE,/*ITEM_BEEDRILLITE*/ SPECIES_MEGA_BEEDRILL}},

You might notice that

ITEM_BEEDRILITE

has comment tags wrapped around it. You will have to delete ITEM_NONE, and remove the characters /* and */, and then add a comma after the item name to enable this mega evolution.

Once you've done that, then all you need to do is put in some way for the player to obtain the Mega Stone for use with the pokemon, as well as a Mega Bracelet. The game requires the pokemon to be holding the stone, and the player to have the Mega Bracelet in their inventory.

To use Mega Evolution in battle, you just select "FIGHT" and then while the moves are displayed, you may notice the mega symbol near your pokemon's health bar. Press START to tell the game you wish to mega evolve, and it will do so before executing the move.


Part 2: Custom Multi-Battles:
Requirements:battle_engine_v2
This is probably my favorite standalone feature. I use it quite extensively, which is why I decided to make this guide.

There are 3 kinds of custom multi battles you can do, I'll list them here, then describe the parameters for each.

Variant 1: Letting the player choose 3 mons to participate:

multi_2_vs_2 TRAINER_OPPONENT_1, Text1, TRAINER_OPPONENT_2, Text2, TRAINER_ALLY, TRAINER_BACK_PIC_ALLY
multi_2_vs_1 TRAINER_OPPONENT, Text1, TRAINER_ALLY, TRAINER_BACK_PIC_ALLY
multi_wild TRAINER_ALLY, TRAINER_BACK_PIC_ALLY

Variant 2: Just using the first three (not fainted) mons in the player's party:

multi_fixed_2_vs_2 TRAINER_WALLACE, Text1, TRAINER_SIDNEY, Text2, TRAINER_RICK, TRAINER_BACK_PIC_RED
multi_fixed_2_vs_1 TRAINER_WALLACE, Text1, TRAINER_RICK, TRAINER_BACK_PIC_RED
multi_fixed_wild TRAINER_RICK, TRAINER_BACK_PIC_RED

The parameters:

• multi_{fixed}_(2_vs_2, 2_vs_1, wild): The type of battle
• {fixed}: Use the fixed macro if you don't want the player to select 3 mons to use. The game will grab the first three healthy mons in the player's party. If the player has less than three, than only the found healthy ones will participate in battle.
• TRAINER_OPPONENT_1: Constant for the the Trainer you want in the first enemy slot
• Text1: Script text for the first opponent upon defeat
• TRAINER_OPPONENT_2: Constant for the the Trainer you want in the second enemy slot
• Text2: Script text for the second opponent upon defeat
• TRAINER_ALLY: The allied trainer constant for the npc you want to fight on player's side
• TRAINER_BACK_PIC_ALLY: The back pic to use for the player's ally in battle. You will need to insert more of your own, as the game only has a few, and this repo does not put more in there.

Creating a custom 2v2 battle:

This is piggybacking off the vanilla code where Steven joins you against the evil team, so it works much the same way. You are expected to supply a trainer back pic and party for your player's ally and it needs to have 2 trainer parties.
The battle macro does not include intro text, so you will need to script that in, yourself.




If you want to do a custom multi 2v2 battle with the player getting to choose the three mons to participate, the script is more complicated.
Custom 2v2 Choice battle Script example:

script_PrepareCustomBattle::
    lockall
    faceplayer
    choose_mons
    compare VAR_RESULT, 0
    goto_if_eq script_NeedToChoose3ValidMons
    goto script_DoCustomBattle
    release
    end

script_DoCustomBattle::
    msgbox msg_YourIntroGoesHere
    multi_2_vs_2 TRAINER_ENEMY_1, TRAINER_1_DEFEAT_TEXT, TRAINER_ENEMY_2, TRAINER_2_DEFEAT_TEXT, TRAINER_ALLY, TRAINER_ALLY_BACK_PIC_ID
    release
    end

script_NeedToChoose3ValidMons::
    msgbox PleasePick3Mons
    choose_mons
    compare VAR_RESULT, 0
    goto_if_eq script_CancelBattle
    goto script_DoCustomBattle

script_CancelBattle::
    msgbox script_BattleWasCancelled
    release
    end

If you just want the player to participate in a custom multi 2v2 battle using the first three healthy mons in the player's party.
Custom fixed 2v2 battle Script example:

script_DoCustom2v2Battle::
    lockall
    faceplayer
    msgbox SpecialMultiBattlIntroText, MSGBOX_NORMAL
    closemessage
    multi_fixed_2_vs_2 TRAINER_ENEMY1, Enemy1DefeatText, TRAINER_ENEMY2, Enemy2DefeatText, TRAINER_ALLY, TRAINER_ALLY_BACK_PIC_ID
    specialvar VAR_RESULT, GetBattleOutcome
    compare VAR_RESULT, B_BATTLE_LOST
    goto_if_eq script_PlayerLostTheFight
    release
    end

You have to include your own defeat condition, because the multi battle code does not handle this for you. So if your player loses and you haven't included this, the game will end the fight and act as if the player had won, which is probably not optimal for your story. You can also use this to go to a special defeat condition, such as having a fight in the game the player is supposed to lose, for story reasons, without doing the DoWhiteOut stuf, aka teleport to last pokecenter, take half money, etc. For example, in my Title Defense script, if the player loses against a challenger, the Nurse rushes in to give triage to the player and their mons, while the partner they battled with watches.

The possible battle results that GetBattleOutcome can return are:

B_OUTCOME_WON
B_OUTCOME_LOST
B_OUTCOME_DREW
B_OUTCOME_RAN
B_OUTCOME_PLAYER_TELEPORTED
B_OUTCOME_MON_FLED
B_OUTCOME_CAUGHT
B_OUTCOME_NO_SAFARI_BALLS
B_OUTCOME_FORFEITED
B_OUTCOME_MON_TELEPORTED
B_OUTCOME_LINK_BATTLE_RAN

The 2v1 scripts are basically the same as above, except you only include ENEMY1 and DefeatTextEnemy1.

 

[Lunos]

There's a feature that isn't documented anywhere else. May as well drop some info about it here.

Trainer Slide-in Messages
This feature originally introduced in Pokémon Platinum is present in the battle_engine branch.
There's an array called sTrainerSlides in src/battle_message.c.
In this array, you can put in a trainer's ID followed by 3 text strings that will be printed in different situations throughout a trainer battle.
Namely, these situations are: opponent using their last Pokémon, said Pokémon having about 25% of their HP and first Pokémon of the opponent to go down.
By default, the battle_engine gives some silly strings to one of the trainerbattles against Wally, TRAINER_WALLY_VR_2, whose ID is 0x291/657.

To manipulate the instances of the battle in which the slide-in messages are triggered, look at the usages of ShouldDoTrainerSlide.​

 

[rm456tr]

How do you set up the code for custom tag battle? Is that an assembly code or can I just put in like that using HxD.exe

 

[rm456tr]

By the way, do I have to change the names of the character (TRAINER_ALLY)? By the way, what happens if I want to a tag battle where the player teams up with their rival, which is the opposite gender of the character the players choose? What if I add want to add new characters, can I do that?

 

[Lunos]

How do you set up the code for custom tag battle? Is that an assembly code or can I just put in like that using HxD.exe

None of the code that the average user needs to interact with is written in ASM, and HxD is 100% worthless when it comes to the decomps; you're editing text files with code written in C86, not a binary file of any type.

By the way, do I have to change the names of the character (TRAINER_ALLY)?

You mean the labels? No, you don't if you don't want to, but it'd be cleaner if you did and it would give you less headaches moving onward.
For example, let's say you change all the basic parameters of TRAINER_ROXANNE_1 which is the label for the 1st battle with Rustboro City's Gym Leader Roxanne.
Let's say you turn her into a generic youngster called Nick in some route by editing the data associated with that label in the trainer data related files at src/data.
Days, weeks, months or even years after you made that change, you might have forgotten that you made these changes and decide to use TRAINER_ROXANNE_1 for whatever reason, not remembering that you repurposed the trainer data associated with that label into Youngster Nick.

By the way, what happens if I want to a tag battle where the player teams up with their rival, which is the opposite gender of the character the players choose?

Nothing in particular happens. What would happen?
In terms of battles, you'd add 2 new trainers with the relevant information for each gender.
In terms of overworld, the games use 2 sets of sprites with different palette IDs; one set is used for the player character, and the other set is used for the rival's event object.

Ex:

pokeemerald-expansion/src/data/object_events/object_event_graphics_info.h at master · rh-hideout/pokeemerald-expansion

Pokémon Romhack Base, based off pret's pokeemerald decompilation. See the wiki for more info. - rh-hideout/pokeemerald-expansion

github.com

pokeemerald-expansion/src/data/object_events/object_event_graphics_info.h at master · rh-hideout/pokeemerald-expansion

Pokémon Romhack Base, based off pret's pokeemerald decompilation. See the wiki for more info. - rh-hideout/pokeemerald-expansion

github.com

What if I add want to add new characters, can I do that?

Yes. The decomps are replicas of the entire codebase of these games. You can change every single aspect of them.

 

[rm456tr]

Then how do you put the code in the game if code is C86 and complile it? I only ever used XSE, Advance Map, and HxD. Can someone help me or do I have to go battle engine upgrade on Github to find it?

 

[Lunos]

Then how do you put the code in the game if code is C86 and complile it?

By modifying the relevant files and then booting up your terminal and typing make.
Check the project's INSTALL.md document for more information on how to set up an environments to build the decomps.

I only ever used XSE, Advance Map, and HxD. Can someone help me or do I have to go battle engine upgrade on Github to find it?

The programs that you're listing here are binary hacking tools. Binary hacking is a different type of ROM Hacking that involves, as you could tell, the usage of programs to modify a .gba ROM file.

The topics of this thread relate to "decomp hacking", which is ROM Hacking by using the decomps.
Technically speaking it's not ROM Hacking because you're not editing a ROM, but for simplicity's sake we call it ROM Hacking anyway.

The Battle Engine Upgrade used to be a standalone feature branch, but it's been merged alongside the other feature branches designed by DizzyEgg into a single project called the
Pokeemerald-expansion, which you can find at:

GitHub - rh-hideout/pokeemerald-expansion: Feature branchélé for the pokeemerald decompilation. See the wiki for more info.

Feature branchélé for the pokeemerald decompilation. See the wiki for more info. - rh-hideout/pokeemerald-expansion

github.com

You git clone the project from your terminal after setting up an environment to build the decomps with and, again, build it by typing make on it.
As I said above, if you're interested in performing "decomp hacking" check the project's INSTALL.md document for more information on how to set up an environment to build it.