Skip to content
Star Haven Documentation

Working without Diorama64

Diorama64 sets up, builds, runs, and updates your mod for you. You can do all of that yourself instead, with any text editor and a terminal.

Setting up a project

You need your own copy of Paper Mario (US) as a ROM in .z64 format. If your ROM is in another format, such as .n64 or .v64, convert it with Hack64's ROM byte-order converter. To make a ROM from your cartridge, see the dumping guide.

  1. Install Git for Windows, keeping all the installer's default options.
  2. Open a terminal and run git clone https://knot.starhaven.dev/did:plc:dfsxnyhzxwqpmykryrjtjabz papermario-dx, then cd papermario-dx.
  3. Rename your ROM to baserom.z64, and put it in the ver\us folder inside the project.

Where your files go

Diorama64 shows your mod as a single set of files. On disk, those files come from three layers, each a folder with the same layout:

  • Directoryassets
    • dx Assets DX adds or changes (do not edit)
    • us Assets from your copy of the game (do not edit)
  • Directorysrc Your mod's code and assets
    • Directorydx
      • config.h Mod settings

When more than one layer has a file at the same path, the build uses the highest one: src/ first, then assets/dx/, then assets/us/. To change a file from the game, copy it to the same path in src/ and edit the copy. For example, to change the messages in assets/us/msg/0C_Chapter1.msg, copy it to src/msg/0C_Chapter1.msg.

The paths in this manual are relative to the layers. For example, battle/actor/goomba.c means the file at that path in whichever layer has it, and when the manual asks you to create a file, create it under src/.

To remove something a lower layer provides, create a .meta file containing delete: true at the same path in src/. For a folder, put the .meta file inside it. For example, src/sprite/npc/Goomba/.meta removes the Goomba sprite.

Building

Build from the project folder:

.\tools\build.bat

The first build downloads the compiler toolchain. The output ROM is ver/us/build/papermario.z64.

If the build fails in a way that doesn't make sense, such as after you update DX, run ./tools/configure.sh --clean (.\tools\configure.bat --clean on Windows) to delete the files from earlier builds, then build again.

Running

Load ver/us/build/papermario.z64 in an emulator. Use ares, which is accurate enough to show the problems real hardware would. To play on a console, copy the ROM to a flashcart.

Editing maps and sprites

Diorama64 opens the right editor when you open a map or sprite. Without it, use Star Rod, which DX downloads with its toolchain. To open it, run ./tools/star-rod.sh (.\tools\star-rod.bat on Windows), or star-rod in a Nix shell.

To create a map:

  1. Create a folder for the map in its area's folder, such as src/world/area/cool_city/house_of_fun/. To start a new area, create the area's folder too.

  2. In the map's folder, create main.c:

    #include "map.h"
#include "map.xml.h"

EvtScript EVS_BindExitTriggers = {
    Return
    End
};

EvtScript EVS_Main = {
    Set(LVar0, EVS_BindExitTriggers)
    Exec(EnterWalk)
    Return
    End
};

    The game starts the map's EVS_Main when the player enters the map.

  3. In Star Rod's Map Editor, select Create. For Name, enter the map folder's name, such as house_of_fun. Star Rod finds the folder and fills in its Area.

  4. Make the map, and add an Entry marker where the player arrives.

  5. Save. Star Rod saves the map in the map's folder.

Updating DX

Paper Mario DX publishes releases. Each one is a Git tag that ends in a date, in the form dx-YYYY-MM-DD, and a fix for an older release adds a number after the date, as in dx-YYYY-MM-DD.1. To update your project, merge a release into your main branch. Run these commands from the project folder.

Adding DX as a remote

The first time you update, add Paper Mario DX as a remote named papermario-dx:

git remote add papermario-dx https://knot.starhaven.dev/did:plc:dfsxnyhzxwqpmykryrjtjabz

If one of your remotes already points at Paper Mario DX, such as origin because you cloned your project from it, rename that remote instead and point it at the address above:

git remote rename origin papermario-dx
git remote set-url papermario-dx https://knot.starhaven.dev/did:plc:dfsxnyhzxwqpmykryrjtjabz

See what's new

Fetch the releases and list them, newest first:

git fetch papermario-dx --tags
git tag --list 'dx-*' --sort=-creatordate

Before you merge, read the changelog for each release newer than the one you have. It says what you need to change in your own project.

Merging a release

git checkout main
git merge dx-YYYY-MM-DD

Replace dx-YYYY-MM-DD with the release you want. If your project is on an older release, merge the newest release rather than each one in turn. A release includes everything before it.

If git reports merge conflicts, it marks each conflicting section in the file with <<<<<<<, =======, and >>>>>>> lines. Edit each file to keep the code you want and remove the markers, then run git add on it. When you've resolved them all, run git commit to finish the merge.

Then build as usual. The first build after an update downloads the toolchain for that release.

Merging main instead

If you need a change that isn't in a release yet, you can merge papermario-dx/main:

git fetch papermario-dx
git merge papermario-dx/main

main can hold unfinished work, and its changes aren't in the changelog's release notes until the next release. Every release and every commit on main gets a toolchain. A main commit's toolchain is deleted 90 days after the next commit lands. If you've merged a main commit whose toolchain has been deleted, your build warns you and keeps using the toolchain you already downloaded. A fresh copy of your project has nothing to fall back on, so its build fails with an error that no commit in your history has a published toolchain. Merge a release to fix it.