The easiest way to install the mod is through the CurseForge or Modrinth app. Both make it easier to keep the mod, Minecraft version, loader, and required dependencies together.
Choose the right release
Choose the download that matches your Minecraft version and mod loader. The current guides cover these releases:
| Minecraft / loader | Referenced release | What to expect |
|---|---|---|
| 1.21.1 / NeoForge | 2.5.0 (release) | The source-reviewed playable Ocarina, song wheel, Free Play, and the default note-key map documented here. |
| 1.20.1 / Forge | 2.5.0c (beta) | Official backport includes the playable Ocarina overhaul, radial selector, Free Play, song HUD and keybind support. Check your in-game bindings; NeoForge-specific defaults are not guaranteed. |
| Other / older versions | Choose a matching file from the file archive | Earlier builds may use older Ocarina controls and different progression or world-generation behavior. Don't apply 2.5.0 instructions without checking your actual build. |
Not interchangeable: Forge and NeoForge are different loaders. A matching Minecraft version alone does not make the mod JAR compatible. Dedicated servers and clients should also agree on their mod release and dependencies.
The game will not start, or the update changed controls
Start with the actual JAR in your launcher profile, not just the file you downloaded. Forge 1.20.1 and NeoForge 1.21.1 require different mod builds, and the Ocarina overhaul is available in NeoForge 2.5.0 or Forge 2.5.0c beta. Older Forge 2.3.x guides may describe different input behavior.
| What you see | What to check first | Next guide |
|---|---|---|
| Minecraft crashes before the title screen | Check the first meaningful Caused by line in your crash report, then confirm the profile's Minecraft version, loader, exact JAR and required dependencies. Do not delete a world to solve a launcher crash. | Launch crash triage |
Log includes Duplicate key key_key.mastersword.ocarina_song_menu | This exact Ocarina menu crash has been reported; a universal fix is not confirmed. Back up options.txt before inspecting possible duplicate entries. | Conservative keybind recovery |
| The new Ocarina wheel or notes are missing | Verify the playable-Ocarina release is installed, hold an Ocarina in your main hand, close other menus and inspect the actual key bindings. O is the reviewed NeoForge default, not a guarantee for every Forge profile. | Ocarina controls checklist |
| The client works but a server behaves differently | Compare Minecraft, loader, Master Sword and required dependency versions on both sides; check server configuration for altered abilities, structure generation or tool targets. | Server settings |
| A setting reverted after updating | Back up the file you actually edited. The reviewed Forge 1.20.1 source contains both config/mastersword-common.toml and JSON files under config/mastersword/; the NeoForge 1.21.1 guide documents its JSON files. Do not reset both kinds blindly. | Safe config edits |
When it still fails: test the same release in a clean launcher profile with only the required dependencies, keeping your existing profile and saves untouched. Compare the result, then include the exact file name and latest.log in a useful bug report. A crash at key registration cannot necessarily be solved by changing an in-game keybind.
Install with CurseForge
- Open the CurseForge app.Choose Minecraft: Java Edition.
- Create or select a profile.The profile's Minecraft version and loader must match the Master Sword release you want to use.
- Choose Add More Content.Search for Zelda, Legend of the Master Sword by Mezimaru and install it.
- Keep required dependencies installed.Current releases use required libraries such as GeckoLib and playerAnimator; the app normally resolves required project dependencies for you.
- Launch the profile.Do not mix a Forge mod file into a NeoForge profile or vice versa.
Install with Modrinth
- Open the Modrinth App.Create an instance for the Minecraft version you want to play.
- Select the matching loader.For example, use a NeoForge instance with a NeoForge release of the mod.
- Add content.Search for Zelda, Legend of the Master Sword and install the matching release.
- Keep required dependencies enabled.Required content is shown on the project/version page and the app can install compatible dependencies into the instance.
- Launch and verify.From Minecraft's Mods screen, confirm the Master Sword mod and its required libraries are loaded.
Multiplayer / dedicated servers
The mod is intended for both sides. A dedicated server and players joining it should use compatible Minecraft, loader, mod, and dependency versions.
Manual installation
If you install manually, download the release for your exact Minecraft version and loader, put the mod JAR and required dependencies in that instance's mods folder, then start Minecraft through that loader. The CurseForge/Modrinth apps are recommended because they reduce version and dependency mistakes.