tumbledemerald-legacy/README.md

tumbledemerald

tumbledemerald is an open-source project to modernize and update Pokémon: Emerald Version.

[TOC]

Why?

About a year ago, I started working on the pokecrystal code to update and modernize it. That fell through for two main reasons:

• People were already doing it, a lot.
• I suck at assembly language.

Eventually, the project was put on hold while I looked for a new project to take on. I found the pokeemerald decompilation about a week later. It was nice, it was clean, and it seemed like almost no one was making QoL hacks out of it. It started as a "running indoors and Repel system" hack. Then it got bigger. And bigger. And bigger. That's about all there is to it; a little project to work on when I have nothing better to do.

How do I play tumbledemerald?

Tumbled has releases once or twice every week on average, with pre-compiled ROM images. I test the latest changes, run a specific buildscript to build the files, clean up the repository, and push it to GitLab.

For those who prefer to compile themselves, we have comprehensive install documentation, or you can use the T.E.C.S. (TumbledEmerald Compilation Script) here

Once you've found your way over to the releases, or compiled the latest code yourself, you'll need a way to run the game:

Please note that save files are not compatible between versions of the game, and regular Emerald saves are not compatible at all.

Game Boy Advance, Game Boy Advance SP, Game Boy micro, Game Boy Player, Nintendo DS, Nintendo DS lite, Nintendo DSi, and Nintendo DSi XL/LL consoles

We recommend the usage of a device known as a "flashcart" to play tumbledemerald on the Game Boy line and Nintendo DS/DSi consoles. A cart we recommend can be found here.

Nintendo 3DS, Nintendo 3DS XL/LL, Nintendo 2DS, New Nintendo 3DS, New Nintendo 3DS XL/LL, and New Nintendo 2DS XL/LL consoles

