Code: Complete FireRed Upgrade

[ghoulslash]

Complete FireRed Upgrade

Decomp projects are in full swing, but it may be daunting to port your entire project over. This engine is a great compromise for those who want decomp-quality features in a binary hack. The source code is written almost entirely in C, and can easily be adapted to decomps when the time comes. But in the meantime, it will be an essential tool for FireRed hacks that seek to improve on the game in any way, shape, or form.

If you are starting a new project however; I recommend you use pret's decompilation projects, pokefirered and pokeemerald, over this feature. Having the entire source code at your fingertips will allow you to do things faster, easier, and with less risk of introducing bugs.​

What Is This?

This project is a massive engine upgrade for Pokémon FireRed. It includes an updated battle engine on par with the current generation's, including every single attack, ability, item, AI, and more. In fact, this is the only game engine in gen3 with every single move animation! In addition, it includes several game improvement features such as Expanded PC Boxes, a DexNav, dynamic overworld palettes, character customization, TM/HM expansion, a Battle Frontier, and many others (see the features list below). Most of the engine features are easily configurable to the user by simply commenting and uncommenting lines. An extensive documentation has been written to fully explain what this engine is capable of and how to use all of the features contained within.​

In addition, most table data is untouched or is loaded directly from the rom, allowing this engine to be smoothly implemented for (most) existing hacks!​

Here is the repository.​

Attributes

Spoiler:

• Dynamic Insertion: Pick and choose an offset! Free space can be found from that offset, and all necessary data will be repointed!
• No More Pokémon Encryption: Easier to manipulate Pokémon data!
• Customizable Options: Almost all features are easily included/removed by a simple line comment!
• Choose Between Old/New Mechanics: Most features that have been updated in recent generations can be set to either old or new-style mechanics.
• Unaltered Data: Most data tables have been left alone, meaning it is compatible with (pretty much) every hack!

Battle Features

Spoiler:

• All Moves(Data/Animations/Effects) Abilities, Item Effects, Weather effects, Terrain effects, mechanics, etc. through Gen 7
• Vastly improved AI system with decision-making skills for all new battle effects
• Mega Evolution / Primal Reversion / Ultra Burst
• Z-Moves
• Ability pop-ups
• Hidden Abilities
• Dissapearing HP-bars during Attack Animations
• Trainer Sliding / In-battle messages
• Expanded Poké Balls
• Critical Capture
• Battle Terrain
• Totem Pokémon
• Specified Max Levels (up to 255!)
• Show Move Data From Attack Menu
• Show Pokemon Type Icons on Healthbar
• Trainers with EVs
• Class-based Music
• Class-based Poké Balls
• Dynamic Trainer Backsprites
• Customizable Pre-Battle Mugshot Styles
• Wild Double Battles
• Multi Battles - Battle Two Opponents, Be Spotted By Two Trainers, Battle With a Partner, and More!
• Custom Wild Pokémon (Moves, Hidden Ability, Shininess, etc)
• New Evolution Methods / Evolution Moves / Expanded Evolutions per Pokémon
• Expanded Moves/Learnsets
• Badge-based obedience
• Shiny Charm
• Level Scaling - Wild/Trainer Pokémon levels can be scaled to the highest level of your party
• Updated Exp. Share / Exp. Yields
• Gain Exp. From Capturing Pokémon
• Inverse Battles / Sky Battles
• Overworld Trainer Facing
• Battle Background Switching
• Uncapturable Pokémon (Flag-based)
• Prevent Bag Use in Battle (Flag-based)
• Prevent Running in Battle (Flag-based)
• Capture Trainer's Pokémon (Flag-based)
• Day/Night System in Battle (Palette Shading, Time-Dependent Battle Backgrounds, etc.)
• Type-Changing Moves Show Current Type in Summary Screen
• Fairy type
• And More! Check out the configuration file for all customization options!

Other Features

Spoiler:

• Battle Frontier/Battle Facilities
• Improved Battle Tower - Tiers, Custom/Randomized Teams, Single/Double Battles, etc.
• Expanded Move Relearner (up to 50 moves)
• Improved TM/HM Expansion, Reusable TMs
• Updated Pickup mechanics
• Swarms / Daily Events
• Day/Night, Real Time Clock (RTC)
• Roaming Pokémon
• JPANs engine features ported and improved
  • Character Customization
  • Lots of New Scripting Specials (same special values/arguments/outputs used)
  • Whiteout Hack / Text Updates
  • Run Scripts Each Step
  • Extra Pedometers for Script Events
  • And more!
• Save-Block Expansion
• DexNav and Secondary PokéTools Start Menu
• Dynamic Overworld Palettes
• Updated Daycare System, Specified Hatch Level
• Expanded/Customizable Ability Names
• Direct PC Selection / Accommodating Specials
• Wrapping Summary Screen
• Base stats on Pokédex summary screen
• Updated BW Repel System
• Poison Survival
• Auto Naming-Screen Screen Swap
• Premier Balls From PokéMarts
• Configurable Start Menu
• Expanded Pokémon in the Hall of Fame
• Expanded Text Buffers
• Triple Layer Blocks
• Altering Cave / Tanoby Ruins Support
• Footstep noise in grass & on sand
• Omnidirectional Jumping
• Item Image on acquire
• Auto-Run Capability, Run Inside
• Expanded Game Corner Coins (up to 999,999,999!)
• More Safari Balls / Steps (each up to 65,535!)
• Scrolling Multichoice Lists
• Hold Item Swapping
• Randomizer(s)
• Follow Me
• Bag Sorter
• New Field Moves - Rock Climb, Defog, Dive
• Shiny Charm & Oval Charm
• And More!

Screenshots

Spoiler:

GIFs

Spoiler:

Videos

Spoiler:

Here are a couple promotional videos for Pokemon Unbound that showcase the potential of this engine.

​

Compilation Instructions

Spoiler:

1. Clone or download the repository. It is highly recommended to clone the repository as you can then easily pull updates when they are made. See steps 1-5 here for instructions on how to clone.

2. Installation instruction can be found in the readme.

Note: Anytime you make changes, the compiler will only compile the files you have changed. Any changes made to header files (.h) will require you to type 'python scripts//clean.py build' in cmd and then rerun the build scripts. For more command line options, see "Engine Scripts" in the documentation.

FAQ

Spoiler:

Q: I'm experiencing lags whenever I give myself a Pokemon via a script.
A: Edit your include/constants/items.h to either comment out the Shiny Charm, or set it up properly as instructed in the documentation.

Q: Some vanilla multichoice menus are crashing the game.
A: Comment out SCROLLING_MULTICHOICE in the config file to fix the scrolling multichoice menus. Any other ones will need to be rescripted manually using the new format. Fortunately, this only happens to menus around when the player gets to Celadon City.

Q: All of my overworld sprites are invisible after applying the CFRU!
A: Check out this video solution/tutorial by Fred40!

Q: I applied the DPE and then the CFRU to clean ROM, but I can't evolve any Pokemon.
A: You need to change EVOS_PER_MON in the config file to 16 in order to match the CFRU with the DPE.

Q: I modified something in the config file and ran the make script, but nothing change.
A: You need to run python scripts//clean.py build first.

Q: I applied the Dynamic Pokemon Expansion, but the new Pokemon appear in AdvanceMap with glitchy names. Did I do something wrong?
A: Make sure you're using AdvanceMap 1.9.5. By default, the DPE inserts Pokemon data after 0xFFFFFF, the last offset AdvanceMap 1.9.2 can read from. However, had you followed the suggested instructions in the documentation, this wouldn't be an issue for you.

Q: Patch?
A: No official patch will be provided. That defeats the purpose of this engine. Additonally users of any patch made would be at the liberty of the pre-defined customization options and wouldn't get to choose anything for themselves.

Q: How can use a specific feature from the engine without installing the whole thing?
A: Figure out how to extract it yourself. However, most likely the feature is interconnected with other features and will be a pain to pull out. The engine was designed for maximum compatability with hacks in progress, so if it doesn't work for you, your hack may just be too far along.

Q: I installed the engine but I can't add any new wild Pokemon in Advance Map. Did I do something wrong?
A: Use the Dynamic Pokemon Expansion for FireRed to get the new Pokemon.

Q: What game editors should I use with this engine?
A: Ideally, if you use both this and the Dynamic Pokemon Expansion, you won't need any. Any data can be edited directly by modifying the files in the engines. If you only use the CFRU, then G3T is recommended. DON'T USE PGE!!!!

Q: I don't know how to code. How do I customize the engine for my game?
A: There is a section in the documentation that explains various C syntax to allow you to edit pretty much anything in the engine. The documentation also explains how to 'ignore' specific moves, abilities, and items so you don't have to mess with any of the generated tables. Otherwise, all of the customizable features should be in src/config.h. Beyond that, you will need to follow some C coding tutorials (eg. this one) to understand how to optimize this engine for your own hack.

Q: I compiled the CFRU but can't see any of the new items or Pokémon in my tool! Where are they?
A: The CFRU doesn't create any new item or Pokémon data for user flexibility. You can either create the new item data first and edit the values in include/constants/items.h (same with include/constants/species.h), or make the item (species) data match the values that are already in those header files.

Q: I opened my game in G3T but the ability names are all messed up. Did I do something wrong?
A: No, you didn't do anything wrong. The length of the ability names are expanded as part of the engine. To undo this, open the file strings/Ability_Name_Table.string and change the first line to MAX_LENGTH=12. If you compile after doing this, you'll receive several warnings stating that certain strings have been truncated. Modify all of these mentioned ability names and reduce their length to fit within the new twelve character limit.

Q: If I install this engine with default settings on vanilla FireRed, can I play a QOL (Quality-of-Life) FireRed?
A: The Trainer Tower on Seven Island will no longer retain it's data when the game is saved (if the Save Block Expansion is used). Either replace the Trainer Tower with a Battle Tower, or remove save game capabilities while in the Trainer Tower.​

Q: Does this engine expand Pokemon or Item data?
A: No, the DPE expands Pokemon, but neither that or the CFRU touches the item data. Base item IDs are assigned in include/constants/items.h. You will have to create your own item data (via G3T or in this engine if you have the coding knowledge) after first expanding items (see this post or step 1 in this tutorial). The item IDs can be match those already defined in include/constants/items.h, or you can create the items with whatever IDs you like and redefine the values in include/constants/items.h.

Q: I applied both the Complete FireRed Upgrade and Dynamic Pokemon Expansion, but the new Pokemon can only use Struggle. Did I do something wrong?
A: By default, the CFRU has the learnsets for expanded Pokemon commented out. You need to uncomment the new learnsets in src/Tables/level_up_learnsets.c. Additionally, don't forget to update the config file with any data related to new Pokemon (for instance, the National Pokedex size).

Bugs

Spoiler:

A full list of bugs can be found here

Bug reporting options:

• Reply to this thread
• Reach out to Skeli or ghoulslash directly (discord or pokecommunity)
• Open an issue on github
• Comment in Pokemon Unbound's Discord server in the cfru channel

In general, please try to be respectful of the developers and the resource. We cannot create a tool that is perfectly applicable to every hack, and therefore a lot of data was left untouched/is loaded directly from the rom and most options left customizable. This requires effort from the user, and will inevitably cause frustation among new users. We are a lot more receptive to helping you if you are willing to learn.​

Recommended Add-Ons

Spoiler:

Since we can't add every feature ever created, we instead recommend some standalone features to include in your game alongside this engine:

• Dynamic Pokemon Expansion
• Overworld Form Change (Only Arceus, Silvally, Genesect, & Giratina are included in the CFRU)
• Sideways Stairs
• DS-Style Selection Screen
• BW Summary Screen (recommended to fit some expanded move descriptions)
• Nature Coloured Stats (see BW Summary Screen comments for alternate implementation)
• IV Rankings (see BW Summary Screen comments for alternate implementation)
• Unown Report (NOT COMPATIBLE)
• Various music patches. See documentation for full list.

