c-of-time

Logo by Irdkwia

An environment for hooking and linking to Pokémon Mystery Dungeon: Explorers of Sky.

Credits

This project is loosely based on EternalCode's template. The build configuration is based on scripts provided by devkitPro. The patch format was inspired by Starlight.

Special thanks to UsernameFodder for the pmdsky-debug project, End45 for the ExtraSpace patch and irdkwia for their research on item, move and special process effects.

Rust subsystem

NOTE: The main branch does currently not contain the Rust subsystem anymore, as it's support for symbols for pmdsky-debug is outdated and we eventually want to split the Rust subsytem off so we can keep c-of-time up-to-date with pmdsky-debug more easily. Use the rust branch if you want to use the Rust subsystem.

c-of-time can also be used with Rust projects. If you want to use Rust (including mixed Rust + C projects), continue reading the README.md in the rust directory.

If you want to build pure C projects, continue below.

Project setup

Preparing the ROM

You need a US or EU ROM of Pokémon Mystery Dungeon: Explorers of Sky. The ROM must be patched with the ExtraSpace patch by End45. You can apply the patch with SkyTemple:

1. Open the ROM in SkyTemple
2. Click ASM Patches (Patches > ASM in SkyTemple 1.4+) and switch to the Utility tab
3. Select the ExtraSpace patch and click Apply

Installing dependencies

Refer to the setup guide for your platform:

• Windows
• Linux
• macOS

Building

To build the project, run make patch. This command will build your code, inject it into an overlay in the provided ROM and apply the patches in the patches directory. The output ROM will be saved as out.nds by default.

If you want to check the generated assembly, run make asmdump. A file out.asm will be generated, which contains an assembly listing annotated with the corresponding source code lines.

Usage

Patches can be added to .asm files inside the patches directory. These patch files contain offsets into functions that should be patched and assembly instructions, which allow calling into custom code. See src/main.c and patches/patches.asm for examples.

Logging and assertions

You can use the logging macros COT_LOG, COT_WARN and COT_ERROR. To view the logs, open the ROM in the SkyTemple debugger and check "Game Internal" in the log window. A macro for assertions COT_ASSERT(expr) is also available.

To disable assertions and logging globally and save some performance, change RELEASE_CONFIG in Makefile.

Custom move/item effects and special processes

To create custom special processes, add them into the switch statement in CustomScriptSpecialProcessCall. This function is only called for special process ID 100 and greater for compatibility with existing patches.

You can add custom item or move effects in CustomApplyItemEffect and CustomApplyMoveEffect.

Please note that custom move effects are currently not handled by the Metronome move.

Compatiblity with existing patches

Note: ROMs patched with c-of-time currently experience crashes with the ExtractItemCode and ExtractMoveCode patch.

You can work around the crash by removing .open "overlay29.bin", overlay29_start and all following lines in patches/internal.asm. However, doing so will cause custom effects written in C to have no effect.

Please reach out to us on Discord for potential workarounds if you need to use the aforementioned patches while also adding effects via c-of-time.

Custom script engine instructions

Custom script engine instructions are a more complex, but more powerful alternative to special processes.

Advantages over special processes include:

• No frame delay (especially beneficial when building complex minigames or other real-time interactions)
• Custom instructions can be used inside targeted routines, while ProcessSpecial doesn't work
• Cleaner script code overall without resorting to macros

Disadvantages:

• No built-in support in SkyTemple (workaround provided below)
• No support for return values at the moment (the variable $EVENT_LOCAL is used as a "return register" by convention)

Custom instructions are disabled by default. Follow these steps to enable support for custom instructions in c-of-time:

1. Open the file include/cot/custom_instructions.h and change the line #define CUSTOM_GROUND_INSTRUCTIONS 0 to #define CUSTOM_GROUND_INSTRUCTIONS 1.
2. Restore the commented-out code in patches/internal.asm

You can now add your own instructions to the CUSTOM_INSTRUCTIONS array in ground_instructions.c.

Accessing custom script engine instructions in SkyTemple

SkyTemple will not recognize custom script engine instructions by default. Trying to save a script that references a custom instruction will lead to an error, and scripts containing custom instructions won't decompile. To use custom instructions in SkyTemple, open the folder where SkyTemple is installed, edit the file <SkyTemple installation directory>/skytemple_files/_resources/ppmdu_config/pmd2scriptdata.xml and add the following lines under the <OpCodes> tag:

  <!-- Custom instructions start at ID 0x1000 -->
  <OpCode id="0x1000" name="SetDialogueBoxAttributes"              params="6"  stringidx="-1" unk2="0"  unk3="0"   >
    <Argument id="0" type="uint" name="offset_x"/>
    <Argument id="1" type="uint" name="offset_y"/>
    <Argument id="2" type="uint" name="width"/>
    <Argument id="3" type="uint" name="height"/>
    <Argument id="4" type="uint" name="screen"/>
    <Argument id="5" type="uint" name="frame"/>
  </OpCode>
  <OpCode id="0x1001" name="CheckInputStatus"                      params="1"  stringidx="-1" unk2="0"  unk3="0"   >
    <Argument id="0" type="uint" name="mode"/>
  </OpCode>
  (add additional instructions here...)
</OpCodes>

We're planning to provide a SkyTemple plug-in that will make this process easier in the future.

Updating symbol definitions and headers

To update symbol data from pmdsky-debug, run git submodule foreach git pull origin master, then clean the build with make clean.

Adding custom symbols

If you've found symbols that are currently missing, consider contributing them to pmdsky-debug. You can find instructions in the repository's contribution docs.

For quick testing, you can also add symbols to symbols/custom_[region].ld (symbols/generated_[region].ld is auto-generated and should not be modified). You need to specify the file each symbol belongs to in comments:

/* !file arm9 */
MyCoolFunction = 0x200DABC;

/* !file overlay29 */
SomeDungeonFunction = 0x22DEABC;
SomeOtherDungeonFunction = 0x22DEEFF;

Code size constraints

The built code gets injected into the custom overlay 36. The entire overlay is 228 KB big, most of which is reserved for common patches provided by SkyTemple. Your code will be placed in the last 32 KB, which are considered the "common area" . If the binary is larger than 32 KB, you will get the following linker error:

error "section '.text' will not fit in region 'out'"

Expanding the available space

To work around this issue, you can extend the space allocated in the overlay. If you decide to extend the space, you do so at your own risk. Be careful since this space might be used by future patches! Check the list of assigned areas to find out if patches used in your ROM are affected.

The value of ORIGIN must a multiple of 16 (end with 0 in hexadecimal). Therefore, the amount of bytes added to LENGTH must also be a multiple of 16.

To extend the allocated space, open linker.ld and edit the following line:

out     : ORIGIN = 0x23D7FF0, LENGTH = 0x8010

Subtract the amount of additional bytes you want to allocate from ORIGIN and add them to LENGTH. Next, open patches/patch.py and set START_ADDRESS of the top of the file to the same value as ORIGIN in the linker script.

Optimizing for size

You can also change the compiler flags to optimize for size instead of speed. To do so, set OPT_LEVEL := Os in Makefile. Effectiveness varies per project.

Licensing

• Build scripts (everything under the tools) are licensed under GPLv3. Review the file LICENSE_GPLv3 for more information.
• All other code is licensed under MIT. Review the file LICENSE_MIT for more information.