中文简介

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.

• 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 - implemented in June 12 2024 in Dance.cs

• 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

• (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... Implemented in v0.3.2

• 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)

• (for both games) DirectXHook - fixes compatibility with the Steam overlay hook by temporarily un-patching Steam's hook when Present is being called more than one time for a single frame (being called more than one time but has returned 0 times)
• (for both games) Implement display settings in Settings.txt, resolution, fullscreen, refresh rate, anti-aliasing, v-sync, target framerate
• (for AMBA) Background music was too quiet, I adjusted it so that setting 100% is now +20db instead of -0db
• (for AMBA) Move all minigame tutorials to appear before the "3, 2, 1, go" countdown
• (for AMBA) Recover audio instructions from many of the minigame tutorials (yes they all used to have audio, but some are disabled in release)
• (for AMBA) Fix Zipp's Flight Academy minigame's background music volume (was too quiet and didn't comply with the menu's audio settings)
• (for AMBA) Recover the hit evaluation text ("good", "cool", "perfect") in the Pipp Pipp Dance Parade minigame (yes, this existed in the game but was disabled in release)
• (for AMBA) In the Sprout's Roller Blading Chase minigame, shorten the distance between Sprout and the player as the game progresses while in singleplayer mode
• (for AMBA) In the Sprout's Roller Blading Chase minigame, play some of the unused audio clips in story mode ("story mode" means entering the minigame through the story instead of from the main menu)
• (for AMBA) Remove the green filter in the swamp area (in Town Park where the herding crabs minigame is) and in the herding crabs minigame
• (for AMBA, can be used for both games) Implement custom font?... I spent 4 days trying out different ideas, but after finally understanding the situation, I've concluded that this is not possible until I implement the Generosity module

• (for both games) added MelonLoader support, you can now apply this mod using MelonLoader. in MelonLoaderReference
• (for AZHM) fixed a bug where the Chinese language cannot be displayed due to the base game's incorrect language mappings in Localization.cs
• (for both games) added BepInEx support in BepInExReference
• (for AZHM) The URP shaders in AZHM were stripped, I tried to bring them back and succeeded by patching globalgamemanagers.assets after fixing AssetRipper/AssetRipper#1365
• (for AMBA) fix combo bar's stutter issue in the dancing game minigame by depending on Time.time instead of AudioSource.time for checking time progression. My reason and supporting evidence for Fixing the issue in this way are: 1.Timeline AudioTrack stuttering and artifacts; 2.Audiosource.time innaccurate in Android?
• (for AZHM) fix stutter every 1 second by stopping it from re-setting the same resolution every 1 second in DirectXHook.cs

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

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

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

1. create a folder named Elements of Harmony in the game folder (where MLP.exe is)

2. 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)

3. 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

4. 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

5. 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/)

6. 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

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

1. open (game folder)\MLP_Data\Managed\Assembly-CSharp.dll with a binary file editor of your liking (I'm using HxD)
2. 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
3. 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
4. replace ru to any other 2 characters but do not change the length of the string
5. 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)

_{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