Credits

Spoiler:

• Primary Developers:
  • Skeli-
  • ghoulslash
• Code:
  • Pret Team - decomps
  • DizzyEgg - Emerald Battle Engine Upgrade Source
  • FBI - DexNav Source, Saveblock Expansion
  • Touched - Mega Evolution
  • Navenatox - Dynamic Overworld Palettes
  • Zeturic - Various Fixes
  • JPAN - Hacked Engine Source Code
  • azurile13 - Hidden Abilities
  • DoesntKnowHowToPlay - Pokedex Screen Stats, Trainer's with EVs source
  • Squeetz - Pokedex Screen Stats, Footstep noises
  • Diegoisawesome - Triple Layer Tiles
  • Jiangzhengwenjz – Linux compatibility
• Graphics:
  • Golche - Attack Particles, Battle Backgrounds, Other Graphics
  • Lixdel - Attack Animations
  • Bela - Poké Balls
  • Solo993 - Backsprites
  • Criminon - Mega Indicators
  • canstockphoto.ca - Battle Backgrounds
• Testers:
  • Criminon
  • Dionen
  • Gail
  • Recko Juice
  • Anyone who played the Unbound Battle Tower Demo in its early stages

If you have contributed to this project and we forgot, please let us know asap! :)

 

[Sarkrai]

Incredible work !

 

[DrFuji]

Pinned, because if any thread deserves it, this one does.

I've been following this project since skeli brought it up on Discord and I'm so excited that its in a release state now. JPAN's engine was great back in 2009, but looking at this shows just how far everything has come in the past ten years. This is going to be mandatory for any serious FR hacker going forward <3

 

[Lance Koijer 2.0]

THE BEST CREATION EVER!

 

[U.Flame]

Oh, this is great! So if I were to implement this in an existing hack, how would I know if it's incompatible? Would there be an error of some sort or would I just have to find out through testing?

Also, when it comes to hack compatibility, is there any conflict with hacks that used other rom bases like MrDollSteak's, or already implemented features like class based pokeballs? I'm assuming you can just choose not to implement features already implemented, but hopefully there's no conflict of some kind because of them.

 

[Lunos]

A huge dynamic project that add multiple features to Pokémon Fire Red and can be easily modified by anyone, in order to fix problems or add even more new features?
Dude, that's exactly what Pokémon Fire Red needed.

Excellent work guys, and congratulations for reaching a publicly releasable state :D!

 

[Too much a loner for social media]

Fantastic! Been eagerly waiting on this, what an achievement for the gen 3 romhacking community. Let the games begin!

 

[RoadToCerulean]

This project is sweet!

 

[Trainer 766]

bro if someone made a sideshow showcase hack using this base in the style of Yet Another Fire Red Hack or FireRed Advanced, everyone be wildin'.

 

[Burningocean2012]

Amazing!

 

[lowkey1202]

This is wonderful, I can't wait to see what happens now with fire red Roms and what people can do with this amazing work

 

[CloudsShade]

This looks amazing! Thanks for all the hard work and will definitely try it out!

 

[ghoulslash]

Oh, this is great! So if I were to implement this in an existing hack, how would I know if it's incompatible? Would there be an error of some sort or would I just have to find out through testing?

Also, when it comes to hack compatibility, is there any conflict with hacks that used other rom bases like MrDollSteak's, or already implemented features like class based pokeballs? I'm assuming you can just choose not to implement features already implemented, but hopefully there's no conflict of some kind because of them.

It *should* be compatible with most hacks, as well as most other bases. It repoints attack data and rewrites a few battle functions, but if you find any problems with other bases let us know. All customization is in src/config.h as well.

 

[thedarkdragon11]

Whoa! This one is a dream come true for many people who aren't good at scripting...

I have a few questions:

• Is this engine compatible with expanded ROMs (i.e. 32MB)?
• Is this engine compatible with this fix?
• Can this engine expand the usable map headers/names to 255 and add fly points?

 

[desvol]

That is amazing super engine， can I know any hack is current using this engine？ such like Unbound ？ any other？

 

