Contributing to mmr‐patches - Adex-8x/mmr-patches GitHub Wiki

Want to add your own custom ASM and/or C code to MysteryMail Rehearsal? You sure are dedicated for a silly little test event, but welcome! To contribute to this repository, please open up a pull request with any edits you'd like to make. If you haven't done so before, you may view this tutorial for further instructions.

Standalone ASM Patches

While ASM can be directly incorporated into this repository (via a .s file or making naked functions), there may be an instance where a participant wants to write standalone ASM to import via something like ExtractSPCode or a Skypatch. If so, please create a designated folder for your custom code and contribute it.

Main Linker Section

The main linker section begins at 0x023DB1B0 in Overlay36, consisting of 0x4E50 bytes. As far as a brief overview of each of the files you're most likely to work with...

extern.h

A header file used to declare various custom definitions, most prominently functions documented in custom_NA.ld.

main.c

The catch-all general file for placing custom C code. This includes code that isn't specific to special processes or script menus. Pretty much anything can go here, be it custom text tags, hijacking how scenes work, updating custom windows...if you can name it, you can code it! You don't necessarily need to use this file for custom code; you can add any .c file you'd like to the src/ directory.

menus.c

The file for custom script menus, or in other words, menus created by the script opcode message_Menu. Menus with ID 80 and above are handled here! For more information, see this section of the repo's README.

patch.asm

Often used in conjunction with main.c, this file is for any overwriting any instructions down at the ASM level. More often than not, you'll find yourself overwriting the base game's code to branch to your own custom ASM/C code. You may also add other .asm files in the directory this is located.

special_processes.c

The file used for creating new special processes. Special processes may be written in ASM and imported via ExtractSPCode, but processes with IDs 100 and above are strictly reserved for processes written in C!

Prohibited Contributions

There are a handful of house rules in place to maintain the cutscene-centric nature of MysteryMail. Not every possible contribution will be accepted. For the most part, you're restricted to writing code that only occurs within Ground Mode. To be more specific, we will not accept the following:

  • Code that cannot run naturally within Ground Mode. This includes, but is not limited to:
    • Top Menu overlays (0-9)
    • Dungeon-related overlays (29-31)
  • Edits to the main section in linker.ld
    • You may, however, add new sections that are not within Overlay36 or an aforementioned banned overlay!
  • Overlay36 patches that occupy space outside of the aforementioned listed regions
  • Code that causes an intentional crash or softlock
  • Custom script opcodes/instructions
  • Edits to CART_REMOVED_IMG_DATA or any functions related to game cart ejection
  • Edits that change how the game saves data
  • Edits to a pre-existing SkyTemple ASM patch

This list is non-exhaustive; contributions may still be rejected for a reason not currently listed.

What If My Code Isn't Compatible With a Certain Platform?

It's heavily preferred that all code does not cause (unintentionally) a crash on any piece of hardware or emulator, but things like hardware compatibility won't be a strict requirement. If any problematic code does slip through, this repo's maintainer will cry try to clean up stuff.

When Can I Contribute?

Whenever you'd like! It doesn't have to be your designated turn to contribute, nor do you even have to participate in the event to contribute. Just be aware that this repository will remain public throughout the event, so any piece of code you write here won't ever be hidden. Spoilers beware, so please try not to write the entirety of a cutscene in C (no matter how impressed we would be).