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

Ryuhouji · Feb 25, 2020

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:

Code:

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:

Code:

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

You might notice that

Code:

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:

Code:

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:

Code:

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:

Code:

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:

Code:

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:

Code:

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 · Sep 15, 2021

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.

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

More options

Ryuhouji

Novice decomp ROMhacker

Lunos

Random Uruguayan User