Mother2GbaTranslation/README.md

| Branch | Status |
| --- | --- |
| `master` | [![Build](https://github.com/jeffman/Mother2GbaTranslation/actions/workflows/build_master.yml/badge.svg)](https://github.com/jeffman/Mother2GbaTranslation/actions/workflows/build_master.yml) |
| `master` | [![Test](https://github.com/jeffman/Mother2GbaTranslation/actions/workflows/test_master.yml/badge.svg)](https://github.com/jeffman/Mother2GbaTranslation/actions/workflows/test_master.yml) |

# MOTHER 2 Translation for the GBA
This is a work-in-progress translation patch for MOTHER 2 on the GBA.

## Discord
Our Discord server is pretty active: https://discord.gg/ADXS5Ub

## Hasn't it been done?
There are at least two other projects that translate the MOTHER 2 side of the game:
- Mato's menu text translation: [here](http://mother12.earthboundcentral.com/)
- TheZunar123's full translation (in progress): [here](http://earthboundcentral.com/forum/viewtopic.php?f=3&t=526) and [here](http://forum.starmen.net/forum/Games/Mother2/Mother-2-Fan-Translation/page/1/)

## Why start another project?
Neither of the above projects use a true variable-width-font (VWF) to render text. A VWF would look much better and would make the game more enjoyable.

Adding a VWF is hard, however. Mato explains [here](http://earthboundcentral.com/2011/04/a-look-at-the-mother-2-side/) why it's generally a very difficult task to fully translate the game, let alone to insert a VWF.

A long time ago (before the release of the [MOTHER 3 Fan Translation](http://mother3.fobby.net)), I started working on a proof-of-concept VWF for MOTHER 2 on the GBA. It worked, but it quickly became apparent that the amount of hacking required would be huge; window-rendering functions contain a ton of repeated code and some of it is downright non-sensical.

A few years after that, I tried it again from scratch with the intent of having a more organized codebase. It went much better, but I was soon limited by not having any translated dialogue, rather than not having a VWF; I couldn't test much of my VWF code without any English text inserted into the ROM.

## Now what?
This project aims to both complete the VWF codebase and to provide a tool for translating the game's dialogue. My new intent is to bring the hack to a state where I can just sit down and translate text efficiently in my spare time with a graphical tool. Not only that, but having such a tool means that other people can contribute!

## Screenshots
![](./screenshots/itshappening2.png) ![](./screenshots/itshappening4.png) ![](./screenshots/itshappening5.png) ![](./screenshots/m2-status2.png) ![](./screenshots/m2-battle-slugs.png) ![](./screenshots/m2-fileselect.png)

# Building

## Building with Docker
Docker allows easily building without having to install the dependencies.

1. Put a MOTHER 1+2 ROM in `bin/m12fresh.gba`
2. While in the root of the project, run: `docker run --rm -it -v ${PWD}:/home/m2gba/src lorenzooone/m2gba_translation:builder`

The output will be inside the newly created `out` folder.

## Manually Building

### Dependencies
- [.NET Core 2.1 or later](https://dotnet.microsoft.com/download)
- [PowerShell Core 6.0 or later](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-6)
- [GNU Arm Embedded Toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads)
- [armips](https://github.com/Kingcom/armips)
- Unmodified MOTHER 1+2 ROM (SHA-1 `F27336B9...`)
- Unmodified, unheadered EarthBound ROM (SHA-1 `D67A8EF3...`)
- (Optional) For building the GUI script tool: [.NET Core 3.0 or later](https://dotnet.microsoft.com/download/dotnet-core/3.0)

1. One-time setup
    1. Install .NET Core 2.1, PowerShell Core, and GNU Arm Embedded Toolchain. Make sure the Arm toolchain's `bin` folder is in your `PATH`.
    2. Create a `bin` folder in the root of the repo.
    3. Copy MOTHER 1+2 ROM to `bin/m12fresh.gba`.
    4. Copy EarthBound ROM to `bin/eb.smc`.
    5. Run `build-tools.ps1`.
        - Windows: `.\build-tools.ps1` in a PowerShell prompt
        - Linux and MacOS: `pwsh build-tools.ps1`
    6. Copy/build `armips` to `bin`.
        - Windows: grab the latest release [here](https://github.com/Kingcom/armips/releases) and copy the executable to `bin/armips.exe`.
        - Linux: follow the [README](https://github.com/Kingcom/armips/blob/master/Readme.md) to build `armips` and copy the executable to `bin/armips`.
        - MacOS: grab the latest release [here](https://github.com/Emory-M/armips/releases) and copy the executable to `bin/armips`.
2. Building the ROM
    1. Run `build.ps1`.
    2. The default compiled ROM is copied to `bin/m12.gba`.
3. (Optional) Build the GUI script tool:
    1. `dotnet build tools/ScriptTool` (don't set the output directory)
    2. `dotnet build tools/ScriptToolGui -o bin/ScriptToolGui`
    3. Run with `dotnet bin/ScriptToolGui/ScriptToolGui.dll` (or just run the EXE file directly).

# Testing

## Testing with Docker
Docker allows easily testing without having to install the dependencies.

1. Put a MOTHER 1+2 ROM in `bin/m12fresh.gba`
2. While in the root of the project, run: `docker run --rm -it -v ${PWD}:/home/m2gba/src lorenzooone/m2gba_translation:tester`

## Manually Testing

### Dependencies
- [mGBA 0.9.3 or later, or nightly built after Nov 29, 2021](https://mgba.io/downloads.html)
- [Building dependencies](#Building)

1. One-time setup
    1. Install .NET Core 2.1, PowerShell Core, and GNU Arm Embedded Toolchain. Make sure the Arm toolchain's `bin` folder is in your `PATH`.
    2. Create a `bin` folder in the root of the repo.
    3. Copy MOTHER 1+2 ROM to `bin/m12fresh.gba`.
    4. Copy EarthBound ROM to `bin/eb.smc`.
    5. Run `build-tools.ps1`.
        - Windows: `.\build-tools.ps1` in a PowerShell prompt
        - Linux and MacOS: `pwsh build-tools.ps1`
    6. Copy/build `armips` to `bin`.
        - Windows: grab the latest release [here](https://github.com/Kingcom/armips/releases) and copy the executable to `bin/armips.exe`.
        - Linux: follow the [README](https://github.com/Kingcom/armips/blob/master/Readme.md) to build `armips` and copy the executable to `bin/armips`.
        - MacOS: grab the latest release [here](https://github.com/Emory-M/armips/releases) and copy the executable to `bin/armips`.
    7. Copy/build `mgba-sdl` to `bin`.
        - You can also use mgba-QT (which is normally named mgba), but you will need to change the name of the executed program in `test.ps1`.
2. Running the tests
    1. Run `test.ps1`.
    2. The default compiled ROM is copied to `bin/m12test.gba`.
    3. The tests' log will be in `bin/test.log`.
    4. The output will also be visible in the console.
Feature/fileselect (#57) * Start file select notes * Blank out file select tileset template * Preliminary string printing Had to change the signature of the base print_chr function because the file select screen uses a lot of non-standard memory layouts. For example, the tilemap has a variable width instead of the standard 32 tiles. * Include string data in linker script * Update notes * Print the full array * Add external calls * Add FILE_SELECT struct * Add format_file_string * Widen main file select window * Format full text speed string * Add build badges to readme 2019-08-06 03:12:45 +01:00			`\| Branch \| Status \|`
			`\| --- \| --- \|`
Update README.md 2022-07-03 21:53:10 +01:00			\| `master` \| [![Build](https://github.com/jeffman/Mother2GbaTranslation/actions/workflows/build_master.yml/badge.svg)](https://github.com/jeffman/Mother2GbaTranslation/actions/workflows/build_master.yml) \|
			\| `master` \| [![Test](https://github.com/jeffman/Mother2GbaTranslation/actions/workflows/test_master.yml/badge.svg)](https://github.com/jeffman/Mother2GbaTranslation/actions/workflows/test_master.yml) \|
Feature/fileselect (#57) * Start file select notes * Blank out file select tileset template * Preliminary string printing Had to change the signature of the base print_chr function because the file select screen uses a lot of non-standard memory layouts. For example, the tilemap has a variable width instead of the standard 32 tiles. * Include string data in linker script * Update notes * Print the full array * Add external calls * Add FILE_SELECT struct * Add format_file_string * Widen main file select window * Format full text speed string * Add build badges to readme 2019-08-06 03:12:45 +01:00
Re-organize build script and README Convert build-tools to PowerShell. Note the use of full paths for dotnet's output directory: https://github.com/dotnet/cli/issues/10550 2019-01-08 03:38:52 +00:00			`# MOTHER 2 Translation for the GBA`
Added README 2015-03-25 22:30:30 +00:00			`This is a work-in-progress translation patch for MOTHER 2 on the GBA.`

Re-organize build script and README Convert build-tools to PowerShell. Note the use of full paths for dotnet's output directory: https://github.com/dotnet/cli/issues/10550 2019-01-08 03:38:52 +00:00			`## Discord`
Update README 2018-11-27 04:48:54 +00:00			`Our Discord server is pretty active: https://discord.gg/ADXS5Ub`

Re-organize build script and README Convert build-tools to PowerShell. Note the use of full paths for dotnet's output directory: https://github.com/dotnet/cli/issues/10550 2019-01-08 03:38:52 +00:00			`## Hasn't it been done?`
Added README 2015-03-25 22:30:30 +00:00			`There are at least two other projects that translate the MOTHER 2 side of the game:`
			`- Mato's menu text translation: [here](http://mother12.earthboundcentral.com/)`
			`- TheZunar123's full translation (in progress): [here](http://earthboundcentral.com/forum/viewtopic.php?f=3&t=526) and [here](http://forum.starmen.net/forum/Games/Mother2/Mother-2-Fan-Translation/page/1/)`

Re-organize build script and README Convert build-tools to PowerShell. Note the use of full paths for dotnet's output directory: https://github.com/dotnet/cli/issues/10550 2019-01-08 03:38:52 +00:00			`## Why start another project?`
Added README 2015-03-25 22:30:30 +00:00			`Neither of the above projects use a true variable-width-font (VWF) to render text. A VWF would look much better and would make the game more enjoyable.`

			`Adding a VWF is hard, however. Mato explains [here](http://earthboundcentral.com/2011/04/a-look-at-the-mother-2-side/) why it's generally a very difficult task to fully translate the game, let alone to insert a VWF.`

			`A long time ago (before the release of the [MOTHER 3 Fan Translation](http://mother3.fobby.net)), I started working on a proof-of-concept VWF for MOTHER 2 on the GBA. It worked, but it quickly became apparent that the amount of hacking required would be huge; window-rendering functions contain a ton of repeated code and some of it is downright non-sensical.`

			`A few years after that, I tried it again from scratch with the intent of having a more organized codebase. It went much better, but I was soon limited by not having any translated dialogue, rather than not having a VWF; I couldn't test much of my VWF code without any English text inserted into the ROM.`

Re-organize build script and README Convert build-tools to PowerShell. Note the use of full paths for dotnet's output directory: https://github.com/dotnet/cli/issues/10550 2019-01-08 03:38:52 +00:00			`## Now what?`
Added README 2015-03-25 22:30:30 +00:00			`This project aims to both complete the VWF codebase and to provide a tool for translating the game's dialogue. My new intent is to bring the hack to a state where I can just sit down and translate text efficiently in my spare time with a graphical tool. Not only that, but having such a tool means that other people can contribute!`

Re-organize build script and README Convert build-tools to PowerShell. Note the use of full paths for dotnet's output directory: https://github.com/dotnet/cli/issues/10550 2019-01-08 03:38:52 +00:00			`## Screenshots`
Update README 2019-08-06 03:41:06 +01:00			`![](./screenshots/itshappening2.png) ![](./screenshots/itshappening4.png) ![](./screenshots/itshappening5.png) ![](./screenshots/m2-status2.png) ![](./screenshots/m2-battle-slugs.png) ![](./screenshots/m2-fileselect.png)`
Added README 2015-03-25 22:30:30 +00:00
Add testing docker build files and usage 2021-12-28 01:04:40 +00:00			`# Building`

			`## Building with Docker`
Change docker script's execution flow Changes the user who will build the ROM. Separates building the docker image and building the ROM. Updates README.md to reflect the new building method. 2021-12-27 18:47:19 +00:00			`Docker allows easily building without having to install the dependencies.`

			1. Put a MOTHER 1+2 ROM in `bin/m12fresh.gba`
Improve compatibility with Windows and its Powershell 2021-12-30 20:48:59 +00:00			2. While in the root of the project, run: `docker run --rm -it -v ${PWD}:/home/m2gba/src lorenzooone/m2gba_translation:builder`
Change docker script's execution flow Changes the user who will build the ROM. Separates building the docker image and building the ROM. Updates README.md to reflect the new building method. 2021-12-27 18:47:19 +00:00
			The output will be inside the newly created `out` folder.

Add testing docker build files and usage 2021-12-28 01:04:40 +00:00			`## Manually Building`
Update README 2018-11-27 04:48:54 +00:00
Add testing docker build files and usage 2021-12-28 01:04:40 +00:00			`### Dependencies`
Re-organize build script and README Convert build-tools to PowerShell. Note the use of full paths for dotnet's output directory: https://github.com/dotnet/cli/issues/10550 2019-01-08 03:38:52 +00:00			`- [.NET Core 2.1 or later](https://dotnet.microsoft.com/download)`
			`- [PowerShell Core 6.0 or later](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-6)`
			`- [GNU Arm Embedded Toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads)`
			`- [armips](https://github.com/Kingcom/armips)`
			- Unmodified MOTHER 1+2 ROM (SHA-1 `F27336B9...`)
			- Unmodified, unheadered EarthBound ROM (SHA-1 `D67A8EF3...`)
README updates for the GUI tool 2019-01-09 01:53:14 +00:00			`- (Optional) For building the GUI script tool: [.NET Core 3.0 or later](https://dotnet.microsoft.com/download/dotnet-core/3.0)`
Update README 2018-11-27 04:48:54 +00:00
			`1. One-time setup`
Update notes 2019-01-29 03:44:38 +00:00			1. Install .NET Core 2.1, PowerShell Core, and GNU Arm Embedded Toolchain. Make sure the Arm toolchain's `bin` folder is in your `PATH`.
			2. Create a `bin` folder in the root of the repo.
			3. Copy MOTHER 1+2 ROM to `bin/m12fresh.gba`.
			4. Copy EarthBound ROM to `bin/eb.smc`.
			5. Run `build-tools.ps1`.
Re-organize build script and README Convert build-tools to PowerShell. Note the use of full paths for dotnet's output directory: https://github.com/dotnet/cli/issues/10550 2019-01-08 03:38:52 +00:00			- Windows: `.\build-tools.ps1` in a PowerShell prompt
Update README with macOS build instructions 2020-03-24 16:45:48 +00:00			- Linux and MacOS: `pwsh build-tools.ps1`
Update notes 2019-01-29 03:44:38 +00:00			6. Copy/build `armips` to `bin`.
Re-organize build script and README Convert build-tools to PowerShell. Note the use of full paths for dotnet's output directory: https://github.com/dotnet/cli/issues/10550 2019-01-08 03:38:52 +00:00			- Windows: grab the latest release [here](https://github.com/Kingcom/armips/releases) and copy the executable to `bin/armips.exe`.
			- Linux: follow the [README](https://github.com/Kingcom/armips/blob/master/Readme.md) to build `armips` and copy the executable to `bin/armips`.
Update README with macOS build instructions 2020-03-24 16:45:48 +00:00			- MacOS: grab the latest release [here](https://github.com/Emory-M/armips/releases) and copy the executable to `bin/armips`.
Update README 2018-11-27 04:48:54 +00:00			`2. Building the ROM`
Update README 2019-08-06 03:41:06 +01:00			1. Run `build.ps1`.
Re-organize build script and README Convert build-tools to PowerShell. Note the use of full paths for dotnet's output directory: https://github.com/dotnet/cli/issues/10550 2019-01-08 03:38:52 +00:00			2. The default compiled ROM is copied to `bin/m12.gba`.
Add missing step to README for building GUI tool 2019-01-19 20:43:49 +00:00			`3. (Optional) Build the GUI script tool:`
			1. `dotnet build tools/ScriptTool` (don't set the output directory)
			2. `dotnet build tools/ScriptToolGui -o bin/ScriptToolGui`
			3. Run with `dotnet bin/ScriptToolGui/ScriptToolGui.dll` (or just run the EXE file directly).
Update README.md Testing webhook 2020-04-09 06:14:10 +01:00
Add testing docker build files and usage 2021-12-28 01:04:40 +00:00			`# Testing`

			`## Testing with Docker`
Use multi-stage building for docker 2021-12-30 13:04:07 +00:00			`Docker allows easily testing without having to install the dependencies.`
Add testing docker build files and usage 2021-12-28 01:04:40 +00:00
			1. Put a MOTHER 1+2 ROM in `bin/m12fresh.gba`
Improve compatibility with Windows and its Powershell 2021-12-30 20:48:59 +00:00			2. While in the root of the project, run: `docker run --rm -it -v ${PWD}:/home/m2gba/src lorenzooone/m2gba_translation:tester`
Add testing docker build files and usage 2021-12-28 01:04:40 +00:00
			`## Manually Testing`
Add target_name boundary tests 2021-12-18 01:08:25 +00:00
Add testing docker build files and usage 2021-12-28 01:04:40 +00:00			`### Dependencies`
Add target_name boundary tests 2021-12-18 01:08:25 +00:00			`- [mGBA 0.9.3 or later, or nightly built after Nov 29, 2021](https://mgba.io/downloads.html)`
			`- [Building dependencies](#Building)`

			`1. One-time setup`
			1. Install .NET Core 2.1, PowerShell Core, and GNU Arm Embedded Toolchain. Make sure the Arm toolchain's `bin` folder is in your `PATH`.
			2. Create a `bin` folder in the root of the repo.
			3. Copy MOTHER 1+2 ROM to `bin/m12fresh.gba`.
			4. Copy EarthBound ROM to `bin/eb.smc`.
			5. Run `build-tools.ps1`.
			- Windows: `.\build-tools.ps1` in a PowerShell prompt
			- Linux and MacOS: `pwsh build-tools.ps1`
			6. Copy/build `armips` to `bin`.
			- Windows: grab the latest release [here](https://github.com/Kingcom/armips/releases) and copy the executable to `bin/armips.exe`.
			- Linux: follow the [README](https://github.com/Kingcom/armips/blob/master/Readme.md) to build `armips` and copy the executable to `bin/armips`.
			- MacOS: grab the latest release [here](https://github.com/Emory-M/armips/releases) and copy the executable to `bin/armips`.
			7. Copy/build `mgba-sdl` to `bin`.
			- You can also use mgba-QT (which is normally named mgba), but you will need to change the name of the executed program in `test.ps1`.
			`2. Running the tests`
			1. Run `test.ps1`.
			2. The default compiled ROM is copied to `bin/m12test.gba`.
			3. The tests' log will be in `bin/test.log`.
			`4. The output will also be visible in the console.`