Skip to content

feat(AmpleWin/AmpleLinux): update MAME downloader & rom_manager to v0.289 #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ksherlock merged 7 commits into from
Aug 8, 2026
Merged

feat(AmpleWin/AmpleLinux): update MAME downloader & rom_manager to v0.289 #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
00f910b
Fix slot persistence logic (AmpleWin/Linux) for upstream PR preparati…
anomixer May 11, 2026
a56b65c
Fix: Explicitly pass empty string arguments for disabled slots (None)…
anomixer May 18, 2026
6c97cef
Merge remote-tracking branch 'upstream/master'
anomixer Jun 4, 2026
8cac6ed
feat(core): update MAME to 0.288, fix compatibility bugs, add PowerBo…
anomixer Jun 4, 2026
f4044d5
Merge remote-tracking branch 'upstream/master'
anomixer Jun 5, 2026
5459bd5
Merge remote-tracking branch 'upstream/master'
anomixer Aug 2, 2026
f5a33e9
feat(AmpleWin/AmpleLinux): update MAME to 0.289, remove PowerBook EAS…
anomixer Aug 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
407 changes: 222 additions & 185 deletions AmpleLinux/Agent.md
View file
Open in desktop

Large diffs are not rendered by default.

253 changes: 128 additions & 125 deletions AmpleLinux/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,125 +1,128 @@
# AmpleLinux - Linux Port (Legacy Apple Emulator Frontend)

[English](README.md) | [繁體中文](README_tw.md)