[shivamyadav]

Good

 

[Xacop]

First of all, I really want to thank you for your work. It sounds and looks amazing. So, I really want to set this up but I'm having a bit of a problem. I've read the CFRU documentation and managed to patch the game with the Dynamic Pokemon Expansion and also generated the test.gba with the CFRU patch. It boots up just fine, and I did follow the steps to expand the TMs modifying the src/config.h. I uncommented the necessary line and also changed the amount from 50 to 120 but when I load the rom in G3T, I'm not able to see any change at all. I do want apologize if it's because of something really simple, I'm very new at rom hacking. Dunno if it's something that I have to change in the G3T .ini file.

I guess my question really is, how can I make sure that the TMs/HMs are expanded? Do I have to edit other Items or free spaces in the G3T to make the TMs? Because I can see the TMs are in the "include/constants/items.h" file. I just don't know how to actually work with them. Also, if I do end up having to edit the other Items or ???? spaces in the G3T, how do I actually expand the amount of items? Because after I apply the CFRU patch, it shows the same amount of items in the G3T tool and no other new items or free space to edit. If someone could help me out a bit, I'd really appreciate it.

 

[Lance Koijer 2.0]

This is, once again, amazing and is considered already the best engine for Fire Red.
Some questions though:
1. Abilities and moves are expanded once the upgrade is installed. However, the items remain the same. If I am right, this does not expand the item. It has to be me that will expand it and should follow the correct Item List in Master file in order for me to get no error or else I will be modifying the list.
2. Does this allow regional pokedex? If so, how? Or what file I should customize? I tried browsing it and I only found Pokedex and species which I don't know if editing it would be a good idea.

 

[U.Flame]

I read up on the documentation, and I think I get it for the most part. Following the installation instructions, configured the bytereplacement, config.h, and make.py. I installed Python and DevkitPro, set them up in PATH, and typed "python scripts//clean.py build" in the folder's command prompt, with the rom in the master folder named BPRE0.gba, that seemed to run fine. Then "python scripts/make.py"

This is the result:

Spoiler:

Assembling ./assembly\main.s
Assembling ./assembly\pokedex_screen_stats.s
Assembling ./assembly\rtc.s
Assembling ./assembly\thumb_compiler_helper.s
Assembling ./assembly\triple_layer_blocks.s
Assembling ./assembly\battle_scripts\ability_battle_scripts.s
Assembling ./assembly\battle_scripts\attackcanceler_battle_scripts.s
Assembling ./assembly\battle_scripts\battle_start_turn_start_battle_scripts.s
Assembling ./assembly\battle_scripts\cmd49_battle_scripts.s
Assembling ./assembly\battle_scripts\et_battle_scripts.s
Assembling ./assembly\battle_scripts\fainting_battle_scripts.s
Assembling ./assembly\battle_scripts\general_attack_battle_scripts.s
Assembling ./assembly\battle_scripts\item_battle_scripts.s
Assembling ./assembly\battle_scripts\mega_battle_script.s
Assembling ./assembly\battle_scripts\move_menu_battle_scripts.s
Assembling ./assembly\battle_scripts\set_effect_battle_scripts.s
Assembling ./assembly\battle_scripts\standard_damage_battle_script.s
Assembling ./assembly\battle_scripts\switch_battle_scripts.s
Assembling ./assembly\battle_scripts\trainer_sliding_battle_scripts.s
Assembling ./assembly\battle_scripts\z_effect_battle_scripts.s
Assembling ./assembly\data\ability_description_table.s
Assembling ./assembly\data\ability_tables.s
Assembling ./assembly\data\anim_backgrounds_graphics_defines.s
Assembling ./assembly\data\anim_background_table.s
Assembling ./assembly\data\anim_particle_graphics_defines.s
Assembling ./assembly\data\anim_particle_table.s
Assembling ./assembly\data\attack_anim_table.s
Assembling ./assembly\data\attack_description_table.s
Assembling ./assembly\data\battle_script_commands_table.s
Assembling ./assembly\data\item_tables.s
Assembling ./assembly\data\move_effect_table.s
Assembling ./assembly\data\move_tables.s
Assembling ./assembly\data\special_battle_anim_table.s
Assembling ./assembly\data\type_tables.s
Assembling ./assembly\data\z_move_name_table.s
Assembling ./assembly\hooks\bag_expansion_hooks.s
Assembling ./assembly\hooks\character_customization_hooks.s
Assembling ./assembly\hooks\dynamic_ow_pal_hooks.s
Assembling ./assembly\hooks\follow_me_hooks.s
Assembling ./assembly\hooks\general_hooks.s
Assembling ./assembly\hooks\illusion_hooks.s
Assembling ./assembly\hooks\mega_hooks.s
Assembling ./assembly\hooks\move_reminder_hooks.s
Assembling ./assembly\hooks\multi_hooks.s
Assembling ./assembly\hooks\multi_partner_hooks.s
Assembling ./assembly\hooks\pc_select_hooks.s
Assembling ./assembly\hooks\pokemon_data_hooks.s
Assembling ./assembly\hooks\tmhm_hooks.s
Assembling ./assembly\overworld_scripts\system_scripts.s
Assembling ./assembly\overworld_scripts\trainer_battle_scripts.s
Compiling ./src\ability_battle_effects.c
Compiling ./src\accuracy_calc.c
Compiling ./src\attackcanceler.c
Compiling ./src\battle_anims.c
./src\battle_anims.c: In function 'UpdateOamPriorityInAllHealthboxes':
./src\battle_anims.c:1222:3: warning: empty declaration
__attribute__ ((fallthrough));
^
Compiling ./src\battle_controller_opponent.c
Compiling ./src\battle_script_util.c
Compiling ./src\battle_start_turn_start.c
./src\battle_start_turn_start.c: In function 'BattleBeginFirstTurn':
./src\battle_start_turn_start.c:227:4: warning: empty declaration
__attribute__ ((fallthrough));
^
Compiling ./src\battle_strings.c
Compiling ./src\battle_terrain.c
Compiling ./src\battle_transition.c
Compiling ./src\battle_util.c
Compiling ./src\build_pokemon.c
./src\build_pokemon.c: In function 'BuildFrontierParty':
./src\build_pokemon.c:1041:8: warning: empty declaration
__attribute__ ((fallthrough));
^
Compiling ./src\catching.c
Compiling ./src\character_customization.c
Compiling ./src\cmd49.c
./src\cmd49.c: In function 'atk49_moveend':
./src\cmd49.c:103:18: warning: comparison is always false due to limited range of data type [-Wtype-limits]
if (gChosenMove == -1)
^
Compiling ./src\damage_calc.c
./src\damage_calc.c:32:2: error: invalid preprocessing directive #elifdef
#elifdef CRIT_CHANCE_GEN_2_TO_5
^
./src\damage_calc.c: In function 'atk04_critcalc':
./src\damage_calc.c:96:4: error: invalid preprocessing directive #elifdef
#elifdef CRIT_CHANCE_GEN_2_TO_5
^
./src\damage_calc.c: In function 'CalcPossibleCritChance':
./src\damage_calc.c:168:4: error: invalid preprocessing directive #elifdef
#elifdef CRIT_CHANCE_GEN_2_TO_5
^

It didn't output test.gba or offsets.ini as far as I can tell. Did I configure something wrong?

Edit: It seems to have been an issue with older compilers, Skeli just pushed a fix for it and that got it to successfully compile.
The result however, broke a lot of things. Upon naming the Player, the OW sprite is blank, although I noticed the feature of automatically switching to lowecase worked. The opening script didn't execute however, and the game shortly crashed and reset.

I don't know if this was a result of configuration or if my hack simply isn't compatible.

 

[Dr. Seuss]

I had to build the project using the WSL bash console since for some weird reason it never compiled using cmd/powershell. Besides that the project is the best resource ever created for FireRed. I do apprecite the effort made by the developers. It is so sad it won't work with my hack. I guess is so advanced in development so it crashesh right after the titlescreen.

Nice job!