Skip to content

v1.1

Choose a tag to compare

View all tags
@github-actions github-actions released this 27 Sep 15:12
· 57 commits to main since this release
v1.1
7852ecd

v1.1, or: it turns out "it works on my machine" was the whole problem

v1.0 shipped. People could download it. Then I looked more closely at what I'd shipped, and it turned out v1.0 worked beautifully on exactly one kind of computer: the one GitHub built it on.

Things I'm confessing about v1.0

The Mac download needed macOS 26.6. Not 11, not 14, not even 26.0. 26.6. Homebrew's SDL3 and a default Zig build both quietly aim at whatever macOS the build machine runs, and GitHub's build machine runs the latest. If you tried v1.0 on a Mac that's a year old and it wouldn't open, it wasn't your Mac's fault. It was mine. v1.1 builds SDL3 itself and targets macOS 11, and CI now refuses to ship anything that asks for more.

Every binary was tuned to GitHub's CPU. With no target given, Zig builds for the exact processor it's running on, which on a cloud server means every instruction set extension Intel ever dreamed up. On an older PC that's a crash waiting to happen. v1.1 targets a baseline CPU everywhere, so it runs on your hardware and not just theirs.

The Linux build wanted the newest glibc around. It was built on Ubuntu 26.04, against the glibc and SDL3 that come with it, so it needed something about that new. Linux users running the stable release their distro recommends deserved better.

What's actually new

macOS gets a real app. No more folder of loose binaries and a dylib you shouldn't touch. It's alttp-zig.app, with the triforce icon, and you drag it to Applications like a civilised person. SDL3 lives inside it. It still isn't notarised, because I still haven't given Apple $99, so the first launch still needs the quarantine dance (below).

Linux gets an AppImage. One file. Mark it executable, run it. SDL3 is inside, built on Ubuntu 22.04 so it only asks for glibc 2.35, and it picks X11 or Wayland and PulseAudio, PipeWire or ALSA at run time, whatever your desktop happens to be running. Arch users are welcome to build it from source instead. They will anyway.

Your files moved, on those two. An app bundle and an AppImage are both read-only from the inside, and the game's whole deal was writing its settings, assets and saves next to itself. So when the launcher notices it's running from one, it uses a proper per-user folder instead:

  • macOS: ~/Library/Application Support/alttp-zig
  • Linux: ~/.local/share/alttp-zig

That's where zelda3.ini, zelda3_assets.dat and your saves live now, and where an MSU pack goes. Coming from v1.0? Copy your saves folder and zelda3.ini across and you're set. Windows is unchanged and keeps everything in its own folder, because Windows has never once stopped a program writing wherever it likes.

Behind the scenes, where the jokes write themselves

Building SDL3 for macOS 11 meant telling Zig which macOS to build for, and once you do that, Zig stops assuming it's building for the Mac it's running on, and forgets where the Mac SDK is. So it couldn't find OpenGL. On a Mac. Then the Mac binaries turned out to have no room in their headers to point at the SDL3 inside the bundle, because the new library path was 10 characters longer than the old one. Ten. Fixed with a linker flag whose name reads like a sentence: headerpad_max_install_names.

The packaging now builds on every change that touches it, so the next surprise shows up in CI instead of in your Downloads folder.

Getting it running

  1. Download the file for your system.
  2. macOS (Apple Silicon, macOS 11+): unzip, move alttp-zig.app to Applications, then run xattr -dr com.apple.quarantine /Applications/alttp-zig.app once, or allow it under System Settings → Privacy & Security after the first blocked launch.
  3. Linux (x86_64, glibc 2.35+): chmod +x alttp-zig-v1.1-x86_64.AppImage and run it. If it complains about FUSE, install libfuse2 or fuse3, or run it with --appimage-extract-and-run.
  4. Windows (x86_64): unzip anywhere and run zelda3-launcher.exe. SmartScreen will still be dramatic about it. "More info", then "Run anyway".
  5. Give the launcher your US ROM when it asks, press Launch, and the first run builds the assets.

No game data included, as ever. Bring your own ROM.

If it breaks, open an issue. And if it breaks on a computer older than GitHub's, I'd especially like to hear about it.

Assets 5
Loading