freighter 0.2.3

Kai's GameCube modding library enabling C/C++ code injection into .dol executables.

Okay, what's Freighter?

<<<<<<< HEAD

Hey there, Kai here.

Freighter is toolkit made for compiling C, C++, or ASM using DevkitPPC for injecting new code/data sections into GameCube/Wii *.dol executables. This is an extension of Yoshi2's C-Kit I worked on around middle of 2019 because I was abhorred with the methods modders used abusing C.

Credits

Yoshi2 (RenolY2)

The OG who made C-kit. He enthused about Python so I had no choice but to learn it.

MintyMeeo

YoshiFirebird This man helped me ALOT way back when I was first learning C++. He originally had the idea of using the #pragma keyword where C-kit would preprocess the source file and import the injection address.

How do install?

Make sure you are using the latest version of Python 3.10.

After that, simply install using pip on your console of choice:

• Windows: py -m pip install freighter
• Unix & Such: python3 -m pip install freighter

Dependencies should automatically be downloaded from PyPi.

Optionals

• Window's Terminal: It's a nice command-line manager that looks modern, has tabs, and support of emoji unicode characters. ✨
• VSCode: My go to code editor. Supports Intellisense and it's what I exclusively use. It's got a huge list of extensions that make coding a breeze. =======

Hey there, Kai here.

Freighter is toolkit made for compiling C, C++, or ASM using DevkitPPC for injecting new code/data sections into GameCube/Wii *.dol executables. This is an extension of Yoshi2's C-Kit I worked on around middle of 2019 because I was abhorred with the methods modders used abusing C.

Credits

Yoshi2 (RenolY2): The OG who made C-kit who made alot of the tools for Pikmin 2 and MKDD. He helped raise baby Kai when he was first learning hex and figuring out how pointers worked. He made a ton of tools that operate on Gamecube era gamefiles and really made the modding scene pop off. Thank you!

Minty Meeo: Mostly found around the Pikmin 1 scene but recently has been working on stuff on Pikmin 2. He has made alot of great changes to C-kit such as relocating the stack frame and cleaning up the code for injection hooks.

YoshiFirebird: This man helped me ALOT way back when I was first learning C++. He originally had the nice idea of using the #pragma keyword where C-kit would preprocess the source file and import the injection address wherever it found it. Saved time having to backtrack to the build.py when I wanted to adjust the codecave site. Also doesn't make intellisense yell at you hah.

How do install?

⚠️ Make sure you are using the latest version of Python 3.10.

Simply install using pip on your console of choice:

• Windows: py -m pip install freighter
• Unix & Such: python3 -m pip install freighter

Dependencies should automatically be downloaded from PyPi.

Optionals

• Window's Terminal: It's a nice command-line manager that looks modern, has tabs, and support of emoji unicode characters. ✨
• VSCode: My go to code editor. Supports Intellisense and it's what I exclusively use. It's got a huge list of extensions that make coding a breeze.

5afd3f330a8c6ad704181e8bb964decfeaa1d193

What next?

<<<<<<< HEAD Next just create a build.py inside your work directory and import the Project class.

🛎️NOTE: Freighter does it's best to fetch include and source folders found in the root folder. All source files found will be auto-imported into the project for compilation.

Example build.py

=======

🛎️NOTE: Freighter does it's best to fetch include and source folders found in the root folder. All source files found will be auto-imported into the project for compilation.

5afd3f330a8c6ad704181e8bb964decfeaa1d193

Better documentation will come.. when I feel like it.

from freighter import Project

# Pick your poison (compiler args)
common_args = [
    "-O3",
    "-fno-asynchronous-unwind-tables",
    "-fno-exceptions",
]

gcc_args = [
    "-std=c17",  # The C standard to compile with
]

gpp_args = [
    "-std=gnu++2b",  # The C++ standard to compile with
]

ld_args = [
    "-gc-sections",  # Runs garbage collector on unused sections
    # "-print-gc-sections", # Shows what symbols are getting thrown out
]

if __name__ == "__main__":
    # Name your project and it's GameID
    project = Project("MyMod", "GPVE01")

    # Assign compiler args to the project
    project.common_args = common_args
    project.gcc_args = gcc_args
    project.gpp_args = gpp_args
    project.ld_args = ld_args
<<<<<<< HEAD

    # Setting an entry function is essential for -gc-sections to work it's magic. Make sure this function has
=======
    
    # Setting an entry function is essential for -gc-sections to work it's magic. Make sure this function has 
>>>>>>> 5afd3f330a8c6ad704181e8bb964decfeaa1d193
    # C linkage
    project.set_entry_function("Entry")

    # If you're lucky to have a Codewarrior map, Freighter can append new symbols for debugging in Dolphin
    project.set_symbol_map("GPVE01.map")

    # You can manually define symbols in a linkerscript file.
    project.add_linkerscript("c_symbols.ld")
<<<<<<< HEAD

    # Add additional map outputs with this method
    project.add_map_output("build/files/GPVE01.map")

    # Imports manually defined symbols in .txt foles found within this folder
    project.add_symbols_folder("symbols/")

=======
    
    # Add additional map outputs with this method
    project.add_map_output("build/files/GPVE01.map")
    
    # Imports manually defined symbols in .txt foles found within this folder  
    project.add_symbols_folder("symbols/")
    
>>>>>>> 5afd3f330a8c6ad704181e8bb964decfeaa1d193
    # Use these methods so Freighter doesn't compile these files
    project.ignore_file("source/test.c")
    project.ignore_file("source/test.cpp")

    # You can also add source files explicitly if you want
    project.add_asm_file("itWork.s")
    project.add_c_file("uglyCode.c")
    project.add_cpp_file("coolHacks.cpp")

    # Write a b instruction that points to this symbol's address
    # NOTE: Symbols with C-linkage (declared extern "C") don't need their parameters within ()
    project.hook_branch("cringe", 0x800992C8)

    # Write a bl to this symbol's address at each of these addresses
    project.hook_branchlink("OnUpdateDoStuff(Game::BaseGameSection &)", 0x80102040, 0x8036D7E8, 0x80387F74)

    # Write this symbol's address to a specific location. Useful for overriding vtable pointers.
    project.hook_pointer("doMyStuffInstead(GameObject *, int)", 0x802B6708)

    # Specify the input .dol file and injection location for your code/data
    project.build("pikmin2.dol", 0x80520E00, verbose=True, clean_up=True)