Elements of Harmony

中文简介

This project started as a localization mod for My Little Pony: A Maretime Bay Adventure using Harmony API aiming to enable fan translation of the game into Chinese.

The codebase I ended up writing does not limit it to translate to only Chinese, which is why in collaboration with Ponywka, we re-enabled Russian localizations as well.

However, since anything is possible with Harmony API, I plan to add tons of more features, unlocking the true potential of this mod, this game, and the Unity engine.

One of those featured is already proven back in 2022 - Loyalty: the Motion Control module.

New Goal 2024

A new MLP game from the same publisher (not the same developer, but they are from España, like the previous one) is confirmed, it's called A Zephyr Heights Mystery.

That motivated me to remaster this project to use it to mod both games and implement all those features I dreamed of back in 2022

Bug fixes & improvements for the base game + small additional features

(for AMBA) In the controls menu, two text fields were not localized, and one text field has a missing character... Fixed on March 17
(for AZHM, can be used for both games) Did they turn off ACES tone mapping for AZHM? No problem, let me just invent a way to turn it back on... There, fixed
(for AMBA) I saw a line that says "Logo language" in the log, and that's when I knew that I could implement a logo localization feature, too. Implemented on March 19, recovered the Russian game logo, made a Chinese game logo.
(for AMBA) After some investigation in the logs and some scouting on the Internet, I found the reason why all the text on the main menu appears blurry, it's because the main menu is using FXAA! Fixed on March 19 (when encounters FXAA settings, change it to SMAA)
All this talk of tone mapping made me sort of want to find ways to enable HDR output for the game. Codes of interest I found are: Camera.allowHDR; implemented on March 21 but didn't test it out yet, I don't have an HDR display right now, I'm attending college in another province and my HDR TV is back at home...
With all these gradually increasing amounts of settings, I feel like I need to bring the property editor module from my DirectX game engine project (not on GitHub) into this mod, to support real-time adjustments of settings. However, I need to consider whether to use a separate window (already implemented) or re-render controls with Direct2D in-game (not implemented yet), the latter will take time, and may not make it before the game comes out. (If anyone asks why I don't just use ImGUI or something, it's because I don't like using any third-party libraries)

Note

It's been some time since I updated this list, I couldn't keep track and post the code links anymore, so from now on I'm just going to post only the descriptions. (April, 16)

Note

First update following AZHM's release, it's a shame that I'm 2 days late due to classes (whose idea was it to put classes on Saturday?)

(for both games) added MelonLoader support, you can now apply this mod using MelonLoader, which is non-destructive mod manager (non-destructive as in doesn't modify game files at all)
(for AZHM) fixed a bug where the Chinese language cannot be displayed due to the base game's incorrect language mappings

Goals

Magic - Hook the DirectX API to acquire the game's swap chain, so that we can render our graphics on top of the original game using Direct2D - already implemented in 2022, will improve in the future
Loyalty - Kinect motion control - already implemented in 2022, will refactor in the future
Generosity - Enable the game to load custom models - AssetBundle.LoadAsset seems like a promising lead
Laughter - Add online multiplayer functionality, you should be able to see other players as any pony they choose, there will be text chat and voice chat, and you should be able to compete with other players in a minigame - should I use P2P or dedicated server?
Battle of the Bands - Add the ability to add custom songs to the music minigame - I think it's possible, and fun
Friendship Games - Add new minigames - my current idea is to create new projects in Unity, make the gameplay there, build it, and then abuse AssetBundle.LoadAsset and Assembly.Load to load that onto this game
Loyalty (Extended) - implement VR support

Warning

Everything beyond this line is legacy documentation from 2022, only for archive purposes

Applying the mod to the game (obsolete)

build the DLL (remember to restore NuGet package first) (or just download from release tag)
put ElementsOfHarmony.dll and 0Harmony.dll and 0Harmony.xml into (game folder)\MLP_Data\Managed
add "ElementsOfHarmony.dll" into "names" in \MLP_Data\ScriptingAssemblies.json and corresponding value 16 into "types"
add the following element into "root" in \MLP_Data\RuntimeInitializeOnLoads.json

{
  "assemblyName": "ElementsOfHarmony.dll",
  "nameSpace": "ElementsOfHarmony",
  "className": "ElementsOfHarmony",
  "methodName": "Exist",
  "loadTypes": 2,
  "isUnityClass": false
}

Adding our custom translations

to add a language that the game didn't originally support, follow the following steps

create a folder named Elements of Harmony in the game folder (where MLP.exe is)
to add text translations, in the Elements of Harmony folder, create ~~a sub folder named Translations and put translation files inside~~ (since version 0.3.0, this location is changed to Elements of Harmony/Assets/Localization/[GameTitleInitials]/[YourLanguageISOCode]/[YourLanguageISOCode].txt)
the translation file name should be (language ISO code).txt (case sensitive), its content should be tab-separated values (TSV), where first column is the term (case sensitive) and second column is the translated text (use \n for line break during text); other columns will be ignored
please also add your language code as term and your language name as translated text so that your language name can show up in the game menu correctly
to add localized audio files, in the Elements of Harmony folder, ~~create a sub folder named AudioClip and put the audio files inside (you can create sub folders in AudioClip as well, the mod will recursively search for all audio files in all sub folders)~~ (since version 0.3.0, this location is changed to Elements of Harmony/Assets/Localization/[GameTitleInitials]/[YourLanguageISOCode]/AudioClip/)
the name of the audio files should match the translated terms (case sensitive); in nerds' language, it's a two-stage-mapping method. look for the field OurSupportedAudioFormats in ElementsOfHarmony.cs for a list of supported audio formats;

example for audio clip:
term Audio_BeachCove/INTRO/EV_01/BC_INTRO_EV_01_01_CS_ZP_01
translated (en-US) BC_INTRO_EV_01_01_CS_ZP_01_en-US
translated (ru) BC_INTRO_EV_01_01_CS_ZP_01_ru
audio file name (en-US) BC_INTRO_EV_01_01_CS_ZP_01_en-US.ogg
audio file name (ru) BC_INTRO_EV_01_01_CS_ZP_01_ru.ogg

Look here for a list of terms

Disable the block on the Russian language (obsolete)

the mod itself is in charge of doing this now, you don't need to change Assembly-CSharp.dll anymore, but I'm leaving the content here for archieve purposes

open (game folder)\MLP_Data\Managed\Assembly-CSharp.dll with a binary file editor of your liking (I'm using HxD)
search for one of the following strings in UTF-16 Little Endian encoding ru fr-BE fr-CA fr-LU fr-MC fr-CH es-AR es-BO es-ES es-CL es-CO es-CR es-DO es-EC es-SV es-GT es-HN es-US es-MX es-NI es-PA es-PY es-PE es-PR es-UY es-VE es-LA
the strings you found should be together in this order but with 00 0B or 01 0B in between them, if not, repeat step 2
replace ru to any other 2 characters but do not change the length of the string
save the file and you're good to go (HxD will automatically make a backup .bak file in the same folder, I trust that other binary file editor will do it too, but you can always verify integrity of game files if anything goes wrong)

Bugs? what do?

_{during the course of the making of this mod, a lot of things can go wrong (and they did), but I knew it's to be expected for unorthodox projects like this, so I came prepared.}

The mod attachs/hooks to every kind of error events/exceptions I can think of, AppDomain.CurrentDomain.UnhandledException event, UnityEngine.Debug.LogError method, System.Exception constructor, and so on; and then it logs those errors (stack trace + error message) into Elements of Harmony/Elements of Harmony.log if it's enabled in the settings

To enable log setting add line Debug=true and Debug.Log.Enabled=true in Elements of Harmony/Settings.txt

if your game is installed in C:\Program Files or C:\Program Files (x86) the log probably won't work because writing in those folders requires administrator privileges _{(so I'd recommend NOT to install your game into those folders...)}

so if you think you've encountered a bug, look into Elements of Harmony/Elements of Harmony.log, there is about 70% chance that the clues we needed are recorded in there

wd357dui / Elements-of-Harmony