All Nintendo 3DS and 2DS consoles will need to be modified by the end-user (that's you!) to play tumbledemerald.

This is a limitation imposed by Nintendo's default software. There's no better way to go about this, sadly. (Believe me, I've looked!)

• Follow the recommended guide to install the necessary software modifications onto the console.

We are not liable for any hardware or software damage caused by this procedure. While we believe this process to be perfectly safe, and have used it ourselves, this is being done at your own risk.

• Download the latest tumbledemerald.cia package from the releases page and transfer it to your console's SD or μSD card.
• Open the FBI application on your console.
  • Select SD on the menu that appears.
  • Navigate to the tumbledemerald.cia package.
  • Select Install and delete CIA.
  • Wait while the program is installed.
• Return to the HOME Menu and unwrap the "tumbledemerald version xx.xx" present.
• Launch the game and enjoy!

Nintendo Switch

All Nintendo Switch consoles will need to be modified by the end-user (that's you!) to play tumbledemerald.

Running tumbledemerald on the Nintendo Switch is a little more complex than other platforms. Nevertheless, the instructions are relatively simple:

• Follow the recommended guide to install the necessary software modifications onto the console. Please note that later Nintendo Switch consoles, as well as all Nintendo Switch Lite and Nintendo Switch (OLED version) consoles are not compatible with tumbledemerald.

We are not liable for any hardware or software damage caused by this procedure. While we believe this process to be perfectly safe, and have used it ourselves, this is being done at your own risk.

• Download the latest tumbledemerald.gba file from the releases page and transfer it to your console's μSD card.
• Open the 4TU QuickStore on your computer.

If Homebrew App Store is selected, de-select it by clicking on it or touching it. - Select mGBA from the list. - Click Download 1 Selected. - Copy the contents of the downloaded .zip file to the root of the µSD card, overwriting any existing files. - Reinsert the µSD card and boot Atmosphère.

• Open the Album from Atmosphère's HOME Menu to open the Homebrew Menu.
• Open mGBA
• Browse to and select tumbledemerald.gba.
• Enjoy!

PlayStation Vita

All PlayStation Vita consoles will need to be modified by the end-user (that's you!) to play tumbledemerald.

This is a limitation imposed by Sony's default software. There's no better way to go about this, sadly. (Believe me, I've looked!)

• Follow the recommended guide to install the necessary software modifications onto the console.

We are not liable for any hardware or software damage caused by this procedure. While we believe this process to be perfectly safe, this is being done at your own risk.

• Download the latest tumbledemerald.gba file from the releases page and transfer it to your console's Memory Card.
• Install the latest version of mGBA using the .vpk package.
• Open mGBA
• Browse to and select tumbledemerald.gba.
• Enjoy!

Windows

On some devices, you may need to disable S mode before you can play tumbledemerald. For instructions on how to do so, see this knowledge base article.

Why do I need to disable these settings? Is this safe to use?

mGBA, the program used on macOS to play tumbledemerald is perfectly safe to use. You are welcome to browse the source code to verify this. The reason that you may need to tweak system settings is due to the fact that endrift, mGBA's developer, has not submitted mGBA to the Microsoft Store. S mode allows only apps from the Microsoft Store, hence why S mode needs to be disabled.

Disabling S mode won't cause your computer to lose any functionality. However, disabling S mode is permanent. Once disabled, S mode can't be re-enabled.

• Download the latest tumbledemerald.gba file from the releases page.
• Install the latest version of mGBA, depending on what kind of computer you have.
• Open mGBA
• Navigate to File > Load ROM.
• Browse to and select tumbledemerald.gba.
• Enjoy!

macOS

Playing tumbledemerald on macOS is a bit more complicated due to macOS security features. You may have to change several preferences on your Mac before you can play.

See this page for more details.

Why do I need to disable these settings? Is this safe to use?

mGBA, the program used on macOS to play tumbledemerald is perfectly safe to use. You are welcome to browse the source code to verify this. The reason that you may need to tweak system settings is due to the fact that endrift, mGBA's developer, has not gotten mGBA notarized and signed by Apple as of yet. Additionally, mGBA is not available in the Mac App Store. You will need to allow apps from outside the Mac App Store, and you may or may not need to add mGBA to the Gatekeeper whitelist.

• Download the latest tumbledemerald.gba file from the releases page.
• Install the latest version of mGBA, depending on what kind of Mac and/or what version of macOS you have.
• Open mGBA
• Navigate to File > Load ROM.
• Browse to and select tumbledemerald.gba.
• Enjoy!

Linux

(No, I will not call it GNU/Linux.)

To play tumbledemerald on Steam Deck, we recommend the use of the standalone mgba program rather than RetroArch.

Handy tip: When using Steam Deck in Desktop mode, press the Steam and X buttons simultaneously to open the virtual keyboard.

• Power on your Deck.
• Once Deck UI loads, press and hold the power key.
• Select Switch to Desktop.
  • If you have never used Steam Deck's desktop mode, you will need to set a password. Do this now if necessary.

mGBA can usually be found in your distribution's repositories or ports tree. If not, download the latest development appimage from here

• Open a web browser on your computer and download tumbledemerald.gba from this page.
• Open the mGBA application.
• Navigate to File > Load ROM.
• Browse to and select tumbledemerald.gba.
• Enjoy!

Steam Deck

To play tumbledemerald on Steam Deck, we recommend the use of the standalone mgba program rather than RetroArch.

Handy tip: When using Steam Deck in Desktop mode, press the Steam and X buttons simultaneously to open the virtual keyboard.

• Power on your Deck.
• Once Deck UI loads, press and hold the power key.
• Select Switch to Desktop.
  • If you have never used Steam Deck's desktop mode, you will need to set a password. Do this now if necessary.
• Use the right trackpad to open Discover. It looks like a small shopping bag with a "K" on it.
• Search for mGBA.
• Select Install.
  • You will be prompted to enter your password at this step. Don't forget it!

• If you have never used Steam Deck's desktop mode, you will need to install a web browser:
• Use the right trackpad to open Discover. It looks like a small shopping bag with a "K" on it.
• Search for any web browser you like. (I personally prefer Firefox)
• Select Install.
  • You will be prompted to enter your password at this step. Don't forget it!

• Open a web browser on your Deck and download tumbledemerald.gba from this page.
• Open the mGBA application.
• Navigate to File > Load ROM.
• Browse to and select tumbledemerald.gba.
• Enjoy!

How can I contribute?

Merge Requests and Issues are appreciated greatly. If you find a bug, have a cool idea, or need help with something, just tell us in an issue! (Make sure to mark it with not-issue.)

We do not, have not, cannot, and will not accept any financial contributions due to legal issues. If someone tries to solicit money while masquerading as us, let us know!

If you paid for any part of tumbledemerald, you were ripped off and should ask your bank or credit union for a refund directly.