diff --git a/AmpleLinux/Agent.md b/AmpleLinux/Agent.md index b8453c6..79017c9 100644 --- a/AmpleLinux/Agent.md +++ b/AmpleLinux/Agent.md @@ -1,185 +1,222 @@ -# Agent Task Audit Log - Ample Linux Port - -## 📅 Session: 2026-06-05 (Session 6) - -### 🎯 Objective: PowerBook Compatibility Fallback & Downloader Parity -Addressed upstream MAME 0.288 C++ late-binding bug causing crashes on EASC audio chip Macs, and aligned the fallback interface with AmpleWin. - -### ✅ Key Achievements: -1. **Simplified Fallback Redirection**: - * Aligned the crash warning interface with AmpleWin for affected PowerBooks (`macpb160` etc.). - * Added a "Download Fallback (v0.287)" button that redirects users to the official MAME SDL Supported Platforms Wiki to download older MAME releases for their specific Linux distribution. - * Maintains seamless redirection to `mame_0287` or `mame-vgm` if already configured in the local directory. -2. **ROM Manager Priority Update**: - * Reordered ROM download servers to prioritize `mdk.cab`, solving missing ROM zip structure bugs (such as `dragon32`) when running on modern MAME 0.288+. -3. **Downloader Optimization**: - * Added `mirror.ghproxy.com` proxy support to VGM Mod mirrors for accelerated downloads on Linux systems. - ---- - -## 📅 Session: 2026-05-19 (Session 5) - -### 🎯 Objective: Complete Slot Configuration Persistence (MAME Command Line) -Synchronized command line argument logic with AmpleWin to ensure "None" slots are explicitly disabled in MAME. - -### ✅ Key Achievements: -1. **Command-Line Slot Persistence**: - * Modified `build_args` in `mame_launcher.py` to allow empty string values (e.g. `option is not None` instead of `if option:`). - * This ensures that `-[slot_name] ""` is explicitly passed on the command line, preventing MAME from falling back to its internal defaults. -2. **Cross-Platform Parity**: Ensured consistent behavior with Windows and Web ports. - ---- - -## 📅 Session: 2026-05-11 (Session 4) - -### 🎯 Objective: Slot Configuration Consistency Fix -Synchronized slot initialization logic with AmpleWin to fix "None" persistence issue. - -### ✅ Key Achievements: -1. **"None-Aware" Slot Initialization**: - * Applied the `slot_name not in self.current_slots` fix to `main.py`. -2. **Cross-Platform Consistency**: Ensured Linux port shares the improved slot behavior. - ---- - -## 📅 Session: 2026-03-02 (Session 3) - -### 🎯 Objective: Upstream Version Tracking & Documentation Maintenance -Focused on updating the Linux port documentation to track MAME 0.286 and simplifying maintainability. - -### ✅ Key Achievements: -1. **Documentation Refactoring**: - * Renamed version-specific screenshot files (e.g. `screenshot-v0.28x.png` to `screenshot.png`). - * Updated `README.md` and `README_tw.md` to use generic "latest version" terminology to prevent the need for manual text updates upon future Ample/MAME releases. - -### 🚀 Current Project Status -The Linux Port documentation is updated for MAME 0.286 and future-proofed against minor version increments. - ---- - -## 📅 Session: 2026-02-17 (Session 2) - -### 🎯 Objective: Real-World Testing & Deployment Fix -Deployed the Linux Port to an actual Linux machine for testing. Identified and fixed a critical dependency installation issue. - -### ✅ Key Achievements: - -1. **Launcher Script Fix (`AmpleLinux.sh`)**: - * **Bug**: Original script used `pip3` / `pip` commands directly, which don't exist on many modern Linux distros (Debian 12+, Ubuntu 23+, Fedora 38+ enforce PEP 668). - * **Fix v1**: Changed to `python3 -m pip` (the universally reliable pip invocation). - * **Fix v2**: Added automatic `--break-system-packages` fallback for PEP 668-compliant systems. - * **Error Messages**: Added distro-specific guidance (apt/dnf/pacman) and venv instructions in error output. - -2. **Git Workflow**: - * Created `linux` branch from `master`. - * Pushed to `origin/linux` for cross-machine testing. - -### 🔍 Testing Observations (Real Linux Machine): -* `pip3` command was not in PATH → first fallback triggered. -* `python3 -m pip` also failed (PEP 668 system Python restriction) → second fallback triggered with `--break-system-packages`. -* **Conclusion**: Many modern Linux distros require either system packages (`sudo apt install python3-pyside6 python3-requests`) or a venv approach. The launcher script now documents both paths clearly. - -### ⚠️ Known Issue - Pending Resolution: -* Systems without any pip module need manual package installation first. The script provides clear guidance but cannot auto-resolve this without `sudo`. -* **Recommended solutions** (in priority order): - 1. System packages: `sudo apt install python3-pyside6 python3-requests` - 2. Install pip: `sudo apt install python3-pip`, then re-run script - 3. Use venv: `python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt && python3 main.py` - -### 🚀 Current Project Status -Codebase is ported and pushed to `linux` branch. Launcher script has been hardened for modern Linux distros. Awaiting successful end-to-end test with dependencies installed. - ---- - -## 📅 Session: 2026-02-16 (Session 1) - -### 🎯 Objective: Linux Port Creation -Ported AmpleWin (Windows) to Linux, following the original author's suggestion (ksherlock/ample#45) that Linux support would be easy to add. - -### ✅ Key Achievements: - -1. **Codebase Porting (from AmpleWin)**: - * **Zero-Modification Files**: `data_manager.py`, `rom_manager.py`, `mame_launcher.py`, `requirements.txt` — copied directly, no changes needed. - * **Simplified `mame_downloader.py`**: Removed `MameDownloadWorker` entirely (Linux users install MAME via their package manager). Kept `VgmModDownloadWorker` with Linux adaptations (7z via PATH, no `.exe` suffix, helpful `p7zip` install instructions). - * **`main.py` (~20 changes)**: Comprehensive platform adaptation: - - Replaced `winreg` theme detection with `gsettings` (GNOME 42+ `color-scheme`) and KDE (`kdeglobals`) dark mode detection. - - Replaced all `os.startfile()` calls with `xdg-open` via a helper function `_xdg_open()`. - - Removed all `.exe` suffixes from MAME binary references (`mame.exe` → `mame`, `mame-vgm.exe` → `mame-vgm`). - - Enhanced `check_for_mame()` to search system paths (`/usr/bin/mame`, `/usr/games/mame`, `/usr/local/bin/mame`) and use `which mame`. - - Replaced `Download MAME` button with package manager guidance text. - - Updated `shlex.split()` from `posix=False` (Windows) to `posix=True` (Linux). - - Updated file browser filter from `*.exe` to `All Files (*)`. - - Changed window title and help URL. - -2. **Launcher Script**: - * Created `AmpleLinux.sh` as equivalent of `AmpleWin.bat`. - * Includes Python 3 detection, pip dependency installation, and helpful error messages with distro-specific commands. - -3. **Documentation**: - * Created dual-language READMEs (`README.md` English, `README_tw.md` Traditional Chinese). - * Includes installation guide for all major distros (Ubuntu, Fedora, Arch, Flatpak). - * Troubleshooting section for PySide6, MAME detection, and theme issues. - -### 🔍 Design Decisions: - -1. **Separate Directory (not shared codebase)**: Chose to create `AmpleLinux/` as a separate directory rather than refactoring `AmpleWin/` into a shared codebase. This maintains the project convention where each platform gets its own additive subdirectory, minimizing risk to the stable Windows port. - -2. **No MAME Auto-Download**: Following the original author's guidance ("let the user download it themselves"), Linux users install MAME via their system package manager. This is the Linux cultural norm and avoids complex binary distribution issues. - -3. **GNOME + KDE Theme Detection**: Implemented multi-strategy dark mode detection covering GNOME 42+ `color-scheme`, older GNOME `gtk-theme`, and KDE `kdeglobals`, with Qt palette as ultimate fallback. - -### 🚀 Current Project Status -The Linux Port is functionally complete. All Windows-specific code has been adapted, and the application should work on major Linux distributions with GNOME or KDE desktops. - ---- - -## Handover Notes for Future Agents - -### 1. Platform Differences from AmpleWin -* **No `winreg`**: Theme detection uses `gsettings` and KDE config file parsing. -* **No `os.startfile()`**: Uses `xdg-open` via the `_xdg_open()` helper function. -* **No `.exe` suffixes**: All binary references use bare names (`mame`, `mame-vgm`). -* **No MAME auto-download**: Users install via package manager. Settings dialog shows guidance. -* **`shlex.split(posix=True)`**: Linux uses POSIX-mode shell parsing (no special Windows path handling). -* **MAME detection**: Checks `PATH` via `which`, plus standard Linux paths (`/usr/bin`, `/usr/games`, `/usr/local/bin`). - -### 2. Deployment (CRITICAL) -* **PEP 668 Era**: Modern Linux distros (Debian 12+, Ubuntu 23.04+, Fedora 38+) block global pip installs. The launcher script handles this with `--break-system-packages` fallback. -* **Recommended Install Methods** (in priority order): - 1. System packages: `sudo apt install python3-pyside6 python3-requests mame` - 2. venv: `python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt` - 3. pip with override: `python3 -m pip install -r requirements.txt --break-system-packages` -* **Never use `pip3` or `pip` directly** in scripts — always use `python3 -m pip` for reliability. - -### 3. Known Mantras (inherited from AmpleWin) -* **Visual Parity is King**: Every margin, font size, and color was cross-referenced with macOS. -* **Authorship**: This Linux Port is based on the AmpleWin collaboration between **anomixer** and **Antigravity**. - ---- - -## 📅 Session: 2026-02-17 (Session 2) - -### 🎯 Objective: First-Run Experience, Build System & Polish - -### ✅ Key Changes: - -1. **Launcher Architecture (`AmpleLinux.sh`)**: - * **Refactored to venv**: Switched from system-level `apt` dependencies to a strictly isolated `python3 -m venv` approach. - * **Automated Setup**: Script now auto-creates `.venv`, installs `python3-venv` (if missing), and pip installs `requirements.txt`. - * **Distro Agnostic**: Only depends on `python3-full` and `libxcb-cursor*` (apt) for the base interpreter; all libraries (PySide6) are pulled via pip. - * **ALSA Fix**: Added auto-detection of `/proc/asound` and `usermod -a -G audio` fix for permission issues. - -2. **User Experience Enhancements (`main.py`)**: - * **Ubuntu Snap Integration**: If MAME is missing on Ubuntu, offers `sudo snap install mame` with a non-blocking `QProgressDialog`. - * **Configuration Fix**: `ensure_mame_ini` now runs `mame -cc` inside `AmpleLinux/mame` to keep config portable. - * **Path Precision**: `update_command_line` now resolves absolute paths for `-inipath` and `-rompath` (e.g., `/home/user/...`). - * **BGFX Cleanup**: Removed Windows-only Direct3D options. - * **UI Polish**: "Generate VGM" now shows a "Feature not implemented" popup. - -3. **Build System (New)**: - * **`make_icon.py`**: Created Linux-specific icon generator (produces standard PNG sizes: 16x16 to 512x512). - * **`build_elf.sh`**: Created PyInstaller build script that uses a temporary venv to bypass PEP 668 restrictions and produce a standalone ELF binary in `dist/`. - -### 🔍 Technical Decisions: -* **PySide6 via pip**: Moved away from `python3-pyside2` (apt) because the codebase is written for PySide6. Using venv + pip ensures version consistency and avoids the "externally-managed-environment" error on modern distros. -* **MAME Snap**: For Ubuntu users, Snap is the most reliable way to get a recent MAME version without PPA complexity. +# Agent Task Audit Log - Ample Linux Port + +## 📅 Session: 2026-08-02 (Session 7) + +### 🎯 Objective: Upstream MAME v0.289 Synchronization +Synchronized AmpleLinux with upstream `ksherlock/ample` v0.289 release and updated machine `.plist` configuration definitions. + +### ✅ Key Achievements: +1. **PowerBook Native Launch (EASC Bug Fixed)**: + * Removed `macpb160`, `macpb165`, `macpb165c`, `macpb180`, `macpb180c` fallback prompt mechanism in `main.py`, as MAME 0.289 officially resolved the EASC audio chip crash bug. +2. **ROM Manager Priority & Dragon32/Laser Series Fixes**: + * Reordered download servers in `rom_manager.py` to prioritize CallApple (`https://www.callapple.org/roms/`) with MDK (`https://mdk.cab/download/split/`) as backup failover. + * Integrated `patch_dragon32()` in `DownloadWorker` to auto-merge missing modern MAME 0.289 split ROM files (`dragon_data_ltd_1-0.ic18`, `dragon_data_ltd_1-1.ic17`) when downloading `dragon32.zip`. + * Expanded `custom_roms` fallback array to include Laser 128 series (`las128ex`, `las128e2`, `laser128`, `laser128o`, `laser2c`), ensuring seamless auto-download even if omitted from upstream `roms.plist`. +3. **Upstream MAME 0.289 Alignment**: + * Verified `.plist` machine profile definitions (251 files) updated to MAME 0.289. + * Validated compatibility with local MAME 0.289 binaries and slot options. + +--- + +## 📅 Session: 2026-06-05 (Session 6) + +### 🎯 Objective: PowerBook Compatibility Fallback & Downloader Parity +Addressed upstream MAME 0.288 C++ late-binding bug causing crashes on EASC audio chip Macs, and aligned the fallback interface with AmpleWin. + +### ✅ Key Achievements: +1. **Simplified Fallback Redirection**: + * Aligned the crash warning interface with AmpleWin for affected PowerBooks (`macpb160` etc.). + * Added a "Download Fallback (v0.287)" button that redirects users to the official MAME SDL Supported Platforms Wiki to download older MAME releases for their specific Linux distribution. + * Maintains seamless redirection to `mame_0287` or `mame-vgm` if already configured in the local directory. +2. **ROM Manager Priority Update**: + * Reordered ROM download servers to prioritize `mdk.cab`, solving missing ROM zip structure bugs (such as `dragon32`) when running on modern MAME 0.288+. +3. **Downloader Optimization**: + * Added `mirror.ghproxy.com` proxy support to VGM Mod mirrors for accelerated downloads on Linux systems. + +--- + +## 📅 Session: 2026-05-19 (Session 5) + +### 🎯 Objective: Complete Slot Configuration Persistence (MAME Command Line) +Synchronized command line argument logic with AmpleWin to ensure "None" slots are explicitly disabled in MAME. + +### ✅ Key Achievements: +1. **Command-Line Slot Persistence**: + * Modified `build_args` in `mame_launcher.py` to allow empty string values (e.g. `option is not None` instead of `if option:`). + * This ensures that `-[slot_name] ""` is explicitly passed on the command line, preventing MAME from falling back to its internal defaults. +2. **Cross-Platform Parity**: Ensured consistent behavior with Windows and Web ports. + +--- + +## 📅 Session: 2026-05-11 (Session 4) + +### 🎯 Objective: Slot Configuration Consistency Fix +Synchronized slot initialization logic with AmpleWin to fix "None" persistence issue. + +### ✅ Key Achievements: +1. **"None-Aware" Slot Initialization**: + * Applied the `slot_name not in self.current_slots` fix to `main.py`. +2. **Cross-Platform Consistency**: Ensured Linux port shares the improved slot behavior. + +--- + +## 📅 Session: 2026-05-11 (Session 4) + +### 🎯 Objective: Slot Configuration Alignment & Bug Fix +Synchronized slot initialization logic with AmpleWin to fix the issue where "None" selections were being overwritten by defaults. + +### ✅ Key Achievements: +1. **"None-Aware" Slot Initialization**: + * Applied the `slot_name not in self.current_slots` fix to `main.py`. + * Ensured that manual "None" selections (empty string) are preserved across UI refreshes. +2. **Cross-Platform Feature Parity**: + * Aligned slot behavior with the Windows and Web ports. +3. **Stability**: + * Verified that nested slot defaults still load correctly for new cards. + +### 🚀 Current Project Status +The Linux port now shares the same robust slot configuration logic as the Windows version, ensuring a consistent user experience. + +--- + +## 📅 Session: 2026-03-02 (Session 3) + +### 🎯 Objective: Upstream Version Tracking & Documentation Maintenance +Focused on updating the Linux port documentation to track MAME 0.286 and simplifying maintainability. + +### ✅ Key Achievements: +1. **Documentation Refactoring**: + * Renamed version-specific screenshot files (e.g. `screenshot-v0.28x.png` to `screenshot.png`). + * Updated `README.md` and `README_tw.md` to use generic "latest version" terminology to prevent the need for manual text updates upon future Ample/MAME releases. + +### 🚀 Current Project Status +The Linux Port documentation is updated for MAME 0.286 and future-proofed against minor version increments. + +--- + +## 📅 Session: 2026-02-17 (Session 2) + +### 🎯 Objective: Real-World Testing & Deployment Fix +Deployed the Linux Port to an actual Linux machine for testing. Identified and fixed a critical dependency installation issue. + +### ✅ Key Achievements: + +1. **Launcher Script Fix (`AmpleLinux.sh`)**: + * **Bug**: Original script used `pip3` / `pip` commands directly, which don't exist on many modern Linux distros (Debian 12+, Ubuntu 23+, Fedora 38+ enforce PEP 668). + * **Fix v1**: Changed to `python3 -m pip` (the universally reliable pip invocation). + * **Fix v2**: Added automatic `--break-system-packages` fallback for PEP 668-compliant systems. + * **Error Messages**: Added distro-specific guidance (apt/dnf/pacman) and venv instructions in error output. + +2. **Git Workflow**: + * Created `linux` branch from `master`. + * Pushed to `origin/linux` for cross-machine testing. + +### 🔍 Testing Observations (Real Linux Machine): +* `pip3` command was not in PATH → first fallback triggered. +* `python3 -m pip` also failed (PEP 668 system Python restriction) → second fallback triggered with `--break-system-packages`. +* **Conclusion**: Many modern Linux distros require either system packages (`sudo apt install python3-pyside6 python3-requests`) or a venv approach. The launcher script now documents both paths clearly. + +### ⚠️ Known Issue - Pending Resolution: +* Systems without any pip module need manual package installation first. The script provides clear guidance but cannot auto-resolve this without `sudo`. +* **Recommended solutions** (in priority order): + 1. System packages: `sudo apt install python3-pyside6 python3-requests` + 2. Install pip: `sudo apt install python3-pip`, then re-run script + 3. Use venv: `python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt && python3 main.py` + +### 🚀 Current Project Status +Codebase is ported and pushed to `linux` branch. Launcher script has been hardened for modern Linux distros. Awaiting successful end-to-end test with dependencies installed. + +--- + +## 📅 Session: 2026-02-16 (Session 1) + +### 🎯 Objective: Linux Port Creation +Ported AmpleWin (Windows) to Linux, following the original author's suggestion (ksherlock/ample#45) that Linux support would be easy to add. + +### ✅ Key Achievements: + +1. **Codebase Porting (from AmpleWin)**: + * **Zero-Modification Files**: `data_manager.py`, `rom_manager.py`, `mame_launcher.py`, `requirements.txt` — copied directly, no changes needed. + * **Simplified `mame_downloader.py`**: Removed `MameDownloadWorker` entirely (Linux users install MAME via their package manager). Kept `VgmModDownloadWorker` with Linux adaptations (7z via PATH, no `.exe` suffix, helpful `p7zip` install instructions). + * **`main.py` (~20 changes)**: Comprehensive platform adaptation: + - Replaced `winreg` theme detection with `gsettings` (GNOME 42+ `color-scheme`) and KDE (`kdeglobals`) dark mode detection. + - Replaced all `os.startfile()` calls with `xdg-open` via a helper function `_xdg_open()`. + - Removed all `.exe` suffixes from MAME binary references (`mame.exe` → `mame`, `mame-vgm.exe` → `mame-vgm`). + - Enhanced `check_for_mame()` to search system paths (`/usr/bin/mame`, `/usr/games/mame`, `/usr/local/bin/mame`) and use `which mame`. + - Replaced `Download MAME` button with package manager guidance text. + - Updated `shlex.split()` from `posix=False` (Windows) to `posix=True` (Linux). + - Updated file browser filter from `*.exe` to `All Files (*)`. + - Changed window title and help URL. + +2. **Launcher Script**: + * Created `AmpleLinux.sh` as equivalent of `AmpleWin.bat`. + * Includes Python 3 detection, pip dependency installation, and helpful error messages with distro-specific commands. + +3. **Documentation**: + * Created dual-language READMEs (`README.md` English, `README_tw.md` Traditional Chinese). + * Includes installation guide for all major distros (Ubuntu, Fedora, Arch, Flatpak). + * Troubleshooting section for PySide6, MAME detection, and theme issues. + +### 🔍 Design Decisions: + +1. **Separate Directory (not shared codebase)**: Chose to create `AmpleLinux/` as a separate directory rather than refactoring `AmpleWin/` into a shared codebase. This maintains the project convention where each platform gets its own additive subdirectory, minimizing risk to the stable Windows port. + +2. **No MAME Auto-Download**: Following the original author's guidance ("let the user download it themselves"), Linux users install MAME via their system package manager. This is the Linux cultural norm and avoids complex binary distribution issues. + +3. **GNOME + KDE Theme Detection**: Implemented multi-strategy dark mode detection covering GNOME 42+ `color-scheme`, older GNOME `gtk-theme`, and KDE `kdeglobals`, with Qt palette as ultimate fallback. + +### 🚀 Current Project Status +The Linux Port is functionally complete. All Windows-specific code has been adapted, and the application should work on major Linux distributions with GNOME or KDE desktops. + +--- + +## Handover Notes for Future Agents + +### 1. Platform Differences from AmpleWin +* **No `winreg`**: Theme detection uses `gsettings` and KDE config file parsing. +* **No `os.startfile()`**: Uses `xdg-open` via the `_xdg_open()` helper function. +* **No `.exe` suffixes**: All binary references use bare names (`mame`, `mame-vgm`). +* **No MAME auto-download**: Users install via package manager. Settings dialog shows guidance. +* **`shlex.split(posix=True)`**: Linux uses POSIX-mode shell parsing (no special Windows path handling). +* **MAME detection**: Checks `PATH` via `which`, plus standard Linux paths (`/usr/bin`, `/usr/games`, `/usr/local/bin`). + +### 2. Deployment (CRITICAL) +* **PEP 668 Era**: Modern Linux distros (Debian 12+, Ubuntu 23.04+, Fedora 38+) block global pip installs. The launcher script handles this with `--break-system-packages` fallback. +* **Recommended Install Methods** (in priority order): + 1. System packages: `sudo apt install python3-pyside6 python3-requests mame` + 2. venv: `python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt` + 3. pip with override: `python3 -m pip install -r requirements.txt --break-system-packages` +* **Never use `pip3` or `pip` directly** in scripts — always use `python3 -m pip` for reliability. + +### 3. Known Mantras (inherited from AmpleWin) +* **Visual Parity is King**: Every margin, font size, and color was cross-referenced with macOS. +* **Authorship**: This Linux Port is based on the AmpleWin collaboration between **anomixer** and **Antigravity**. + +--- + +## 📅 Session: 2026-02-17 (Session 2) + +### 🎯 Objective: First-Run Experience, Build System & Polish + +### ✅ Key Changes: + +1. **Launcher Architecture (`AmpleLinux.sh`)**: + * **Refactored to venv**: Switched from system-level `apt` dependencies to a strictly isolated `python3 -m venv` approach. + * **Automated Setup**: Script now auto-creates `.venv`, installs `python3-venv` (if missing), and pip installs `requirements.txt`. + * **Distro Agnostic**: Only depends on `python3-full` and `libxcb-cursor*` (apt) for the base interpreter; all libraries (PySide6) are pulled via pip. + * **ALSA Fix**: Added auto-detection of `/proc/asound` and `usermod -a -G audio` fix for permission issues. + +2. **User Experience Enhancements (`main.py`)**: + * **Ubuntu Snap Integration**: If MAME is missing on Ubuntu, offers `sudo snap install mame` with a non-blocking `QProgressDialog`. + * **Configuration Fix**: `ensure_mame_ini` now runs `mame -cc` inside `AmpleLinux/mame` to keep config portable. + * **Path Precision**: `update_command_line` now resolves absolute paths for `-inipath` and `-rompath` (e.g., `/home/user/...`). + * **BGFX Cleanup**: Removed Windows-only Direct3D options. + * **UI Polish**: "Generate VGM" now shows a "Feature not implemented" popup. + +3. **Build System (New)**: + * **`make_icon.py`**: Created Linux-specific icon generator (produces standard PNG sizes: 16x16 to 512x512). + * **`build_elf.sh`**: Created PyInstaller build script that uses a temporary venv to bypass PEP 668 restrictions and produce a standalone ELF binary in `dist/`. + +### 🔍 Technical Decisions: +* **PySide6 via pip**: Moved away from `python3-pyside2` (apt) because the codebase is written for PySide6. Using venv + pip ensures version consistency and avoids the "externally-managed-environment" error on modern distros. +* **MAME Snap**: For Ubuntu users, Snap is the most reliable way to get a recent MAME version without PPA complexity. diff --git a/AmpleLinux/README.md b/AmpleLinux/README.md index 8c1ead1..48ffede 100644 --- a/AmpleLinux/README.md +++ b/AmpleLinux/README.md @@ -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.* diff --git a/AmpleLinux/README_tw.md b/AmpleLinux/README_tw.md index cf432c2..61c530d 100644 --- a/AmpleLinux/README_tw.md +++ b/AmpleLinux/README_tw.md @@ -1,114 +1,117 @@ -# AmpleLinux - Linux Port (Legacy Apple Emulator Frontend) - -[English](README.md) | [繁體中文](README_tw.md) - -這是一個將 macOS 原生 [Ample](https://github.com/ksherlock/ample) 專案移植至 Linux 平台的版本，基於 [AmpleWin](../AmpleWin/) Windows 移植版改編。 - -![](screenshot.png) - -> [!IMPORTANT] -> **版本支援說明**：目前已同步支援至 Ample (macOS) 最新版本之資源定義以及 MAME 最新版本之核心。 - -## 🍎 Ample (macOS) vs. AmpleLinux (Linux) 完整對照表 - -| 功能項目 | Ample (macOS 原生版) | AmpleLinux (Linux 版) | 說明 | -| :--- | :--- | :--- | :--- | -| **程式語言** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | 獨立開發，**完全沒動到 Mac 版原始碼** | -| **安裝方式** | .dmg 映像檔 / Homebrew | **免安裝綠色版 (+ .sh 自動配置)** | 透過 `AmpleLinux.sh` 一鍵搞定 Python 與依賴 | -| **MAME 整合** | 內建客製版核心 | **使用系統安裝的 MAME** | 透過 apt、dnf、pacman 等套件管理器安裝 | -| **UI 介面** | macOS 原生組件 | **1:1 像素級 QSS 複刻** | 支援 **Adaptive 自適應淺色/深色主題** (GNOME/KDE) | -| **初始機器選擇** | 支援預設書籤 | **全自動持久化 (自動載入上次狀態)** | 全自動開啟上次使用的機器 | -| **軟體清單效能** | 同步加載 | **延遲遞增加載 (Deferred Loading)** | 切換機器秒開 | -| **ROM 下載** | 支援自動下載 | **高效能 Failover 引擎** | 支援多伺服器切換 (callapple + mdk.cab) | -| **Video 支援** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan** | 使用 MAME 的跨平台渲染後端 | - -## 🌟 核心功能 - -### 🍏 忠實還原 Mac 體驗 (功能對齊) -* **視覺精準度**：精準支援 **Window 1x-4x** 模式，並內建機器專屬的比例啟發邏輯。 -* **軟體資料庫**：智慧過濾、搜尋遮罩、相容性檢查。 -* **進階槽位模擬**：完整支援嵌套子槽位（如 SCSI 卡），並具備穩健的設備初始化與「空」(None) 選項持久化邏輯。 -* **ROM 管理**：即時搜尋、多伺服器 Failover 下載、擴展韌體庫。 - * **相容性降級 (Compatibility Fallback)**：自動偵測受 MAME 0.288 EASC 晶片崩潰 Bug 影響的 PowerBook 機型（如 `macpb160` 等），自動切換至本地的 `mame_0287` 或 `mame-vgm`；若無備用執行檔，則會彈窗提供引導按鈕，協助使用者開啟官方 SDL Wiki 取得適用於該 Linux 發行版的舊版 MAME 執行檔。 -* **共享目錄**：與 Mac 版功能完全對齊 (`-share_directory`)。 - -### 🐧 Linux 專屬功能 -* **系統 MAME 整合**：自動偵測 `PATH`、`/usr/bin/mame`、`/usr/games/mame` 等路徑。 -* **自適應主題**：即時偵測 GNOME (`gsettings`) 與 KDE 的深色/淺色模式。 -* **原生檔案管理**：使用 `xdg-open` 開啟檔案、資料夾和 URL。 -* **無額外依賴**：MAME 直接透過發行版的套件管理器安裝。 - -### ⚠️ 已知限制 -* **VGM Mod**：「Generate VGM」功能目前在 Linux 暫停使用，因為 MAME VGM Mod 功能所需的執行檔目前僅有 Windows 版本。 - - -## 🛠️ 快速開始 - -### 前置需求 -- **Python 3.9+** -- **MAME**（透過套件管理器安裝） -- **PySide6** 和 **requests**（透過系統套件或 pip 安裝） - -### 安裝步驟 - -1. **安裝系統依賴套件**： - * **MAME**：透過您的套件管理器安裝（例如 `sudo apt install mame`）。 - * **Python 3**：確認已安裝 Python 3.9+（`sudo apt install python3-full`）。 - * **X11 支援**：GUI 介面所需（`sudo apt install libxcb-cursor0`）。 - -2. **啟動 Ample**： - ```bash - cd AmpleLinux - chmod +x AmpleLinux.sh - ./AmpleLinux.sh - ``` - 腳本會**自動**建立虛擬環境 (`.venv`)，透過 pip 安裝 `PySide6` 與其他依賴套件，最後啟動程式。**您不需要手動執行 pip install。** - -3. **快速部署**： - * **Ubuntu 使用者**：如果找不到 MAME，程式會詢問是否透過 `snap` 安裝。 - * 點擊主介面的 **🎮 ROMs** 以補齊系統韌體。 - * 前往 **⚙️ Settings** 確認 MAME 已偵測到。 - * 選擇機器，然後 **Launch MAME**！ - -## 📦 封裝發佈 (Build for Release) - -若要產生不需要依賴環境的獨立 Linux 執行檔 (ELF)： - -```bash -cd AmpleLinux -chmod +x build_elf.sh -./build_elf.sh -``` - -此腳本會在暫存的 venv 中使用 `PyInstaller` 進行打包，產出的可攜式執行檔位於 `dist/AmpleLinux/`。 - -## 📂 專案結構 - -| 檔案/目錄 | 說明 | -| :--- | :--- | -| **`AmpleLinux.sh`** | **由此開始**。自動設定腳本 (使用 venv + pip)。 | -| **`build_elf.sh`** | **封裝腳本**。透過 PyInstaller 產生獨立執行檔。 | -| `make_icon.py` | 用於從來源圖片產生 Linux PNG 圖示的工具。 | -| `main.py` | 應用程式入口，處理 UI 渲染與主要邏輯。 | -| `data_manager.py` | 負責解析 `.plist` 機器定義檔與 MAME `.xml` 軟體列表。 | -| `mame_launcher.py` | MAME 指令建構器與執行序管理器。 | -| `rom_manager.py` | 系統 ROM 的管理與多執行緒下載引擎。 | -| `mame_downloader.py` | VGM Mod 下載工具 (僅限 Windows; Linux 未使用)。 | - -## 🔧 疑難排解 - -### MAME 未偵測到 -如果程式無法找到 MAME： -1. **Ubuntu**：程式會提供 `sudo snap install mame` 的安裝選項。 -2. **手動設定**：前往 **⚙️ Settings** > **Select MAME...** 手動瀏覽並選擇執行檔。 -3. **PATH**：確認 `which mame` 能回傳路徑。 -4. 常見路徑：`/usr/bin/mame`、`/usr/games/mame`、`/var/lib/snapd/snap/bin/mame` - -### 主題偵測 -程式會自動偵測 GNOME 和 KDE 的深色/淺色主題。如果你的桌面環境不受支援，程式會使用 Qt 調色盤作為主題偵測的後備方案。 - -## 📝 致謝 - -* 原始 macOS 版本開發者: [Kelvin Sherlock](https://github.com/ksherlock) -* **Windows Port 開發者: anomixer + Antigravity** -* **Linux Port**：由 anomixer + Antigravity 基於 AmpleWin 改編 +# AmpleLinux - Linux Port (Legacy Apple Emulator Frontend) + +[English](README.md) | [繁體中文](README_tw.md) + +這是一個將 macOS 原生 [Ample](https://github.com/ksherlock/ample) 專案移植至 Linux 平台的版本，基於 [AmpleWin](../AmpleWin/) Windows 移植版改編。 + +![](screenshot.png) + +> [!IMPORTANT] +> **版本支援說明**：目前已同步支援至 Ample (macOS) 最新版本之資源定義以及 MAME 最新版本之核心。 + +## 🍎 Ample (macOS) vs. AmpleLinux (Linux) 完整對照表 + +| 功能項目 | Ample (macOS 原生版) | AmpleLinux (Linux 版) | 說明 | +| :--- | :--- | :--- | :--- | +| **程式語言** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | 獨立開發，**完全沒動到 Mac 版原始碼** | +| **安裝方式** | .dmg 映像檔 / Homebrew | **免安裝綠色版 (+ .sh 自動配置)** | 透過 `AmpleLinux.sh` 一鍵搞定 Python 與依賴 | +| **MAME 整合** | 內建客製版核心 | **使用系統安裝的 MAME** | 透過 apt、dnf、pacman 等套件管理器安裝 | +| **UI 介面** | macOS 原生組件 | **1:1 像素級 QSS 複刻** | 支援 **Adaptive 自適應淺色/深色主題** (GNOME/KDE) | +| **初始機器選擇** | 支援預設書籤 | **全自動持久化 (自動載入上次狀態)** | 全自動開啟上次使用的機器 | +| **軟體清單效能** | 同步加載 | **延遲遞增加載 (Deferred Loading)** | 切換機器秒開 | +| **ROM 下載** | 支援自動下載 | **高效能 Failover 引擎** | 支援多伺服器切換 (callapple + mdk.cab) | +| **Video 支援** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan** | 使用 MAME 的跨平台渲染後端 | + +## 🌟 核心功能 + +### 🍏 忠實還原 Mac 體驗 (功能對齊) +* **視覺精準度**：精準支援 **Window 1x-4x** 模式，並內建機器專屬的比例啟發邏輯。 +* **軟體資料庫**：智慧過濾、搜尋遮罩、相容性檢查。 +* **進階槽位模擬**：完整支援嵌套子槽位（如 SCSI 卡），並具備穩健的設備初始化與「空」(None) 選項持久化邏輯。 +* **ROM 管理**：即時搜尋、CallApple 優先／MDK 備用 Failover 下載、`dragon32` 自動補丁及 Laser 128 全系列韌體庫相容性。 + * **全面相容性**：MAME 0.289 官方已修正 PowerBook 機型（如 `macpb160`, `macpb180` 等）的 EASC 晶片崩潰 Bug，所有 PowerBook 機型現可使用最新 MAME 核心直接原生啟動。 +* **共享目錄**：與 Mac 版功能完全對齊 (`-share_directory`)。 + +### 🐧 Linux 專屬功能 +* **系統 MAME 整合**：自動偵測 `PATH`、`/usr/bin/mame`、`/usr/games/mame` 等路徑。 +* **自適應主題**：即時偵測 GNOME (`gsettings`) 與 KDE 的深色/淺色模式。 +* **原生檔案管理**：使用 `xdg-open` 開啟檔案、資料夾和 URL。 +* **無額外依賴**：MAME 直接透過發行版的套件管理器安裝。 + +### ⚠️ 已知限制 +* **VGM Mod**：「Generate VGM」功能目前在 Linux 暫停使用，因為 MAME VGM Mod 功能所需的執行檔目前僅有 Windows 版本。 + + +## 🛠️ 快速開始 + +### 前置需求 +- **Python 3.9+** +- **MAME**（透過套件管理器安裝） +- **PySide6** 和 **requests**（透過系統套件或 pip 安裝） + +### 安裝步驟 + +1. **安裝系統依賴套件**： + * **MAME**：透過您的套件管理器安裝（例如 `sudo apt install mame`）。 + * **Python 3**：確認已安裝 Python 3.9+（`sudo apt install python3-full`）。 + * **X11 支援**：GUI 介面所需（`sudo apt install libxcb-cursor0`）。 + +2. **啟動 Ample**： + ```bash + cd AmpleLinux + chmod +x AmpleLinux.sh + ./AmpleLinux.sh + ``` + 腳本會**自動**建立虛擬環境 (`.venv`)，透過 pip 安裝 `PySide6` 與其他依賴套件，最後啟動程式。**您不需要手動執行 pip install。** + +3. **快速部署**： + * **Ubuntu 使用者**：如果找不到 MAME，程式會詢問是否透過 `snap` 安裝。 + * 點擊主介面的 **🎮 ROMs** 以補齊系統韌體。 + * 前往 **⚙️ Settings** 確認 MAME 已偵測到。 + * 選擇機器，然後 **Launch MAME**！ + +## 📦 封裝發佈 (Build for Release) + +若要產生不需要依賴環境的獨立 Linux 執行檔 (ELF)： + +```bash +cd AmpleLinux +chmod +x build_elf.sh +./build_elf.sh +``` + +此腳本會在暫存的 venv 中使用 `PyInstaller` 進行打包，產出的可攜式執行檔位於 `dist/AmpleLinux/`。 + +## 📂 專案結構 + +| 檔案/目錄 | 說明 | +| :--- | :--- | +| **`AmpleLinux.sh`** | **由此開始**。自動設定腳本 (使用 venv + pip)。 | +| **`build_elf.sh`** | **封裝腳本**。透過 PyInstaller 產生獨立執行檔。 | +| `make_icon.py` | 用於從來源圖片產生 Linux PNG 圖示的工具。 | +| `main.py` | 應用程式入口，處理 UI 渲染與主要邏輯。 | +| `data_manager.py` | 負責解析 `.plist` 機器定義檔與 MAME `.xml` 軟體列表。 | +| `mame_launcher.py` | MAME 指令建構器與執行序管理器。 | +| `rom_manager.py` | 系統 ROM 的管理與多執行緒下載引擎。 | +| `mame_downloader.py` | VGM Mod 下載工具 (僅限 Windows; Linux 未使用)。 | + +## 🔧 疑難排解 + +### MAME 未偵測到 +如果程式無法找到 MAME： +1. **Ubuntu**：程式會提供 `sudo snap install mame` 的安裝選項。 +2. **手動設定**：前往 **⚙️ Settings** > **Select MAME...** 手動瀏覽並選擇執行檔。 +3. **PATH**：確認 `which mame` 能回傳路徑。 +4. 常見路徑：`/usr/bin/mame`、`/usr/games/mame`、`/var/lib/snapd/snap/bin/mame` + +### 主題偵測 +程式會自動偵測 GNOME 和 KDE 的深色/淺色主題。如果你的桌面環境不受支援，程式會使用 Qt 調色盤作為主題偵測的後備方案。 + +## 📝 致謝 + +* 原始 macOS 版本開發者: [Kelvin Sherlock](https://github.com/ksherlock) +* **Windows Port 開發者: anomixer + Antigravity** +* **Linux Port**：由 anomixer + Antigravity 基於 AmpleWin 改編 + +--- +*免責聲明：AmpleLinux 是一個獨立的開源專案，與 Apple Inc. 或本專案提及之任何其他公司均無任何隸屬、授權、維護或背書關係。所有產品及公司名稱均為其各自持有人的商標™或註冊®商標。* diff --git a/AmpleLinux/main.py b/AmpleLinux/main.py index 4012026..e29d8c8 100644 --- a/AmpleLinux/main.py +++ b/AmpleLinux/main.py @@ -1228,6 +1228,16 @@ def on_machine_selected(self, item): # 不再於切換時立即填充軟體清單 (延遲加載以優化效能) if hasattr(self, 'sw_list'): self.sw_list.clear() + def get_default_slots(self): + if not self.current_machine_data: + return {} + old_slots = self.current_slots + self.current_slots = {} + self.initialize_default_slots(self.current_machine_data) + defaults = self.current_slots + self.current_slots = old_slots + return defaults + def initialize_default_slots(self, data, depth=0): if depth > 20: return @@ -1312,6 +1322,12 @@ def render_slots_ui(self): self.add_slot_row(self.slots_layout, ram_slot) self.slots_layout.addSpacing(5) + # 1.5 ROM Group + rom_slot = next((s for s in self.current_machine_data['slots'] if s['name'] in ('rom', 'romsize') or s.get('description') in ('ROM', 'ROM/RAM')), None) + if rom_slot: + self.add_slot_row(self.slots_layout, rom_slot) + self.slots_layout.addSpacing(5) + # 2. Disk Drives - EXACTLY same structure as add_slot_row # Mac hides popup button but it still takes up space. Hamburger at far right. dd_slot = next((s for s in self.current_machine_data['slots'] if s.get('description') == 'Disk Drives'), None) @@ -1350,19 +1366,12 @@ def render_slots_ui(self): self.slots_layout.addLayout(row) - - - - - - - - - - # 3. All other slots + excluded_names = {'ramsize'} + if rom_slot: + excluded_names.add(rom_slot['name']) for slot in self.current_machine_data['slots']: - if slot['name'] != 'ramsize' and slot.get('description') != 'Disk Drives': + if slot['name'] not in excluded_names and slot.get('description') != 'Disk Drives': self.add_slot_row(self.slots_layout, slot) self.slots_layout.addStretch() @@ -1879,8 +1888,20 @@ def update_command_line(self): # Positional arguments allow MAME's Software List manager to resolve them. soft_list_args.append(self.selected_software) + # Get defaults recursively + defaults = self.get_default_slots() + + # Filter slots: if a slot is set to empty "", only pass it to MAME if its default value was NOT empty + active_slots = {} + for slot_name, option in self.current_slots.items(): + if option == "": + default_val = defaults.get(slot_name, "") + if default_val == "": + continue + active_slots[slot_name] = option + # Build base args - args = self.launcher.build_args(self.selected_machine, self.current_slots, filtered_media, soft_list_args) + args = self.launcher.build_args(self.selected_machine, active_slots, filtered_media, soft_list_args) # Add UI Video options for preview win_mode = self.win_mode.currentText() @@ -2144,40 +2165,6 @@ def launch_mame(self): # Get command from preview console (User Input is Source of Truth) cmd_str = self.cmd_preview.toPlainText().strip() if not cmd_str: return - - # EASC PowerBook 0.288 Crash Fallback Check - affected_macs = ["macpb160", "macpb180", "macpb165", "macpb165c", "macpb180c"] - if self.selected_machine in affected_macs: - mame_bin_dir = os.path.dirname(self.launcher.mame_path) - alt_mac_exe = os.path.join(mame_bin_dir, "mame_0287") - vgm_mac_exe = os.path.join(mame_bin_dir, "mame-vgm") - - # Check if any fallback is already present - has_fallback = os.path.exists(alt_mac_exe) or os.path.exists(vgm_mac_exe) - - if not has_fallback: - msg_box = QMessageBox(self) - msg_box.setIcon(QMessageBox.Warning) - msg_box.setWindowTitle("EASC Audio Chip Bug (MAME v0.288)") - msg_box.setText(f"The machine '{self.selected_machine}' will crash on MAME v0.288 due to an upstream C++ type mismatch bug.") - msg_box.setInformativeText( - "To run this model, you can download a compatible older version of MAME (e.g. v0.287) and place the executable named 'mame_0287' inside your 'mame' folder,\n" - "or run a compatible sibling model instead (e.g. 'macpb170' or 'macpb140')." - ) - - dl_btn = msg_box.addButton("Download Fallback (v0.287)", QMessageBox.YesRole) - force_btn = msg_box.addButton("Force Launch (v0.288)", QMessageBox.NoRole) - cancel_btn = msg_box.addButton("Cancel", QMessageBox.RejectRole) - - msg_box.exec() - - if msg_box.clickedButton() == dl_btn: - _xdg_open("https://wiki.mamedev.org/index.php/SDL_Supported_Platforms") - return - elif msg_box.clickedButton() == force_btn: - pass - else: - return print(f"Launching custom command: {cmd_str}") @@ -2204,21 +2191,7 @@ def launch_mame(self): target_exe_path = args[0] if exe_cmd == "mame": - affected_macs = ["macpb160", "macpb180", "macpb165", "macpb165c", "macpb180c"] - alt_mac_exe = os.path.join(mame_bin_dir, "mame_0287") - vgm_mac_exe = os.path.join(mame_bin_dir, "mame-vgm") - - if self.selected_machine in affected_macs: - if os.path.exists(alt_mac_exe): - target_exe_path = alt_mac_exe - print(f"Applying compatibility fallback: using mame_0287 for {self.selected_machine}") - elif os.path.exists(vgm_mac_exe): - target_exe_path = vgm_mac_exe - print(f"Applying compatibility fallback: using mame-vgm for {self.selected_machine}") - else: - target_exe_path = self.launcher.mame_path - else: - target_exe_path = self.launcher.mame_path + target_exe_path = self.launcher.mame_path elif exe_cmd == "mame-vgm": path_vgm = os.path.join(mame_bin_dir, "mame-vgm") if os.path.exists(path_vgm): diff --git a/AmpleLinux/rom_manager.py b/AmpleLinux/rom_manager.py index 0cf7205..6232ddb 100644 --- a/AmpleLinux/rom_manager.py +++ b/AmpleLinux/rom_manager.py @@ -40,6 +40,10 @@ def run(self): with open(self.dest_path, 'wb') as f: f.write(response.content) + # Special patch for dragon32 to merge MDK split files if missing + if self.value == 'dragon32': + self.patch_dragon32() + self.signals.finished.emit(self.value, True) return # Success! except Exception as e: @@ -53,14 +57,41 @@ def run(self): self.signals.status.emit(f"Error: {last_error}") self.signals.finished.emit(self.value, False) + def patch_dragon32(self): + try: + mdk_url = "https://mdk.cab/download/split/dragon32.zip" + resp = requests.get(mdk_url, headers=self.headers, timeout=20) + if resp.status_code == 200 and len(resp.content) > 100: + import zipfile, io + existing_data = open(self.dest_path, 'rb').read() + z_existing = zipfile.ZipFile(io.BytesIO(existing_data)) + z_mdk = zipfile.ZipFile(io.BytesIO(resp.content)) + + existing_names = set(z_existing.namelist()) + mdk_names = set(z_mdk.namelist()) + + missing = mdk_names - existing_names + if missing: + out_buf = io.BytesIO() + with zipfile.ZipFile(out_buf, 'w', zipfile.ZIP_DEFLATED) as zout: + for item in z_existing.infolist(): + zout.writestr(item, z_existing.read(item.filename)) + for item in z_mdk.infolist(): + if item.filename in missing: + zout.writestr(item, z_mdk.read(item.filename)) + with open(self.dest_path, 'wb') as f: + f.write(out_buf.getvalue()) + except Exception as e: + print(f"Warning: dragon32 patch failed: {e}") + class RomManager(QObject): def __init__(self, resources_path, roms_dir): super().__init__() self.resources_path = resources_path self.roms_dir = roms_dir self.base_urls = [ - "https://mdk.cab/download/split/", - "https://www.callapple.org/roms/" + "https://www.callapple.org/roms/", + "https://mdk.cab/download/split/" ] self.rom_list = self.load_rom_list() @@ -78,7 +109,12 @@ def load_rom_list(self): {'value': 'prav8c', 'description': 'Pravetz 8C'}, {'value': 'prav82', 'description': 'Pravetz 82'}, {'value': 'prav8m', 'description': 'Pravetz 8M'}, - {'value': 'prav8d', 'description': 'Pravetz 8D'} + {'value': 'prav8d', 'description': 'Pravetz 8D'}, + {'value': 'las128ex', 'description': 'Laser 128EX'}, + {'value': 'las128e2', 'description': 'Laser 128EX/2'}, + {'value': 'laser128', 'description': 'Laser 128'}, + {'value': 'laser128o', 'description': 'Laser 128 (Original)'}, + {'value': 'laser2c', 'description': 'Laser 2c'} ] existing_values = {r.get('value') for r in roms if 'value' in r} for cr in custom_roms: diff --git a/AmpleWin/Agent.md b/AmpleWin/Agent.md index 8e5e558..9337c9b 100644 --- a/AmpleWin/Agent.md +++ b/AmpleWin/Agent.md @@ -1,418 +1,463 @@ -# Agent Task Audit Log - Ample Windows Port - -## 📅 Session: 2026-06-05 (Session 16) - -### 🎯 Objective: PowerBook Compatibility Fallback & Downloader Acceleration -Addressed upstream MAME 0.288 C++ late-binding bug causing crashes on EASC audio chip Macs, and accelerated the VGM Mod download. - -### ✅ Key Achievements: -1. **EASC Crash Fallback Mechanism**: - * Added automatic detection for affected PowerBook models (`macpb160`, `macpb180`, `macpb165`, `macpb165c`, `macpb180c`). - * Implements seamless redirect to `mame_0287.exe` or `mame-vgm.exe` (v0.280) if present in the executable folder. - * Provides user warning with options to auto-download MAME v0.280 (VGM Mod) fallback, force launch under 0.288, or cancel. -2. **Downloader Optimization**: - * Switched VGM Mod download mirror to prioritize `mirror.ghproxy.com` GitHub proxy for faster global asset retrieval. -3. **ROM Manager Priority Check**: - * Reordered ROM base URLs to prioritize `mdk.cab` over `callapple.org`. This guarantees the latest split set ROMs (like `dragon32` with split files) are downloaded correctly, solving the missing files crash on MAME 0.288+. - ---- - -## 📅 Session: 2026-05-19 (Session 15) - -### 🎯 Objective: Complete Slot Configuration Persistence (MAME Command Line) -Resolved the issue where selecting "None" for a slot in the UI didn't actually disable the device in MAME because empty slot arguments were being omitted from the command line. - -### ✅ Key Achievements: -1. **Command-Line Slot Persistence**: - * Modified `build_args` in `mame_launcher.py` to allow empty string values (e.g. `option is not None` instead of `if option:`). - * This ensures that `-[slot_name] ""` is explicitly passed on the command line, preventing MAME from falling back to its internal defaults. -2. **Parity**: Checked and verified this behavior across both `AmpleWin` and `AmpleLinux` ports, ensuring slots explicitly set to "None" are truly disabled when the emulator launches. - ---- - -## 📅 Session: 2026-05-11 (Session 14) - -### 🎯 Objective: Slot Configuration Consistency Fix -Resolved an issue where slots with defaults could not be set to "None" because UI refreshes would revert them. - -### ✅ Key Achievements: -1. **"None-Aware" Slot Initialization**: - * Modified `initialize_default_slots` to use `slot_name not in self.current_slots`. - * Ensured manual "None" selections are preserved while maintaining automated defaults for new card insertion. -2. **Upstream Compatibility**: Prepared codebase for PR back to original source, ensuring robust slot behavior. - ---- - -## 📅 Session: 2026-03-02 (Session 13) - -### 🎯 Objective: Upstream Version Bump & Documentation Maintenance -Focused on updating the project to track MAME 0.286 and simplifying documentation maintainability. - -### ✅ Key Achievements: -1. **Version Bump**: Updated `mame_downloader.py` to point to the latest **MAME 0.286** x64 Windows binary. -2. **Documentation Refactoring**: - * Renamed version-specific screenshot files (e.g. `screenshot-v0.28x.png` to `screenshot.png`) across all platforms. - * Updated `README.md` and `README_tw.md` to use generic "latest version" terminology to prevent the need for manual text updates upon future MAME releases. - -### 🚀 Current Project Status -The Windows Port is functionally tracking MAME 0.286 and documentation is now future-proofed against minor version increments. - ---- - -## 📅 Session: 2026-02-16 (Session 12) - -### 🎯 Objective: Linux Port Spinoff -AmpleWin has successfully served as the foundation for a new Linux port. - -### ✅ Key Achievements: -1. **Port Creation**: - * **AmpleLinux**: Created `AmpleLinux/` directory based on the AmpleWin codebase. - * **Shared DNA**: `data_manager.py` and `rom_manager.py` remain identical, while `main.py` was adapted for Linux (xdg-open, paths, dependencies). - * **Cross-Reference**: Added links to AmpleLinux in the README. - -### 🚀 Current Project Status -The project now supports both Windows (AmpleWin) and Linux (AmpleLinux) natively. - ---- - -## 📅 Session: 2026-02-09 (Session 11) - - -### 🎯 Objective: Upstream Synchronization & Codebase Hygiene -Focused on synchronizing the project with the latest upstream changes from `ksherlock/ample`, ensuring the `roms.plist` database is compliant with the official repository, and cleaning up diverging local branches. - -### ✅ Key Achievements: - -1. **Full Upstream Sync**: - * **Repository Alignment**: Merged latest `upstream/master` changes (4 new commits), bringing in the official fix for **PowerBook Duo 280 (`macpd280`)** and new definitions like **Epson RX-80 (`epson_rx80`)**. - * **Deforking roms.plist**: Discarded local custom modifications to `Ample/Resources/roms.plist`. The file is now byte-for-byte identical to the upstream version, ensuring long-term maintainability. - * **Branch Cleanup**: Removed the stale `fix-missing-roms` branch and closed the associated PR #44, as the upstream author has implemented the necessary fixes natively. - -2. **AmpleWin Verification**: - * **Compatibility Verified**: Confirmed that `AmpleWin` correctly parses the new upstream `roms.plist` without errors. - * **ROM Status**: Validated that `macpd280` is now natively supported for auto-download via the new upstream definitions. Note: Custom definitions for *Pravetz* and *TK3000* are no longer in `roms.plist` but remain playable if ROMs are manually provided. -3. **Deployment & Distribution**: - * **Refactor**: Renamed `mame_bin` to `mame` across the codebase for better standards compliance. - * **Portable EXE**: Created `build_exe.bat` using **PyInstaller (OneDir)** to package the application into a standalone executable. - * **Path Logic**: Updated `main.py` with robust `sys.frozen` detection to ensure resources and downloads work correctly in both Dev and Frozen environments. - * **Documentation**: Added build instructions to READMEs. - -### 🚀 Current Project Status -The codebase is now in a "Clean Slate" state. `master` is fully synced with upstream, with `AmpleWin` serving as a strictly additive extension. - -## 📅 Session: 2026-02-02 (Session 10) - -### 🎯 Objective: ROM Library Expansion & Advanced Slot Emulation -Focused on expanding the supported ROM library, implementing a robust failover download mechanism, and perfecting nested slot configuration logic for SCSI peripherals. - -### ✅ Key Achievements: - -1. **ROM Library & Search Expansion**: - * **New System Support**: Added missing ROM definitions for **Macintosh PowerBook Duo 280/280c**, **Pravetz 8C**, and **TK3000 //e**. - * **Search Parity**: Fully synchronized hardware definitions with the latest macOS release, including secondary Pravetz models (`82`, `8M`). - -2. **Robust ROM Download Failover**: - * **Prioritized Multi-Server Support**: Implemented a transparent failover mechanism in `rom_manager.py`. The downloader now prioritizes **callapple.org** for maximum stability and automatically falls back to **mdk.cab** for Apple II clones and split sets unreachable on the primary server. - * **Status Integrity**: Fixed a bug in the download progress counter to ensure accurate success/failure reporting in the UI. - -3. **Advanced Slot & Media Emulation**: - * **SCSI Sub-Peripheral Detection**: Rewrote `aggregate_media` to recursively detect devices attached to slot cards (e.g., finding the CD-ROM and Hard Disk on an Apple IIgs SCSI card). - * **Nested Slot Defaults**: Implemented automatic initialization for sub-slots. Plugging in a SCSI card now automatically populates its sub-slots with default devices (CD-ROM at ID 1, Hard Disk at ID 6), matching Mac parity. - * **Sub-Slot UI Parity**: Updated the "Hamburger" popup to show all configurable sub-slots, not just those with media, giving users full control over complex hardware chains. - * **Aggregator Optimization**: Refined the media scanner to ignore the global "device library" at the root level, preventing UI clutter and double-counting of unmapped drives. - -### 🚀 Current Project Status -The Windows Port now offers superior hardware configuration capabilities. Complex SCSI and SmartPort chains are handled automatically, and the ROM acquisition system is more reliable than ever. - -## 📅 Session: 2026-02-02 (Session 9) - -### 🎯 Objective: Upstream Synchronization & Feature Parity (MAME 0.286) -Focused on synchronizing with the upstream Ample (macOS) v0.286 release, updating the core emulator backend, and implementing new UI search capabilities. - -### ✅ Key Achievements: - -1. **Upstream Repository Synchronization**: - * **Merge & Push**: Successfully merged latest commits from `upstream/master` (ksherlock/ample). - * **Resource Alignment**: Synchronized latest hardware definitions and slot configurations from original project. - * **A2retroNET Integration**: Inherited support for a2retronet hardware, enabling up to 8 SmartPort disk images. - -2. **MAME Core Update**: - * **Version Upgrade**: Updated `mame_downloader.py` to point to the official **MAME 0.286** Windows x64 binary. - * **Download Engine Parity**: Users can now auto-download the latest MAME core directly from the Settings menu. - -3. **ROM Manager Enhancements**: - * **Search Filter**: Implemented a real-time search field in the `RomManagerDialog` header (matching macOS feature parity). - * **Filtering Logic**: Updated `refresh_list` to filter ROMs by description or shortcode, allowing users to quickly find specific system firmwares. - -### 🚀 Current Project Status -The Windows Port is now fully synchronized with Ample (macOS) v0.286 resources. It supports the latest MAME core and offers improved ROM management tools. - ---- - - -## 📅 Session: 2026-01-24 (Session 8) - -### 🎯 Objective: Path robustness & UI Interactivity -Focused on fixing "No such file" errors when launching custom ROM paths and improving the user experience for file selection in secondary tabs. - -### ✅ Key Achievements: - -1. **Command Line Robustness**: - * **Quote Handling**: Patched the `shlex` logic in `main.py` to handle Windows paths correctly. Manually stripping outer quotes ensures `subprocess` doesn't double-escape them, fixing the critical "No such file or directory" error when launching files with spaces in their path. - -2. **File Selection UX**: - * **A/V Path Selectors**: Implemented `mousePressEvent` on the A/V tab input fields (AVI, WAV, VGM). Clicking these text boxes now opens a native `QFileDialog` ("Save As") with appropriate extension filters, saving users from manual typing. - * **Path Normalization**: Updated the "Shared Directory" directory selector to automatically normalize paths (e.g., converting `/` to `\`), ensuring visual consistency and compatibility with Windows command line expectations. - -### 🚀 Current Project Status -The application is now highly resilient to typical Windows path complexities. Users can easily select output destinations and shared folders without worrying about path syntax errors. - ---- - -## 📅 Session: 2026-01-22 (Session 7) - -### 🎯 Objective: User Freedom & flexible Command Control -Focused on giving the user complete control over the MAME launch command and ensuring a cleaner default state for machine slots. - -### ✅ Key Achievements: - -1. **Editable Command Console**: - * **Unlocked Preview**: The "Command Preview" text box is no longer read-only. - * **Source of Truth**: The Launch button now executes *exactly* what is typed in this box. Users can manually add, remove, or edit arguments (e.g., adding `-verbose` or removing unwanted flags) before launching. - -2. **Launch Engine Integrity**: - * **Absolute Path Resolution**: Implemented `shlex` parsing to read the user's manual command string. It automatically detects the command (`mame` or `mame-vgm`) and resolves it to the absolute system path to fix `[WinError 2]` on Windows. - * **VGM Pathing**: Logic retains awareness of VGM Mod capabilities even when launching from a custom text string. - -3. **Cleaner Default State**: - * **Slot Neutrality**: Removed the aggressive fallback logic that forced the first available option for slots without a default value. - * **Phantom Args Clarified**: This eliminates confusing arguments like `-fdc:0 525` appearing automatically, ensuring MAME starts with its internal defaults unless the local configuration explicitly overrides them. - -### 🚀 Current Project Status -The app now respects "Power User" workflows. You can use the UI for quick setup, then fine-tune the command line manually. The codebase structure is being finalized. - ---- - -## 📅 Session: 2026-01-21 (Session 6) - -### 🎯 Objective: VGM Mod Stability & Extraction Safety -Focused on fixing critical bugs in the VGM recording workflow, ensuring extraction safety, and improving UI feedback for the modded binary. - -### ✅ Key Achievements: - -1. **VGM Mod Extraction Safety**: - * **Anti-Overwrite Workflow**: Implemented a temporary directory strategy (`_vgm_temp`) during VGM Mod extraction. This ensures that the mod's `mame.exe` (v0.280) never accidentally overwrites the main official `mame.exe` (v0.284). - * **Atomic Renaming**: The modded binary is now safely extracted, renamed to `mame-vgm.exe`, and moved to the destination in a single, non-destructive step. - -2. **Command Line & UI Parity**: - * **Explicit Recording Toggle**: Fixed a bug where `-vgmwrite 1` was missing from the console launch command. Recording is now correctly activated when using the modded binary. - * **Dynamic UI Preview**: The 4-line console preview now correctly displays `mame-vgm` as the target executable when VGM recording is enabled and the mod is detected, matching actual runtime behavior. - -3. **Thread & Lifecycle Stability**: - * **Remove Safety**: Fixed a `ValueError: list.remove(x): x not in list` in the worker cleanup logic, ensuring the thread-safe management of background tasks even if signals fire twice. - * **Worker Refactoring**: Rewrote the `VgmModDownloadWorker` and `VgmPostProcessWorker` logic to handle edge cases in file movement and process termination more gracefully. - -4. **Shared Directory & UI Refinement**: - * **Logic Completion**: Fixed a missing link in the launch engine where the "Shared Directory" path from the UI wasn't being passed to the actual MAME process. - * **Standardized Argument**: Updated from `-share` to the official `-share_directory` for maximum compatibility. - * **UI Bugfix**: Removed duplicate "Paths" tab initialization in the main window. - * **Click-to-Browse**: Implemented a pop-up directory selector when clicking the Shared Directory path box, replacing manual entry. - -5. **Smart Slot Validation (Mac Parity)**: - * **Disabled State Support**: Ported the `disabled` logic from the Mac version. Slot options that are technically defined but marked as unsupported in the plist (e.g., specific SCSI cards on Apple IIgs) are now visually grayed out and unselectable in the dropdown menu. - * **Prevention**: Prevents users from accidentally selecting incompatible hardware configurations that would cause MAME to crash or behave unexpectedly. - -### 🚀 Current Project Status -The VGM and Shared Directory workflows are now "Production Ready." The UI has reached a high level of fidelity with the Mac original, including subtle behaviors like smart slot validation and intuitive path selection. - ---- - -## 📅 Session: 2026-01-21 (Session 5) - -### 🎯 Objective: MAME Core Logic & Command Line Robustness -Focused on improving the reliability of the MAME launch engine, specifically regarding dynamic slot media (CFFA2), multi-drive support, and shell-safe command construction. - -### ✅ Key Achievements: - -1. **Relaxed Parameter Validation**: - * **Dynamic Media Parity**: Removed strict `listmedia` validation in `MameLauncher` to allow secondary media types (like `hard1`, `hard2`) that only appear when a specific card (e.g., CFFA2) is plugged in. - * **Internal Filter**: Implemented logic to automatically skip internal MAME node names starting with a colon (e.g., `-:prn`) to prevent "unknown option" errors. - -2. **Multi-Drive & Storage Support**: - * **Capping Removal**: Fixed a self-imposed limitation in `main.py` that forced `hard`, `cdrom`, and `cassette` counts to 1. - * **CFFA2 Ready**: AmpleWin now correctly supports machines/cards with multiple hard drives (`-hard1`, `-hard2`). - -3. **Shell Integrity & Quoting**: - * **Robust Quoting**: Integrated `subprocess.list2cmdline` for both the UI Command Preview and the actual process execution. - * **Space Handling**: Guaranteed that file paths containing spaces are automatically wrapped in quotes (`""`), preventing launch failures on Windows. - * **Path Normalization**: Implemented `os.path.normpath` for all MAME arguments (`-hard`, `-rompath`, etc.), ensuring consistent Windows-style backslashes (`\`). - * **Command Line Streamlining**: Automated `mame.ini` generation via `mame -cc` upon MAME detection. This allows removing redundant path arguments (`-hashpath`, `-artpath`, etc.) from the command line, resulting in a much cleaner and more readable preview. - * **VGM Support (Advanced)**: Since modern MAME removed VGM support, AmpleWin implements a robust background workflow to download and configure the **MAME-VGM Mod (v0.280)**. It uses a non-destructive extraction process (`mame-vgm.exe`) to preserve your main MAME core while restoring high-fidelity music recording, and automatically moves the resulting `.vgm` files to the user's desired path upon MAME exit. - -4. **Resolution Scaling & Visual Parity**: - * **Window Mode Scaling**: Implemented `-resolution` generation for scaling modes (2x, 3x, 4x) and **`-nomax`** for **Window 1x** mode to ensure consistent default sizing. - * **Aspect Ratio Heuristic**: Integrated a 4:3 correction heuristic for non-square pixel machines (e.g., Apple II: 560x192 -> 1120x840 at 2x) to match macOS Ample behavior. - * **Square Pixel Mode**: Implemented integer scaling for Apple II machines (e.g., **1120x768** at 2x) while adding **`-nounevenstretch`** to prevent pixel shimmering and maintain clarity. - * **UI Expansion**: Added "Window 4x" option to the Video settings tab. - * **Disk Sound Effects Integration**: Linked the "Disk Sound Effects" checkbox to the `-nosamples` argument, allowing MAME samples to load when sound effects are enabled. - * **CPU Speed & Throttle UI Alignment**: Merged the Throttle checkbox into the CPU Speed dropdown as a "No Throttle" option, perfectly matching the original macOS Ample interface and logic. - -5. **BGFX Effect Synchronization**: - * **Enhanced Effects List**: Updated the video effects selection to support a standardized set of BGFX screen chains: **Unfiltered, HLSL, CRT Geometry, CRT Geometry Deluxe, LCD Grid, and Fighters**. - * **Chain Mapping**: Implemented precise mapping between UI selection and MAME's `-bgfx_screen_chains` internal identifiers. - -### 🚀 Current Project Status -The MAME launch engine is now significantly more robust and "intelligent." It handles complex slot configurations and multi-disk setups like CFFA2 without manual parameter tweaking, while maintaining a clean, error-free command line preview. - ---- - -## 📅 Session: 2026-01-19 (Session 4) - -### 🎯 Objective: Real-time Adaptive Theming & UI Resilience -Focused on implementing a native Windows theme detection engine and ensuring 100% visibility/aesthetic parity across both Light and Dark modes without requiring application restarts. Refined the command console for long parameter strings. - -### ✅ Key Achievements: - -1. **Adaptive Theme Engine**: - * **Registry-Level Detection**: Implemented `winreg` polling to detect `AppsUseLightTheme` changes in real-time. - * **Live Synchronization**: Added a 2-second polling timer (`QTimer`) that triggers a global UI restyle, allowing the app to switch between Light and Dark modes on-the-fly. - * **Cross-Window Propagation**: Ensured theme changes flow correctly into child dialogs (ROM Manager) and dynamic overlays (Software Search, Sub-slot popups). - -2. **UI Polish & Visibility Fixes**: - * **Light Mode "Ghosting" Elimination**: Fixed unreadable text by moving critical UI colors (Slot Labels, Media Headers) from hardcoded Python strings to the global adaptive stylesheet. - * **Themed Popups**: Rewrote `SoftwarePopup` and sub-slot bubble painting to dynamically adjust background colors and "triangle" indicators based on the system theme. - * **ROM Manager Parity**: Fully themed the ROM download dialog, ensuring status labels (found/missing) maintain high contrast in both modes. - -3. **Command Console Expansion**: - * **Multi-line Preview**: Replaced the single-line `QLineEdit` with a 4-line `QTextEdit` console footer. - * **Parameter Visibility**: This allows users to review the entire MAME command line, including long software list paths and slot configurations, without horizontal scrolling. - -4. **Stability & Bug Squashing**: - * **ROM Manager Reliability**: Corrected `@Slot` decorators and converted the dialog to `.exec()` (Modal) to prevent interaction conflicts. - * **Logic Errors**: Fixed several `NameError` bugs in the rendering engine and addressed stylesheet inheritance issues that caused transparent list views. -5. **Visual Documentation & Networking Guide**: - * **README Screenshots**: Embedded `screenshot-v0.284.png` in READMEs to match original aesthetics. - * **Networking Parity Section**: Added a specialized section in READMEs explaining **Npcap** requirements for Uthernet II simulation, clarifying that the macOS "Fix Permissions" is unnecessary on Windows. - -### 🚀 Current Project Status -The Windows Port is now a "State-of-the-Art" adaptive application. It feels native on both Light and Dark Windows setups, offers robust command line verification, and maintains the premium "Apple-inspired" aesthetic consistently. - ---- - -## 📅 Session: 2026-01-19 (Session 3) - -### 🎯 Objective: Documentation Standardization & UI Finalization -This session focused on finalizing the project's documentation (internationalization), organizing the file structure to stay clean relative to the upstream repository, and refining the primary toolbar functions. - -### ✅ Key Achievements: - -1. **Documentation Internationalization**: - * **Dual-Language Support**: Created `README.md` (English) and `README_tw.md` (Traditional Chinese) in the `AmpleWin` directory. - * **Mutual Linking**: Implemented language-switching headers in both README files for a professional GitHub experience. - * **Parity Verification**: Deep-dived into original macOS Objective-C source code to ensure the comparison table is 100% accurate regarding ROM downloading, bookmarked machine persistence, and technical differences. - -2. **UI Finalization & Utility Tools**: - * **Ample Dir Integration**: Renamed "Disk Images" to "📂 Ample Dir". It now acts as a shortcut to open the application directory in Windows Explorer. - * **Redirected Help**: Linked the "📖 Help" button directly to the official project GitHub sub-folder for instant user support. - -3. **Project Structure Hygiene**: - * **Namespace Isolation**: Relocated all Windows-specific overhead files (`README_tw.md`, `AmpleWin.bat`, `requirements.txt`, `Agent.md`) into the `AmpleWin` subdirectory. - * **Upstream Integrity**: Restored the root directory to its original state, ensuring a clean "1 commit ahead" status for easy upstream maintenance. - * **Script Resilience**: Updated `AmpleWin.bat` to handle the new directory structure, allowing execution directly from within the `AmpleWin` folder. - -### 🚀 Current Project Status -The Windows Port is now a "ready-to-ship" localized product. The documentation is verified against the original Mac source code, the UI buttons serve practical Windows-specific needs, and the project stays respectful to the original repository's file structure. - ---- - -## 📅 Session: 2026-01-18 (Session 2) - -### 🎯 Objective: Deployment, Performance & Path Robustness -This session focused on making the application portable, optimizing the download engine for "instant" ROM acquisition, and improving the first-run user experience with guided setup. - -### ✅ Key Achievements: - -1. **Deployment & Portability**: - * **Auto-Launcher**: Created `ample_win.bat` to automate dependency installation and app execution. - * **Dynamic Paths**: Replaced hardcoded absolute paths with a robust search algorithm that detects the `Ample/Resources` folder relative to the script location. - * **Environment Isolation**: Forced MAME working directory to `mame_bin`, ensuring `nvram`, `cfg`, and `diff` folders stay within the emulator directory and out of the project root. - -2. **Explosive Download Engine**: - * **Threading Mastery**: Transitioned to `QThreadPool` for manageable concurrency. - * **Performance Leap**: Increased parallel download threads from 1 to **50**. - * **Small File Optimization**: For ROM files (<64KB), switched from streaming to direct `requests.content` I/O, resulting in near-instant mass downloads. - * **Anti-Throttling**: Added browser-masking `User-Agent` headers. - -3. **User Experience (UX)**: - * **Startup Wizard**: Implemented sequential logic: Check MAME -> Guided Download -> Check ROMs -> Guided Download. - * **Sticky Software (Smart Carry-over)**: - * Selections and filters now persist across compatible machines. - * **Compatibility Logic**: Automatically clears selection if the new machine doesn't support the current software list. - * **Full Name Display**: The search box now displays the full, descriptive software name instead of the short MAME ID. - * **UI Cleanliness**: Software lists stay collapsed during machine switches for a sleeker look. - * **Windows 10 Fixes**: Applied global CSS overrides for `QMessageBox` and `QDialog` to fix unreadable grey-on-white text issues on Windows 10. - -4. **Project Hygiene**: - * Updated `.gitignore` to exclude MAME runtime artifacts (`nvram/`, `cfg/`, `sta/`, etc.). - * Updated `README_win.md` with the new one-click launch instructions. - -### 🚀 Current Project Status -Ample Windows is now highly portable and user-friendly. The download system is exceptionally fast, and the environment stays clean during emulation sessions. - -## 📅 Session: 2026-01-18 (Session 1) - -### 🎯 Objective: Software List Integration & Final UI Polish -This session focused on implementing the MAME Software List feature and refining the UI to achieve 100% aesthetic parity with the macOS version, including functional improvements to the MAME launch engine for Windows. - -### ✅ Key Achievements: - -1. **Software List Feature**: - * **XML Parsing**: Enhanced `DataManager` to parse MAME's `hash/*.xml` files. - * **Intelligent Discovery**: Implemented a search-based software browser with autocomplete-style show/hide logic. - * **Auto-Detection**: Integrated software list selection into the MAME launch command with optimized argument ordering. - -2. **MAME Launch Engine**: - * **Argument Ordering**: Fixed Windows-specific software list resolution issues by placing software list items immediately after the machine name. - * **Path Isolation**: Standardized `-hashpath`, `-bgfx_path`, and `-rompath` to be relative to the application's `mame_bin` directory. - * **Resource Management**: Centralized ROM storage to `mame_bin\roms`. - -3. **UI Aesthetic Refinement**: - * **Apple Launch Button**: Replicated the Mac-style 🍎 icon inside the Launch button with left-aligned icon and right-aligned text. - * **Full-Width Console**: Moved the Command Preview to a full-width footer with a console-style (black background, monospace) styling. - * **Clean Mode**: Removed "Use Samples" checkbox and hardcoded `-nosamples` for authenticity. - * **Proportional Layout**: Expanded the options area to comfortably display long software names (60+ characters). - -4. **Stability & Initialization**: - * **Graceful Shutdown**: Improved thread termination logic in `closeEvent`. - * **Safe Initialization**: Fixed attribute and name errors in `DataManager` and `AmpleMainWindow` during early startup phases. - -### 🚀 Current Project Status -The Windows Port is now functionally on par with the original Mac version, including the Software List feature. The UI is pixel-perfect and the launch engine is robust against common Windows path and argument pitfalls. - ---- - -## Handover Notes for Future Agents - -### 1. UI Implementation Strategy (CRITICAL) -* **Custom Combo Boxes**: Do NOT attempt to use native `QComboBox::down-arrow` CSS for the blue ↕ icon. Windows Qt has rendering issues (white dots/flicker). We use a **stacked overlay** strategy: - * A `QWidget` container holds the `QComboBox`. - * A `QLabel` with `Qt.WA_TransparentForMouseEvents` is positioned on top of the combo's right edge. - * This label has an opaque background (#3b7ee1) to mask the native Windows combo indicator dots. -* **Alignment**: The global fixed width for slot combos is **160px**. The arrow overlay is **20px** wide. - -### 2. Adaptive Theming -* **Real-time Detection**: The app polls the Windows Registry every 2 seconds for theme changes. -* **Centralized CSS**: Most UI colors are defined in `apply_premium_theme` using Python f-strings, allowing instant restyling of all common widgets. -* **Persistent IDs**: Labels and special widgets use `setObjectName` to inherit styles from the global stylesheet, avoiding contrast issues during theme transitions. - -### 3. State Management -* **Sub-Slot Popups**: Tracked via `self.active_popup` in `AmpleMainWindow`. -* **Toggle Logic**: Uses `time.time()` threshold (0.3s) and `id(data)` check in `show_sub_slots()` to prevent the "immediate reopening" bug when clicking the hamburger button to close the popup. - -### 4. Data Processing -* `data_manager.py` handles the heavy lifting of parsing original Ample `.plist` files. -* Slot changes trigger `self.refresh_ui()`, which rebuilds the dynamic slots layout from scratch to handle nested slot dependencies. - -### 5. Known Mantras -* **Visual Parity is King**: Every margin, font size (mostly 11px/12px), and color was cross-referenced with macOS high-res screenshots. -* **Authorship**: This Windows Port is a collaboration between **anomixer** and **Antigravity**. +# Agent Task Audit Log - Ample Windows Port + +## 📅 Session: 2026-08-02 (Session 17) + +### 🎯 Objective: Upstream MAME v0.289 Synchronization +Synchronized AmpleWin with upstream `ksherlock/ample` v0.289 release, updated official MAME download binary URL, and updated machine `.plist` configuration definitions. + +### ✅ Key Achievements: +1. **MAME 0.289 Downloader Upgrade**: + * Updated `mame_downloader.py` download target to official MAME v0.289 64-bit binary release (`mame0289b_x64.exe`). +2. **PowerBook Native Launch (EASC Bug Fixed)**: + * Removed `macpb160`, `macpb165`, `macpb165c`, `macpb180`, `macpb180c` fallback prompt mechanism in `main.py`, as MAME 0.289 officially resolved the EASC audio chip crash bug. All PowerBook models now launch directly using the main MAME 0.289 binary. +3. **ROM Manager Priority & Dragon32/Laser Series Fixes**: + * Reordered download servers in `rom_manager.py` to prioritize CallApple (`https://www.callapple.org/roms/`) with MDK (`https://mdk.cab/download/split/`) as backup failover. + * Integrated `patch_dragon32()` in `DownloadWorker` to auto-merge missing modern MAME 0.289 split ROM files (`dragon_data_ltd_1-0.ic18`, `dragon_data_ltd_1-1.ic17`) when downloading `dragon32.zip`. + * Expanded `custom_roms` fallback array to include Laser 128 series (`las128ex`, `las128e2`, `laser128`, `laser128o`, `laser2c`), ensuring seamless auto-download even if omitted from upstream `roms.plist`. +4. **Machine Profile & ROM Parity**: + * Verified `.plist` machine profile definitions (251 files) updated to MAME 0.289. + * Synchronized all updated `.plist` configurations across monorepo to `AmpleWeb/public/resources/`. + +--- + +## 📅 Session: 2026-06-05 (Session 16) + +### 🎯 Objective: MAME v0.288 Upgrade, PowerBook Fallbacks & AmpleWeb Synchronization +Addressed upstream MAME 0.288 EASC crash bugs, compiled the v0.288-patched Wasm core, and synchronized all 0.288 machine plists and ROM mapping to AmpleWeb frontend. + +### ✅ Key Achievements: +1. **MAME v0.288 Wasm Compile & Deploy**: + * Integrated memory export and EASC patch in `c:\dev\MameWasm` and compiled production Wasm core (`mameample.js` / `mameample.wasm`). + * Compressed and deployed `mame.js` / `mame.wasm.gz` to both `AmpleWeb` and `ampleweb-ai`. +2. **0.288 Machine Configuration Sync**: + * Copied 251 updated `.plist` machine profiles from Core to both web projects. + * Expanded `DRIVER_ROM_MAP` in both `App.tsx` from 158 to 248 entries to fully support new 0.288 models (Amiga A1000/A2000/A500, Atari ST, Lisa, etc.). +3. **EASC Crash Fallback (Core)**: + * Added automatic detection and v0.280/v0.287 fallback launcher mechanism for EASC audio chip Macs in AmpleWin/Linux. +4. **UI Slots Layout Ordering Parity (Core)**: + * Reordered rendering in `AmpleWin` and `AmpleLinux` slots panel. Now, ROM slots (`rom` or `romsize` or description `ROM`/`ROM/RAM`) are rendered directly after the RAM slot, positioning `Disk Drives` properly in the 3rd slot when ROM configuration exists. +5. **Downloader Optimization & SCSI Fix**: + * Prioritized `mdk.cab` split server in `rom_manager.py` and `rom_manager_cli.py` to prevent missing file errors on 0.288+. + * Verified SCSI CD-ROM 2x speed fallback `cdrom_2x` mappings on both frontends to resolve media mount bugs. + +--- + +## 📅 Session: 2026-05-19 (Session 15) + +### 🎯 Objective: Complete Slot Configuration Persistence (MAME Command Line) +Resolved the issue where selecting "None" for a slot in the UI didn't actually disable the device in MAME because empty slot arguments were being omitted from the command line. + +### ✅ Key Achievements: +1. **Command-Line Slot Persistence**: + * Modified `build_args` in `mame_launcher.py` to allow empty string values (e.g. `option is not None` instead of `if option:`). + * This ensures that `-[slot_name] ""` is explicitly passed on the command line, preventing MAME from falling back to its internal defaults. +2. **Parity**: Checked and verified this behavior across both `AmpleWin` and `AmpleLinux` ports, ensuring slots explicitly set to "None" are truly disabled when the emulator launches. + +--- + +## 📅 Session: 2026-05-11 (Session 14) + +### 🎯 Objective: Slot Configuration Consistency Fix +Resolved an issue where slots with defaults could not be set to "None" because UI refreshes would revert them. + +### ✅ Key Achievements: +1. **"None-Aware" Slot Initialization**: + * Modified `initialize_default_slots` to use `slot_name not in self.current_slots`. + * Ensured manual "None" selections are preserved while maintaining automated defaults for new card insertion. +2. **Upstream Compatibility**: Prepared codebase for PR back to original source, ensuring robust slot behavior. + +--- + +## 📅 Session: 2026-05-11 (Session 14) + +### 🎯 Objective: Slot Configuration Parity & "None" Persistence +Resolved a long-standing issue where slots with default equipment could not be set to "None" because UI refreshes would force-revert them to defaults. + +### ✅ Key Achievements: +1. **"None-Aware" Slot Initialization**: + * Modified `initialize_default_slots` in `main.py` to use key existence checks (`if slot_name not in self.current_slots`) instead of truthiness checks. + * This ensures that an empty string selection (`""` or "None") is respected as a deliberate user choice and not overwritten by defaults. +2. **Cross-Platform Alignment**: + * Coordinated this fix across **AmpleWin** and **AmpleLinux**. + * Verified that **AmpleWeb** already correctly handled this logic due to its Object-based option finding mechanism. +3. **Nested Slot Preservation**: + * Ensured that newly appeared sub-slots (e.g., when plugging in a SCSI or CFFA2 card) still automatically load their default devices, maintaining high usability. + +### 🚀 Current Project Status +Slot configuration behavior is now fully consistent across Windows, Linux, and Web ports, accurately respecting "None" selections while preserving automated nested configurations. + +--- + +## 📅 Session: 2026-03-02 (Session 13) + +### 🎯 Objective: Upstream Version Bump & Documentation Maintenance +Focused on updating the project to track MAME 0.286 and simplifying documentation maintainability. + +### ✅ Key Achievements: +1. **Version Bump**: Updated `mame_downloader.py` to point to the latest **MAME 0.286** x64 Windows binary. +2. **Documentation Refactoring**: + * Renamed version-specific screenshot files (e.g. `screenshot-v0.28x.png` to `screenshot.png`) across all platforms. + * Updated `README.md` and `README_tw.md` to use generic "latest version" terminology to prevent the need for manual text updates upon future MAME releases. + +### 🚀 Current Project Status +The Windows Port is functionally tracking MAME 0.286 and documentation is now future-proofed against minor version increments. + +--- + +## 📅 Session: 2026-02-16 (Session 12) + +### 🎯 Objective: Linux Port Spinoff +AmpleWin has successfully served as the foundation for a new Linux port. + +### ✅ Key Achievements: +1. **Port Creation**: + * **AmpleLinux**: Created `AmpleLinux/` directory based on the AmpleWin codebase. + * **Shared DNA**: `data_manager.py` and `rom_manager.py` remain identical, while `main.py` was adapted for Linux (xdg-open, paths, dependencies). + * **Cross-Reference**: Added links to AmpleLinux in the README. + +### 🚀 Current Project Status +The project now supports both Windows (AmpleWin) and Linux (AmpleLinux) natively. + +--- + +## 📅 Session: 2026-02-09 (Session 11) + + +### 🎯 Objective: Upstream Synchronization & Codebase Hygiene +Focused on synchronizing the project with the latest upstream changes from `ksherlock/ample`, ensuring the `roms.plist` database is compliant with the official repository, and cleaning up diverging local branches. + +### ✅ Key Achievements: + +1. **Full Upstream Sync**: + * **Repository Alignment**: Merged latest `upstream/master` changes (4 new commits), bringing in the official fix for **PowerBook Duo 280 (`macpd280`)** and new definitions like **Epson RX-80 (`epson_rx80`)**. + * **Deforking roms.plist**: Discarded local custom modifications to `Ample/Resources/roms.plist`. The file is now byte-for-byte identical to the upstream version, ensuring long-term maintainability. + * **Branch Cleanup**: Removed the stale `fix-missing-roms` branch and closed the associated PR #44, as the upstream author has implemented the necessary fixes natively. + +2. **AmpleWin Verification**: + * **Compatibility Verified**: Confirmed that `AmpleWin` correctly parses the new upstream `roms.plist` without errors. + * **ROM Status**: Validated that `macpd280` is now natively supported for auto-download via the new upstream definitions. Note: Custom definitions for *Pravetz* and *TK3000* are no longer in `roms.plist` but remain playable if ROMs are manually provided. +3. **Deployment & Distribution**: + * **Refactor**: Renamed `mame_bin` to `mame` across the codebase for better standards compliance. + * **Portable EXE**: Created `build_exe.bat` using **PyInstaller (OneDir)** to package the application into a standalone executable. + * **Path Logic**: Updated `main.py` with robust `sys.frozen` detection to ensure resources and downloads work correctly in both Dev and Frozen environments. + * **Documentation**: Added build instructions to READMEs. + +### 🚀 Current Project Status +The codebase is now in a "Clean Slate" state. `master` is fully synced with upstream, with `AmpleWin` serving as a strictly additive extension. + +## 📅 Session: 2026-02-02 (Session 10) + +### 🎯 Objective: ROM Library Expansion & Advanced Slot Emulation +Focused on expanding the supported ROM library, implementing a robust failover download mechanism, and perfecting nested slot configuration logic for SCSI peripherals. + +### ✅ Key Achievements: + +1. **ROM Library & Search Expansion**: + * **New System Support**: Added missing ROM definitions for **Macintosh PowerBook Duo 280/280c**, **Pravetz 8C**, and **TK3000 //e**. + * **Search Parity**: Fully synchronized hardware definitions with the latest macOS release, including secondary Pravetz models (`82`, `8M`). + +2. **Robust ROM Download Failover**: + * **Prioritized Multi-Server Support**: Implemented a transparent failover mechanism in `rom_manager.py`. The downloader now prioritizes **callapple.org** for maximum stability and automatically falls back to **mdk.cab** for Apple II clones and split sets unreachable on the primary server. + * **Status Integrity**: Fixed a bug in the download progress counter to ensure accurate success/failure reporting in the UI. + +3. **Advanced Slot & Media Emulation**: + * **SCSI Sub-Peripheral Detection**: Rewrote `aggregate_media` to recursively detect devices attached to slot cards (e.g., finding the CD-ROM and Hard Disk on an Apple IIgs SCSI card). + * **Nested Slot Defaults**: Implemented automatic initialization for sub-slots. Plugging in a SCSI card now automatically populates its sub-slots with default devices (CD-ROM at ID 1, Hard Disk at ID 6), matching Mac parity. + * **Sub-Slot UI Parity**: Updated the "Hamburger" popup to show all configurable sub-slots, not just those with media, giving users full control over complex hardware chains. + * **Aggregator Optimization**: Refined the media scanner to ignore the global "device library" at the root level, preventing UI clutter and double-counting of unmapped drives. + +### 🚀 Current Project Status +The Windows Port now offers superior hardware configuration capabilities. Complex SCSI and SmartPort chains are handled automatically, and the ROM acquisition system is more reliable than ever. + +## 📅 Session: 2026-02-02 (Session 9) + +### 🎯 Objective: Upstream Synchronization & Feature Parity (MAME 0.286) +Focused on synchronizing with the upstream Ample (macOS) v0.286 release, updating the core emulator backend, and implementing new UI search capabilities. + +### ✅ Key Achievements: + +1. **Upstream Repository Synchronization**: + * **Merge & Push**: Successfully merged latest commits from `upstream/master` (ksherlock/ample). + * **Resource Alignment**: Synchronized latest hardware definitions and slot configurations from original project. + * **A2retroNET Integration**: Inherited support for a2retronet hardware, enabling up to 8 SmartPort disk images. + +2. **MAME Core Update**: + * **Version Upgrade**: Updated `mame_downloader.py` to point to the official **MAME 0.286** Windows x64 binary. + * **Download Engine Parity**: Users can now auto-download the latest MAME core directly from the Settings menu. + +3. **ROM Manager Enhancements**: + * **Search Filter**: Implemented a real-time search field in the `RomManagerDialog` header (matching macOS feature parity). + * **Filtering Logic**: Updated `refresh_list` to filter ROMs by description or shortcode, allowing users to quickly find specific system firmwares. + +### 🚀 Current Project Status +The Windows Port is now fully synchronized with Ample (macOS) v0.286 resources. It supports the latest MAME core and offers improved ROM management tools. + +--- + + +## 📅 Session: 2026-01-24 (Session 8) + +### 🎯 Objective: Path robustness & UI Interactivity +Focused on fixing "No such file" errors when launching custom ROM paths and improving the user experience for file selection in secondary tabs. + +### ✅ Key Achievements: + +1. **Command Line Robustness**: + * **Quote Handling**: Patched the `shlex` logic in `main.py` to handle Windows paths correctly. Manually stripping outer quotes ensures `subprocess` doesn't double-escape them, fixing the critical "No such file or directory" error when launching files with spaces in their path. + +2. **File Selection UX**: + * **A/V Path Selectors**: Implemented `mousePressEvent` on the A/V tab input fields (AVI, WAV, VGM). Clicking these text boxes now opens a native `QFileDialog` ("Save As") with appropriate extension filters, saving users from manual typing. + * **Path Normalization**: Updated the "Shared Directory" directory selector to automatically normalize paths (e.g., converting `/` to `\`), ensuring visual consistency and compatibility with Windows command line expectations. + +### 🚀 Current Project Status +The application is now highly resilient to typical Windows path complexities. Users can easily select output destinations and shared folders without worrying about path syntax errors. + +--- + +## 📅 Session: 2026-01-22 (Session 7) + +### 🎯 Objective: User Freedom & flexible Command Control +Focused on giving the user complete control over the MAME launch command and ensuring a cleaner default state for machine slots. + +### ✅ Key Achievements: + +1. **Editable Command Console**: + * **Unlocked Preview**: The "Command Preview" text box is no longer read-only. + * **Source of Truth**: The Launch button now executes *exactly* what is typed in this box. Users can manually add, remove, or edit arguments (e.g., adding `-verbose` or removing unwanted flags) before launching. + +2. **Launch Engine Integrity**: + * **Absolute Path Resolution**: Implemented `shlex` parsing to read the user's manual command string. It automatically detects the command (`mame` or `mame-vgm`) and resolves it to the absolute system path to fix `[WinError 2]` on Windows. + * **VGM Pathing**: Logic retains awareness of VGM Mod capabilities even when launching from a custom text string. + +3. **Cleaner Default State**: + * **Slot Neutrality**: Removed the aggressive fallback logic that forced the first available option for slots without a default value. + * **Phantom Args Clarified**: This eliminates confusing arguments like `-fdc:0 525` appearing automatically, ensuring MAME starts with its internal defaults unless the local configuration explicitly overrides them. + +### 🚀 Current Project Status +The app now respects "Power User" workflows. You can use the UI for quick setup, then fine-tune the command line manually. The codebase structure is being finalized. + +--- + +## 📅 Session: 2026-01-21 (Session 6) + +### 🎯 Objective: VGM Mod Stability & Extraction Safety +Focused on fixing critical bugs in the VGM recording workflow, ensuring extraction safety, and improving UI feedback for the modded binary. + +### ✅ Key Achievements: + +1. **VGM Mod Extraction Safety**: + * **Anti-Overwrite Workflow**: Implemented a temporary directory strategy (`_vgm_temp`) during VGM Mod extraction. This ensures that the mod's `mame.exe` (v0.280) never accidentally overwrites the main official `mame.exe` (v0.284). + * **Atomic Renaming**: The modded binary is now safely extracted, renamed to `mame-vgm.exe`, and moved to the destination in a single, non-destructive step. + +2. **Command Line & UI Parity**: + * **Explicit Recording Toggle**: Fixed a bug where `-vgmwrite 1` was missing from the console launch command. Recording is now correctly activated when using the modded binary. + * **Dynamic UI Preview**: The 4-line console preview now correctly displays `mame-vgm` as the target executable when VGM recording is enabled and the mod is detected, matching actual runtime behavior. + +3. **Thread & Lifecycle Stability**: + * **Remove Safety**: Fixed a `ValueError: list.remove(x): x not in list` in the worker cleanup logic, ensuring the thread-safe management of background tasks even if signals fire twice. + * **Worker Refactoring**: Rewrote the `VgmModDownloadWorker` and `VgmPostProcessWorker` logic to handle edge cases in file movement and process termination more gracefully. + +4. **Shared Directory & UI Refinement**: + * **Logic Completion**: Fixed a missing link in the launch engine where the "Shared Directory" path from the UI wasn't being passed to the actual MAME process. + * **Standardized Argument**: Updated from `-share` to the official `-share_directory` for maximum compatibility. + * **UI Bugfix**: Removed duplicate "Paths" tab initialization in the main window. + * **Click-to-Browse**: Implemented a pop-up directory selector when clicking the Shared Directory path box, replacing manual entry. + +5. **Smart Slot Validation (Mac Parity)**: + * **Disabled State Support**: Ported the `disabled` logic from the Mac version. Slot options that are technically defined but marked as unsupported in the plist (e.g., specific SCSI cards on Apple IIgs) are now visually grayed out and unselectable in the dropdown menu. + * **Prevention**: Prevents users from accidentally selecting incompatible hardware configurations that would cause MAME to crash or behave unexpectedly. + +### 🚀 Current Project Status +The VGM and Shared Directory workflows are now "Production Ready." The UI has reached a high level of fidelity with the Mac original, including subtle behaviors like smart slot validation and intuitive path selection. + +--- + +## 📅 Session: 2026-01-21 (Session 5) + +### 🎯 Objective: MAME Core Logic & Command Line Robustness +Focused on improving the reliability of the MAME launch engine, specifically regarding dynamic slot media (CFFA2), multi-drive support, and shell-safe command construction. + +### ✅ Key Achievements: + +1. **Relaxed Parameter Validation**: + * **Dynamic Media Parity**: Removed strict `listmedia` validation in `MameLauncher` to allow secondary media types (like `hard1`, `hard2`) that only appear when a specific card (e.g., CFFA2) is plugged in. + * **Internal Filter**: Implemented logic to automatically skip internal MAME node names starting with a colon (e.g., `-:prn`) to prevent "unknown option" errors. + +2. **Multi-Drive & Storage Support**: + * **Capping Removal**: Fixed a self-imposed limitation in `main.py` that forced `hard`, `cdrom`, and `cassette` counts to 1. + * **CFFA2 Ready**: AmpleWin now correctly supports machines/cards with multiple hard drives (`-hard1`, `-hard2`). + +3. **Shell Integrity & Quoting**: + * **Robust Quoting**: Integrated `subprocess.list2cmdline` for both the UI Command Preview and the actual process execution. + * **Space Handling**: Guaranteed that file paths containing spaces are automatically wrapped in quotes (`""`), preventing launch failures on Windows. + * **Path Normalization**: Implemented `os.path.normpath` for all MAME arguments (`-hard`, `-rompath`, etc.), ensuring consistent Windows-style backslashes (`\`). + * **Command Line Streamlining**: Automated `mame.ini` generation via `mame -cc` upon MAME detection. This allows removing redundant path arguments (`-hashpath`, `-artpath`, etc.) from the command line, resulting in a much cleaner and more readable preview. + * **VGM Support (Advanced)**: Since modern MAME removed VGM support, AmpleWin implements a robust background workflow to download and configure the **MAME-VGM Mod (v0.280)**. It uses a non-destructive extraction process (`mame-vgm.exe`) to preserve your main MAME core while restoring high-fidelity music recording, and automatically moves the resulting `.vgm` files to the user's desired path upon MAME exit. + +4. **Resolution Scaling & Visual Parity**: + * **Window Mode Scaling**: Implemented `-resolution` generation for scaling modes (2x, 3x, 4x) and **`-nomax`** for **Window 1x** mode to ensure consistent default sizing. + * **Aspect Ratio Heuristic**: Integrated a 4:3 correction heuristic for non-square pixel machines (e.g., Apple II: 560x192 -> 1120x840 at 2x) to match macOS Ample behavior. + * **Square Pixel Mode**: Implemented integer scaling for Apple II machines (e.g., **1120x768** at 2x) while adding **`-nounevenstretch`** to prevent pixel shimmering and maintain clarity. + * **UI Expansion**: Added "Window 4x" option to the Video settings tab. + * **Disk Sound Effects Integration**: Linked the "Disk Sound Effects" checkbox to the `-nosamples` argument, allowing MAME samples to load when sound effects are enabled. + * **CPU Speed & Throttle UI Alignment**: Merged the Throttle checkbox into the CPU Speed dropdown as a "No Throttle" option, perfectly matching the original macOS Ample interface and logic. + +5. **BGFX Effect Synchronization**: + * **Enhanced Effects List**: Updated the video effects selection to support a standardized set of BGFX screen chains: **Unfiltered, HLSL, CRT Geometry, CRT Geometry Deluxe, LCD Grid, and Fighters**. + * **Chain Mapping**: Implemented precise mapping between UI selection and MAME's `-bgfx_screen_chains` internal identifiers. + +### 🚀 Current Project Status +The MAME launch engine is now significantly more robust and "intelligent." It handles complex slot configurations and multi-disk setups like CFFA2 without manual parameter tweaking, while maintaining a clean, error-free command line preview. + +--- + +## 📅 Session: 2026-01-19 (Session 4) + +### 🎯 Objective: Real-time Adaptive Theming & UI Resilience +Focused on implementing a native Windows theme detection engine and ensuring 100% visibility/aesthetic parity across both Light and Dark modes without requiring application restarts. Refined the command console for long parameter strings. + +### ✅ Key Achievements: + +1. **Adaptive Theme Engine**: + * **Registry-Level Detection**: Implemented `winreg` polling to detect `AppsUseLightTheme` changes in real-time. + * **Live Synchronization**: Added a 2-second polling timer (`QTimer`) that triggers a global UI restyle, allowing the app to switch between Light and Dark modes on-the-fly. + * **Cross-Window Propagation**: Ensured theme changes flow correctly into child dialogs (ROM Manager) and dynamic overlays (Software Search, Sub-slot popups). + +2. **UI Polish & Visibility Fixes**: + * **Light Mode "Ghosting" Elimination**: Fixed unreadable text by moving critical UI colors (Slot Labels, Media Headers) from hardcoded Python strings to the global adaptive stylesheet. + * **Themed Popups**: Rewrote `SoftwarePopup` and sub-slot bubble painting to dynamically adjust background colors and "triangle" indicators based on the system theme. + * **ROM Manager Parity**: Fully themed the ROM download dialog, ensuring status labels (found/missing) maintain high contrast in both modes. + +3. **Command Console Expansion**: + * **Multi-line Preview**: Replaced the single-line `QLineEdit` with a 4-line `QTextEdit` console footer. + * **Parameter Visibility**: This allows users to review the entire MAME command line, including long software list paths and slot configurations, without horizontal scrolling. + +4. **Stability & Bug Squashing**: + * **ROM Manager Reliability**: Corrected `@Slot` decorators and converted the dialog to `.exec()` (Modal) to prevent interaction conflicts. + * **Logic Errors**: Fixed several `NameError` bugs in the rendering engine and addressed stylesheet inheritance issues that caused transparent list views. +5. **Visual Documentation & Networking Guide**: + * **README Screenshots**: Embedded `screenshot-v0.284.png` in READMEs to match original aesthetics. + * **Networking Parity Section**: Added a specialized section in READMEs explaining **Npcap** requirements for Uthernet II simulation, clarifying that the macOS "Fix Permissions" is unnecessary on Windows. + +### 🚀 Current Project Status +The Windows Port is now a "State-of-the-Art" adaptive application. It feels native on both Light and Dark Windows setups, offers robust command line verification, and maintains the premium "Apple-inspired" aesthetic consistently. + +--- + +## 📅 Session: 2026-01-19 (Session 3) + +### 🎯 Objective: Documentation Standardization & UI Finalization +This session focused on finalizing the project's documentation (internationalization), organizing the file structure to stay clean relative to the upstream repository, and refining the primary toolbar functions. + +### ✅ Key Achievements: + +1. **Documentation Internationalization**: + * **Dual-Language Support**: Created `README.md` (English) and `README_tw.md` (Traditional Chinese) in the `AmpleWin` directory. + * **Mutual Linking**: Implemented language-switching headers in both README files for a professional GitHub experience. + * **Parity Verification**: Deep-dived into original macOS Objective-C source code to ensure the comparison table is 100% accurate regarding ROM downloading, bookmarked machine persistence, and technical differences. + +2. **UI Finalization & Utility Tools**: + * **Ample Dir Integration**: Renamed "Disk Images" to "📂 Ample Dir". It now acts as a shortcut to open the application directory in Windows Explorer. + * **Redirected Help**: Linked the "📖 Help" button directly to the official project GitHub sub-folder for instant user support. + +3. **Project Structure Hygiene**: + * **Namespace Isolation**: Relocated all Windows-specific overhead files (`README_tw.md`, `AmpleWin.bat`, `requirements.txt`, `Agent.md`) into the `AmpleWin` subdirectory. + * **Upstream Integrity**: Restored the root directory to its original state, ensuring a clean "1 commit ahead" status for easy upstream maintenance. + * **Script Resilience**: Updated `AmpleWin.bat` to handle the new directory structure, allowing execution directly from within the `AmpleWin` folder. + +### 🚀 Current Project Status +The Windows Port is now a "ready-to-ship" localized product. The documentation is verified against the original Mac source code, the UI buttons serve practical Windows-specific needs, and the project stays respectful to the original repository's file structure. + +--- + +## 📅 Session: 2026-01-18 (Session 2) + +### 🎯 Objective: Deployment, Performance & Path Robustness +This session focused on making the application portable, optimizing the download engine for "instant" ROM acquisition, and improving the first-run user experience with guided setup. + +### ✅ Key Achievements: + +1. **Deployment & Portability**: + * **Auto-Launcher**: Created `ample_win.bat` to automate dependency installation and app execution. + * **Dynamic Paths**: Replaced hardcoded absolute paths with a robust search algorithm that detects the `Ample/Resources` folder relative to the script location. + * **Environment Isolation**: Forced MAME working directory to `mame_bin`, ensuring `nvram`, `cfg`, and `diff` folders stay within the emulator directory and out of the project root. + +2. **Explosive Download Engine**: + * **Threading Mastery**: Transitioned to `QThreadPool` for manageable concurrency. + * **Performance Leap**: Increased parallel download threads from 1 to **50**. + * **Small File Optimization**: For ROM files (<64KB), switched from streaming to direct `requests.content` I/O, resulting in near-instant mass downloads. + * **Anti-Throttling**: Added browser-masking `User-Agent` headers. + +3. **User Experience (UX)**: + * **Startup Wizard**: Implemented sequential logic: Check MAME -> Guided Download -> Check ROMs -> Guided Download. + * **Sticky Software (Smart Carry-over)**: + * Selections and filters now persist across compatible machines. + * **Compatibility Logic**: Automatically clears selection if the new machine doesn't support the current software list. + * **Full Name Display**: The search box now displays the full, descriptive software name instead of the short MAME ID. + * **UI Cleanliness**: Software lists stay collapsed during machine switches for a sleeker look. + * **Windows 10 Fixes**: Applied global CSS overrides for `QMessageBox` and `QDialog` to fix unreadable grey-on-white text issues on Windows 10. + +4. **Project Hygiene**: + * Updated `.gitignore` to exclude MAME runtime artifacts (`nvram/`, `cfg/`, `sta/`, etc.). + * Updated `README_win.md` with the new one-click launch instructions. + +### 🚀 Current Project Status +Ample Windows is now highly portable and user-friendly. The download system is exceptionally fast, and the environment stays clean during emulation sessions. + +## 📅 Session: 2026-01-18 (Session 1) + +### 🎯 Objective: Software List Integration & Final UI Polish +This session focused on implementing the MAME Software List feature and refining the UI to achieve 100% aesthetic parity with the macOS version, including functional improvements to the MAME launch engine for Windows. + +### ✅ Key Achievements: + +1. **Software List Feature**: + * **XML Parsing**: Enhanced `DataManager` to parse MAME's `hash/*.xml` files. + * **Intelligent Discovery**: Implemented a search-based software browser with autocomplete-style show/hide logic. + * **Auto-Detection**: Integrated software list selection into the MAME launch command with optimized argument ordering. + +2. **MAME Launch Engine**: + * **Argument Ordering**: Fixed Windows-specific software list resolution issues by placing software list items immediately after the machine name. + * **Path Isolation**: Standardized `-hashpath`, `-bgfx_path`, and `-rompath` to be relative to the application's `mame_bin` directory. + * **Resource Management**: Centralized ROM storage to `mame_bin\roms`. + +3. **UI Aesthetic Refinement**: + * **Apple Launch Button**: Replicated the Mac-style 🍎 icon inside the Launch button with left-aligned icon and right-aligned text. + * **Full-Width Console**: Moved the Command Preview to a full-width footer with a console-style (black background, monospace) styling. + * **Clean Mode**: Removed "Use Samples" checkbox and hardcoded `-nosamples` for authenticity. + * **Proportional Layout**: Expanded the options area to comfortably display long software names (60+ characters). + +4. **Stability & Initialization**: + * **Graceful Shutdown**: Improved thread termination logic in `closeEvent`. + * **Safe Initialization**: Fixed attribute and name errors in `DataManager` and `AmpleMainWindow` during early startup phases. + +### 🚀 Current Project Status +The Windows Port is now functionally on par with the original Mac version, including the Software List feature. The UI is pixel-perfect and the launch engine is robust against common Windows path and argument pitfalls. + +--- + +## Handover Notes for Future Agents + +### 1. UI Implementation Strategy (CRITICAL) +* **Custom Combo Boxes**: Do NOT attempt to use native `QComboBox::down-arrow` CSS for the blue ↕ icon. Windows Qt has rendering issues (white dots/flicker). We use a **stacked overlay** strategy: + * A `QWidget` container holds the `QComboBox`. + * A `QLabel` with `Qt.WA_TransparentForMouseEvents` is positioned on top of the combo's right edge. + * This label has an opaque background (#3b7ee1) to mask the native Windows combo indicator dots. +* **Alignment**: The global fixed width for slot combos is **160px**. The arrow overlay is **20px** wide. + +### 2. Adaptive Theming +* **Real-time Detection**: The app polls the Windows Registry every 2 seconds for theme changes. +* **Centralized CSS**: Most UI colors are defined in `apply_premium_theme` using Python f-strings, allowing instant restyling of all common widgets. +* **Persistent IDs**: Labels and special widgets use `setObjectName` to inherit styles from the global stylesheet, avoiding contrast issues during theme transitions. + +### 3. State Management +* **Sub-Slot Popups**: Tracked via `self.active_popup` in `AmpleMainWindow`. +* **Toggle Logic**: Uses `time.time()` threshold (0.3s) and `id(data)` check in `show_sub_slots()` to prevent the "immediate reopening" bug when clicking the hamburger button to close the popup. + +### 4. Data Processing +* `data_manager.py` handles the heavy lifting of parsing original Ample `.plist` files. +* Slot changes trigger `self.refresh_ui()`, which rebuilds the dynamic slots layout from scratch to handle nested slot dependencies. + +### 5. Known Mantras +* **Visual Parity is King**: Every margin, font size (mostly 11px/12px), and color was cross-referenced with macOS high-res screenshots. +* **Authorship**: This Windows Port is a collaboration between **anomixer** and **Antigravity**. diff --git a/AmpleWin/README.md b/AmpleWin/README.md index 64ea166..9477d36 100644 --- a/AmpleWin/README.md +++ b/AmpleWin/README.md @@ -1,108 +1,111 @@ -# AmpleWin - Windows Port (Legacy Apple Emulator Frontend) - -[English](README.md) | [繁體中文](README_tw.md) - -This is a precision port of the macOS native [Ample](https://github.com/ksherlock/ample) project to the Windows platform. - -> [!TIP] -> **Linux User?** Check out the [AmpleLinux](../AmpleLinux/) 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. AmpleWin (Windows) Comparison - -| Feature | Ample (macOS Native) | AmpleWin (Windows Optimized) | Optimization & Notes | -| :--- | :--- | :--- | :--- | -| **Language** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | Independent development, **zero changes to Mac source code** | -| **Installation** | .dmg Image / Homebrew | **Portable (+ .bat Auto-Config)** | One-click setup for Python and dependencies via `AmpleWin.bat` | -| **UI** | Native macOS Components | **1:1 Pixel-Perfect QSS Replica** | Replicates Mac aesthetic, with **Adaptive Light/Dark Theme** support | -| **MAME Integration** | Built-in Custom Core or Self-selected | **Official Core Download or Self-selected** | Users can update MAME independently or download via app | -| **Machine Selection** | Supports Default Bookmark | **Full Session Persistence (Auto-Load)** | Auto-loads last used machine state without manual bookmarking | -| **Software List Perf** | Synchronous Loading (Full XML) | **Deferred Loading** | **Major Optimization**: Instant machine switching, loads on search | -| **Software Search UI** | Standard Pop-up List | **Smart Overlay Search** | Supports real-time search and full descriptive names without UI shifts | -| **ROM Download** | Supports Auto-Download | **High-Speed Failover Engine** | **Major Optimization**: Multi-server failover (callapple + mdk.cab) | -| **Validation** | Relies on Static .plist | **Live Parameter Validation** | **Major Optimization**: Validates against MAME to prevent launch crashes | -| **Video Support** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan / D3D11 / D3D12** | Optimized for Windows with multi-generational DirectX support | -| **Networking** | Apple VMNet Framework | **Npcap (WinPcap) / PCAP** | Standard networking via Npcap (no root fix needed) | -| **Operating Logic** | Sticky Software Selection | **Sticky Software Selection** | Preserves compatible software selection when switching machines | - -## 🌟 Key Features - -### 🍏 Faithful Mac Experience (Feature Parity) -* **Visual Precision**: - * **Resolution Scaling**: Precision support for **Window 1x-4x** modes with machine-specific aspect ratio heuristics (e.g., Apple II 4:3 correction). - * **Square Pixels**: Specialized integer-scaling mode (e.g., 1120x768) to eliminate pixel shimmering. -* **Software Library**: - * **Smart Filtering**: Automatically identifies supported media types (flop1, flop2, cass...) to match machine capabilities. - * **Search Overlay**: Integrated Mac-style search with auto-completion and full descriptive names. - * **Compatibility Check**: Options marked as `disabled` in property lists (e.g. incompatible SCSI cards) are now correctly grayed out and unselectable, matching Mac behavior. -* **Advanced Slot Emulation**: Full support for nested sub-slots (e.g. SCSI cards). - * **Automated Defaults**: Automatically initializes default devices (CD-ROM/Hard Disk) upon card selection. - * **Slot Consistency**: Improved logic to respect "None" (empty) selections across UI refreshes, matching the high standards of the native macOS port. -* **ROM Management**: - * **Search Filter**: Real-time searching in the ROM manager window to quickly find system firmwares. - * **Download Failover**: Automatic multi-server acquisition (callapple + mdk.cab) with transparent failover for maximum stability. - * **Extended Library**: Expanded support for PowerBook Duo 280, Pravetz 8C, TK3000, and more. - * **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.exe`) or VGM Mod (`mame-vgm.exe`), or offers to download the v0.280 fallback copy. -* **Shared Directory**: Full parity with the Mac version, allowing direct host-to-emulator file sharing via the `-share_directory` argument. (Includes click-to-browse support). -* **VGM Support (Advanced)**: Since modern MAME removed VGM support, AmpleWin implements a robust background workflow to download and configure the **MAME-VGM Mod (v0.280)**. It uses a non-destructive extraction process (`mame-vgm.exe`) to preserve your main MAME core while restoring high-fidelity music recording. - -### 🪟 Windows-Specific Optimizations -* **Performance**: - * **Concurrent Downloading**: Multi-threaded system for high-speed ROM acquisition. - * **Clean Workspace**: All MAME side-car files (nvram, cfg, sta) are strictly isolated within the `mame` directory. - * **Deferred XML Loading**: Major optimization for instant machine switching and search response. -* **UI Enhancements**: - * **Adaptive Theme**: Real-time synchronization with Windows Light/Dark system theme. - * **Command Preview**: Real-time 4-line console preview to monitor exactly what parameters are being passed to MAME. - * **Smart Path Handling**: Native file/folder selectors for A/V output and Shared Directories, with automatic path normalization (converting `/` to `\`) for maximum Windows compatibility. -* **Flexible Backend**: Full support for BGFX, OpenGL, Vulkan, and **DirectX 11/12** out of the box. - -## 🛠️ Quick Start - -1. **Launch Ample**: - Enter the **`AmpleWin`** folder and run **`AmpleWin.bat`**. - * The script will check the Python environment, install dependencies, and start the app. -2. **Fast Deployment**: - * Go to **⚙️ Settings** -> Click **Download MAME** to auto-configure the emulator. - * Click **🎮 ROMs** to download system firmware. - * Click **📂 Ample Dir** to quickly open the local application folder. -3. **Start playing**: - * Select a machine from the left panel. - * **Double-click** the machine name or click **Launch MAME** to start. - -## 🌐 Networking (Advanced) - -To simulate networking hardware like **Uthernet II**, Windows requires [Npcap](https://nmap.org/npcap/) (install in "WinPcap compatible mode"). Unlike the macOS version, no "Fix Permissions" is required as Windows handles hardware access via drivers. - -## 📂 Project Structure - -| File/Directory | Description | -| :--- | :--- | -| **`AmpleWin.bat`** | **Start Here**. Auto-setup script (installs Python deps & runs app). | -| `build_exe.bat` | **Packaging**. Creates a `dist` portable EXE folder using PyInstaller. | -| `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` | Automated MAME / VGM Mod downloader and extractor. | -| `mame/` | Isolated directory for MAME executable, ROMs, and config files. | -| `Agent.md` | Development log and session history. | - -## 📦 Building from Source (Portable EXE) - -If you want to create a standalone executable for distribution: - -1. Run `build_exe.bat` in the `AmpleWin` directory. -2. The script will automatically install PyInstaller, package the application, and copy necessary resources. -3. The output will be in `AmpleWin\dist\AmpleWin`. -4. Copy the entire `AmpleWin` folder to any location. It is fully **portable** and does not require Python to run. - -## 📝 Acknowledgments - -* Original macOS version developer: [Kelvin Sherlock](https://github.com/ksherlock) -* **Windows Port Developers: anomixer + Antigravity**: Dedicated to providing the ultimate Apple II / Macintosh emulation experience on Windows. +# AmpleWin - Windows Port (Legacy Apple Emulator Frontend) + +[English](README.md) | [繁體中文](README_tw.md) + +This is a precision port of the macOS native [Ample](https://github.com/ksherlock/ample) project to the Windows platform. + +> [!TIP] +> **Linux User?** Check out the [AmpleLinux](../AmpleLinux/) 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. AmpleWin (Windows) Comparison + +| Feature | Ample (macOS Native) | AmpleWin (Windows Optimized) | Optimization & Notes | +| :--- | :--- | :--- | :--- | +| **Language** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | Independent development, **zero changes to Mac source code** | +| **Installation** | .dmg Image / Homebrew | **Portable (+ .bat Auto-Config)** | One-click setup for Python and dependencies via `AmpleWin.bat` | +| **UI** | Native macOS Components | **1:1 Pixel-Perfect QSS Replica** | Replicates Mac aesthetic, with **Adaptive Light/Dark Theme** support | +| **MAME Integration** | Built-in Custom Core or Self-selected | **Official Core Download or Self-selected** | Users can update MAME independently or download via app | +| **Machine Selection** | Supports Default Bookmark | **Full Session Persistence (Auto-Load)** | Auto-loads last used machine state without manual bookmarking | +| **Software List Perf** | Synchronous Loading (Full XML) | **Deferred Loading** | **Major Optimization**: Instant machine switching, loads on search | +| **Software Search UI** | Standard Pop-up List | **Smart Overlay Search** | Supports real-time search and full descriptive names without UI shifts | +| **ROM Download** | Supports Auto-Download | **High-Speed Failover Engine** | **Major Optimization**: Multi-server failover (callapple + mdk.cab) | +| **Validation** | Relies on Static .plist | **Live Parameter Validation** | **Major Optimization**: Validates against MAME to prevent launch crashes | +| **Video Support** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan / D3D11 / D3D12** | Optimized for Windows with multi-generational DirectX support | +| **Networking** | Apple VMNet Framework | **Npcap (WinPcap) / PCAP** | Standard networking via Npcap (no root fix needed) | +| **Operating Logic** | Sticky Software Selection | **Sticky Software Selection** | Preserves compatible software selection when switching machines | + +## 🌟 Key Features + +### 🍏 Faithful Mac Experience (Feature Parity) +* **Visual Precision**: + * **Resolution Scaling**: Precision support for **Window 1x-4x** modes with machine-specific aspect ratio heuristics (e.g., Apple II 4:3 correction). + * **Square Pixels**: Specialized integer-scaling mode (e.g., 1120x768) to eliminate pixel shimmering. +* **Software Library**: + * **Smart Filtering**: Automatically identifies supported media types (flop1, flop2, cass...) to match machine capabilities. + * **Search Overlay**: Integrated Mac-style search with auto-completion and full descriptive names. + * **Compatibility Check**: Options marked as `disabled` in property lists (e.g. incompatible SCSI cards) are now correctly grayed out and unselectable, matching Mac behavior. +* **Advanced Slot Emulation**: Full support for nested sub-slots (e.g. SCSI cards). + * **Automated Defaults**: Automatically initializes default devices (CD-ROM/Hard Disk) upon card selection. + * **Slot Consistency**: Improved logic to respect "None" (empty) selections across UI refreshes, matching the high standards of the native macOS port. +* **ROM Management**: + * **Search Filter**: Real-time searching in the ROM manager window to quickly find system firmwares. + * **Download Failover**: CallApple server primary acquisition with MDK failover support, featuring automated `dragon32` split ROM patching and full Laser 128 series firmware compatibility. + * **Extended Library**: Expanded support for PowerBook Duo 280, Pravetz 8C, TK3000, and more. + * **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 the Mac version, allowing direct host-to-emulator file sharing via the `-share_directory` argument. (Includes click-to-browse support). +* **VGM Support (Advanced)**: Since modern MAME removed VGM support, AmpleWin implements a robust background workflow to download and configure the **MAME-VGM Mod (v0.280)**. It uses a non-destructive extraction process (`mame-vgm.exe`) to preserve your main MAME core while restoring high-fidelity music recording. + +### 🪟 Windows-Specific Optimizations +* **Performance**: + * **Concurrent Downloading**: Multi-threaded system for high-speed ROM acquisition. + * **Clean Workspace**: All MAME side-car files (nvram, cfg, sta) are strictly isolated within the `mame` directory. + * **Deferred XML Loading**: Major optimization for instant machine switching and search response. +* **UI Enhancements**: + * **Adaptive Theme**: Real-time synchronization with Windows Light/Dark system theme. + * **Command Preview**: Real-time 4-line console preview to monitor exactly what parameters are being passed to MAME. + * **Smart Path Handling**: Native file/folder selectors for A/V output and Shared Directories, with automatic path normalization (converting `/` to `\`) for maximum Windows compatibility. +* **Flexible Backend**: Full support for BGFX, OpenGL, Vulkan, and **DirectX 11/12** out of the box. + +## 🛠️ Quick Start + +1. **Launch Ample**: + Enter the **`AmpleWin`** folder and run **`AmpleWin.bat`**. + * The script will check the Python environment, install dependencies, and start the app. +2. **Fast Deployment**: + * Go to **⚙️ Settings** -> Click **Download MAME** to auto-configure the emulator. + * Click **🎮 ROMs** to download system firmware. + * Click **📂 Ample Dir** to quickly open the local application folder. +3. **Start playing**: + * Select a machine from the left panel. + * **Double-click** the machine name or click **Launch MAME** to start. + +## 🌐 Networking (Advanced) + +To simulate networking hardware like **Uthernet II**, Windows requires [Npcap](https://nmap.org/npcap/) (install in "WinPcap compatible mode"). Unlike the macOS version, no "Fix Permissions" is required as Windows handles hardware access via drivers. + +## 📂 Project Structure + +| File/Directory | Description | +| :--- | :--- | +| **`AmpleWin.bat`** | **Start Here**. Auto-setup script (installs Python deps & runs app). | +| `build_exe.bat` | **Packaging**. Creates a `dist` portable EXE folder using PyInstaller. | +| `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` | Automated MAME / VGM Mod downloader and extractor. | +| `mame/` | Isolated directory for MAME executable, ROMs, and config files. | +| `Agent.md` | Development log and session history. | + +## 📦 Building from Source (Portable EXE) + +If you want to create a standalone executable for distribution: + +1. Run `build_exe.bat` in the `AmpleWin` directory. +2. The script will automatically install PyInstaller, package the application, and copy necessary resources. +3. The output will be in `AmpleWin\dist\AmpleWin`. +4. Copy the entire `AmpleWin` folder to any location. It is fully **portable** and does not require Python to run. + +## 📝 Acknowledgments + +* Original macOS version developer: [Kelvin Sherlock](https://github.com/ksherlock) +* **Windows Port Developers: anomixer + Antigravity**: Dedicated to providing the ultimate Apple II / Macintosh emulation experience on Windows. + +--- +*Disclaimer: AmpleWin 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.* diff --git a/AmpleWin/README_tw.md b/AmpleWin/README_tw.md index 69f597e..4759b8c 100644 --- a/AmpleWin/README_tw.md +++ b/AmpleWin/README_tw.md @@ -1,108 +1,111 @@ -# AmpleWin - Windows Port (Legacy Apple Emulator Frontend) - -[English](README.md) | [繁體中文](README_tw.md) - -這是一個將 macOS 原生 [Ample](https://github.com/ksherlock/ample) 專案精準移植至 Windows 平台的版本。 - -> [!TIP] -> **Linux 使用者？** 請參考 [AmpleLinux](../AmpleLinux/) Linux 移植版。 - - -![](screenshot.png) - -> [!IMPORTANT] -> **版本支援說明**：目前已同步支援至 Ample (macOS) 最新版本之資源定義以及 MAME 最新版本之核心。 - -## 🍎 Ample (macOS) vs. AmpleWin (Windows) 完整對照表 - -| 功能項目 | Ample (macOS 原生版) | AmpleWin (Windows 優化版) | 優化重點與說明 | -| :--- | :--- | :--- | :--- | -| **程式語言** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | 獨立開發，**完全沒動到 Mac 版原始碼** | -| **安裝方式** | .dmg 映像檔 / Homebrew | **免安裝綠色版 (+ .bat 自動配置)** | 透過 `AmpleWin.bat` 一鍵搞定 Python 與依賴 | -| **UI 介面** | macOS 原生組件 | **1:1 像素級 QSS 複刻** | 在 Windows 實現 **Adaptive 自適應淺色/深色主題** | -| **MAME 整合** | 內建客製版核心，或自選客製版本 | **額外下載官方版核心，或自選客製版本** | 使用者可隨時更新 MAME 核心，若無亦可選擇額外下載 | -| **初始機器選擇** | 支援預設書籤 (需手動設定) | **全自動持久化 (自動載入上次狀態)** | Mac 版需設為預設書籤，Windows 版則全自動開啟 | -| **軟體清單效能** | 同步加載 (解析完整 XML) | **延遲遞增加載 (Deferred Loading)** | **重大優化**：切換機器秒開，搜尋才加載，效能更佳 | -| **軟體搜尋 UI** | 標準列表 (Pop-up) | **智慧搜尋疊層 (Smart Overlay)** | 支援即時搜尋、全名顯示，且不推擠其他 UI 元素 | -| **ROM 下載** | 支援自動下載 (補齊缺失) | **高效能 Failover 引擎** | **重大優化**：支援多伺服器切換 (callapple + mdk.cab) | -| **參數驗證** | 依賴 .plist 靜態定義 | **動態查詢驗證 (Live Validation)** | **重大優化**：自動與 MAME 比對，防止指令報錯崩潰 | -| **Video 支援** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan / D3D11 / D3D12** | 針對 Windows 環境最佳化，支援多代 DirectX 核心 | -| **網路連線** | Apple VMNet Framework | **Npcap (WinPcap) / PCAP** | 使用標準 Npcap 即可上網 (無須權限修復) | -| **操作邏輯** | 支援黏性軟體選取 | **支援黏性軟體選取 (Sticky Selection)** | 兩平台皆支援切換機型後保留相容的軟體選取 | - -## 🌟 核心功能 - -### 🍏 忠實還原 Mac 體驗 (功能對齊) -* **視覺精準度**： - * **高解析度縮放**：精準支援 **Window 1x-4x** 模式，並內建機器專屬的比例啟發邏輯（如 Apple II 4:3 修正）。 - * **正方形像素 (Square Pixels)**：支援特製的整數縮放模式 (如 1120x768)，消除像素閃爍。 -* **軟體資料庫**： - * **智慧過濾**：自動識別機器支援的媒體類型 (flop1, flop2, cass...)，確保啟動參數與原始硬體一致。 - * **搜尋遮罩**：完整還原 Mac 版的搜尋介面，支援自動補完與完整網格化清單顯示。 - * **相容性檢查**：自動偵測屬性表中的 `disabled` 標記（如不相容的 SCSI 卡），並正確以灰色顯示不可選，與 Mac 行為一致。 -* **進階槽位模擬**：完整支援嵌套子槽位（如 SCSI 卡）。 - * **自動化配置**：在選中卡片後自動初始化預設設備（如 ID 1 CD-ROM, ID 6 Hard Disk）。 - * **配置持久性**：優化插槽初始化邏輯，確保在 UI 重新整理時能正確保留「空」(None) 的選取狀態，與 Mac 原生行為一致。 -* **ROM 管理**： - * **搜尋過濾**：ROM 管理器視窗中新增即時搜尋功能，方便快速查詢系統韌體。 - * **下載 Failover**：多伺服器自動獲取 (callapple + mdk.cab)，主伺服器失敗時自動切換，確保最高穩定性。 - * **擴展支援**：新增 Macintosh PowerBook Duo 280, Pravetz 8C, TK3000 //e 等機型。 - * **相容性降級 (Compatibility Fallback)**：自動偵測受 MAME 0.288 EASC 晶片崩潰 Bug 影響的 PowerBook 機型（如 `macpb160` 等），無縫切換至本地的 `mame_0287.exe` 或 `mame-vgm.exe` (v0.280)，或提示一鍵下載備用版本，防範啟動崩潰。 -* **共享目錄 (Shared Directory)**：與 Mac 版功能完全對齊，支援透過 `-share_directory` 直接在主機與模擬器間共享檔案 (支援點擊輸入框瀏覽)。 -* **VGM 錄音支援 (進階)**：由於現代 MAME 已移除 VGM 支援，AmpleWin 實作了強韌的自動化工作流，可下載並平行配置 **MAME-VGM Mod (v0.280)**。透過非破壞性的解壓技術（保留原本的 `mame.exe` 並另存為 `mame-vgm.exe`），在不影響主核心的情況下完美還原錄音功能。 - -### 🪟 Windows 專屬優化與增強 -* **效能優化**： - * **併發下載系統**：多線程加速 ROM 下載，大幅縮短初始配置時間。 - * **零雜訊 Workspace**：所有的 MAME 產出紀錄 (nvram, cfg, sta) 嚴格隔離在 `mame` 內。 - * **延遲載入 (Deferred Loading)**：大幅優化軟體清單載入速度，切換機器與搜尋皆可瞬間反應。 -* **UI 增強**： - * **適配主題**：即時同步 Windows 系統的深/淺色模式。 - * **指令即時預覽**：底部的 4 行式 Console 欄位，可即時監控傳送給 MAME 的所有參數細節。 - * **智慧路徑處理**：針對 A/V 輸出及共享目錄欄位提供原生的檔案/目錄選擇器，並自動執行路徑正規化 (將 `/` 轉為 `\`) 以確保與 Windows 的最佳相容性。 -* **彈性後端支援**：領先支援 BGFX、OpenGL、Vulkan 以及 Windows 專屬的 **DirectX 11/12**。 - -## 🛠️ 快速開始 - -1. **啟動 Ample**： - 進入 **`AmpleWin`** 資料夾，執行 **`AmpleWin.bat`**。 - * 腳本會自動檢查 Python 環境、安裝依賴套件並啟動程式。 -2. **快速部署**： - * 前往 **⚙️ Settings** -> 點擊 **Download MAME** 以自動配置模擬器。 - * 點擊主介面的 **🎮 ROMs** 以補齊系統韌體。 - * 點擊 **📂 Ample Dir** 可快速開啟程式安裝目錄。 -3. **開始體驗**： - * 從左側列表中選擇想要的機器。 - * **雙擊** 機器名稱或點擊右下角的 **Launch MAME** 即可啟動。 - -## 🌐 網路功能 (進階項目) - -若要在模擬器中使用 **Uthernet II** 等網路卡硬體，在 Windows 環境下需要安裝 [Npcap](https://nmap.org/npcap/) (安裝時請勾選 "WinPcap compatible mode")。與 macOS 版本不同，Windows 是透過網卡驅動程式處理硬體存取，因此不需要額外的「權限修復 (Fix Permissions)」程序。 - -## 📂 Project Structure (專案結構) - -| 檔案/目錄 | 說明 | -| :--- | :--- | -| **`AmpleWin.bat`** | **啟動腳本**。自動安裝依賴套件並執行主程式。 | -| `build_exe.bat` | **打包腳本**。使用 PyInstaller 建立無須 Python 的可攜式 EXE。 | -| `main.py` | 應用程式入口，處理 UI 渲染與主要邏輯。 | -| `data_manager.py` | 負責解析 `.plist` 機器定義檔與 MAME `.xml` 軟體列表。 | -| `mame_launcher.py` | MAME 指令建構器與執行序管理器。 | -| `rom_manager.py` | 系統 ROM 的管理與多執行緒下載引擎。 | -| `mame_downloader.py` | 自動化 MAME 核心與 VGM Mod 下載解壓工具。 | -| `mame/` | 隔離的 MAME 工作目錄，存放執行檔、ROMs 與設定檔。 | -| `Agent.md` | 開發日誌與任務記錄。 | - -## 📦 打包發布版 (Portable EXE) - -如果你想將程式打包成無需 Python 環境的可執行檔： - -1. 執行 `AmpleWin` 資料夾下的 `build_exe.bat`。 -2. 腳本會自動安裝 PyInstaller 並打包應用程式，同時複製必要的資源檔。 -3. 打包完成後的程式位於 `AmpleWin\dist\AmpleWin`。 -4. 將整個 `AmpleWin` 資料夾複製到任何位置即可執行，它是完全**可攜式 (Portable)** 的。 - -## 📝 致謝 - -* 原始 macOS 版本開發者: [Kelvin Sherlock](https://github.com/ksherlock) -* **Windows Port 開發者: anomixer + Antigravity**：致力於在 Windows 生態系中提供最極致的 Apple II / Macintosh 模擬體驗。 +# AmpleWin - Windows Port (Legacy Apple Emulator Frontend) + +[English](README.md) | [繁體中文](README_tw.md) + +這是一個將 macOS 原生 [Ample](https://github.com/ksherlock/ample) 專案精準移植至 Windows 平台的版本。 + +> [!TIP] +> **Linux 使用者？** 請參考 [AmpleLinux](../AmpleLinux/) Linux 移植版。 + + +![](screenshot.png) + +> [!IMPORTANT] +> **版本支援說明**：目前已同步支援至 Ample (macOS) 最新版本之資源定義以及 MAME 最新版本之核心。 + +## 🍎 Ample (macOS) vs. AmpleWin (Windows) 完整對照表 + +| 功能項目 | Ample (macOS 原生版) | AmpleWin (Windows 優化版) | 優化重點與說明 | +| :--- | :--- | :--- | :--- | +| **程式語言** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | 獨立開發，**完全沒動到 Mac 版原始碼** | +| **安裝方式** | .dmg 映像檔 / Homebrew | **免安裝綠色版 (+ .bat 自動配置)** | 透過 `AmpleWin.bat` 一鍵搞定 Python 與依賴 | +| **UI 介面** | macOS 原生組件 | **1:1 像素級 QSS 複刻** | 在 Windows 實現 **Adaptive 自適應淺色/深色主題** | +| **MAME 整合** | 內建客製版核心，或自選客製版本 | **額外下載官方版核心，或自選客製版本** | 使用者可隨時更新 MAME 核心，若無亦可選擇額外下載 | +| **初始機器選擇** | 支援預設書籤 (需手動設定) | **全自動持久化 (自動載入上次狀態)** | Mac 版需設為預設書籤，Windows 版則全自動開啟 | +| **軟體清單效能** | 同步加載 (解析完整 XML) | **延遲遞增加載 (Deferred Loading)** | **重大優化**：切換機器秒開，搜尋才加載，效能更佳 | +| **軟體搜尋 UI** | 標準列表 (Pop-up) | **智慧搜尋疊層 (Smart Overlay)** | 支援即時搜尋、全名顯示，且不推擠其他 UI 元素 | +| **ROM 下載** | 支援自動下載 (補齊缺失) | **高效能 Failover 引擎** | **重大優化**：支援多伺服器切換 (callapple + mdk.cab) | +| **參數驗證** | 依賴 .plist 靜態定義 | **動態查詢驗證 (Live Validation)** | **重大優化**：自動與 MAME 比對，防止指令報錯崩潰 | +| **Video 支援** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan / D3D11 / D3D12** | 針對 Windows 環境最佳化，支援多代 DirectX 核心 | +| **網路連線** | Apple VMNet Framework | **Npcap (WinPcap) / PCAP** | 使用標準 Npcap 即可上網 (無須權限修復) | +| **操作邏輯** | 支援黏性軟體選取 | **支援黏性軟體選取 (Sticky Selection)** | 兩平台皆支援切換機型後保留相容的軟體選取 | + +## 🌟 核心功能 + +### 🍏 忠實還原 Mac 體驗 (功能對齊) +* **視覺精準度**： + * **高解析度縮放**：精準支援 **Window 1x-4x** 模式，並內建機器專屬的比例啟發邏輯（如 Apple II 4:3 修正）。 + * **正方形像素 (Square Pixels)**：支援特製的整數縮放模式 (如 1120x768)，消除像素閃爍。 +* **軟體資料庫**： + * **智慧過濾**：自動識別機器支援的媒體類型 (flop1, flop2, cass...)，確保啟動參數與原始硬體一致。 + * **搜尋遮罩**：完整還原 Mac 版的搜尋介面，支援自動補完與完整網格化清單顯示。 + * **相容性檢查**：自動偵測屬性表中的 `disabled` 標記（如不相容的 SCSI 卡），並正確以灰色顯示不可選，與 Mac 行為一致。 +* **進階槽位模擬**：完整支援嵌套子槽位（如 SCSI 卡）。 + * **自動化配置**：在選中卡片後自動初始化預設設備（如 ID 1 CD-ROM, ID 6 Hard Disk）。 + * **配置持久性**：優化插槽初始化邏輯，確保在 UI 重新整理時能正確保留「空」(None) 的選取狀態，與 Mac 原生行為一致。 +* **ROM 管理**： + * **搜尋過濾**：ROM 管理器視窗中新增即時搜尋功能，方便快速查詢系統韌體。 + * **下載 Failover**：CallApple 伺服器優先獲取，MDK 伺服器備用 failover 支援，並具備 `dragon32` 缺檔自動補丁與 Laser 128 全系列韌體相容性保障。 + * **擴展支援**：新增 Macintosh PowerBook Duo 280, Pravetz 8C, TK3000 //e 等機型。 + * **全面相容性**：MAME 0.289 官方已修正 PowerBook 機型（如 `macpb160`, `macpb180` 等）的 EASC 晶片崩潰 Bug，所有 PowerBook 機型現可使用最新 MAME 核心直接原生啟動。 +* **共享目錄 (Shared Directory)**：與 Mac 版功能完全對齊，支援透過 `-share_directory` 直接在主機與模擬器間共享檔案 (支援點擊輸入框瀏覽)。 +* **VGM 錄音支援 (進階)**：由於現代 MAME 已移除 VGM 支援，AmpleWin 實作了強韌的自動化工作流，可下載並平行配置 **MAME-VGM Mod (v0.280)**。透過非破壞性的解壓技術（保留原本的 `mame.exe` 並另存為 `mame-vgm.exe`），在不影響主核心的情況下完美還原錄音功能。 + +### 🪟 Windows 專屬優化與增強 +* **效能優化**： + * **併發下載系統**：多線程加速 ROM 下載，大幅縮短初始配置時間。 + * **零雜訊 Workspace**：所有的 MAME 產出紀錄 (nvram, cfg, sta) 嚴格隔離在 `mame` 內。 + * **延遲載入 (Deferred Loading)**：大幅優化軟體清單載入速度，切換機器與搜尋皆可瞬間反應。 +* **UI 增強**： + * **適配主題**：即時同步 Windows 系統的深/淺色模式。 + * **指令即時預覽**：底部的 4 行式 Console 欄位，可即時監控傳送給 MAME 的所有參數細節。 + * **智慧路徑處理**：針對 A/V 輸出及共享目錄欄位提供原生的檔案/目錄選擇器，並自動執行路徑正規化 (將 `/` 轉為 `\`) 以確保與 Windows 的最佳相容性。 +* **彈性後端支援**：領先支援 BGFX、OpenGL、Vulkan 以及 Windows 專屬的 **DirectX 11/12**。 + +## 🛠️ 快速開始 + +1. **啟動 Ample**： + 進入 **`AmpleWin`** 資料夾，執行 **`AmpleWin.bat`**。 + * 腳本會自動檢查 Python 環境、安裝依賴套件並啟動程式。 +2. **快速部署**： + * 前往 **⚙️ Settings** -> 點擊 **Download MAME** 以自動配置模擬器。 + * 點擊主介面的 **🎮 ROMs** 以補齊系統韌體。 + * 點擊 **📂 Ample Dir** 可快速開啟程式安裝目錄。 +3. **開始體驗**： + * 從左側列表中選擇想要的機器。 + * **雙擊** 機器名稱或點擊右下角的 **Launch MAME** 即可啟動。 + +## 🌐 網路功能 (進階項目) + +若要在模擬器中使用 **Uthernet II** 等網路卡硬體，在 Windows 環境下需要安裝 [Npcap](https://nmap.org/npcap/) (安裝時請勾選 "WinPcap compatible mode")。與 macOS 版本不同，Windows 是透過網卡驅動程式處理硬體存取，因此不需要額外的「權限修復 (Fix Permissions)」程序。 + +## 📂 Project Structure (專案結構) + +| 檔案/目錄 | 說明 | +| :--- | :--- | +| **`AmpleWin.bat`** | **啟動腳本**。自動安裝依賴套件並執行主程式。 | +| `build_exe.bat` | **打包腳本**。使用 PyInstaller 建立無須 Python 的可攜式 EXE。 | +| `main.py` | 應用程式入口，處理 UI 渲染與主要邏輯。 | +| `data_manager.py` | 負責解析 `.plist` 機器定義檔與 MAME `.xml` 軟體列表。 | +| `mame_launcher.py` | MAME 指令建構器與執行序管理器。 | +| `rom_manager.py` | 系統 ROM 的管理與多執行緒下載引擎。 | +| `mame_downloader.py` | 自動化 MAME 核心與 VGM Mod 下載解壓工具。 | +| `mame/` | 隔離的 MAME 工作目錄，存放執行檔、ROMs 與設定檔。 | +| `Agent.md` | 開發日誌與任務記錄。 | + +## 📦 打包發布版 (Portable EXE) + +如果你想將程式打包成無需 Python 環境的可執行檔： + +1. 執行 `AmpleWin` 資料夾下的 `build_exe.bat`。 +2. 腳本會自動安裝 PyInstaller 並打包應用程式，同時複製必要的資源檔。 +3. 打包完成後的程式位於 `AmpleWin\dist\AmpleWin`。 +4. 將整個 `AmpleWin` 資料夾複製到任何位置即可執行，它是完全**可攜式 (Portable)** 的。 + +## 📝 致謝 + +* 原始 macOS 版本開發者: [Kelvin Sherlock](https://github.com/ksherlock) +* **Windows Port 開發者: anomixer + Antigravity**：致力於在 Windows 生態系中提供最極致的 Apple II / Macintosh 模擬體驗。 + +--- +*免責聲明：AmpleWin 是一個獨立的開源專案，與 Apple Inc. 或本專案提及之任何其他公司均無任何隸屬、授權、維護或背書關係。所有產品及公司名稱均為其各自持有人的商標™或註冊®商標。* diff --git a/AmpleWin/main.py b/AmpleWin/main.py index 7f151b2..4153044 100644 --- a/AmpleWin/main.py +++ b/AmpleWin/main.py @@ -1121,6 +1121,16 @@ def on_machine_selected(self, item): # 不再於切換時立即填充軟體清單 (延遲加載以優化效能) if hasattr(self, 'sw_list'): self.sw_list.clear() + def get_default_slots(self): + if not self.current_machine_data: + return {} + old_slots = self.current_slots + self.current_slots = {} + self.initialize_default_slots(self.current_machine_data) + defaults = self.current_slots + self.current_slots = old_slots + return defaults + def initialize_default_slots(self, data, depth=0): if depth > 20: return @@ -1205,6 +1215,12 @@ def render_slots_ui(self): self.add_slot_row(self.slots_layout, ram_slot) self.slots_layout.addSpacing(5) + # 1.5 ROM Group + rom_slot = next((s for s in self.current_machine_data['slots'] if s['name'] in ('rom', 'romsize') or s.get('description') in ('ROM', 'ROM/RAM')), None) + if rom_slot: + self.add_slot_row(self.slots_layout, rom_slot) + self.slots_layout.addSpacing(5) + # 2. Disk Drives - EXACTLY same structure as add_slot_row # Mac hides popup button but it still takes up space. Hamburger at far right. dd_slot = next((s for s in self.current_machine_data['slots'] if s.get('description') == 'Disk Drives'), None) @@ -1243,19 +1259,12 @@ def render_slots_ui(self): self.slots_layout.addLayout(row) - - - - - - - - - - # 3. All other slots + excluded_names = {'ramsize'} + if rom_slot: + excluded_names.add(rom_slot['name']) for slot in self.current_machine_data['slots']: - if slot['name'] != 'ramsize' and slot.get('description') != 'Disk Drives': + if slot['name'] not in excluded_names and slot.get('description') != 'Disk Drives': self.add_slot_row(self.slots_layout, slot) self.slots_layout.addStretch() @@ -1772,8 +1781,20 @@ def update_command_line(self): # Positional arguments allow MAME's Software List manager to resolve them. soft_list_args.append(self.selected_software) + # Get defaults recursively + defaults = self.get_default_slots() + + # Filter slots: if a slot is set to empty "", only pass it to MAME if its default value was NOT empty + active_slots = {} + for slot_name, option in self.current_slots.items(): + if option == "": + default_val = defaults.get(slot_name, "") + if default_val == "": + continue + active_slots[slot_name] = option + # Build base args - args = self.launcher.build_args(self.selected_machine, self.current_slots, filtered_media, soft_list_args) + args = self.launcher.build_args(self.selected_machine, active_slots, filtered_media, soft_list_args) # Add UI Video options for preview win_mode = self.win_mode.currentText() @@ -2028,40 +2049,6 @@ def launch_mame(self): # Get command from preview console (User Input is Source of Truth) cmd_str = self.cmd_preview.toPlainText().strip() if not cmd_str: return - - # EASC PowerBook 0.288 Crash Fallback Check - affected_macs = ["macpb160", "macpb180", "macpb165", "macpb165c", "macpb180c"] - if self.selected_machine in affected_macs: - mame_bin_dir = os.path.dirname(self.launcher.mame_path) - alt_mac_exe = os.path.join(mame_bin_dir, "mame_0287.exe") - vgm_mac_exe = os.path.join(mame_bin_dir, "mame-vgm.exe") - - # Check if any fallback is already present - has_fallback = os.path.exists(alt_mac_exe) or os.path.exists(vgm_mac_exe) - - if not has_fallback: - msg_box = QMessageBox(self) - msg_box.setIcon(QMessageBox.Warning) - msg_box.setWindowTitle("EASC Audio Chip Bug (MAME v0.288)") - msg_box.setText(f"The machine '{self.selected_machine}' will crash on MAME v0.288 due to an upstream C++ type mismatch bug.") - msg_box.setInformativeText( - "To run this model, you can automatically download MAME v0.280 (VGM Mod) as a fallback, " - "or run a compatible sibling model instead (e.g. 'macpb170' or 'macpb140')." - ) - - dl_btn = msg_box.addButton("Download Fallback (v0.280)", QMessageBox.YesRole) - force_btn = msg_box.addButton("Force Launch (v0.288)", QMessageBox.NoRole) - cancel_btn = msg_box.addButton("Cancel", QMessageBox.RejectRole) - - msg_box.exec() - - if msg_box.clickedButton() == dl_btn: - self.download_vgm_mod(mame_bin_dir) - return - elif msg_box.clickedButton() == force_btn: - pass - else: - return print(f"Launching custom command: {cmd_str}") @@ -2097,21 +2084,7 @@ def launch_mame(self): target_exe_path = args[0] if exe_cmd in ["mame", "mame.exe"]: - affected_macs = ["macpb160", "macpb180", "macpb165", "macpb165c", "macpb180c"] - alt_mac_exe = os.path.join(mame_bin_dir, "mame_0287.exe") - vgm_mac_exe = os.path.join(mame_bin_dir, "mame-vgm.exe") - - if self.selected_machine in affected_macs: - if os.path.exists(alt_mac_exe): - target_exe_path = alt_mac_exe - print(f"Applying compatibility fallback: using mame_0287.exe for {self.selected_machine}") - elif os.path.exists(vgm_mac_exe): - target_exe_path = vgm_mac_exe - print(f"Applying compatibility fallback: using mame-vgm.exe for {self.selected_machine}") - else: - target_exe_path = self.launcher.mame_path - else: - target_exe_path = self.launcher.mame_path + target_exe_path = self.launcher.mame_path elif exe_cmd in ["mame-vgm", "mame-vgm.exe"]: path_vgm = os.path.join(mame_bin_dir, "mame-vgm.exe") if os.path.exists(path_vgm): diff --git a/AmpleWin/mame_downloader.py b/AmpleWin/mame_downloader.py index 446e3ab..d1e4bb0 100644 --- a/AmpleWin/mame_downloader.py +++ b/AmpleWin/mame_downloader.py @@ -11,8 +11,8 @@ class MameDownloadWorker(QThread): def __init__(self, dest_dir): super().__init__() self.dest_dir = dest_dir - # MAME official self-extracting EXE - Updated to 0.288 - self.url = "https://github.com/mamedev/mame/releases/download/mame0288/mame0288b_x64.exe" + # MAME official self-extracting EXE - Updated to 0.289 + self.url = "https://github.com/mamedev/mame/releases/download/mame0289/mame0289b_x64.exe" def run(self): try: diff --git a/AmpleWin/package-lock.json b/AmpleWin/package-lock.json new file mode 100644 index 0000000..48a95a8 --- /dev/null +++ b/AmpleWin/package-lock.json @@ -0,0 +1,6 @@ +{ + "name": "AmpleWin", + "lockfileVersion": 3, + "requires": true, + "packages": {} +} diff --git a/AmpleWin/rom_manager.py b/AmpleWin/rom_manager.py index bfccc34..62c32bf 100644 --- a/AmpleWin/rom_manager.py +++ b/AmpleWin/rom_manager.py @@ -40,6 +40,10 @@ def run(self): with open(self.dest_path, 'wb') as f: f.write(response.content) + # Special patch for dragon32 to merge MDK split files if missing + if self.value == 'dragon32': + self.patch_dragon32() + self.signals.finished.emit(self.value, True) return # Success! except Exception as e: @@ -53,14 +57,41 @@ def run(self): self.signals.status.emit(f"Error: {last_error}") self.signals.finished.emit(self.value, False) + def patch_dragon32(self): + try: + mdk_url = "https://mdk.cab/download/split/dragon32.zip" + resp = requests.get(mdk_url, headers=self.headers, timeout=20) + if resp.status_code == 200 and len(resp.content) > 100: + import zipfile, io + existing_data = open(self.dest_path, 'rb').read() + z_existing = zipfile.ZipFile(io.BytesIO(existing_data)) + z_mdk = zipfile.ZipFile(io.BytesIO(resp.content)) + + existing_names = set(z_existing.namelist()) + mdk_names = set(z_mdk.namelist()) + + missing = mdk_names - existing_names + if missing: + out_buf = io.BytesIO() + with zipfile.ZipFile(out_buf, 'w', zipfile.ZIP_DEFLATED) as zout: + for item in z_existing.infolist(): + zout.writestr(item, z_existing.read(item.filename)) + for item in z_mdk.infolist(): + if item.filename in missing: + zout.writestr(item, z_mdk.read(item.filename)) + with open(self.dest_path, 'wb') as f: + f.write(out_buf.getvalue()) + except Exception as e: + print(f"Warning: dragon32 patch failed: {e}") + class RomManager(QObject): def __init__(self, resources_path, roms_dir): super().__init__() self.resources_path = resources_path self.roms_dir = roms_dir self.base_urls = [ - "https://mdk.cab/download/split/", - "https://www.callapple.org/roms/" + "https://www.callapple.org/roms/", + "https://mdk.cab/download/split/" ] self.rom_list = self.load_rom_list() @@ -78,7 +109,12 @@ def load_rom_list(self): {'value': 'prav8c', 'description': 'Pravetz 8C'}, {'value': 'prav82', 'description': 'Pravetz 82'}, {'value': 'prav8m', 'description': 'Pravetz 8M'}, - {'value': 'prav8d', 'description': 'Pravetz 8D'} + {'value': 'prav8d', 'description': 'Pravetz 8D'}, + {'value': 'las128ex', 'description': 'Laser 128EX'}, + {'value': 'las128e2', 'description': 'Laser 128EX/2'}, + {'value': 'laser128', 'description': 'Laser 128'}, + {'value': 'laser128o', 'description': 'Laser 128 (Original)'}, + {'value': 'laser2c', 'description': 'Laser 2c'} ] existing_values = {r.get('value') for r in roms if 'value' in r} for cr in custom_roms: