Skip to content

Building From Source

Jump to bottom
initsu edited this page Aug 20, 2025 · 2 revisions

Building Z2Randomizer

What You'll Need

  1. A development environment that supports .NET 8.

    • On Windows, Visual Studio Community is recommended. Choose C# and .NET development during installation.
    • On Linux and macOS, install the .NET SDK (see instructions below).

  2. (Optional, Windows only) The Visual Studio Installer Projects Extension if you want to build the installer. If you don't download it you might get some warnings about the setup project, but it is not necessary to just run the randomizer.

  3. (Optional) A Git client. Recommended for easier updating, but you can also download a .zip from GitHub.

Obtaining the Source

You can either:

  • Click the green Code button on GitHub → Download ZIP, or

  • Clone via Git:

    git clone --recursive https://github.com/Ellendar/Z2Randomizer.git
cd Z2Randomizer
git checkout 4.4  # switch to the tag/branch you want to build

Windows (Visual Studio)

  1. Open the solution: Z2Randomizer.sln
  2. From the dropdown near the green play button, select the project you want to build:
    • CrossPlatformUI.Desktop (for the Desktop GUI).
  3. (Optional) From the dropdown that says Debug, switch to Release for a more optimized build.
  4. Press the green play button to build and run.

Linux / macOS

Install .NET SDK 8.0

Install Dependencies

From inside the Z2Randomizer folder:

dotnet workload restore
dotnet restore

Note: It’s expected that the Setup1 project may fail. This does not affect building or running the randomizer.

Build the Project

Desktop GUI App

dotnet build CrossPlatformUI.Desktop --configuration Release

The executable Z2Randomizer will be created in CrossPlatformUI.Desktop/bin/Release/net8.0.

Run with:

./CrossPlatformUI.Desktop/bin/Release/net8.0/Z2Randomizer &

Command-line App

dotnet build CommandLine --configuration Release

The executable Z2R will be created in CommandLine/bin/Release/net8.0.

Example usage:

cd CommandLine/bin/Release/net8.0
./Z2R -r /path/to/Zelda2.nes \
      -f RAAA2dJALw3MXoaJCKTLPeo++OwsL63s1ADhAAsBAA \
      -s 12345678

The randomized ROM will be created in the same folder as the input ROM. The filename will be shown when the generation has finished.

Using Config Files Instead of Flags

You can also use JSON config files to determine randomizer settings.

Copy the sample config:

cp ../../../Sample.json ./Sample.json

(You may move this config file anywhere convenient.)

Run the randomizer with a config:

./Z2R -r /path/to/Zelda2.nes \
      -c ./Sample.json \
      -s 12345678

Clone this wiki locally