Getting Altirra Running on macOS Sequoia 15.x

A Wine Success Story

I’ve been wrestling with running Altirra, the gold standard Atari 8-bit emulator, on recent macOS versions with wine for over a year now. The issue cropped up in both Sonoma (14.x) and Sequoia (15.x), where I kept hitting a frustrating green screen problem. The emulator was running underneath – I could tell – but all I got was a solid green overlay. This worked fine with Crossover- but my subscription ran out and I didn’t feel like renewing it again.

Quick background: Wine (the free Windows emulation layer for Unix systems) is what makes this possible on macOS. If you’re running Apple Silicon, don’t worry – while Wine is primarily designed for Intel architecture, it runs great with Rosetta 2 doing all the heavy lifting behind the scenes.

I knew the commercial solution, Crossover (basically a paid Wine wrapper), worked fine – but at nearly $80 a year, I kept looking for a better way. The solution, it turns out, was right in front of me all along. Thanks to someone on the FujiNet Discord (Brad!), I learned that simply disabling the DirectX layer when launching Wine fixes everything.

Below, I’ll walk you through setting this up on a fresh macOS Sequoia install. By the end, you’ll have both the latest version of Altirra up and running with an emulated Atari, and FujiNet working as well on the Mac (using FujiNet-PC) – giving you a complete Atari development and testing environment right on your Mac.

TL;DR

Run Altirra with wine, disabling the direct X component!
bash
wine ~/Altirra-4.30/Altirra64.exe /gdi


Setup Instructions for Altirra on macOS

Prerequisites:
– macOS Sequoia (15.x) or earlier
– Homebrew package manager
– If using Apple Silicon (M1/M2/M3): Rosetta 2
– Feeling comfortable with the Terminal

Step-by-Step Setup:

1. Install Homebrew (if you haven’t already)
   Visit brew.sh and follow their installation instructions, or run:
   bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"


2. Install Rosetta 2
   bash
/usr/sbin/softwareupdate --install-rosetta --agree-to-license


3. Install Wine Development Version
   bash
brew install wine@devel


4. Download Altirra

5. Visit virtualdub.org/altirra

6. Download the latest x86 ZIP version (currently 4.30)

7. Extract to your Downloads folder (or preferred location)

8. Run Altirra with wine, disabling the direct X component!
   bash
wine ~/Downloads/Altirra-4.30/Altirra64.exe /gdi


First-Time Setup Note:

• When you first run Wine, macOS will block it
• Go to System Settings > Privacy & Security
• Look in the Security Section towards the bottom notification and click “Open Anyway”
• see below!
• Enter your admin password
• Click on Open Anyway if a pop-up asks you
• Return to Terminal and run the wine command again

The /gdi parameter is crucial here – it’s what prevents the green screen issue that’s been plaguing recent macOS versions.

Optional: Create a Launch Script

Create a file called run-altirra.sh:
bash
#!/bin/bash
wine ~/Downloads/Altirra-4.30/Altirra64.exe /gdi

Make it executable:
bash
chmod +x run-altirra.sh


Setting up Altirra

Configuring Altirra for FujiNet Use

Initial Altirra Setup:
1. First Launch
– When Altirra starts for the first time, it will run through a basic setup wizard
– Follow the prompts, but don’t worry too much about the initial settings – we’ll adjust the important ones later

1. ROM Configuration
2. Go to File > Settings > System
3. Under “ROM Set,” click “…” to browse
4. Navigate to your ROMs folder (this should be a folder you’ve already set up containing your legally obtained ROM files)
5. Once your ROMs are configured, Altirra will use these for system emulation

Looking for ROMs…

ROMS found!

1. Critical Setting Change
2. Go to File > Settings > System
3. Uncheck “Enable Fast Boot”
4. This step is essential for proper FujiNet operation

Ensure Fast Boot is disabled!

1. Installing the FujiNet Bridge Device
2. Visit github.com/FujiNetWIFI/fujinet-emulator-bridge
3. Download or clone the repository
4. Look for the custom device file (typically a .dll or binary file)
5. In Altirra, go to Device > Custom Device
6. Add the FujiNet bridge device from the location where you saved it
   – https://github.com/FujiNetWIFI/fujinet-emulator-bridge/blob/main/altirra-custom-device/netsio.atdevice
7. This bridge enables communication between Altirra and the FujiNet services running on your Mac

Add a custom Device

The NetSIO device to link to FujiNet-PC

Device Added!

The FujiNet bridge is what makes the magic happen – it allows your emulated Atari to communicate with FujiNet services just like real hardware would.

Setting Up FujiNet:

Once Altirra is running, you can enable FujiNet emulation by running both the FujiNet Emulation Bridge (python) and running the FujiNet-PC (which you have built from the repo, or downloaded my pre-built version (coming soon). This gives you access to disk images, printers, and network services, just like with real hardware.

Troubleshooting Tips:
– If you get a green screen, double-check you included the /gdi parameter
– For Apple Silicon Macs, make sure Rosetta 2 is properly installed
– If Altirra seems slow, check CPU usage in Activity Monitor

With this setup, you’ll have a fully functional Atari 8-bit development and testing environment on your Mac, including FujiNet capabilities for networking and peripheral emulation.