# How to Configure Emulator Paths and N64 Toolchain Settings in Pyrite64

> Configure emulator paths and N64 toolchain with Pyrite64. Learn to edit the project.p64proj JSON file using pathEmu and pathN64Inst for seamless development. Get started now.

- Repository: [Max Bebök/pyrite64](https://github.com/hailtododongo/pyrite64)
- Tags: how-to-guide
- Published: 2026-02-19

---

**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`](https://github.com/HailToDodongo/pyrite64/blob/main/src/project/project.h) and handles read/write operations through [`src/project/project.cpp`](https://github.com/HailToDodongo/pyrite64/blob/main/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:

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

```

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

```json
"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`](https://github.com/HailToDodongo/pyrite64/blob/main/src/editor/pages/parts/projectSettings.cpp) renders the emulator path field using:

```cpp
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`](https://github.com/HailToDodongo/pyrite64/blob/main/src/editor/globalActions.cpp) (line 116) executes:

```cpp
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.):

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

```

On Linux or macOS, use Unix-style paths:

```json
"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`](https://github.com/HailToDodongo/pyrite64/blob/main/src/utils/toolchain.cpp) (lines 30-38) checks for the environment variable first:

```cpp
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:

```bash
export N64_INST=$HOME/libdragon

```

### Toolchain Detection Logic

The `Toolchain::scan()` function in [`src/utils/toolchain.cpp`](https://github.com/HailToDodongo/pyrite64/blob/main/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`](https://github.com/HailToDodongo/pyrite64/blob/main/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`](https://github.com/HailToDodongo/pyrite64/blob/main/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`](https://github.com/HailToDodongo/pyrite64/blob/main/src/editor/globalActions.cpp).
- **`pathN64Inst`** specifies the toolchain root directory containing `bin/mips64-elf-gcc`, used by [`src/utils/toolchain.cpp`](https://github.com/HailToDodongo/pyrite64/blob/main/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`](https://github.com/HailToDodongo/pyrite64/blob/main/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`](https://github.com/HailToDodongo/pyrite64/blob/main/src/project/project.h) and used by [`src/editor/globalActions.cpp`](https://github.com/HailToDodongo/pyrite64/blob/main/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`](https://github.com/HailToDodongo/pyrite64/blob/main/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`](https://github.com/HailToDodongo/pyrite64/blob/main/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`](https://github.com/HailToDodongo/pyrite64/blob/main/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"`.