Magikoopa 3DS: Difference between revisions

From GameBrew
No edit summary
m (Text replacement - "Category:Homebrew hack utility for 3DS games" to "")
 
(23 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Infobox 3DS homebrew
{{Infobox 3DS Homebrews
| title = Magikoopa
|title=Magikoopa
| image = https://dlhb.gamebrew.org/3dshomebrew/Magikoopa.jpeg|250px
|image=Magikoopa4.png
| type = Utilities
|description=Code patcher for 3ds games.
| version = unknown
|author=RicBent
| licence = Mixed
|lastupdated=2019/06/29
| author = RicBent
|type=Hack Utilities
| website = https://github.com/RicBent/Magikoopa
|version=2019
| download = https://dlhb.gamebrew.org/3dshomebrew/Magikoopa-master.zip
|license=GPL-3.0
| source = https://dlhb.gamebrew.org/3dshomebrew/Magikoopa-master.zip
|download=https://dlhb.gamebrew.org/3dshomebrews/magikoopa.7z?k33p0fil35
|website=https://github.com/RicBent/Magikoopa
|source=https://github.com/RicBent/Magikoopa
}}
}}
Magikoopa is a homebrew tool aimed at rom hackers or people who want to modify the code of an existing applicaiton.


= Magikoopa =
Because of memory segmentation it is not easy to add as much code to code.bin files as we want. To allow that we insert a small loader into the padding between the executable and data section that reprotects memory to our needs to mark perviously read-write only memory as executable.
Compiles custom code for 3ds games and injects it into existing code.bin files and patches the exheader Motivation for this is to create a NSMB2 hack with fully custom code. In theory this should work with all other games as well tho. Work in progress. Should be in a kinda working state now. Might still have bugs that wait to be reported :) You can find examples on how to use Magikoopa in combination with NSMB2 here: [https://github.com/RicBent/Magikoopa-NSMB2-Examples/ https://github.com/RicBent/Magikoopa-NSMB2-Examples/]
 
Magikoopa compiles code for 3DS games and injects it into existing code.bin files and also patches the exheader.bin file. Furthermore it allows creating hooks from existing code into custom code. It features a nice UI that displays anything that can go wrong during the compiling and inserting steps.
 
It even allows you to jump directly to issues in code/hooks my clicking on the issues displayed in the UI. The motivation for this is to create a NSMB2 hack with fully custom code. In theory this should work with all other games as well tho. Work in progress. Should be in a kinda working state now.
 
==User guide==
=== Getting started ===
=== Getting started ===
* Build the project in QtCreator.
* Build the project in QtCreator.
* Run <code>Magikoopa</code> in the build directory.
* Run <code>Magikoopa</code> in the build directory.
=== Hooks ===
 
You can find examples on how to use Magikoopa in combination with NSMB2 [https://github.com/RicBent/Magikoopa-NSMB2-Examples here].
 
===Hooks===
Hooks can be specified with hks files in a patch's working directory. The format is similar to YAML:
Hooks can be specified with hks files in a patch's working directory. The format is similar to YAML:
<pre>hook_name_1:
hook_name_1:
type: xxx
type: xxx
link: false
link: false
addr: 0x00430988
addr: 0x00430988
func: FunctionNameHere
func: FunctionNameHere
hook_name_2:
hook_name_2:
...
...
</pre>
 
There are several types of hooks. | Type | Description | | - | - | | branch | Branch to a function (overwrites the original instruction) | | softbranch | Branch to a function (preserves the original instruction) | | patch | Patch data at an offset | | symbol | Write the address of a symbol | The following parameters are common to all hook types: | Parameter | Description | | - | - | | addr | Hook address |
There are several types of hooks.  
==== Branch hooks ====
{| class="wikitable" style="width: 800px;"
{|
|-
! Parameter
! style="width: 10%;"|Type  
! Description  
|-  
| branch || Branch to a function (overwrites the original instruction).
|-
| softbranch || Branch to a function (preserves the original instruction).
|-
| patch || Patch data at an offset.
|-
| symbol || Write the address of a symbol.
|-
|}
The following parameters are common to all hook types:  
{|class="wikitable" style="width: 800px;"
|-
! style="width: 10%;"|Parameter  
! Description  
|-
| addr || Hook address.
|-
|}
 
===Branch hooks===
{|class="wikitable" style="width: 800px;"
|-
! style="width: 10%;"|Parameter
! Description
! Description
|-
|-
| link
| link
| <code>true</code> to make a BL instruction, <code>false</code> for B
| <code>true</code> to make a BL instruction, <code>false</code> for B.
|-
|-
| func
| func
Line 39: Line 76:
|-
|-
| dest
| dest
| (2) Branch destination address
| (2) Branch destination address.
|-
|-
| link and one of func and dest are required parameters.
|
|}
|}
==== Soft-branch hooks ====
 
{|
Link and one of func and dest are required parameters.
! Parameter
 
===Soft-branch hooks===
{|class="wikitable" style="width: 800px;"
|-
! style="width: 10%;"|Parameter  
! Description
! Description
|-
|-
Line 53: Line 92:
|-
|-
| dest
| dest
| (2) Branch destination address
| (2) Branch destination address.
|-
|-
| opcode
| opcode
| &quot;pre&quot;, &quot;post&quot; or &quot;ignore&quot;. Defaults to &quot;ignore&quot; if not specified. &quot;pre&quot; to branch to func/dest after the original instruction, &quot;post&quot; to branch before the original instruction.
| "pre" (branch to func/dest after the original instruction), "post" (branch before the original instruction) or "ignore" (default).
|-
|-
| One of func and dest are required parameters.
|
|}
|}
==== Patch hooks ====
 
{|
One of func and dest are required parameters.
! Parameter
 
===Patch hooks===
{|class="wikitable" style="width: 800px;"
|-
! style="width: 10%;"|Parameter
! Description
! Description
|-
|-
| data
| data
| (1) Data to insert (in hexadecimal)
| (1) Data to insert (in hexadecimal).
|-
|-
| src
| src
| (2) Symbol name of data to insert
| (2) Symbol name of data to insert.
|-
|-
| len
| len
| (2) Length of data to insert
| (2) Length of data to insert.
|-
|-
| data, or both src and len, are required parameters.
|
|}
|}
=== Thanks to ===
* Dirbaio -- Creator of the NSMBDS asm patch template which was used as a basis
* StapleButter -- Partial coding of the Filesystem classes
* Icons8 -- Icons ([https://icons8.com/ https://icons8.com/])


===Magikoopa Code patcher for 3ds games===
data, or both src and len, are required parameters.
 
Magikoopa is a tool that compiles custom code for 3ds games and inserts it into code.bin files and also allows to insert hooks into the original code to the inserted code allowing for example replacing functions.
Because of memory segmentation it is not easy to add as much code to code.bin files as we want. To allow that we insert a small loader into the padding between the executable and data section that reprotects memory to our needs to mark perviously read-write only memory as executable.


Magikoopa features a nice UI that displays anthing that can go wrong during the compiling and inserting steps. It even allows you to jump directly to issues in code/hooks my clicking on the issues displayed in the UI.
==Screenshots==
https://dlhb.gamebrew.org/3dshomebrews/magikoopa3.png


Source Code: [https://github.com/RicBent/Magikoopa https://github.com/RicBent/Magikoopa]
==Credits==
Thanks to:
* Dirbaio - Creator of the NSMBDS asm patch template which was used as a basis.
* StapleButter - Partial coding of the Filesystem classes.
* Icons8 - Icons ([https://icons8.com https://icons8.com]).


I will add better explaination how to use the tool and add builds when I make a bit more progress on it.
==External links==
You can also find examples working with NSMB2 here: [https://github.com/RicBent/Magikoopa-NSMB2-Examples https://github.com/RicBent/Magikoopa-NSMB2-Examples] (The memory offsets in the example are based on the US Gold Edition)
* GitHub (Magikoopa) - https://github.com/RicBent/Magikoopa
* GitHub (Magikoopa-Examples) - https://github.com/RicBent/Magikoopa-NSMB2-Examples
* Reddit - https://www.reddit.com/r/3dshacks/comments/78bokx/magikoopa_code_patcher_for_3ds_games
* Kuribo64 - http://kuribo64.net/board/thread.php?id=3423

Latest revision as of 04:15, 6 May 2024

Magikoopa
Magikoopa4.png
General
AuthorRicBent
TypeHack Utilities
Version2019
LicenseGPL-3.0
Last Updated2019/06/29
Links
Download
Website
Source

Magikoopa is a homebrew tool aimed at rom hackers or people who want to modify the code of an existing applicaiton.

Because of memory segmentation it is not easy to add as much code to code.bin files as we want. To allow that we insert a small loader into the padding between the executable and data section that reprotects memory to our needs to mark perviously read-write only memory as executable.

Magikoopa compiles code for 3DS games and injects it into existing code.bin files and also patches the exheader.bin file. Furthermore it allows creating hooks from existing code into custom code. It features a nice UI that displays anything that can go wrong during the compiling and inserting steps.

It even allows you to jump directly to issues in code/hooks my clicking on the issues displayed in the UI. The motivation for this is to create a NSMB2 hack with fully custom code. In theory this should work with all other games as well tho. Work in progress. Should be in a kinda working state now.

User guide

Getting started

  • Build the project in QtCreator.
  • Run Magikoopa in the build directory.

You can find examples on how to use Magikoopa in combination with NSMB2 here.

Hooks

Hooks can be specified with hks files in a patch's working directory. The format is similar to YAML: 

hook_name_1:
type: xxx
link: false
addr: 0x00430988
func: FunctionNameHere
hook_name_2:
...

There are several types of hooks.

Type Description
branch Branch to a function (overwrites the original instruction).
softbranch Branch to a function (preserves the original instruction).
patch Patch data at an offset.
symbol Write the address of a symbol.

The following parameters are common to all hook types:

Parameter Description
addr Hook address.

Branch hooks

Parameter Description
link true to make a BL instruction, false for B.
func (1) Branch destination function name. This will be converted to an address using the symbol table.
dest (2) Branch destination address.

Link and one of func and dest are required parameters.

Soft-branch hooks

Parameter Description
func (1) Branch destination function name. This will be converted to an address using the symbol table.
dest (2) Branch destination address.
opcode "pre" (branch to func/dest after the original instruction), "post" (branch before the original instruction) or "ignore" (default).

One of func and dest are required parameters.

Patch hooks

Parameter Description
data (1) Data to insert (in hexadecimal).
src (2) Symbol name of data to insert.
len (2) Length of data to insert.

data, or both src and len, are required parameters.

Screenshots

magikoopa3.png

Credits

Thanks to:

  • Dirbaio - Creator of the NSMBDS asm patch template which was used as a basis.
  • StapleButter - Partial coding of the Filesystem classes.
  • Icons8 - Icons (https://icons8.com).

External links

Retrieved from ‘https://www.gamebrew.org/index.php?title=Magikoopa_3DS&oldid=153216’

Advertising: