How to Configure Emulator Paths and N64 Toolchain Settings in Pyrite64

Pyrite64 stores emulator and toolchain configurations in the project.p64proj JSON file, using the pathEmu key for emulator commands and pathN64Inst key for the N64 toolchain root directory.

Configuring emulator paths and N64 toolchain settings in Pyrite64 is essential for building Nintendo 64 ROMs and testing them seamlessly. The IDE maintains per-project settings in a dedicated configuration file that controls both the build toolchain and the emulator launch behavior. Understanding how to modify these settings ensures that Pyrite64 can locate your compiler, linker, and preferred N64 emulator.

Understanding the Project Configuration File

Pyrite64 uses a JSON-based project file named project.p64proj located in the root directory of every project. This file serializes the Project::Config structure defined in src/project/project.h and handles read/write operations through src/project/project.cpp.

The two critical fields for build and runtime operations are:

• pathEmu: The command or full path used to launch the N64 emulator
• pathN64Inst: The absolute path to the root of your libdragon or N64 toolchain installation

Configuring the Emulator Path (pathEmu)

The pathEmu setting determines which emulator Pyrite64 launches when you press the Run command.

Editing the JSON Configuration

Open project.p64proj in a text editor and modify the pathEmu field:

{
  "name": "MyN64Adventure",
  "pathEmu": "gopher64",
  "pathN64Inst": "",
  "romName": "myadventure"
}

For Windows systems with spaces in paths, use escaped backslashes or forward slashes:

"pathEmu": "C:/Emulators/Ares/ares.exe"

Using the Project Settings UI

Alternatively, configure the emulator through the graphical interface. The UI implementation in src/editor/pages/parts/projectSettings.cpp renders the emulator path field using:

ImTable::addPath("Emulator", ctx.project->conf.pathEmu, true, "$PATH_EMU");

Navigate to Project → Settings and enter the emulator command in the Emulator field.

Emulator Launch Mechanism

When you execute the Run command, Pyrite64 concatenates the emulator path with the generated ROM path. The implementation in src/editor/globalActions.cpp (line 116) executes:

std::string runCmd = ctx.project->conf.pathEmu + " " + z64Path;
runCommand(runCmd.c_str());

Configuring the N64 Toolchain Path (pathN64Inst)

The pathN64Inst setting tells Pyrite64 where to find the compiler (mips64-elf-gcc), linker, and libdragon utilities required to build N64 ROMs.

Setting the Toolchain Root Directory

Edit project.p64proj to specify the absolute path to your toolchain root (the directory containing bin/, include/, lib/, etc.):

{
  "pathEmu": "ares",
  "pathN64Inst": "C:/tools/libdragon",
  "romName": "mygame"
}

On Linux or macOS, use Unix-style paths:

"pathN64Inst": "/usr/local/libdragon"

Environment Variable Fallback

Pyrite64 supports the N64_INST environment variable as a fallback mechanism. The detection logic in src/utils/toolchain.cpp (lines 30-38) checks for the environment variable first:

const char* n64InstEnv = std::getenv("N64_INST");
if (n64InstEnv != nullptr) {
    state.toolchainPath = fs::path{n64InstEnv};
}
else {
    state.toolchainPath = project.conf.pathN64Inst;
}
state.hasToolchain = fs::exists(state.toolchainPath / "bin" / "mips64-elf-gcc");

Set the environment variable in your shell:

export N64_INST=$HOME/libdragon

Toolchain Detection Logic

The Toolchain::scan() function in src/utils/toolchain.cpp validates the installation by verifying the existence of bin/mips64-elf-gcc within the specified directory. If detection fails, the status overlay in src/editor/pages/parts/toolchainOverlay.cpp displays a warning and provides an Install Toolchain button for automated setup on Windows.

Verification and Troubleshooting

Verifying Toolchain Detection

After configuring the paths, launch Pyrite64 and observe the status line. The toolchain overlay in src/editor/pages/parts/toolchainOverlay.cpp (lines 140-152) displays one of the following messages:

• "The N64 toolchain is correctly installed" – Configuration successful
• "Toolchain missing" – pathN64Inst is empty and N64_INST environment variable is not set

Common Configuration Pitfalls

Symptom	Cause	Solution
"Toolchain missing" error	pathN64Inst empty and N64_INST not set	Fill the N64_INST field in Project Settings or set the environment variable
Emulator does not launch	pathEmu points to non-executable or contains spaces without proper escaping	Use absolute paths or wrapper scripts; avoid spaces in paths
Build fails with "cannot find mips64-elf-gcc"	Wrong toolchain root (missing bin/ subfolder)	Verify that bin/mips64-elf-gcc exists inside pathN64Inst

Summary

• Pyrite64 stores configuration in project.p64proj at the project root, specifically using the pathEmu and pathN64Inst JSON keys.
• pathEmu defines the emulator command executed when you press Run, concatenated with the ROM path in src/editor/globalActions.cpp.
• pathN64Inst specifies the toolchain root directory containing bin/mips64-elf-gcc, used by src/utils/toolchain.cpp for compilation.
• The N64_INST environment variable serves as a fallback when pathN64Inst is empty, checked in Toolchain::scan().
• Verify configuration through the toolchain status overlay in src/editor/pages/parts/toolchainOverlay.cpp before building.

Frequently Asked Questions

Where does Pyrite64 store emulator configuration?

Pyrite64 stores the emulator path in the pathEmu field of the project.p64proj JSON file located in your project root. This value is read by the Project::Config structure in src/project/project.h and used by src/editor/globalActions.cpp to construct the launch command when you press the Run button.

Can I use an environment variable instead of editing project.p64proj?

Yes. While pathEmu must be defined in the JSON file, the N64 toolchain path supports the N64_INST environment variable as a fallback. According to src/utils/toolchain.cpp, the Toolchain::scan() function checks std::getenv("N64_INST") first, and only falls back to project.conf.pathN64Inst if the environment variable is unset.

Why does Pyrite64 fail to detect my installed toolchain?

Detection fails when the path specified in pathN64Inst or N64_INST does not contain the expected directory structure. The validation logic in src/utils/toolchain.cpp specifically checks for the existence of bin/mips64-elf-gcc within the toolchain root. Ensure your path points to the directory containing bin/, include/, and lib/ subdirectories, not the bin folder itself.

How do I configure a custom emulator wrapper script?

Set pathEmu to the absolute path of your wrapper script in project.p64proj. The script must be executable and accept the ROM file path as its first argument, as Pyrite64 in src/editor/globalActions.cpp executes the command by concatenating pathEmu, a space, and the generated .z64 file path. For Windows, use forward slashes or escaped backslashes: "C:/scripts/run_ares.bat" or "C:\\\\scripts\\\\run_ares.bat".

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}