Skip to main content

Zelda 3 Guide

Requirements​

You need:

  • Zelda3 UWP .msixbundle
  • Xbox Developer Mode
  • Xbox Dev Portal access
  • Windows PC
  • Python 3.11 or newer
  • pillow and pyyaml
  • Legally dumped US Zelda 3 ROM

The ROM must be named:

zelda3.sfc

Required SHA256:

66871d66be19ad2c34c927d6b14cd8eb6fc3181965b6e517cb361f7316009cfb

1. Extract Zelda3 Assets

The UWP port needs this file:

zelda3_assets.dat

This is generated from your ROM. Once generated, the ROM is no longer needed by the app.

Install Python Requirements​

Install Python from:

https://www.python.org/downloads/

During setup, enable:

Add Python to PATH

Then open Command Prompt and run:

python -m pip install --upgrade pip pillow pyyaml

Download Zelda3​

Download the source:

https://github.com/snesrev/zelda3

Or clone it:

git clone https://github.com/snesrev/zelda3
cd zelda3

Generate the Asset File​

  1. Place your US ROM in the Zelda3 source folder.
  2. Rename it to:
zelda3.sfc
  1. Run:
extract_assets.bat
  1. Confirm this file was created:
zelda3_assets.dat

That is the file you need for Xbox.

2. Install Zelda3 UWP

  1. Open Xbox Dev Portal.
  2. Install the Zelda3 UWP .msixbundle.
  3. Launch the app once.
  4. Close the app.

Launching once lets the app create its config and storage folders.

3. Choose Storage Method

Zelda3 UWP supports:

  • External storage: E:/Zelda3/
  • Internal storage: LocalState/

External storage is preferred if present. If not found, the app falls back to LocalState.

External Storage Setup​

Create this folder:

E:/Zelda3/

Place your asset file here:

E:/Zelda3/zelda3_assets.dat

Recommended layout:

E:/Zelda3/
├─ zelda3_assets.dat
├─ zelda3.ini
├─ MSU/
├─ sprites-gfx/
└─ glsl-shaders/

Internal Storage Setup​

Use the app's Xbox Dev Mode LocalState folder.

Place your asset file here:

LocalState/zelda3_assets.dat

Recommended layout:

LocalState/
├─ zelda3_assets.dat
├─ zelda3.ini
├─ MSU/
├─ sprites-gfx/
└─ glsl-shaders/

Typical Xbox Dev Portal path:

Q:/Users/UserMgr0/AppData/Local/Packages/Zelda3/LocalState/

4. Configure Zelda3

The app creates zelda3.ini automatically if it is missing.

Edit the config in whichever storage location you are using:

E:/Zelda3/zelda3.ini

or:

LocalState/zelda3.ini

Aspect Ratio​

For original 4:3:

[General]
ExtendedAspectRatio = 4:3

[Graphics]
IgnoreAspectRatio = 0

For 16:9 widescreen:

[General]
ExtendedAspectRatio = 16:9

[Graphics]
IgnoreAspectRatio = 0

Keep IgnoreAspectRatio = 0 for normal behavior.

In widescreen mode, unrevealed side areas stay black until the camera exposes them. This matches the current PC build behavior.

5. MSU Audio

Enable MSU audio in zelda3.ini:

[Sound]
EnableMSU = true
MSUPath = MSU/

Place MSU files in:

E:/Zelda3/MSU/

or:

LocalState/MSU/

Supported examples:

alttp_msu-1.pcm
alttp_msu-2.pcm
alttp_msu-3.pcm

or:

1.pcm
2.pcm
3.pcm

OPUZ files are also supported:

alttp_msu-1.opuz
1.opuz

For PCM packs:

AudioFreq = 44100

For OPUZ packs:

AudioFreq = 48000

6. Custom Sprites

Custom .zspr Link sprites are supported.

Set this in zelda3.ini:

[Graphics]
LinkGraphics = sprites-gfx/your_sprite.zspr

Place sprites in:

E:/Zelda3/sprites-gfx/

or:

LocalState/sprites-gfx/

Custom sprites can be found here:

https://snesrev.github.io/sprites-gfx/snes/zelda3/link/

7. Shader Folder

The app may create:

glsl-shaders

External path:

E:/Zelda3/glsl-shaders/

Internal path:

LocalState/glsl-shaders/

GLSL shaders do not currently work on the normal Xbox UWP build because they depend on OpenGL shader support.

Troubleshooting

Game Does Not Start​

Check:

  • zelda3_assets.dat exists
  • The file is in E:/Zelda3/ or LocalState/
  • The asset file was generated from the correct US ROM
  • The ROM hash matched before extraction
  • The app was launched once before copying files

Widescreen Not Working​

Use:

[General]
ExtendedAspectRatio = 16:9

[Graphics]
IgnoreAspectRatio = 0

Also make sure you edited the active config:

E:/Zelda3/zelda3.ini

or:

LocalState/zelda3.ini

MSU Audio Not Working​

Check:

  • EnableMSU = true
  • MSUPath = MSU/
  • Files are inside E:/Zelda3/MSU/ or LocalState/MSU/
  • File names match a supported naming style
  • PCM uses AudioFreq = 44100
  • OPUZ uses AudioFreq = 48000

Custom Sprite Not Working​

Check:

  • The sprite is a valid .zspr file
  • The file is inside sprites-gfx
  • LinkGraphics points to the correct filename
  • You edited the active zelda3.ini

Contributor: MewLew