This is a port of the macOS native [Ample](https://github.com/ksherlock/ample) project to the Linux platform, based on the [AmpleWin](../AmpleWin/) Windows Port.

![](screenshot.png)

> [!IMPORTANT]
> **Current Version Support**: Updated to stay in sync with the latest version of Ample (macOS) resources and also MAME latest binary.

## 🍎 Ample (macOS) vs. AmpleLinux (Linux) Comparison

| Feature | Ample (macOS Native) | AmpleLinux (Linux) | Notes |
| :--- | :--- | :--- | :--- |
| **Language** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | Independent development, **zero changes to Mac source code** |
| **Installation** | .dmg Image / Homebrew | **Portable (+ .sh Auto-Config)** | One-click setup via `AmpleLinux.sh` |
| **MAME Integration** | Built-in Custom Core | **System-installed MAME** | Uses `mame` from your package manager (apt, dnf, pacman, etc.) |
| **UI** | Native macOS Components | **1:1 Pixel-Perfect QSS Replica** | With **Adaptive Light/Dark Theme** support (GNOME/KDE) |
| **Machine Selection** | Supports Default Bookmark | **Full Session Persistence (Auto-Load)** | Auto-loads last used machine state |
| **Software List Perf** | Synchronous Loading | **Deferred Loading** | Instant machine switching |
| **ROM Download** | Supports Auto-Download | **High-Speed Failover Engine** | Multi-server failover (callapple + mdk.cab) |
| **Video Support** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan** | Leveraging MAME's cross-platform rendering |

## 🌟 Key Features

### 🍏 Faithful Mac Experience (Feature Parity)
* **Visual Precision**: Precision support for **Window 1x-4x** modes with machine-specific aspect ratio heuristics.
* **Software Library**: Smart filtering, search overlay, and compatibility checking.
* **Advanced Slot Emulation**: Full support for nested sub-slots (e.g. SCSI cards) with robust default device initialization and persistence for "None" selections.
* **ROM Management**: Real-time search, multi-server failover download, extended library.
* **Compatibility Fallback**: Automatically detects affected Macintosh PowerBook models (`macpb160` etc.) that suffer from the MAME 0.288 EASC crash bug. Seamlessly switches to a local MAME 0.287 (`mame_0287`) or VGM Mod (`mame-vgm`) if available, or guides users to the MAME SDL Supported Platforms Wiki page to retrieve older packages.
* **Shared Directory**: Full parity with `-share_directory` argument.

### 🐧 Linux-Specific Features
* **System MAME Integration**: Auto-detects MAME from `PATH`, `/usr/bin/mame`, `/usr/games/mame`, etc.
* **Adaptive Theme**: Detects GNOME (`gsettings`) and KDE dark/light mode in real-time.
* **Native File Management**: Uses `xdg-open` for file/folder/URL opening.
* **No External Dependencies**: MAME is installed via your distribution's package manager.

### ⚠️ Known Limitations
* **VGM Mod**: The "Generate VGM" feature is currently disabled on Linux because the required MAME VGM Mod binary is only available for Windows.


## 🛠️ Quick Start

### Prerequisites
- **Python 3.9+**
- **MAME** installed via your package manager
- **PySide6** and **requests** (installed via system packages or pip)

### Installation

1. **Install System Dependencies**:
* **MAME**: Install via your package manager (e.g., `sudo apt install mame`).
* **Python 3**: Ensure Python 3.9+ is installed (`sudo apt install python3-full`).
* **X11 Support**: Required for GUI (`sudo apt install libxcb-cursor0`).

2. **Launch Ample**:
```bash
cd AmpleLinux
chmod +x AmpleLinux.sh
./AmpleLinux.sh
```
The script will **automatically** create a virtual environment (`.venv`), install `PySide6` and other dependencies via pip, and launch the app. **No manual pip install required.**

3. **Fast Deployment**:
* **Ubuntu Users**: If MAME is not found, the app will offer to install it via `snap`.
* Click **🎮 ROMs** to download system firmware.
* Go to **⚙️ Settings** to verify MAME is detected.
* Select a machine and **Launch MAME**!

## 📦 Building for Release

To create a standalone Linux binary (ELF) that requires no dependencies:

```bash
cd AmpleLinux
chmod +x build_elf.sh
./build_elf.sh
```

This script uses `PyInstaller` within a temporary venv to build a portable binary.

### 4. Desktop Integration (Icon Fix)

To see the correct icon in your Dock/Taskbar, copy the generated `.desktop` file:

```bash
mkdir -p ~/.local/share/applications/
cp dist/AmpleLinux/AmpleLinux.desktop ~/.local/share/applications/
```

Then search for "**AmpleLinux**" in your applications menu.

## 📂 Project Structure

| File/Directory | Description |
| :--- | :--- |
| **`AmpleLinux.sh`** | **Start Here**. Auto-setup script (uses venv + pip). |
| **`build_elf.sh`** | **Build Script**. Creates standalone binary via PyInstaller. |
| `make_icon.py` | Helper to generate Linux PNG icons from source. |
| `main.py` | Application entry point, UI rendering, and event loop. |
| `data_manager.py` | Parser for `.plist` machine definitions and MAME `.xml` software lists. |
| `mame_launcher.py` | Command-line builder and process manager. |
| `rom_manager.py` | Management and multi-threaded downloading of system ROMs. |
| `mame_downloader.py` | VGM Mod downloader (Windows only; unused on Linux). |

## 🔧 Troubleshooting

### MAME Not Detected
If the app can't find MAME:
1. **Ubuntu**: The app will offer to run `sudo snap install mame`.
2. **Manual**: Go to **⚙️ Settings** > **Select MAME...** to browse to the binary.
3. **PATH**: Verify `which mame` returns a path.
4. Common paths: `/usr/bin/mame`, `/usr/games/mame`, `/var/lib/snapd/snap/bin/mame`

### Theme Detection
The app auto-detects GNOME and KDE dark/light themes. If your desktop environment isn't supported, the app defaults to the Qt palette for theme detection.

## 📝 Acknowledgments

* Original macOS version developer: [Kelvin Sherlock](https://github.com/ksherlock)
* **Windows Port Developers: anomixer + Antigravity**
* **Linux Port**: Adapted from AmpleWin by anomixer + Antigravity
# AmpleLinux - Linux Port (Legacy Apple Emulator Frontend)

[English](README.md) | [繁體中文](README_tw.md)

This is a port of the macOS native [Ample](https://github.com/ksherlock/ample) project to the Linux platform, based on the [AmpleWin](../AmpleWin/) Windows Port.

![](screenshot.png)

> [!IMPORTANT]
> **Current Version Support**: Updated to stay in sync with the latest version of Ample (macOS) resources and also MAME latest binary.

## 🍎 Ample (macOS) vs. AmpleLinux (Linux) Comparison

| Feature | Ample (macOS Native) | AmpleLinux (Linux) | Notes |
| :--- | :--- | :--- | :--- |
| **Language** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | Independent development, **zero changes to Mac source code** |
| **Installation** | .dmg Image / Homebrew | **Portable (+ .sh Auto-Config)** | One-click setup via `AmpleLinux.sh` |
| **MAME Integration** | Built-in Custom Core | **System-installed MAME** | Uses `mame` from your package manager (apt, dnf, pacman, etc.) |
| **UI** | Native macOS Components | **1:1 Pixel-Perfect QSS Replica** | With **Adaptive Light/Dark Theme** support (GNOME/KDE) |
| **Machine Selection** | Supports Default Bookmark | **Full Session Persistence (Auto-Load)** | Auto-loads last used machine state |
| **Software List Perf** | Synchronous Loading | **Deferred Loading** | Instant machine switching |
| **ROM Download** | Supports Auto-Download | **High-Speed Failover Engine** | Multi-server failover (callapple + mdk.cab) |
| **Video Support** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan** | Leveraging MAME's cross-platform rendering |

## 🌟 Key Features

### 🍏 Faithful Mac Experience (Feature Parity)
* **Visual Precision**: Precision support for **Window 1x-4x** modes with machine-specific aspect ratio heuristics.
* **Software Library**: Smart filtering, search overlay, and compatibility checking.
* **Advanced Slot Emulation**: Full support for nested sub-slots (e.g. SCSI cards) with robust default device initialization and persistence for "None" selections.
* **ROM Management**: Real-time search, CallApple primary / MDK failover downloads, `dragon32` auto-patching, and full Laser 128 series library compatibility.
* **Full Native Compatibility**: Upstream MAME 0.289 resolved the EASC audio chip crash bug on Macintosh PowerBook models (`macpb160`, `macpb180`, etc.), enabling seamless native launch across all PowerBook systems.
* **Shared Directory**: Full parity with `-share_directory` argument.

### 🐧 Linux-Specific Features
* **System MAME Integration**: Auto-detects MAME from `PATH`, `/usr/bin/mame`, `/usr/games/mame`, etc.
* **Adaptive Theme**: Detects GNOME (`gsettings`) and KDE dark/light mode in real-time.
* **Native File Management**: Uses `xdg-open` for file/folder/URL opening.
* **No External Dependencies**: MAME is installed via your distribution's package manager.

### ⚠️ Known Limitations
* **VGM Mod**: The "Generate VGM" feature is currently disabled on Linux because the required MAME VGM Mod binary is only available for Windows.


## 🛠️ Quick Start

### Prerequisites
- **Python 3.9+**
- **MAME** installed via your package manager
- **PySide6** and **requests** (installed via system packages or pip)

### Installation

1. **Install System Dependencies**:
* **MAME**: Install via your package manager (e.g., `sudo apt install mame`).
* **Python 3**: Ensure Python 3.9+ is installed (`sudo apt install python3-full`).
* **X11 Support**: Required for GUI (`sudo apt install libxcb-cursor0`).

2. **Launch Ample**:
```bash
cd AmpleLinux
chmod +x AmpleLinux.sh
./AmpleLinux.sh
```
The script will **automatically** create a virtual environment (`.venv`), install `PySide6` and other dependencies via pip, and launch the app. **No manual pip install required.**

3. **Fast Deployment**:
* **Ubuntu Users**: If MAME is not found, the app will offer to install it via `snap`.
* Click **🎮 ROMs** to download system firmware.
* Go to **⚙️ Settings** to verify MAME is detected.
* Select a machine and **Launch MAME**!

## 📦 Building for Release

To create a standalone Linux binary (ELF) that requires no dependencies:

```bash
cd AmpleLinux
chmod +x build_elf.sh
./build_elf.sh
```

This script uses `PyInstaller` within a temporary venv to build a portable binary.

### 4. Desktop Integration (Icon Fix)

To see the correct icon in your Dock/Taskbar, copy the generated `.desktop` file:

```bash
mkdir -p ~/.local/share/applications/
cp dist/AmpleLinux/AmpleLinux.desktop ~/.local/share/applications/
```

Then search for "**AmpleLinux**" in your applications menu.

## 📂 Project Structure

| File/Directory | Description |
| :--- | :--- |
| **`AmpleLinux.sh`** | **Start Here**. Auto-setup script (uses venv + pip). |
| **`build_elf.sh`** | **Build Script**. Creates standalone binary via PyInstaller. |
| `make_icon.py` | Helper to generate Linux PNG icons from source. |
| `main.py` | Application entry point, UI rendering, and event loop. |
| `data_manager.py` | Parser for `.plist` machine definitions and MAME `.xml` software lists. |
| `mame_launcher.py` | Command-line builder and process manager. |
| `rom_manager.py` | Management and multi-threaded downloading of system ROMs. |
| `mame_downloader.py` | VGM Mod downloader (Windows only; unused on Linux). |

## 🔧 Troubleshooting

### MAME Not Detected
If the app can't find MAME:
1. **Ubuntu**: The app will offer to run `sudo snap install mame`.
2. **Manual**: Go to **⚙️ Settings** > **Select MAME...** to browse to the binary.
3. **PATH**: Verify `which mame` returns a path.
4. Common paths: `/usr/bin/mame`, `/usr/games/mame`, `/var/lib/snapd/snap/bin/mame`

### Theme Detection
The app auto-detects GNOME and KDE dark/light themes. If your desktop environment isn't supported, the app defaults to the Qt palette for theme detection.

## 📝 Acknowledgments

* Original macOS version developer: [Kelvin Sherlock](https://github.com/ksherlock)
* **Windows Port Developers: anomixer + Antigravity**
* **Linux Port**: Adapted from AmpleWin by anomixer + Antigravity

---
*Disclaimer: AmpleLinux is an independent open-source project and is not affiliated with, authorized, maintained, or endorsed by Apple Inc. or any other respective companies mentioned. All product and company names are trademarks™ or registered® trademarks of their respective holders.*
Loading
Loading