BoxStudio

BoxStudio is an early visual editor for N64 decomp-based ROM hacking projects, starting with HackerSM64. The goal is to make decomp ROM hacking feel closer to using a small game editor: create a project, open a level, inspect real geometry, place objects, save changes, rebuild the ROM, and test on accurate emulators or real hardware.

The long-term target is broader than SM64. BoxStudio is being designed around decomp bases such as HackerSM64, HackerOoT, and zeldaret's mm, but the current implementation is focused on proving the HackerSM64 workflow first.

To test the Capabilities of BoxStudio, we have made a small ROM hack of SM64 using it. Not much changes except the Castle grounds fence is now the Troll face, there are 2 goombas, 4 coins, and 1 star. (Note that collecting the star causes the game to crash due to an issue with the game itself.). You should use ares v148 for this ROM hack.

BoxStudio does not use proprietary N64 SDKs or libraries.

Current Status

bsarestestdemo.mp4

The Goomba, Coin, and Star were all added into the Castle Grounds using BoxStudio. This video was recorded using ares v148. NOTE that the game crashes after collecting the star, and does not save the game, which is an issue in which we are hoping to come up with a solution soon.

BoxStudio is in active early development. Expect missing tools, changing project metadata, and rough editor workflows. The important pieces that are already taking shape are:

• Project creation from an existing built HackerSM64 decomp tree.
• BoxStudio project metadata under .boxstudio/.
• Default project storage under Documents/BoxStudioProjects.
• Existing level discovery from the copied HackerSM64 workspace.
• A 3D level editor viewport with orbit and fly controls.
• Rendered SM64 level geometry with texture-mode support.
• Object placement/editing for supported objects.
• Save/write support for safe level-script object edits.
• Guardrails for actor segment groups so unsupported objects are skipped instead of producing ROMs that crash at runtime.

Why Decomp Bases?

BoxStudio was originally imagined as a visual ROM and raw assembly hacking tool. That direction was dropped because raw ROM hacking becomes painful very quickly, even with matching C code beside the disassembly. Decomp projects already expose source files, level scripts, assets, model declarations, and build systems, so BoxStudio now works with those structures instead of fighting the raw ROM directly.

TLDR: raw ROM hacking is and will remain a pain in the ass.

The editor copies a decomp workspace into a BoxStudio project folder, then writes normal project files back into that copied tree. Rebuilding the ROM remains the job of the decomp base.

Games and Decomp bases currently supported:

Super Mario 64: HackerSM64 is the only supported game and decomp base supported as of now, altough in the future, there will be much more games and decomp bases to be supported. It is also possible that both HackerSM64 and the Vanilla SM64 Decomp will be supported.

HackerOoT and papermario-dx support are currently being worked on. No AI bullshit, I promise.

Recommended Testing

BoxStudio targets real hardware behavior, so accurate emulation matters.

• Use ares v147 or newer for emulator testing.
• For hardware testing, a flashcart such as SummerCart64 is recommended.
• Many hacks should be tested with the Expansion Pak enabled.

Building BoxStudio

BoxStudio uses CMake and C++17.

Windows GUI Build

The full editor currently uses Win32, Dear ImGui, and DirectX 11.

cmake -S . -B build -DBOXSTUDIO_BUILD_GUI=ON
cmake --build build --config Release

The executable is written to the CMake build output directory. During development, Debug builds are also supported:

cmake -S . -B build -DBOXSTUDIO_BUILD_GUI=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug

Linux/macOS Portable Build

The full GUI renderer is not ported to Linux/macOS yet. Non-Windows platforms currently build a portable command-line shell that keeps CI green and gives contributors a place to work on project parsing, metadata, and non-renderer systems.

cmake -S . -B build -DBOXSTUDIO_BUILD_GUI=OFF -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build

Portable commands available today:

BoxStudio --version
BoxStudio --check-project /path/to/BoxStudioProject

Repository Layout

src/
  main.cpp              Thin application entrypoint.
  BoxStudioApp.h        Shared platform app entrypoint contract.
  app/                  Editor state, app commands, and lifecycle glue.
  core/                 Shared utilities and future common services.
  decomps/
    oot/
      hackeroot/        HackerOoT workspace rules.
    pm/
      papermario-dx/    Paper Mario DX workspace rules.
    sm64/
      hackersm64/       HackerSM64 workspace and level-script compatibility rules.
  editor/               Level editor loading and object-editing workflow.
  project/              Project manifests, level discovery, and script writes.
  renderer/             Level render data extraction and viewport rendering.
  ui/                   ImGui panels and editor presentation.
  platform/
    win32/              Current full Win32/DX11 editor implementation.
    portable/           Cross-platform CLI shell used by CI and non-Windows work.
docs/                   Format notes and design notes.
third_party/imgui/      Dear ImGui submodule.

The current editor implementation is still larger than it should be. Public-facing cleanup is happening in stages:

1. Keep platform-specific code out of the root source folder.
2. Preserve a working Windows editor while Linux/macOS builds stay valid.
3. Convert the current implementation fragments into normal .cpp/.h modules with tests.
4. Add tests around project metadata, level-script writes, and actor-group compatibility.

HackerSM64 Notes

HackerSM64 actor models depend on segment groups. BoxStudio must respect those groups when writing objects into a level. For example, Goombas are safe in levels that load the common0 model group, while Koopas require group14. If a level does not load the needed group, BoxStudio should warn or skip the object instead of writing a script that compiles but crashes in-game.

When rebuilding a HackerSM64 project, use the toolchain command expected by your local decomp setup. For example:

make CROSS=mips-linux-gnu- -j4

PC Port mods?

There have been some questions about exporting ROM hacks made with BoxStudio into stuff like a native binary (Or exporting MM Rom Hacks as mods for the MM Recomp). Unfortunately, this is not in our current scope, and will likely never be a real feature in BoxStudio. The main goal of this project is to make modding easier, not make mods for sm64coopdx or any other N64 PC Ports.

Contributing

BoxStudio is not ready for broad feature work without coordination yet, but useful contributions include:

• Build fixes and CI improvements.
• Cross-platform platform-layer work.
• HackerSM64 level-script parsing fixes.
• Actor/model group metadata.
• Renderer and texture-mode accuracy fixes.
• Documentation for decomp workflows.

Please avoid editing third-party submodules directly. Dear ImGui lives under third_party/imgui as a dependency; BoxStudio-specific fixes should stay in BoxStudio source.

License

Copyright (c) 2025-2026 ExpansionPak.

BoxStudio is licensed under the MIT License. See LICENSE for details.

Crediting BoxStudio in a ROM hack is not required, but credit through a name, logo, or boot/credits sequence is appreciated.