add gio64_gfx for SGI

enable SGI Indigo2, Indy R4600, and Indy R5000, since they function. Add support for choosing graphics boards. (#55 )
move lisa from Ample lite to Ample
2026-10-25 13:02:57 +00:00 · 2026-08-29 23:18:40 -04:00 · 2026-08-29 23:01:44 -04:00 · 2026-08-07 22:41:40 -04:00 · 2026-08-07 21:44:51 -04:00
20 changed files with 1491 additions and 1189 deletions
@@ -64,6 +64,29 @@
          </dict>
        </array>
      </dict>
      <dict>
        <key>name</key>
        <string>gio64_gfx</string>
        <key>description</key>
        <string>GIO64 Graphics</string>
        <key>options</key>
        <array>
          <dict>
            <key>value</key>
            <string>xl24</string>
            <key>description</key>
            <string>SGI 24-bit XL board</string>
            <key>default</key>
            <true/>
          </dict>
          <dict>
            <key>value</key>
            <string>xl8</string>
            <key>description</key>
            <string>SGI 8-bit XL board</string>
          </dict>
        </array>
      </dict>
    </array>
    <key>devices</key>
    <array>
@@ -76,6 +76,29 @@
          </dict>
        </array>
      </dict>
      <dict>
        <key>name</key>
        <string>gio64_gfx</string>
        <key>description</key>
        <string>GIO32 Graphics</string>
        <key>options</key>
        <array>
          <dict>
            <key>value</key>
            <string>xl24</string>
            <key>description</key>
            <string>SGI 24-bit XL board</string>
            <key>default</key>
            <true/>
          </dict>
          <dict>
            <key>value</key>
            <string>xl8</string>
            <key>description</key>
            <string>SGI 8-bit XL board</string>
          </dict>
        </array>
      </dict>
    </array>
    <key>devices</key>
    <array>
@@ -76,6 +76,29 @@
          </dict>
        </array>
      </dict>
      <dict>
        <key>name</key>
        <string>gio64_gfx</string>
        <key>description</key>
        <string>GIO32 Graphics</string>
        <key>options</key>
        <array>
          <dict>
            <key>value</key>
            <string>xl24</string>
            <key>description</key>
            <string>SGI 24-bit XL board</string>
            <key>default</key>
            <true/>
          </dict>
          <dict>
            <key>value</key>
            <string>xl8</string>
            <key>description</key>
            <string>SGI 8-bit XL board</string>
          </dict>
        </array>
      </dict>
    </array>
    <key>devices</key>
    <array>
@@ -58,6 +58,29 @@
          </dict>
        </array>
      </dict>
      <dict>
        <key>name</key>
        <string>gio64_gfx</string>
        <key>description</key>
        <string>GIO32 Graphics</string>
        <key>options</key>
        <array>
          <dict>
            <key>value</key>
            <string>xl24</string>
            <key>description</key>
            <string>SGI 24-bit XL board</string>
            <key>default</key>
            <true/>
          </dict>
          <dict>
            <key>value</key>
            <string>xl8</string>
            <key>description</key>
            <string>SGI 8-bit XL board</string>
          </dict>
        </array>
      </dict>
    </array>
    <key>devices</key>
    <array>
@@ -880,6 +880,37 @@
        </dict>
      </array>
    </dict>
    <dict>
      <key>description</key>
      <string>Lisa</string>
      <key>children</key>
      <array>
        <dict>
          <key>description</key>
          <string>Lisa</string>
          <key>value</key>
          <string>lisa</string>
        </dict>
        <dict>
          <key>description</key>
          <string>Lisa2</string>
          <key>value</key>
          <string>lisa2</string>
        </dict>
        <dict>
          <key>description</key>
          <string>Lisa2/10</string>
          <key>value</key>
          <string>lisa210</string>
        </dict>
        <dict>
          <key>description</key>
          <string>Macintosh XL</string>
          <key>value</key>
          <string>macxl</string>
        </dict>
      </array>
    </dict>
    <dict>
      <key>description</key>
      <string>Acorn</string>
@@ -1129,5 +1160,36 @@
        </dict>
      </array>
    </dict>
    <dict>
      <key>description</key>
      <string>Silicon Graphics</string>
      <key>children</key>
      <array>
        <dict>
          <key>description</key>
          <string> Indigo2 (R4400, 150MHz)</string>
          <key>value</key>
          <string>indigo2_4415</string>
        </dict>
        <dict>
          <key>description</key>
          <string> Indy (R4600, 100MHz)</string>
          <key>value</key>
          <string>indy_4610</string>
        </dict>
        <dict>
          <key>description</key>
          <string> Indy (R4600, 133MHz)</string>
          <key>value</key>
          <string>indy_4613</string>
        </dict>
        <dict>
          <key>description</key>
          <string> Indy (R5000, 150MHz)</string>
          <key>value</key>
          <string>indy_5015</string>
        </dict>
      </array>
    </dict>
  </array>
 </plist>
@@ -1921,6 +1921,12 @@
      <string>pd3_mclr</string>
      <key>description</key>
      <string>Micron/XCEED Technology MacroColor 30</string>
    </dict>
     <dict>
      <key>value</key>
      <string>kb_ms_natural</string>
      <key>description</key>
      <string>Microsoft Natural Keyboard</string>
    </dict>
    <dict>
      <key>value</key>
@@ -2174,6 +2180,12 @@
      <key>description</key>
      <string>Prológica CP-450 BASIC Disco V. 1.0 (1984)</string>
    </dict>
    <dict>
      <key>value</key>
      <string>ps2_keybc</string>
      <key>description</key>
      <string>PS/2 Keyboard</string>
    </dict>
    <dict>
      <key>value</key>
      <string>qsound</string>
@@ -2282,6 +2294,18 @@
      <key>description</key>
      <string>SDTANDY FDC</string>
    </dict>
    <dict>
      <key>value</key>
      <string>indigo2_4415</string>
      <key>description</key>
      <string>SGI Indigo2 (R4400, 150MHz)</string>
    </dict>
    <dict>
      <key>value</key>
      <string>indy_4610</string>
      <key>description</key>
      <string>SGI Indy (R4600, 100MHz)</string>
    </dict>
    <dict>
      <key>value</key>
      <string>gpib_hardbox</string>
@@ -1,185 +1,222 @@
-# Agent Task Audit Log - Ample Linux Port
+# Agent Task Audit Log - Ample Linux Port
-
+
-## 📅 Session: 2026-06-05 (Session 6)
+## 📅 Session: 2026-08-02 (Session 7)
-
+
-### 🎯 Objective: PowerBook Compatibility Fallback & Downloader Parity
+### 🎯 Objective: Upstream MAME v0.289 Synchronization
-Addressed upstream MAME 0.288 C++ late-binding bug causing crashes on EASC audio chip Macs, and aligned the fallback interface with AmpleWin.
+Synchronized AmpleLinux with upstream `ksherlock/ample` v0.289 release and updated machine `.plist` configuration definitions.
-
+
-### ✅ Key Achievements:
+### ✅ Key Achievements:
-1.  **Simplified Fallback Redirection**:
+1.  **PowerBook Native Launch (EASC Bug Fixed)**:
-    *   Aligned the crash warning interface with AmpleWin for affected PowerBooks (`macpb160` etc.).
+    *   Removed `macpb160`, `macpb165`, `macpb165c`, `macpb180`, `macpb180c` fallback prompt mechanism in `main.py`, as MAME 0.289 officially resolved the EASC audio chip crash bug.
-    *   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.
+2.  **ROM Manager Priority & Dragon32/Laser Series Fixes**:
-    *   Maintains seamless redirection to `mame_0287` or `mame-vgm` if already configured in the local directory.
+    *   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.
-2.  **ROM Manager Priority Update**:
+    *   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`.
-    *   Reordered ROM download servers to prioritize `mdk.cab`, solving missing ROM zip structure bugs (such as `dragon32`) when running on modern MAME 0.288+.
+    *   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.  **Downloader Optimization**:
+3.  **Upstream MAME 0.289 Alignment**:
-    *   Added `mirror.ghproxy.com` proxy support to VGM Mod mirrors for accelerated downloads on Linux systems.
+    *   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-05-19 (Session 5)
+
-
+## 📅 Session: 2026-06-05 (Session 6)
-### 🎯 Objective: Complete Slot Configuration Persistence (MAME Command Line)
+
-Synchronized command line argument logic with AmpleWin to ensure "None" slots are explicitly disabled in MAME.
+### 🎯 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.  **Command-Line Slot Persistence**:
+### ✅ Key Achievements:
-    *   Modified `build_args` in `mame_launcher.py` to allow empty string values (e.g. `option is not None` instead of `if option:`).
+1.  **Simplified Fallback Redirection**:
-    *   This ensures that `-[slot_name] ""` is explicitly passed on the command line, preventing MAME from falling back to its internal defaults.
+    *   Aligned the crash warning interface with AmpleWin for affected PowerBooks (`macpb160` etc.).
-2.  **Cross-Platform Parity**: Ensured consistent behavior with Windows and Web ports.
+    *   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+.
-## 📅 Session: 2026-05-11 (Session 4)
+3.  **Downloader Optimization**:
-
+    *   Added `mirror.ghproxy.com` proxy support to VGM Mod mirrors for accelerated downloads on Linux systems.
-### 🎯 Objective: Slot Configuration Consistency Fix
+
-Synchronized slot initialization logic with AmpleWin to fix "None" persistence issue.
+---
-
+
-### ✅ Key Achievements:
+## 📅 Session: 2026-05-19 (Session 5)
-1.  **"None-Aware" Slot Initialization**:
+
-    *   Applied the `slot_name not in self.current_slots` fix to `main.py`.
+### 🎯 Objective: Complete Slot Configuration Persistence (MAME Command Line)
-2.  **Cross-Platform Consistency**: Ensured Linux port shares the improved slot behavior.
+Synchronized command line argument logic with AmpleWin to ensure "None" slots are explicitly disabled in MAME.
-
+
---
+### ✅ Key Achievements:
-
+1.  **Command-Line Slot Persistence**:
-## 📅 Session: 2026-03-02 (Session 3)
+    *   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.
-### 🎯 Objective: Upstream Version Tracking & Documentation Maintenance
+2.  **Cross-Platform Parity**: Ensured consistent behavior with Windows and Web ports.
-Focused on updating the Linux port documentation to track MAME 0.286 and simplifying maintainability.
+
-
+---
-### ✅ Key Achievements:
+
-1.  **Documentation Refactoring**:
+## 📅 Session: 2026-05-11 (Session 4)
-    *   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.
+### 🎯 Objective: Slot Configuration Consistency Fix
-
+Synchronized slot initialization logic with AmpleWin to fix "None" persistence issue.
-### 🚀 Current Project Status
+
-The Linux Port documentation is updated for MAME 0.286 and future-proofed against minor version increments.
+### ✅ 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-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.
+## 📅 Session: 2026-05-11 (Session 4)
-
+
-### ✅ Key Achievements:
+### 🎯 Objective: Slot Configuration Alignment & Bug Fix
-
+Synchronized slot initialization logic with AmpleWin to fix the issue where "None" selections were being overwritten by defaults.
-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).
+### ✅ Key Achievements:
-    *   **Fix v1**: Changed to `python3 -m pip` (the universally reliable pip invocation).
+1.  **"None-Aware" Slot Initialization**:
-    *   **Fix v2**: Added automatic `--break-system-packages` fallback for PEP 668-compliant systems.
+    *   Applied the `slot_name not in self.current_slots` fix to `main.py`.
-    *   **Error Messages**: Added distro-specific guidance (apt/dnf/pacman) and venv instructions in error output.
+    *   Ensured that manual "None" selections (empty string) are preserved across UI refreshes.
-
+2.  **Cross-Platform Feature Parity**:
-2.  **Git Workflow**:
+    *   Aligned slot behavior with the Windows and Web ports.
-    *   Created `linux` branch from `master`.
+3.  **Stability**:
-    *   Pushed to `origin/linux` for cross-machine testing.
+    *   Verified that nested slot defaults still load correctly for new cards.
-
+
-### 🔍 Testing Observations (Real Linux Machine):
+### 🚀 Current Project Status
-*   `pip3` command was not in PATH → first fallback triggered.
+The Linux port now shares the same robust slot configuration logic as the Windows version, ensuring a consistent user experience.
-*   `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:
+## 📅 Session: 2026-03-02 (Session 3)
-*   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):
+### 🎯 Objective: Upstream Version Tracking & Documentation Maintenance
-    1.  System packages: `sudo apt install python3-pyside6 python3-requests`
+Focused on updating the Linux port documentation to track MAME 0.286 and simplifying maintainability.
-    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`
+### ✅ Key Achievements:
-
+1.  **Documentation Refactoring**:
-### 🚀 Current Project Status
+    *   Renamed version-specific screenshot files (e.g. `screenshot-v0.28x.png` to `screenshot.png`).
-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.
+    *   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-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.
+## 📅 Session: 2026-02-17 (Session 2)
-
+
-### ✅ Key Achievements:
+### 🎯 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.
-1.  **Codebase Porting (from AmpleWin)**:
+
-    *   **Zero-Modification Files**: `data_manager.py`, `rom_manager.py`, `mame_launcher.py`, `requirements.txt` — copied directly, no changes needed.
+### ✅ Key Achievements:
-    *   **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:
+1.  **Launcher Script Fix (`AmpleLinux.sh`)**:
-        -   Replaced `winreg` theme detection with `gsettings` (GNOME 42+ `color-scheme`) and KDE (`kdeglobals`) dark mode detection.
+    *   **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).
-        -   Replaced all `os.startfile()` calls with `xdg-open` via a helper function `_xdg_open()`.
+    *   **Fix v1**: Changed to `python3 -m pip` (the universally reliable pip invocation).
-        -   Removed all `.exe` suffixes from MAME binary references (`mame.exe` → `mame`, `mame-vgm.exe` → `mame-vgm`).
+    *   **Fix v2**: Added automatic `--break-system-packages` fallback for PEP 668-compliant systems.
-        -   Enhanced `check_for_mame()` to search system paths (`/usr/bin/mame`, `/usr/games/mame`, `/usr/local/bin/mame`) and use `which mame`.
+    *   **Error Messages**: Added distro-specific guidance (apt/dnf/pacman) and venv instructions in error output.
-        -   Replaced `Download MAME` button with package manager guidance text.
+
-        -   Updated `shlex.split()` from `posix=False` (Windows) to `posix=True` (Linux).
+2.  **Git Workflow**:
-        -   Updated file browser filter from `*.exe` to `All Files (*)`.
+    *   Created `linux` branch from `master`.
-        -   Changed window title and help URL.
+    *   Pushed to `origin/linux` for cross-machine testing.
-
+
-2.  **Launcher Script**:
+### 🔍 Testing Observations (Real Linux Machine):
-    *   Created `AmpleLinux.sh` as equivalent of `AmpleWin.bat`.
+*   `pip3` command was not in PATH → first fallback triggered.
-    *   Includes Python 3 detection, pip dependency installation, and helpful error messages with distro-specific commands.
+*   `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.
-3.  **Documentation**:
+
-    *   Created dual-language READMEs (`README.md` English, `README_tw.md` Traditional Chinese).
+### ⚠️ Known Issue - Pending Resolution:
-    *   Includes installation guide for all major distros (Ubuntu, Fedora, Arch, Flatpak).
+*   Systems without any pip module need manual package installation first. The script provides clear guidance but cannot auto-resolve this without `sudo`.
-    *   Troubleshooting section for PySide6, MAME detection, and theme issues.
+*   **Recommended solutions** (in priority order):
-
+    1.  System packages: `sudo apt install python3-pyside6 python3-requests`
-### 🔍 Design Decisions:
+    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`
-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.
+
-
+### 🚀 Current Project Status
-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.
+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.
-
+
-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
+## 📅 Session: 2026-02-16 (Session 1)
-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.
+
-
+### 🎯 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.
-
+
-##  Handover Notes for Future Agents
+### ✅ Key Achievements:
-
+
-### 1. Platform Differences from AmpleWin
+1.  **Codebase Porting (from AmpleWin)**:
-*   **No `winreg`**: Theme detection uses `gsettings` and KDE config file parsing.
+    *   **Zero-Modification Files**: `data_manager.py`, `rom_manager.py`, `mame_launcher.py`, `requirements.txt` — copied directly, no changes needed.
-*   **No `os.startfile()`**: Uses `xdg-open` via the `_xdg_open()` helper function.
+    *   **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).
-*   **No `.exe` suffixes**: All binary references use bare names (`mame`, `mame-vgm`).
+    *   **`main.py` (~20 changes)**: Comprehensive platform adaptation:
-*   **No MAME auto-download**: Users install via package manager. Settings dialog shows guidance.
+        -   Replaced `winreg` theme detection with `gsettings` (GNOME 42+ `color-scheme`) and KDE (`kdeglobals`) dark mode detection.
-*   **`shlex.split(posix=True)`**: Linux uses POSIX-mode shell parsing (no special Windows path handling).
+        -   Replaced all `os.startfile()` calls with `xdg-open` via a helper function `_xdg_open()`.
-*   **MAME detection**: Checks `PATH` via `which`, plus standard Linux paths (`/usr/bin`, `/usr/games`, `/usr/local/bin`).
+        -   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`.
-### 2. Deployment (CRITICAL)
+        -   Replaced `Download MAME` button with package manager guidance text.
-*   **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.
+        -   Updated `shlex.split()` from `posix=False` (Windows) to `posix=True` (Linux).
-*   **Recommended Install Methods** (in priority order):
+        -   Updated file browser filter from `*.exe` to `All Files (*)`.
-    1.  System packages: `sudo apt install python3-pyside6 python3-requests mame`
+        -   Changed window title and help URL.
-    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`
+2.  **Launcher Script**:
-*   **Never use `pip3` or `pip` directly** in scripts — always use `python3 -m pip` for reliability.
+    *   Created `AmpleLinux.sh` as equivalent of `AmpleWin.bat`.
-
+    *   Includes Python 3 detection, pip dependency installation, and helpful error messages with distro-specific commands.
-### 3. Known Mantras (inherited from AmpleWin)
+
-*   **Visual Parity is King**: Every margin, font size, and color was cross-referenced with macOS.
+3.  **Documentation**:
-*   **Authorship**: This Linux Port is based on the AmpleWin collaboration between **anomixer** and **Antigravity**.
+    *   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.
-
+
-## 📅 Session: 2026-02-17 (Session 2)
+### 🔍 Design Decisions:
-
+
-### 🎯 Objective: First-Run Experience, Build System & Polish
+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.
-
+
-### ✅ Key Changes:
+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.
-
+
-1.  **Launcher Architecture (`AmpleLinux.sh`)**:
+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.
-    *   **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`.
+### 🚀 Current Project Status
-    *   **Distro Agnostic**: Only depends on `python3-full` and `libxcb-cursor*` (apt) for the base interpreter; all libraries (PySide6) are pulled via pip.
+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.
-    *   **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`.
+##  Handover Notes for Future Agents
-    *   **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/...`).
+### 1. Platform Differences from AmpleWin
-    *   **BGFX Cleanup**: Removed Windows-only Direct3D options.
+*   **No `winreg`**: Theme detection uses `gsettings` and KDE config file parsing.
-    *   **UI Polish**: "Generate VGM" now shows a "Feature not implemented" popup.
+*   **No `os.startfile()`**: Uses `xdg-open` via the `_xdg_open()` helper function.
-
+*   **No `.exe` suffixes**: All binary references use bare names (`mame`, `mame-vgm`).
-3.  **Build System (New)**:
+*   **No MAME auto-download**: Users install via package manager. Settings dialog shows guidance.
-    *   **`make_icon.py`**: Created Linux-specific icon generator (produces standard PNG sizes: 16x16 to 512x512).
+*   **`shlex.split(posix=True)`**: Linux uses POSIX-mode shell parsing (no special Windows path handling).
-    *   **`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/`.
+*   **MAME detection**: Checks `PATH` via `which`, plus standard Linux paths (`/usr/bin`, `/usr/games`, `/usr/local/bin`).
-
+
-### 🔍 Technical Decisions:
+### 2. Deployment (CRITICAL)
-*   **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.
+*   **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.
-*   **MAME Snap**: For Ubuntu users, Snap is the most reliable way to get a recent MAME version without PPA complexity.
+*   **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.
@@ -1,125 +1,128 @@
-# AmpleLinux - Linux Port (Legacy Apple Emulator Frontend)
+# AmpleLinux - Linux Port (Legacy Apple Emulator Frontend)
-
+
-[English](README.md) | [繁體中文](README_tw.md)
+[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.
+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)
+![](screenshot.png)
-
+
-> [!IMPORTANT]
+> [!IMPORTANT]
-> **Current Version Support**: Updated to stay in sync with the latest version of Ample (macOS) resources and also MAME latest binary.
+> **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
+## 🍎 Ample (macOS) vs. AmpleLinux (Linux) Comparison
-
+
-| Feature | Ample (macOS Native) | AmpleLinux (Linux) | Notes |
+| Feature | Ample (macOS Native) | AmpleLinux (Linux) | Notes |
-| :--- | :--- | :--- | :--- |
+| :--- | :--- | :--- | :--- |
-| **Language** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | Independent development, **zero changes to Mac source code** |
+| **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` |
+| **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.) |
+| **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) |
+| **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 |
+| **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 |
+| **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) |
+| **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 |
+| **Video Support** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan** | Leveraging MAME's cross-platform rendering |
-
+
-## 🌟 Key Features
+## 🌟 Key Features
-
+
-### 🍏 Faithful Mac Experience (Feature Parity)
+### 🍏 Faithful Mac Experience (Feature Parity)
-*   **Visual Precision**: Precision support for **Window 1x-4x** modes with machine-specific aspect ratio heuristics.
+*   **Visual Precision**: Precision support for **Window 1x-4x** modes with machine-specific aspect ratio heuristics.
-*   **Software Library**: Smart filtering, search overlay, and compatibility checking.
+*   **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.
+*   **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.
+*   **ROM Management**: Real-time search, CallApple primary / MDK failover downloads, `dragon32` auto-patching, and full Laser 128 series library compatibility.
-    *   **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.
+    *   **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.
+*   **Shared Directory**: Full parity with `-share_directory` argument.
-
+
-### 🐧 Linux-Specific Features
+### 🐧 Linux-Specific Features
-*   **System MAME Integration**: Auto-detects MAME from `PATH`, `/usr/bin/mame`, `/usr/games/mame`, etc.
+*   **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.
+*   **Adaptive Theme**: Detects GNOME (`gsettings`) and KDE dark/light mode in real-time.
-*   **Native File Management**: Uses `xdg-open` for file/folder/URL opening.
+*   **Native File Management**: Uses `xdg-open` for file/folder/URL opening.
-*   **No External Dependencies**: MAME is installed via your distribution's package manager.
+*   **No External Dependencies**: MAME is installed via your distribution's package manager.
-
+
-### ⚠️ Known Limitations
+### ⚠️ 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.
+*   **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
+## 🛠️ Quick Start
-
+
-### Prerequisites
+### Prerequisites
-   **Python 3.9+**
+-   **Python 3.9+**
-   **MAME** installed via your package manager
+-   **MAME** installed via your package manager
-   **PySide6** and **requests** (installed via system packages or pip)
+-   **PySide6** and **requests** (installed via system packages or pip)
-
+
-### Installation
+### Installation
-
+
-1.  **Install System Dependencies**:
+1.  **Install System Dependencies**:
-    *   **MAME**: Install via your package manager (e.g., `sudo apt install mame`).
+    *   **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`).
+    *   **Python 3**: Ensure Python 3.9+ is installed (`sudo apt install python3-full`).
-    *   **X11 Support**: Required for GUI (`sudo apt install libxcb-cursor0`).
+    *   **X11 Support**: Required for GUI (`sudo apt install libxcb-cursor0`).
-
+
-2.  **Launch Ample**:
+2.  **Launch Ample**:
-    ```bash
+    ```bash
-    cd AmpleLinux
+    cd AmpleLinux
-    chmod +x AmpleLinux.sh
+    chmod +x AmpleLinux.sh
-    ./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.**
+    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**:
+3.  **Fast Deployment**:
-    *   **Ubuntu Users**: If MAME is not found, the app will offer to install it via `snap`.
+    *   **Ubuntu Users**: If MAME is not found, the app will offer to install it via `snap`.
-    *   Click **🎮 ROMs** to download system firmware.
+    *   Click **🎮 ROMs** to download system firmware.
-    *   Go to **⚙️ Settings** to verify MAME is detected.
+    *   Go to **⚙️ Settings** to verify MAME is detected.
-    *   Select a machine and **Launch MAME**!
+    *   Select a machine and **Launch MAME**!
-
+
-## 📦 Building for Release
+## 📦 Building for Release
-
+
-To create a standalone Linux binary (ELF) that requires no dependencies:
+To create a standalone Linux binary (ELF) that requires no dependencies:
-
+
-```bash
+```bash
-cd AmpleLinux
+cd AmpleLinux
-chmod +x build_elf.sh
+chmod +x build_elf.sh
-./build_elf.sh
+./build_elf.sh
-```
+```
-
+
-This script uses `PyInstaller` within a temporary venv to build a portable binary.
+This script uses `PyInstaller` within a temporary venv to build a portable binary.
-
+
-### 4. Desktop Integration (Icon Fix)
+### 4. Desktop Integration (Icon Fix)
-
+
-To see the correct icon in your Dock/Taskbar, copy the generated `.desktop` file:
+To see the correct icon in your Dock/Taskbar, copy the generated `.desktop` file:
-
+
-```bash
+```bash
-mkdir -p ~/.local/share/applications/
+mkdir -p ~/.local/share/applications/
-cp dist/AmpleLinux/AmpleLinux.desktop ~/.local/share/applications/
+cp dist/AmpleLinux/AmpleLinux.desktop ~/.local/share/applications/
-```
+```
-
+
-Then search for "**AmpleLinux**" in your applications menu.
+Then search for "**AmpleLinux**" in your applications menu.
-
+
-## 📂 Project Structure
+## 📂 Project Structure
-
+
-| File/Directory | Description |
+| File/Directory | Description |
-| :--- | :--- |
+| :--- | :--- |
-| **`AmpleLinux.sh`** | **Start Here**. Auto-setup script (uses venv + pip). |
+| **`AmpleLinux.sh`** | **Start Here**. Auto-setup script (uses venv + pip). |
-| **`build_elf.sh`** | **Build Script**. Creates standalone binary via PyInstaller. |
+| **`build_elf.sh`** | **Build Script**. Creates standalone binary via PyInstaller. |
-| `make_icon.py` | Helper to generate Linux PNG icons from source. |
+| `make_icon.py` | Helper to generate Linux PNG icons from source. |
-| `main.py` | Application entry point, UI rendering, and event loop. |
+| `main.py` | Application entry point, UI rendering, and event loop. |
-| `data_manager.py` | Parser for `.plist` machine definitions and MAME `.xml` software lists. |
+| `data_manager.py` | Parser for `.plist` machine definitions and MAME `.xml` software lists. |
-| `mame_launcher.py` | Command-line builder and process manager. |
+| `mame_launcher.py` | Command-line builder and process manager. |
-| `rom_manager.py` | Management and multi-threaded downloading of system ROMs. |
+| `rom_manager.py` | Management and multi-threaded downloading of system ROMs. |
-| `mame_downloader.py` | VGM Mod downloader (Windows only; unused on Linux). |
+| `mame_downloader.py` | VGM Mod downloader (Windows only; unused on Linux). |
-
+
-## 🔧 Troubleshooting
+## 🔧 Troubleshooting
-
+
-### MAME Not Detected
+### MAME Not Detected
-If the app can't find MAME:
+If the app can't find MAME:
-1.  **Ubuntu**: The app will offer to run `sudo snap install 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.
+2.  **Manual**: Go to **⚙️ Settings** > **Select MAME...** to browse to the binary.
-3.  **PATH**: Verify `which mame` returns a path.
+3.  **PATH**: Verify `which mame` returns a path.
-4.  Common paths: `/usr/bin/mame`, `/usr/games/mame`, `/var/lib/snapd/snap/bin/mame`
+4.  Common paths: `/usr/bin/mame`, `/usr/games/mame`, `/var/lib/snapd/snap/bin/mame`
-
+
-### Theme Detection
+### 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.
+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
+## 📝 Acknowledgments
-
+
-*   Original macOS version developer: [Kelvin Sherlock](https://github.com/ksherlock)
+*   Original macOS version developer: [Kelvin Sherlock](https://github.com/ksherlock)
-*   **Windows Port Developers: anomixer + Antigravity**
+*   **Windows Port Developers: anomixer + Antigravity**
-*   **Linux Port**: Adapted from AmpleWin by 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.*
@@ -1,114 +1,117 @@
-# AmpleLinux - Linux Port (Legacy Apple Emulator Frontend)
+# AmpleLinux - Linux Port (Legacy Apple Emulator Frontend)
-
+
-[English](README.md) | [繁體中文](README_tw.md)
+[English](README.md) | [繁體中文](README_tw.md)
-
+
-這是一個將 macOS 原生 [Ample](https://github.com/ksherlock/ample) 專案移植至 Linux 平台的版本，基於 [AmpleWin](../AmpleWin/) Windows 移植版改編。
+這是一個將 macOS 原生 [Ample](https://github.com/ksherlock/ample) 專案移植至 Linux 平台的版本，基於 [AmpleWin](../AmpleWin/) Windows 移植版改編。
-
+
-![](screenshot.png)
+![](screenshot.png)
-
+
-> [!IMPORTANT]
+> [!IMPORTANT]
-> **版本支援說明**：目前已同步支援至 Ample (macOS) 最新版本之資源定義以及 MAME 最新版本之核心。
+> **版本支援說明**：目前已同步支援至 Ample (macOS) 最新版本之資源定義以及 MAME 最新版本之核心。
-
+
-## 🍎 Ample (macOS) vs. AmpleLinux (Linux) 完整對照表
+## 🍎 Ample (macOS) vs. AmpleLinux (Linux) 完整對照表
-
+
-| 功能項目 | Ample (macOS 原生版) | AmpleLinux (Linux 版) | 說明 |
+| 功能項目 | Ample (macOS 原生版) | AmpleLinux (Linux 版) | 說明 |
-| :--- | :--- | :--- | :--- |
+| :--- | :--- | :--- | :--- |
-| **程式語言** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | 獨立開發，**完全沒動到 Mac 版原始碼** |
+| **程式語言** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | 獨立開發，**完全沒動到 Mac 版原始碼** |
-| **安裝方式** | .dmg 映像檔 / Homebrew | **免安裝綠色版 (+ .sh 自動配置)** | 透過 `AmpleLinux.sh` 一鍵搞定 Python 與依賴 |
+| **安裝方式** | .dmg 映像檔 / Homebrew | **免安裝綠色版 (+ .sh 自動配置)** | 透過 `AmpleLinux.sh` 一鍵搞定 Python 與依賴 |
-| **MAME 整合** | 內建客製版核心 | **使用系統安裝的 MAME** | 透過 apt、dnf、pacman 等套件管理器安裝 |
+| **MAME 整合** | 內建客製版核心 | **使用系統安裝的 MAME** | 透過 apt、dnf、pacman 等套件管理器安裝 |
-| **UI 介面** | macOS 原生組件 | **1:1 像素級 QSS 複刻** | 支援 **Adaptive 自適應淺色/深色主題** (GNOME/KDE) |
+| **UI 介面** | macOS 原生組件 | **1:1 像素級 QSS 複刻** | 支援 **Adaptive 自適應淺色/深色主題** (GNOME/KDE) |
-| **初始機器選擇** | 支援預設書籤 | **全自動持久化 (自動載入上次狀態)** | 全自動開啟上次使用的機器 |
+| **初始機器選擇** | 支援預設書籤 | **全自動持久化 (自動載入上次狀態)** | 全自動開啟上次使用的機器 |
-| **軟體清單效能** | 同步加載 | **延遲遞增加載 (Deferred Loading)** | 切換機器秒開 |
+| **軟體清單效能** | 同步加載 | **延遲遞增加載 (Deferred Loading)** | 切換機器秒開 |
-| **ROM 下載** | 支援自動下載 | **高效能 Failover 引擎** | 支援多伺服器切換 (callapple + mdk.cab) |
+| **ROM 下載** | 支援自動下載 | **高效能 Failover 引擎** | 支援多伺服器切換 (callapple + mdk.cab) |
-| **Video 支援** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan** | 使用 MAME 的跨平台渲染後端 |
+| **Video 支援** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan** | 使用 MAME 的跨平台渲染後端 |
-
+
-## 🌟 核心功能
+## 🌟 核心功能
-
+
-### 🍏 忠實還原 Mac 體驗 (功能對齊)
+### 🍏 忠實還原 Mac 體驗 (功能對齊)
-*   **視覺精準度**：精準支援 **Window 1x-4x** 模式，並內建機器專屬的比例啟發邏輯。
+*   **視覺精準度**：精準支援 **Window 1x-4x** 模式，並內建機器專屬的比例啟發邏輯。
-*   **軟體資料庫**：智慧過濾、搜尋遮罩、相容性檢查。
+*   **軟體資料庫**：智慧過濾、搜尋遮罩、相容性檢查。
-*   **進階槽位模擬**：完整支援嵌套子槽位（如 SCSI 卡），並具備穩健的設備初始化與「空」(None) 選項持久化邏輯。
+*   **進階槽位模擬**：完整支援嵌套子槽位（如 SCSI 卡），並具備穩健的設備初始化與「空」(None) 選項持久化邏輯。
-*   **ROM 管理**：即時搜尋、多伺服器 Failover 下載、擴展韌體庫。
+*   **ROM 管理**：即時搜尋、CallApple 優先／MDK 備用 Failover 下載、`dragon32` 自動補丁及 Laser 128 全系列韌體庫相容性。
-    *   **相容性降級 (Compatibility Fallback)**：自動偵測受 MAME 0.288 EASC 晶片崩潰 Bug 影響的 PowerBook 機型（如 `macpb160` 等），自動切換至本地的 `mame_0287` 或 `mame-vgm`；若無備用執行檔，則會彈窗提供引導按鈕，協助使用者開啟官方 SDL Wiki 取得適用於該 Linux 發行版的舊版 MAME 執行檔。
+    *   **全面相容性**：MAME 0.289 官方已修正 PowerBook 機型（如 `macpb160`, `macpb180` 等）的 EASC 晶片崩潰 Bug，所有 PowerBook 機型現可使用最新 MAME 核心直接原生啟動。
-*   **共享目錄**：與 Mac 版功能完全對齊 (`-share_directory`)。
+*   **共享目錄**：與 Mac 版功能完全對齊 (`-share_directory`)。
-
+
-### 🐧 Linux 專屬功能
+### 🐧 Linux 專屬功能
-*   **系統 MAME 整合**：自動偵測 `PATH`、`/usr/bin/mame`、`/usr/games/mame` 等路徑。
+*   **系統 MAME 整合**：自動偵測 `PATH`、`/usr/bin/mame`、`/usr/games/mame` 等路徑。
-*   **自適應主題**：即時偵測 GNOME (`gsettings`) 與 KDE 的深色/淺色模式。
+*   **自適應主題**：即時偵測 GNOME (`gsettings`) 與 KDE 的深色/淺色模式。
-*   **原生檔案管理**：使用 `xdg-open` 開啟檔案、資料夾和 URL。
+*   **原生檔案管理**：使用 `xdg-open` 開啟檔案、資料夾和 URL。
-*   **無額外依賴**：MAME 直接透過發行版的套件管理器安裝。
+*   **無額外依賴**：MAME 直接透過發行版的套件管理器安裝。
-
+
-### ⚠️ 已知限制
+### ⚠️ 已知限制
-*   **VGM Mod**：「Generate VGM」功能目前在 Linux 暫停使用，因為 MAME VGM Mod 功能所需的執行檔目前僅有 Windows 版本。
+*   **VGM Mod**：「Generate VGM」功能目前在 Linux 暫停使用，因為 MAME VGM Mod 功能所需的執行檔目前僅有 Windows 版本。
-
+
-
+
-## 🛠️ 快速開始
+## 🛠️ 快速開始
-
+
-### 前置需求
+### 前置需求
-   **Python 3.9+**
+-   **Python 3.9+**
-   **MAME**（透過套件管理器安裝）
+-   **MAME**（透過套件管理器安裝）
-   **PySide6** 和 **requests**（透過系統套件或 pip 安裝）
+-   **PySide6** 和 **requests**（透過系統套件或 pip 安裝）
-
+
-### 安裝步驟
+### 安裝步驟
-
+
-1.  **安裝系統依賴套件**：
+1.  **安裝系統依賴套件**：
-    *   **MAME**：透過您的套件管理器安裝（例如 `sudo apt install mame`）。
+    *   **MAME**：透過您的套件管理器安裝（例如 `sudo apt install mame`）。
-    *   **Python 3**：確認已安裝 Python 3.9+（`sudo apt install python3-full`）。
+    *   **Python 3**：確認已安裝 Python 3.9+（`sudo apt install python3-full`）。
-    *   **X11 支援**：GUI 介面所需（`sudo apt install libxcb-cursor0`）。
+    *   **X11 支援**：GUI 介面所需（`sudo apt install libxcb-cursor0`）。
-
+
-2.  **啟動 Ample**：
+2.  **啟動 Ample**：
-    ```bash
+    ```bash
-    cd AmpleLinux
+    cd AmpleLinux
-    chmod +x AmpleLinux.sh
+    chmod +x AmpleLinux.sh
-    ./AmpleLinux.sh
+    ./AmpleLinux.sh
-    ```
+    ```
-    腳本會**自動**建立虛擬環境 (`.venv`)，透過 pip 安裝 `PySide6` 與其他依賴套件，最後啟動程式。**您不需要手動執行 pip install。**
+    腳本會**自動**建立虛擬環境 (`.venv`)，透過 pip 安裝 `PySide6` 與其他依賴套件，最後啟動程式。**您不需要手動執行 pip install。**
-
+
-3.  **快速部署**：
+3.  **快速部署**：
-    *   **Ubuntu 使用者**：如果找不到 MAME，程式會詢問是否透過 `snap` 安裝。
+    *   **Ubuntu 使用者**：如果找不到 MAME，程式會詢問是否透過 `snap` 安裝。
-    *   點擊主介面的 **🎮 ROMs** 以補齊系統韌體。
+    *   點擊主介面的 **🎮 ROMs** 以補齊系統韌體。
-    *   前往 **⚙️ Settings** 確認 MAME 已偵測到。
+    *   前往 **⚙️ Settings** 確認 MAME 已偵測到。
-    *   選擇機器，然後 **Launch MAME**！
+    *   選擇機器，然後 **Launch MAME**！
-
+
-## 📦 封裝發佈 (Build for Release)
+## 📦 封裝發佈 (Build for Release)
-
+
-若要產生不需要依賴環境的獨立 Linux 執行檔 (ELF)：
+若要產生不需要依賴環境的獨立 Linux 執行檔 (ELF)：
-
+
-```bash
+```bash
-cd AmpleLinux
+cd AmpleLinux
-chmod +x build_elf.sh
+chmod +x build_elf.sh
-./build_elf.sh
+./build_elf.sh
-```
+```
-
+
-此腳本會在暫存的 venv 中使用 `PyInstaller` 進行打包，產出的可攜式執行檔位於 `dist/AmpleLinux/`。
+此腳本會在暫存的 venv 中使用 `PyInstaller` 進行打包，產出的可攜式執行檔位於 `dist/AmpleLinux/`。
-
+
-## 📂 專案結構
+## 📂 專案結構
-
+
-| 檔案/目錄 | 說明 |
+| 檔案/目錄 | 說明 |
-| :--- | :--- |
+| :--- | :--- |
-| **`AmpleLinux.sh`** | **由此開始**。自動設定腳本 (使用 venv + pip)。 |
+| **`AmpleLinux.sh`** | **由此開始**。自動設定腳本 (使用 venv + pip)。 |
-| **`build_elf.sh`** | **封裝腳本**。透過 PyInstaller 產生獨立執行檔。 |
+| **`build_elf.sh`** | **封裝腳本**。透過 PyInstaller 產生獨立執行檔。 |
-| `make_icon.py` | 用於從來源圖片產生 Linux PNG 圖示的工具。 |
+| `make_icon.py` | 用於從來源圖片產生 Linux PNG 圖示的工具。 |
-| `main.py` | 應用程式入口，處理 UI 渲染與主要邏輯。 |
+| `main.py` | 應用程式入口，處理 UI 渲染與主要邏輯。 |
-| `data_manager.py` | 負責解析 `.plist` 機器定義檔與 MAME `.xml` 軟體列表。 |
+| `data_manager.py` | 負責解析 `.plist` 機器定義檔與 MAME `.xml` 軟體列表。 |
-| `mame_launcher.py` | MAME 指令建構器與執行序管理器。 |
+| `mame_launcher.py` | MAME 指令建構器與執行序管理器。 |
-| `rom_manager.py` | 系統 ROM 的管理與多執行緒下載引擎。 |
+| `rom_manager.py` | 系統 ROM 的管理與多執行緒下載引擎。 |
-| `mame_downloader.py` | VGM Mod 下載工具 (僅限 Windows; Linux 未使用)。 |
+| `mame_downloader.py` | VGM Mod 下載工具 (僅限 Windows; Linux 未使用)。 |
-
+
-## 🔧 疑難排解
+## 🔧 疑難排解
-
+
-### MAME 未偵測到
+### MAME 未偵測到
-如果程式無法找到 MAME：
+如果程式無法找到 MAME：
-1.  **Ubuntu**：程式會提供 `sudo snap install mame` 的安裝選項。
+1.  **Ubuntu**：程式會提供 `sudo snap install mame` 的安裝選項。
-2.  **手動設定**：前往 **⚙️ Settings** > **Select MAME...** 手動瀏覽並選擇執行檔。
+2.  **手動設定**：前往 **⚙️ Settings** > **Select MAME...** 手動瀏覽並選擇執行檔。
-3.  **PATH**：確認 `which mame` 能回傳路徑。
+3.  **PATH**：確認 `which mame` 能回傳路徑。
-4.  常見路徑：`/usr/bin/mame`、`/usr/games/mame`、`/var/lib/snapd/snap/bin/mame`
+4.  常見路徑：`/usr/bin/mame`、`/usr/games/mame`、`/var/lib/snapd/snap/bin/mame`
-
+
-### 主題偵測
+### 主題偵測
-程式會自動偵測 GNOME 和 KDE 的深色/淺色主題。如果你的桌面環境不受支援，程式會使用 Qt 調色盤作為主題偵測的後備方案。
+程式會自動偵測 GNOME 和 KDE 的深色/淺色主題。如果你的桌面環境不受支援，程式會使用 Qt 調色盤作為主題偵測的後備方案。
-
+
-## 📝 致謝
+## 📝 致謝
-
+
-*   原始 macOS 版本開發者: [Kelvin Sherlock](https://github.com/ksherlock)
+*   原始 macOS 版本開發者: [Kelvin Sherlock](https://github.com/ksherlock)
-*   **Windows Port 開發者: anomixer + Antigravity**
+*   **Windows Port 開發者: anomixer + Antigravity**
-*   **Linux Port**：由 anomixer + Antigravity 基於 AmpleWin 改編
+*   **Linux Port**：由 anomixer + Antigravity 基於 AmpleWin 改編
 ---
 *免責聲明：AmpleLinux 是一個獨立的開源專案，與 Apple Inc. 或本專案提及之任何其他公司均無任何隸屬、授權、維護或背書關係。所有產品及公司名稱均為其各自持有人的商標™或註冊®商標。*
@@ -1228,6 +1228,16 @@ class AmpleMainWindow(QMainWindow):
            # 不再於切換時立即填充軟體清單 (延遲加載以優化效能)
            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 @@ class AmpleMainWindow(QMainWindow):
                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 @@ class AmpleMainWindow(QMainWindow):
                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 @@ class AmpleMainWindow(QMainWindow):
            # 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 @@ class AmpleMainWindow(QMainWindow):
        # 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 @@ class AmpleMainWindow(QMainWindow):
            target_exe_path = args[0]
            if exe_cmd == "mame":
-                affected_macs = ["macpb160", "macpb180", "macpb165", "macpb165c", "macpb180c"]
+                target_exe_path = 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")
                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
            elif exe_cmd == "mame-vgm":
                 path_vgm = os.path.join(mame_bin_dir, "mame-vgm")
                 if os.path.exists(path_vgm):
@@ -40,6 +40,10 @@ class DownloadWorker(QRunnable):
                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 @@ class DownloadWorker(QRunnable):
        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 @@ class RomManager(QObject):
            {'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:
@@ -1,418 +1,463 @@
-# Agent Task Audit Log - Ample Windows Port
+# Agent Task Audit Log - Ample Windows Port
-
+
-## 📅 Session: 2026-06-05 (Session 16)
+## 📅 Session: 2026-08-02 (Session 17)
-
+
-### 🎯 Objective: PowerBook Compatibility Fallback & Downloader Acceleration
+### 🎯 Objective: Upstream MAME v0.289 Synchronization
-Addressed upstream MAME 0.288 C++ late-binding bug causing crashes on EASC audio chip Macs, and accelerated the VGM Mod download.
+Synchronized AmpleWin with upstream `ksherlock/ample` v0.289 release, updated official MAME download binary URL, and updated machine `.plist` configuration definitions.
-
+
-### ✅ Key Achievements:
+### ✅ Key Achievements:
-1.  **EASC Crash Fallback Mechanism**:
+1.  **MAME 0.289 Downloader Upgrade**:
-    *   Added automatic detection for affected PowerBook models (`macpb160`, `macpb180`, `macpb165`, `macpb165c`, `macpb180c`).
+    *   Updated `mame_downloader.py` download target to official MAME v0.289 64-bit binary release (`mame0289b_x64.exe`).
-    *   Implements seamless redirect to `mame_0287.exe` or `mame-vgm.exe` (v0.280) if present in the executable folder.
+2.  **PowerBook Native Launch (EASC Bug Fixed)**:
-    *   Provides user warning with options to auto-download MAME v0.280 (VGM Mod) fallback, force launch under 0.288, or cancel.
+    *   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.
-2.  **Downloader Optimization**:
+3.  **ROM Manager Priority & Dragon32/Laser Series Fixes**:
-    *   Switched VGM Mod download mirror to prioritize `mirror.ghproxy.com` GitHub proxy for faster global asset retrieval.
+    *   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.
-3.  **ROM Manager Priority Check**:
+    *   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`.
-    *   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+.
+    *   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-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.
+## 📅 Session: 2026-06-05 (Session 16)
-
+
-### ✅ Key Achievements:
+### 🎯 Objective: MAME v0.288 Upgrade, PowerBook Fallbacks & AmpleWeb Synchronization
-1.  **Command-Line Slot Persistence**:
+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.
-    *   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.
+### ✅ Key Achievements:
-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.
+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**:
-## 📅 Session: 2026-05-11 (Session 14)
+    *   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.).
-### 🎯 Objective: Slot Configuration Consistency Fix
+3.  **EASC Crash Fallback (Core)**:
-Resolved an issue where slots with defaults could not be set to "None" because UI refreshes would revert them.
+    *   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)**:
-### ✅ Key Achievements:
+    *   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.
-1.  **"None-Aware" Slot Initialization**:
+5.  **Downloader Optimization & SCSI Fix**:
-    *   Modified `initialize_default_slots` to use `slot_name not in self.current_slots`.
+    *   Prioritized `mdk.cab` split server in `rom_manager.py` and `rom_manager_cli.py` to prevent missing file errors on 0.288+.
-    *   Ensured manual "None" selections are preserved while maintaining automated defaults for new card insertion.
+    *   Verified SCSI CD-ROM 2x speed fallback `cdrom_2x` mappings on both frontends to resolve media mount bugs.
-2.  **Upstream Compatibility**: Prepared codebase for PR back to original source, ensuring robust slot behavior.
+
-
+---
---
+
-
+## 📅 Session: 2026-05-19 (Session 15)
-## 📅 Session: 2026-03-02 (Session 13)
+
-
+### 🎯 Objective: Complete Slot Configuration Persistence (MAME Command Line)
-### 🎯 Objective: Upstream Version Bump & Documentation Maintenance
+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.
-Focused on updating the project to track MAME 0.286 and simplifying documentation maintainability.
+
-
+### ✅ Key Achievements:
-### ✅ Key Achievements:
+1.  **Command-Line Slot Persistence**:
-1.  **Version Bump**: Updated `mame_downloader.py` to point to the latest **MAME 0.286** x64 Windows binary.
+    *   Modified `build_args` in `mame_launcher.py` to allow empty string values (e.g. `option is not None` instead of `if option:`).
-2.  **Documentation Refactoring**: 
+    *   This ensures that `-[slot_name] ""` is explicitly passed on the command line, preventing MAME from falling back to its internal defaults.
-    *   Renamed version-specific screenshot files (e.g. `screenshot-v0.28x.png` to `screenshot.png`) across all platforms.
+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.
-    *   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-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.
-## 📅 Session: 2026-02-16 (Session 12)
+
-
+### ✅ Key Achievements:
-### 🎯 Objective: Linux Port Spinoff
+1.  **"None-Aware" Slot Initialization**:
-AmpleWin has successfully served as the foundation for a new Linux port. 
+    *   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.
-### ✅ Key Achievements:
+2.  **Upstream Compatibility**: Prepared codebase for PR back to original source, ensuring robust slot behavior.
-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.
+## 📅 Session: 2026-05-11 (Session 14)
-
+
-### 🚀 Current Project Status
+### 🎯 Objective: Slot Configuration Parity & "None" Persistence
-The project now supports both Windows (AmpleWin) and Linux (AmpleLinux) natively.
+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**: 
-## 📅 Session: 2026-02-09 (Session 11)
+    *   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**:
-### 🎯 Objective: Upstream Synchronization & Codebase Hygiene
+    *   Coordinated this fix across **AmpleWin** and **AmpleLinux**.
-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.
+    *   Verified that **AmpleWeb** already correctly handled this logic due to its Object-based option finding mechanism.
-
+3.  **Nested Slot Preservation**:
-### ✅ Key Achievements:
+    *   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.
-
+
-1.  **Full Upstream Sync**:
+### 🚀 Current Project Status
-    *   **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`)**.
+Slot configuration behavior is now fully consistent across Windows, Linux, and Web ports, accurately respecting "None" selections while preserving automated nested configurations.
-    *   **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**:
+## 📅 Session: 2026-03-02 (Session 13)
-    *   **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.
+### 🎯 Objective: Upstream Version Bump & Documentation Maintenance
-3.  **Deployment & Distribution**:
+Focused on updating the project to track MAME 0.286 and simplifying documentation maintainability.
-    *   **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.
+### ✅ Key Achievements:
-    *   **Path Logic**: Updated `main.py` with robust `sys.frozen` detection to ensure resources and downloads work correctly in both Dev and Frozen environments.
+1.  **Version Bump**: Updated `mame_downloader.py` to point to the latest **MAME 0.286** x64 Windows binary.
-    *   **Documentation**: Added build instructions to READMEs.
+2.  **Documentation Refactoring**: 
-
+    *   Renamed version-specific screenshot files (e.g. `screenshot-v0.28x.png` to `screenshot.png`) across all platforms.
-### 🚀 Current Project Status
+    *   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.
-The codebase is now in a "Clean Slate" state. `master` is fully synced with upstream, with `AmpleWin` serving as a strictly additive extension.
+
-
+### 🚀 Current Project Status
-## 📅 Session: 2026-02-02 (Session 10)
+The Windows Port is functionally tracking MAME 0.286 and documentation is now future-proofed against minor version increments.
-
+
-### 🎯 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.
+
-
+## 📅 Session: 2026-02-16 (Session 12)
-### ✅ Key Achievements:
+
-
+### 🎯 Objective: Linux Port Spinoff
-1.  **ROM Library & Search Expansion**:
+AmpleWin has successfully served as the foundation for a new Linux port. 
-    *   **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`).
+### ✅ Key Achievements:
-
+1.  **Port Creation**:
-2.  **Robust ROM Download Failover**:
+    *   **AmpleLinux**: Created `AmpleLinux/` directory based on the AmpleWin codebase.
-    *   **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.
+    *   **Shared DNA**: `data_manager.py` and `rom_manager.py` remain identical, while `main.py` was adapted for Linux (xdg-open, paths, dependencies).
-    *   **Status Integrity**: Fixed a bug in the download progress counter to ensure accurate success/failure reporting in the UI.
+    *   **Cross-Reference**: Added links to AmpleLinux in the README.
-
+
-3.  **Advanced Slot & Media Emulation**:
+### 🚀 Current Project Status
-    *   **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).
+The project now supports both Windows (AmpleWin) and Linux (AmpleLinux) natively.
-    *   **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.
+
-
+## 📅 Session: 2026-02-09 (Session 11)
-### 🚀 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.
+
-
+### 🎯 Objective: Upstream Synchronization & Codebase Hygiene
-## 📅 Session: 2026-02-02 (Session 9)
+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.
-
+
-### 🎯 Objective: Upstream Synchronization & Feature Parity (MAME 0.286)
+### ✅ Key Achievements:
-Focused on synchronizing with the upstream Ample (macOS) v0.286 release, updating the core emulator backend, and implementing new UI search capabilities.
+
-
+1.  **Full Upstream Sync**:
-### ✅ Key Achievements:
+    *   **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.
-1.  **Upstream Repository Synchronization**:
+    *   **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.
-    *   **Merge & Push**: Successfully merged latest commits from `upstream/master` (ksherlock/ample).
+
-    *   **Resource Alignment**: Synchronized latest hardware definitions and slot configurations from original project.
+2.  **AmpleWin Verification**:
-    *   **A2retroNET Integration**: Inherited support for a2retronet hardware, enabling up to 8 SmartPort disk images.
+    *   **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.
-2.  **MAME Core Update**:
+3.  **Deployment & Distribution**:
-    *   **Version Upgrade**: Updated `mame_downloader.py` to point to the official **MAME 0.286** Windows x64 binary.
+    *   **Refactor**: Renamed `mame_bin` to `mame` across the codebase for better standards compliance.
-    *   **Download Engine Parity**: Users can now auto-download the latest MAME core directly from the Settings menu.
+    *   **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.
-3.  **ROM Manager Enhancements**:
+    *   **Documentation**: Added build instructions to READMEs.
-    *   **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 codebase is now in a "Clean Slate" state. `master` is fully synced with upstream, with `AmpleWin` serving as a strictly additive extension.
-### 🚀 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-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.
-
+
-## 📅 Session: 2026-01-24 (Session 8)
+### ✅ Key Achievements:
-
+
-### 🎯 Objective: Path robustness & UI Interactivity
+1.  **ROM Library & Search Expansion**:
-Focused on fixing "No such file" errors when launching custom ROM paths and improving the user experience for file selection in secondary tabs.
+    *   **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`).
-### ✅ Key Achievements:
+
-
+2.  **Robust ROM Download Failover**:
-1.  **Command Line Robustness**:
+    *   **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.
-    *   **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.
+    *   **Status Integrity**: Fixed a bug in the download progress counter to ensure accurate success/failure reporting in the UI.
-
+
-2.  **File Selection UX**:
+3.  **Advanced Slot & Media Emulation**:
-    *   **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.
+    *   **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).
-    *   **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.
+    *   **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.
-### 🚀 Current Project Status
+    *   **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.
-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.
+
-
+### 🚀 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-01-22 (Session 7)
+## 📅 Session: 2026-02-02 (Session 9)
-
+
-### 🎯 Objective: User Freedom & flexible Command Control
+### 🎯 Objective: Upstream Synchronization & Feature Parity (MAME 0.286)
-Focused on giving the user complete control over the MAME launch command and ensuring a cleaner default state for machine slots.
+Focused on synchronizing with the upstream Ample (macOS) v0.286 release, updating the core emulator backend, and implementing new UI search capabilities.
-
+
-### ✅ Key Achievements:
+### ✅ Key Achievements:
-
+
-1.  **Editable Command Console**:
+1.  **Upstream Repository Synchronization**:
-    *   **Unlocked Preview**: The "Command Preview" text box is no longer read-only.
+    *   **Merge & Push**: Successfully merged latest commits from `upstream/master` (ksherlock/ample).
-    *   **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.
+    *   **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.  **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.
+2.  **MAME Core Update**:
-    *   **VGM Pathing**: Logic retains awareness of VGM Mod capabilities even when launching from a custom text string.
+    *   **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.  **Cleaner Default State**:
+
-    *   **Slot Neutrality**: Removed the aggressive fallback logic that forced the first available option for slots without a default value.
+3.  **ROM Manager Enhancements**:
-    *   **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.
+    *   **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 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.
+### 🚀 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-21 (Session 6)
+
-
+
-### 🎯 Objective: VGM Mod Stability & Extraction Safety
+## 📅 Session: 2026-01-24 (Session 8)
-Focused on fixing critical bugs in the VGM recording workflow, ensuring extraction safety, and improving UI feedback for the modded binary.
+
-
+### 🎯 Objective: Path robustness & UI Interactivity
-### ✅ Key Achievements:
+Focused on fixing "No such file" errors when launching custom ROM paths and improving the user experience for file selection in secondary tabs.
-
+
-1.  **VGM Mod Extraction Safety**:
+### ✅ Key Achievements:
-    *   **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.
+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.  **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.
+2.  **File Selection UX**:
-    *   **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.
+    *   **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.
-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.
+### 🚀 Current Project Status
-    *   **Worker Refactoring**: Rewrote the `VgmModDownloadWorker` and `VgmPostProcessWorker` logic to handle edge cases in file movement and process termination more gracefully.
+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.
-
+
-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.
+## 📅 Session: 2026-01-22 (Session 7)
-    *   **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.
+### 🎯 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.
-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.
+### ✅ Key Achievements:
-    *   **Prevention**: Prevents users from accidentally selecting incompatible hardware configurations that would cause MAME to crash or behave unexpectedly.
+
-
+1.  **Editable Command Console**:
-### 🚀 Current Project Status
+    *   **Unlocked Preview**: The "Command Preview" text box is no longer read-only.
-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.
+    *   **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.
-## 📅 Session: 2026-01-21 (Session 5)
+    *   **VGM Pathing**: Logic retains awareness of VGM Mod capabilities even when launching from a custom text string.
-
+
-### 🎯 Objective: MAME Core Logic & Command Line Robustness
+3.  **Cleaner Default State**:
-Focused on improving the reliability of the MAME launch engine, specifically regarding dynamic slot media (CFFA2), multi-drive support, and shell-safe command construction.
+    *   **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.
-### ✅ Key Achievements:
+
-
+### 🚀 Current Project Status
-1.  **Relaxed Parameter Validation**:
+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.
-    *   **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**:
+## 📅 Session: 2026-01-21 (Session 6)
-    *   **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`).
+### 🎯 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.
-3.  **Shell Integrity & Quoting**:
+
-    *   **Robust Quoting**: Integrated `subprocess.list2cmdline` for both the UI Command Preview and the actual process execution.
+### ✅ Key Achievements:
-    *   **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 (`\`).
+1.  **VGM Mod Extraction Safety**:
-    *   **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.
+    *   **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).
-    *   **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.
+    *   **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.
-
+
-4.  **Resolution Scaling & Visual Parity**:
+2.  **Command Line & UI Parity**:
-    *   **Window Mode Scaling**: Implemented `-resolution` generation for scaling modes (2x, 3x, 4x) and **`-nomax`** for **Window 1x** mode to ensure consistent default sizing.
+    *   **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.
-    *   **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.
+    *   **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.
-    *   **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.
+3.  **Thread & Lifecycle Stability**:
-    *   **Disk Sound Effects Integration**: Linked the "Disk Sound Effects" checkbox to the `-nosamples` argument, allowing MAME samples to load when sound effects are enabled.
+    *   **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.
-    *   **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.
+    *   **Worker Refactoring**: Rewrote the `VgmModDownloadWorker` and `VgmPostProcessWorker` logic to handle edge cases in file movement and process termination more gracefully.
-
+
-5.  **BGFX Effect Synchronization**:
+4.  **Shared Directory & UI Refinement**:
-    *   **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**.
+    *   **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.
-    *   **Chain Mapping**: Implemented precise mapping between UI selection and MAME's `-bgfx_screen_chains` internal identifiers.
+    *   **Standardized Argument**: Updated from `-share` to the official `-share_directory` for maximum compatibility.
-
+    *   **UI Bugfix**: Removed duplicate "Paths" tab initialization in the main window.
-### 🚀 Current Project Status
+    *   **Click-to-Browse**: Implemented a pop-up directory selector when clicking the Shared Directory path box, replacing manual entry.
-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.
+
-
+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.
-## 📅 Session: 2026-01-19 (Session 4)
+
-
+### 🚀 Current Project Status
-### 🎯 Objective: Real-time Adaptive Theming & UI Resilience
+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.
-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:
+
-
+## 📅 Session: 2026-01-21 (Session 5)
-1.  **Adaptive Theme Engine**:
+
-    *   **Registry-Level Detection**: Implemented `winreg` polling to detect `AppsUseLightTheme` changes in real-time.
+### 🎯 Objective: MAME Core Logic & Command Line Robustness
-    *   **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.
+Focused on improving the reliability of the MAME launch engine, specifically regarding dynamic slot media (CFFA2), multi-drive support, and shell-safe command construction.
-    *   **Cross-Window Propagation**: Ensured theme changes flow correctly into child dialogs (ROM Manager) and dynamic overlays (Software Search, Sub-slot popups).
+
-
+### ✅ Key Achievements:
-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.
+1.  **Relaxed Parameter Validation**:
-    *   **Themed Popups**: Rewrote `SoftwarePopup` and sub-slot bubble painting to dynamically adjust background colors and "triangle" indicators based on the system theme.
+    *   **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.
-    *   **ROM Manager Parity**: Fully themed the ROM download dialog, ensuring status labels (found/missing) maintain high contrast in both modes.
+    *   **Internal Filter**: Implemented logic to automatically skip internal MAME node names starting with a colon (e.g., `-:prn`) to prevent "unknown option" errors.
-
+
-3.  **Command Console Expansion**:
+2.  **Multi-Drive & Storage Support**:
-    *   **Multi-line Preview**: Replaced the single-line `QLineEdit` with a 4-line `QTextEdit` console footer.
+    *   **Capping Removal**: Fixed a self-imposed limitation in `main.py` that forced `hard`, `cdrom`, and `cassette` counts to 1. 
-    *   **Parameter Visibility**: This allows users to review the entire MAME command line, including long software list paths and slot configurations, without horizontal scrolling.
+    *   **CFFA2 Ready**: AmpleWin now correctly supports machines/cards with multiple hard drives (`-hard1`, `-hard2`).
-
+
-4.  **Stability & Bug Squashing**:
+3.  **Shell Integrity & Quoting**:
-    *   **ROM Manager Reliability**: Corrected `@Slot` decorators and converted the dialog to `.exec()` (Modal) to prevent interaction conflicts.
+    *   **Robust Quoting**: Integrated `subprocess.list2cmdline` for both the UI Command Preview and the actual process execution.
-    *   **Logic Errors**: Fixed several `NameError` bugs in the rendering engine and addressed stylesheet inheritance issues that caused transparent list views.
+    *   **Space Handling**: Guaranteed that file paths containing spaces are automatically wrapped in quotes (`""`), preventing launch failures on Windows.
-5.  **Visual Documentation & Networking Guide**:
+    *   **Path Normalization**: Implemented `os.path.normpath` for all MAME arguments (`-hard`, `-rompath`, etc.), ensuring consistent Windows-style backslashes (`\`).
-    *   **README Screenshots**: Embedded `screenshot-v0.284.png` in READMEs to match original aesthetics.
+    *   **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.
-    *   **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.
+    *   **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.
-
+
-### 🚀 Current Project Status
+4.  **Resolution Scaling & Visual Parity**:
-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.
+    *   **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.
-## 📅 Session: 2026-01-19 (Session 3)
+    *   **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.
-### 🎯 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.
+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**.
-### ✅ Key Achievements:
+    *   **Chain Mapping**: Implemented precise mapping between UI selection and MAME's `-bgfx_screen_chains` internal identifiers.
-
+
-1.  **Documentation Internationalization**:
+### 🚀 Current Project Status
-    *   **Dual-Language Support**: Created `README.md` (English) and `README_tw.md` (Traditional Chinese) in the `AmpleWin` directory.
+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.
-    *   **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**:
+## 📅 Session: 2026-01-19 (Session 4)
-    *   **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.
+### 🎯 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.
-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.
+### ✅ Key Achievements:
-    *   **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.
+1.  **Adaptive Theme Engine**:
-
+    *   **Registry-Level Detection**: Implemented `winreg` polling to detect `AppsUseLightTheme` changes in real-time.
-### 🚀 Current Project Status
+    *   **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.
-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.
+    *   **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.
-## 📅 Session: 2026-01-18 (Session 2)
+    *   **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.
-### 🎯 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.
+3.  **Command Console Expansion**:
-
+    *   **Multi-line Preview**: Replaced the single-line `QLineEdit` with a 4-line `QTextEdit` console footer.
-### ✅ Key Achievements:
+    *   **Parameter Visibility**: This allows users to review the entire MAME command line, including long software list paths and slot configurations, without horizontal scrolling.
-
+
-1.  **Deployment & Portability**:
+4.  **Stability & Bug Squashing**:
-    *   **Auto-Launcher**: Created `ample_win.bat` to automate dependency installation and app execution.
+    *   **ROM Manager Reliability**: Corrected `@Slot` decorators and converted the dialog to `.exec()` (Modal) to prevent interaction conflicts.
-    *   **Dynamic Paths**: Replaced hardcoded absolute paths with a robust search algorithm that detects the `Ample/Resources` folder relative to the script location.
+    *   **Logic Errors**: Fixed several `NameError` bugs in the rendering engine and addressed stylesheet inheritance issues that caused transparent list views.
-    *   **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.
+5.  **Visual Documentation & Networking Guide**:
-
+    *   **README Screenshots**: Embedded `screenshot-v0.284.png` in READMEs to match original aesthetics.
-2.  **Explosive Download Engine**:
+    *   **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.
-    *   **Threading Mastery**: Transitioned to `QThreadPool` for manageable concurrency.
+
-    *   **Performance Leap**: Increased parallel download threads from 1 to **50**.
+### 🚀 Current Project Status
-    *   **Small File Optimization**: For ROM files (<64KB), switched from streaming to direct `requests.content` I/O, resulting in near-instant mass downloads.
+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.
-    *   **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.
+## 📅 Session: 2026-01-19 (Session 3)
-    *   **Sticky Software (Smart Carry-over)**: 
+
-        *   Selections and filters now persist across compatible machines.
+### 🎯 Objective: Documentation Standardization & UI Finalization
-        *   **Compatibility Logic**: Automatically clears selection if the new machine doesn't support the current software list.
+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.
-        *   **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.
+### ✅ Key Achievements:
-    *   **Windows 10 Fixes**: Applied global CSS overrides for `QMessageBox` and `QDialog` to fix unreadable grey-on-white text issues on Windows 10.
+
-
+1.  **Documentation Internationalization**:
-4.  **Project Hygiene**:
+    *   **Dual-Language Support**: Created `README.md` (English) and `README_tw.md` (Traditional Chinese) in the `AmpleWin` directory.
-    *   Updated `.gitignore` to exclude MAME runtime artifacts (`nvram/`, `cfg/`, `sta/`, etc.).
+    *   **Mutual Linking**: Implemented language-switching headers in both README files for a professional GitHub experience.
-    *   Updated `README_win.md` with the new one-click launch instructions.
+    *   **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.
-
+
-### 🚀 Current Project Status
+2.  **UI Finalization & Utility Tools**:
-Ample Windows is now highly portable and user-friendly. The download system is exceptionally fast, and the environment stays clean during emulation sessions.
+    *   **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.
-## 📅 Session: 2026-01-18 (Session 1)
+
-
+3.  **Project Structure Hygiene**:
-### 🎯 Objective: Software List Integration & Final UI Polish
+    *   **Namespace Isolation**: Relocated all Windows-specific overhead files (`README_tw.md`, `AmpleWin.bat`, `requirements.txt`, `Agent.md`) into the `AmpleWin` subdirectory.
-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.
+    *   **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.
-### ✅ Key Achievements:
+
-
+### 🚀 Current Project Status
-1.  **Software List Feature**:
+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.
-    *   **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.
+
-
+## 📅 Session: 2026-01-18 (Session 2)
-2.  **MAME Launch Engine**:
+
-    *   **Argument Ordering**: Fixed Windows-specific software list resolution issues by placing software list items immediately after the machine name.
+### 🎯 Objective: Deployment, Performance & Path Robustness
-    *   **Path Isolation**: Standardized `-hashpath`, `-bgfx_path`, and `-rompath` to be relative to the application's `mame_bin` directory.
+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.
-    *   **Resource Management**: Centralized ROM storage to `mame_bin\roms`.
+
-
+### ✅ Key Achievements:
-3.  **UI Aesthetic Refinement**:
+
-    *   **Apple Launch Button**: Replicated the Mac-style 🍎 icon inside the Launch button with left-aligned icon and right-aligned text.
+1.  **Deployment & Portability**:
-    *   **Full-Width Console**: Moved the Command Preview to a full-width footer with a console-style (black background, monospace) styling.
+    *   **Auto-Launcher**: Created `ample_win.bat` to automate dependency installation and app execution.
-    *   **Clean Mode**: Removed "Use Samples" checkbox and hardcoded `-nosamples` for authenticity.
+    *   **Dynamic Paths**: Replaced hardcoded absolute paths with a robust search algorithm that detects the `Ample/Resources` folder relative to the script location.
-    *   **Proportional Layout**: Expanded the options area to comfortably display long software names (60+ characters).
+    *   **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.
-
+
-4.  **Stability & Initialization**:
+2.  **Explosive Download Engine**:
-    *   **Graceful Shutdown**: Improved thread termination logic in `closeEvent`.
+    *   **Threading Mastery**: Transitioned to `QThreadPool` for manageable concurrency.
-    *   **Safe Initialization**: Fixed attribute and name errors in `DataManager` and `AmpleMainWindow` during early startup phases.
+    *   **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.
-### 🚀 Current Project Status
+    *   **Anti-Throttling**: Added browser-masking `User-Agent` headers.
-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.
+
-
+3.  **User Experience (UX)**:
---
+    *   **Startup Wizard**: Implemented sequential logic: Check MAME -> Guided Download -> Check ROMs -> Guided Download.
-
+    *   **Sticky Software (Smart Carry-over)**: 
-##  Handover Notes for Future Agents
+        *   Selections and filters now persist across compatible machines.
-
+        *   **Compatibility Logic**: Automatically clears selection if the new machine doesn't support the current software list.
-### 1. UI Implementation Strategy (CRITICAL)
+        *   **Full Name Display**: The search box now displays the full, descriptive software name instead of the short MAME ID.
-*   **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:
+        *   **UI Cleanliness**: Software lists stay collapsed during machine switches for a sleeker look.
-    *   A `QWidget` container holds the `QComboBox`.
+    *   **Windows 10 Fixes**: Applied global CSS overrides for `QMessageBox` and `QDialog` to fix unreadable grey-on-white text issues on Windows 10.
-    *   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.
+4.  **Project Hygiene**:
-*   **Alignment**: The global fixed width for slot combos is **160px**. The arrow overlay is **20px** wide.
+    *   Updated `.gitignore` to exclude MAME runtime artifacts (`nvram/`, `cfg/`, `sta/`, etc.).
-
+    *   Updated `README_win.md` with the new one-click launch instructions.
-### 2. Adaptive Theming
+
-*   **Real-time Detection**: The app polls the Windows Registry every 2 seconds for theme changes.
+### 🚀 Current Project Status
-*   **Centralized CSS**: Most UI colors are defined in `apply_premium_theme` using Python f-strings, allowing instant restyling of all common widgets.
+Ample Windows is now highly portable and user-friendly. The download system is exceptionally fast, and the environment stays clean during emulation sessions.
-*   **Persistent IDs**: Labels and special widgets use `setObjectName` to inherit styles from the global stylesheet, avoiding contrast issues during theme transitions.
+
-
+## 📅 Session: 2026-01-18 (Session 1)
-### 3. State Management
+
-*   **Sub-Slot Popups**: Tracked via `self.active_popup` in `AmpleMainWindow`. 
+### 🎯 Objective: Software List Integration & Final UI Polish
-*   **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.
+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.
-
+
-### 4. Data Processing
+### ✅ Key Achievements:
-*   `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.
+1.  **Software List Feature**:
-
+    *   **XML Parsing**: Enhanced `DataManager` to parse MAME's `hash/*.xml` files.
-### 5. Known Mantras
+    *   **Intelligent Discovery**: Implemented a search-based software browser with autocomplete-style show/hide logic.
-*   **Visual Parity is King**: Every margin, font size (mostly 11px/12px), and color was cross-referenced with macOS high-res screenshots.
+    *   **Auto-Detection**: Integrated software list selection into the MAME launch command with optimized argument ordering.
-*   **Authorship**: This Windows Port is a collaboration between **anomixer** and **Antigravity**.
+
 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**.
@@ -1,108 +1,111 @@
-# AmpleWin - Windows Port (Legacy Apple Emulator Frontend)
+# AmpleWin - Windows Port (Legacy Apple Emulator Frontend)
-
+
-[English](README.md) | [繁體中文](README_tw.md)
+[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.
+This is a precision port of the macOS native [Ample](https://github.com/ksherlock/ample) project to the Windows platform.
-
+
-> [!TIP]
+> [!TIP]
-> **Linux User?** Check out the [AmpleLinux](../AmpleLinux/) Port.
+> **Linux User?** Check out the [AmpleLinux](../AmpleLinux/) Port.
-
+
-
+
-![](screenshot.png)
+![](screenshot.png)
-
+
-> [!IMPORTANT]
+> [!IMPORTANT]
-> **Current Version Support**: Updated to stay in sync with the latest version of Ample (macOS) resources and also MAME latest binary.
+> **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
+## 🍎 Ample (macOS) vs. AmpleWin (Windows) Comparison
-
+
-| Feature | Ample (macOS Native) | AmpleWin (Windows Optimized) | Optimization & Notes |
+| 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** |
+| **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` |
+| **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 |
+| **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 |
+| **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 |
+| **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 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 |
+| **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) |
+| **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 |
+| **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 |
+| **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) |
+| **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 |
+| **Operating Logic** | Sticky Software Selection | **Sticky Software Selection** | Preserves compatible software selection when switching machines |
-
+
-## 🌟 Key Features
+## 🌟 Key Features
-
+
-### 🍏 Faithful Mac Experience (Feature Parity)
+### 🍏 Faithful Mac Experience (Feature Parity)
-*   **Visual Precision**: 
+*   **Visual Precision**: 
-    *   **Resolution Scaling**: Precision support for **Window 1x-4x** modes with machine-specific aspect ratio heuristics (e.g., Apple II 4:3 correction).
+    *   **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.
+    *   **Square Pixels**: Specialized integer-scaling mode (e.g., 1120x768) to eliminate pixel shimmering.
-*   **Software Library**:
+*   **Software Library**:
-    *   **Smart Filtering**: Automatically identifies supported media types (flop1, flop2, cass...) to match machine capabilities.
+    *   **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.
+    *   **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.
+    *   **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). 
+*   **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.
+    *   **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.
+    *   **Slot Consistency**: Improved logic to respect "None" (empty) selections across UI refreshes, matching the high standards of the native macOS port.
-*   **ROM Management**:
+*   **ROM Management**:
-    *   **Search Filter**: Real-time searching in the ROM manager window to quickly find system firmwares.
+    *   **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.
+    *   **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.
+    *   **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.
+    *   **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).
+*   **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.
+*   **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
+### 🪟 Windows-Specific Optimizations
-*   **Performance**:
+*   **Performance**:
-    *   **Concurrent Downloading**: Multi-threaded system for high-speed ROM acquisition.
+    *   **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.
+    *   **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.
+    *   **Deferred XML Loading**: Major optimization for instant machine switching and search response.
-*   **UI Enhancements**:
+*   **UI Enhancements**:
-    *   **Adaptive Theme**: Real-time synchronization with Windows Light/Dark system theme.
+    *   **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.
+    *   **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.
+    *   **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.
+*   **Flexible Backend**: Full support for BGFX, OpenGL, Vulkan, and **DirectX 11/12** out of the box.
-
+
-## 🛠️ Quick Start
+## 🛠️ Quick Start
-
+
-1.  **Launch Ample**:
+1.  **Launch Ample**:
-    Enter the **`AmpleWin`** folder and run **`AmpleWin.bat`**.
+    Enter the **`AmpleWin`** folder and run **`AmpleWin.bat`**.
-    *   The script will check the Python environment, install dependencies, and start the app.
+    *   The script will check the Python environment, install dependencies, and start the app.
-2.  **Fast Deployment**:
+2.  **Fast Deployment**:
-    *   Go to **⚙️ Settings** -> Click **Download MAME** to auto-configure the emulator.
+    *   Go to **⚙️ Settings** -> Click **Download MAME** to auto-configure the emulator.
-    *   Click **🎮 ROMs** to download system firmware.
+    *   Click **🎮 ROMs** to download system firmware.
-    *   Click **📂 Ample Dir** to quickly open the local application folder.
+    *   Click **📂 Ample Dir** to quickly open the local application folder.
-3.  **Start playing**:
+3.  **Start playing**:
-    *   Select a machine from the left panel.
+    *   Select a machine from the left panel.
-    *   **Double-click** the machine name or click **Launch MAME** to start.
+    *   **Double-click** the machine name or click **Launch MAME** to start.
-
+
-## 🌐 Networking (Advanced)
+## 🌐 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.
+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
+## 📂 Project Structure
-
+
-| File/Directory | Description |
+| File/Directory | Description |
-| :--- | :--- |
+| :--- | :--- |
-| **`AmpleWin.bat`** | **Start Here**. Auto-setup script (installs Python deps & runs app). |
+| **`AmpleWin.bat`** | **Start Here**. Auto-setup script (installs Python deps & runs app). |
-| `build_exe.bat` | **Packaging**. Creates a `dist` portable EXE folder using PyInstaller. |
+| `build_exe.bat` | **Packaging**. Creates a `dist` portable EXE folder using PyInstaller. |
-| `main.py` | Application entry point, UI rendering, and event loop. |
+| `main.py` | Application entry point, UI rendering, and event loop. |
-| `data_manager.py` | Parser for `.plist` machine definitions and MAME `.xml` software lists. |
+| `data_manager.py` | Parser for `.plist` machine definitions and MAME `.xml` software lists. |
-| `mame_launcher.py` | Command-line builder and process manager. |
+| `mame_launcher.py` | Command-line builder and process manager. |
-| `rom_manager.py` | Management and multi-threaded downloading of system ROMs. |
+| `rom_manager.py` | Management and multi-threaded downloading of system ROMs. |
-| `mame_downloader.py` | Automated MAME / VGM Mod downloader and extractor. |
+| `mame_downloader.py` | Automated MAME / VGM Mod downloader and extractor. |
-| `mame/` | Isolated directory for MAME executable, ROMs, and config files. |
+| `mame/` | Isolated directory for MAME executable, ROMs, and config files. |
-| `Agent.md` | Development log and session history. |
+| `Agent.md` | Development log and session history. |
-
+
-## 📦 Building from Source (Portable EXE)
+## 📦 Building from Source (Portable EXE)
-
+
-If you want to create a standalone executable for distribution:
+If you want to create a standalone executable for distribution:
-
+
-1.  Run `build_exe.bat` in the `AmpleWin` directory.
+1.  Run `build_exe.bat` in the `AmpleWin` directory.
-2.  The script will automatically install PyInstaller, package the application, and copy necessary resources.
+2.  The script will automatically install PyInstaller, package the application, and copy necessary resources.
-3.  The output will be in `AmpleWin\dist\AmpleWin`.
+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.
+4.  Copy the entire `AmpleWin` folder to any location. It is fully **portable** and does not require Python to run.
-
+
-## 📝 Acknowledgments
+## 📝 Acknowledgments
-
+
-*   Original macOS version developer: [Kelvin Sherlock](https://github.com/ksherlock)
+*   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.
+*   **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.*
@@ -1,108 +1,111 @@
-# AmpleWin - Windows Port (Legacy Apple Emulator Frontend)
+# AmpleWin - Windows Port (Legacy Apple Emulator Frontend)
-
+
-[English](README.md) | [繁體中文](README_tw.md)
+[English](README.md) | [繁體中文](README_tw.md)
-
+
-這是一個將 macOS 原生 [Ample](https://github.com/ksherlock/ample) 專案精準移植至 Windows 平台的版本。
+這是一個將 macOS 原生 [Ample](https://github.com/ksherlock/ample) 專案精準移植至 Windows 平台的版本。
-
+
-> [!TIP]
+> [!TIP]
-> **Linux 使用者？** 請參考 [AmpleLinux](../AmpleLinux/) Linux 移植版。
+> **Linux 使用者？** 請參考 [AmpleLinux](../AmpleLinux/) Linux 移植版。
-
+
-
+
-![](screenshot.png)
+![](screenshot.png)
-
+
-> [!IMPORTANT]
+> [!IMPORTANT]
-> **版本支援說明**：目前已同步支援至 Ample (macOS) 最新版本之資源定義以及 MAME 最新版本之核心。
+> **版本支援說明**：目前已同步支援至 Ample (macOS) 最新版本之資源定義以及 MAME 最新版本之核心。
-
+
-## 🍎 Ample (macOS) vs. AmpleWin (Windows) 完整對照表
+## 🍎 Ample (macOS) vs. AmpleWin (Windows) 完整對照表
-
+
-| 功能項目 | Ample (macOS 原生版) | AmpleWin (Windows 優化版) | 優化重點與說明 |
+| 功能項目 | Ample (macOS 原生版) | AmpleWin (Windows 優化版) | 優化重點與說明 |
-| :--- | :--- | :--- | :--- |
+| :--- | :--- | :--- | :--- |
-| **程式語言** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | 獨立開發，**完全沒動到 Mac 版原始碼** |
+| **程式語言** | Objective-C (Cocoa) | **Python 3.11 + PySide6 (Qt)** | 獨立開發，**完全沒動到 Mac 版原始碼** |
-| **安裝方式** | .dmg 映像檔 / Homebrew | **免安裝綠色版 (+ .bat 自動配置)** | 透過 `AmpleWin.bat` 一鍵搞定 Python 與依賴 |
+| **安裝方式** | .dmg 映像檔 / Homebrew | **免安裝綠色版 (+ .bat 自動配置)** | 透過 `AmpleWin.bat` 一鍵搞定 Python 與依賴 |
-| **UI 介面** | macOS 原生組件 | **1:1 像素級 QSS 複刻** | 在 Windows 實現 **Adaptive 自適應淺色/深色主題** |
+| **UI 介面** | macOS 原生組件 | **1:1 像素級 QSS 複刻** | 在 Windows 實現 **Adaptive 自適應淺色/深色主題** |
-| **MAME 整合** | 內建客製版核心，或自選客製版本 | **額外下載官方版核心，或自選客製版本** | 使用者可隨時更新 MAME 核心，若無亦可選擇額外下載 |
+| **MAME 整合** | 內建客製版核心，或自選客製版本 | **額外下載官方版核心，或自選客製版本** | 使用者可隨時更新 MAME 核心，若無亦可選擇額外下載 |
-| **初始機器選擇** | 支援預設書籤 (需手動設定) | **全自動持久化 (自動載入上次狀態)** | Mac 版需設為預設書籤，Windows 版則全自動開啟 |
+| **初始機器選擇** | 支援預設書籤 (需手動設定) | **全自動持久化 (自動載入上次狀態)** | Mac 版需設為預設書籤，Windows 版則全自動開啟 |
-| **軟體清單效能** | 同步加載 (解析完整 XML) | **延遲遞增加載 (Deferred Loading)** | **重大優化**：切換機器秒開，搜尋才加載，效能更佳 |
+| **軟體清單效能** | 同步加載 (解析完整 XML) | **延遲遞增加載 (Deferred Loading)** | **重大優化**：切換機器秒開，搜尋才加載，效能更佳 |
-| **軟體搜尋 UI** | 標準列表 (Pop-up) | **智慧搜尋疊層 (Smart Overlay)** | 支援即時搜尋、全名顯示，且不推擠其他 UI 元素 |
+| **軟體搜尋 UI** | 標準列表 (Pop-up) | **智慧搜尋疊層 (Smart Overlay)** | 支援即時搜尋、全名顯示，且不推擠其他 UI 元素 |
-| **ROM 下載** | 支援自動下載 (補齊缺失) | **高效能 Failover 引擎** | **重大優化**：支援多伺服器切換 (callapple + mdk.cab) |
+| **ROM 下載** | 支援自動下載 (補齊缺失) | **高效能 Failover 引擎** | **重大優化**：支援多伺服器切換 (callapple + mdk.cab) |
-| **參數驗證** | 依賴 .plist 靜態定義 | **動態查詢驗證 (Live Validation)** | **重大優化**：自動與 MAME 比對，防止指令報錯崩潰 |
+| **參數驗證** | 依賴 .plist 靜態定義 | **動態查詢驗證 (Live Validation)** | **重大優化**：自動與 MAME 比對，防止指令報錯崩潰 |
-| **Video 支援** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan / D3D11 / D3D12** | 針對 Windows 環境最佳化，支援多代 DirectX 核心 |
+| **Video 支援** | Metal / OpenGL / BGFX | **BGFX / OpenGL / Vulkan / D3D11 / D3D12** | 針對 Windows 環境最佳化，支援多代 DirectX 核心 |
-| **網路連線** | Apple VMNet Framework | **Npcap (WinPcap) / PCAP** | 使用標準 Npcap 即可上網 (無須權限修復) |
+| **網路連線** | Apple VMNet Framework | **Npcap (WinPcap) / PCAP** | 使用標準 Npcap 即可上網 (無須權限修復) |
-| **操作邏輯** | 支援黏性軟體選取 | **支援黏性軟體選取 (Sticky Selection)** | 兩平台皆支援切換機型後保留相容的軟體選取 |
+| **操作邏輯** | 支援黏性軟體選取 | **支援黏性軟體選取 (Sticky Selection)** | 兩平台皆支援切換機型後保留相容的軟體選取 |
-
+
-## 🌟 核心功能
+## 🌟 核心功能
-
+
-### 🍏 忠實還原 Mac 體驗 (功能對齊)
+### 🍏 忠實還原 Mac 體驗 (功能對齊)
-*   **視覺精準度**： 
+*   **視覺精準度**： 
-    *   **高解析度縮放**：精準支援 **Window 1x-4x** 模式，並內建機器專屬的比例啟發邏輯（如 Apple II 4:3 修正）。
+    *   **高解析度縮放**：精準支援 **Window 1x-4x** 模式，並內建機器專屬的比例啟發邏輯（如 Apple II 4:3 修正）。
-    *   **正方形像素 (Square Pixels)**：支援特製的整數縮放模式 (如 1120x768)，消除像素閃爍。
+    *   **正方形像素 (Square Pixels)**：支援特製的整數縮放模式 (如 1120x768)，消除像素閃爍。
-*   **軟體資料庫**：
+*   **軟體資料庫**：
-    *   **智慧過濾**：自動識別機器支援的媒體類型 (flop1, flop2, cass...)，確保啟動參數與原始硬體一致。
+    *   **智慧過濾**：自動識別機器支援的媒體類型 (flop1, flop2, cass...)，確保啟動參數與原始硬體一致。
-    *   **搜尋遮罩**：完整還原 Mac 版的搜尋介面，支援自動補完與完整網格化清單顯示。
+    *   **搜尋遮罩**：完整還原 Mac 版的搜尋介面，支援自動補完與完整網格化清單顯示。
-    *   **相容性檢查**：自動偵測屬性表中的 `disabled` 標記（如不相容的 SCSI 卡），並正確以灰色顯示不可選，與 Mac 行為一致。
+    *   **相容性檢查**：自動偵測屬性表中的 `disabled` 標記（如不相容的 SCSI 卡），並正確以灰色顯示不可選，與 Mac 行為一致。
-*   **進階槽位模擬**：完整支援嵌套子槽位（如 SCSI 卡）。 
+*   **進階槽位模擬**：完整支援嵌套子槽位（如 SCSI 卡）。 
-    *   **自動化配置**：在選中卡片後自動初始化預設設備（如 ID 1 CD-ROM, ID 6 Hard Disk）。
+    *   **自動化配置**：在選中卡片後自動初始化預設設備（如 ID 1 CD-ROM, ID 6 Hard Disk）。
-    *   **配置持久性**：優化插槽初始化邏輯，確保在 UI 重新整理時能正確保留「空」(None) 的選取狀態，與 Mac 原生行為一致。
+    *   **配置持久性**：優化插槽初始化邏輯，確保在 UI 重新整理時能正確保留「空」(None) 的選取狀態，與 Mac 原生行為一致。
-*   **ROM 管理**：
+*   **ROM 管理**：
-    *   **搜尋過濾**：ROM 管理器視窗中新增即時搜尋功能，方便快速查詢系統韌體。
+    *   **搜尋過濾**：ROM 管理器視窗中新增即時搜尋功能，方便快速查詢系統韌體。
-    *   **下載 Failover**：多伺服器自動獲取 (callapple + mdk.cab)，主伺服器失敗時自動切換，確保最高穩定性。
+    *   **下載 Failover**：CallApple 伺服器優先獲取，MDK 伺服器備用 failover 支援，並具備 `dragon32` 缺檔自動補丁與 Laser 128 全系列韌體相容性保障。
-    *   **擴展支援**：新增 Macintosh PowerBook Duo 280, Pravetz 8C, TK3000 //e 等機型。
+    *   **擴展支援**：新增 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)，或提示一鍵下載備用版本，防範啟動崩潰。
+    *   **全面相容性**：MAME 0.289 官方已修正 PowerBook 機型（如 `macpb160`, `macpb180` 等）的 EASC 晶片崩潰 Bug，所有 PowerBook 機型現可使用最新 MAME 核心直接原生啟動。
-*   **共享目錄 (Shared Directory)**：與 Mac 版功能完全對齊，支援透過 `-share_directory` 直接在主機與模擬器間共享檔案 (支援點擊輸入框瀏覽)。
+*   **共享目錄 (Shared Directory)**：與 Mac 版功能完全對齊，支援透過 `-share_directory` 直接在主機與模擬器間共享檔案 (支援點擊輸入框瀏覽)。
-*   **VGM 錄音支援 (進階)**：由於現代 MAME 已移除 VGM 支援，AmpleWin 實作了強韌的自動化工作流，可下載並平行配置 **MAME-VGM Mod (v0.280)**。透過非破壞性的解壓技術（保留原本的 `mame.exe` 並另存為 `mame-vgm.exe`），在不影響主核心的情況下完美還原錄音功能。
+*   **VGM 錄音支援 (進階)**：由於現代 MAME 已移除 VGM 支援，AmpleWin 實作了強韌的自動化工作流，可下載並平行配置 **MAME-VGM Mod (v0.280)**。透過非破壞性的解壓技術（保留原本的 `mame.exe` 並另存為 `mame-vgm.exe`），在不影響主核心的情況下完美還原錄音功能。
-
+
-### 🪟 Windows 專屬優化與增強
+### 🪟 Windows 專屬優化與增強
-*   **效能優化**：
+*   **效能優化**：
-    *   **併發下載系統**：多線程加速 ROM 下載，大幅縮短初始配置時間。
+    *   **併發下載系統**：多線程加速 ROM 下載，大幅縮短初始配置時間。
-    *   **零雜訊 Workspace**：所有的 MAME 產出紀錄 (nvram, cfg, sta) 嚴格隔離在 `mame` 內。
+    *   **零雜訊 Workspace**：所有的 MAME 產出紀錄 (nvram, cfg, sta) 嚴格隔離在 `mame` 內。
-    *   **延遲載入 (Deferred Loading)**：大幅優化軟體清單載入速度，切換機器與搜尋皆可瞬間反應。
+    *   **延遲載入 (Deferred Loading)**：大幅優化軟體清單載入速度，切換機器與搜尋皆可瞬間反應。
-*   **UI 增強**：
+*   **UI 增強**：
-    *   **適配主題**：即時同步 Windows 系統的深/淺色模式。
+    *   **適配主題**：即時同步 Windows 系統的深/淺色模式。
-    *   **指令即時預覽**：底部的 4 行式 Console 欄位，可即時監控傳送給 MAME 的所有參數細節。
+    *   **指令即時預覽**：底部的 4 行式 Console 欄位，可即時監控傳送給 MAME 的所有參數細節。
-    *   **智慧路徑處理**：針對 A/V 輸出及共享目錄欄位提供原生的檔案/目錄選擇器，並自動執行路徑正規化 (將 `/` 轉為 `\`) 以確保與 Windows 的最佳相容性。
+    *   **智慧路徑處理**：針對 A/V 輸出及共享目錄欄位提供原生的檔案/目錄選擇器，並自動執行路徑正規化 (將 `/` 轉為 `\`) 以確保與 Windows 的最佳相容性。
-*   **彈性後端支援**：領先支援 BGFX、OpenGL、Vulkan 以及 Windows 專屬的 **DirectX 11/12**。
+*   **彈性後端支援**：領先支援 BGFX、OpenGL、Vulkan 以及 Windows 專屬的 **DirectX 11/12**。
-
+
-## 🛠️ 快速開始
+## 🛠️ 快速開始
-
+
-1.  **啟動 Ample**：
+1.  **啟動 Ample**：
-    進入 **`AmpleWin`** 資料夾，執行 **`AmpleWin.bat`**。
+    進入 **`AmpleWin`** 資料夾，執行 **`AmpleWin.bat`**。
-    *   腳本會自動檢查 Python 環境、安裝依賴套件並啟動程式。
+    *   腳本會自動檢查 Python 環境、安裝依賴套件並啟動程式。
-2.  **快速部署**：
+2.  **快速部署**：
-    *   前往 **⚙️ Settings** -> 點擊 **Download MAME** 以自動配置模擬器。
+    *   前往 **⚙️ Settings** -> 點擊 **Download MAME** 以自動配置模擬器。
-    *   點擊主介面的 **🎮 ROMs** 以補齊系統韌體。
+    *   點擊主介面的 **🎮 ROMs** 以補齊系統韌體。
-    *   點擊 **📂 Ample Dir** 可快速開啟程式安裝目錄。
+    *   點擊 **📂 Ample Dir** 可快速開啟程式安裝目錄。
-3.  **開始體驗**：
+3.  **開始體驗**：
-    *   從左側列表中選擇想要的機器。
+    *   從左側列表中選擇想要的機器。
-    *   **雙擊** 機器名稱或點擊右下角的 **Launch MAME** 即可啟動。
+    *   **雙擊** 機器名稱或點擊右下角的 **Launch MAME** 即可啟動。
-
+
-## 🌐 網路功能 (進階項目)
+## 🌐 網路功能 (進階項目)
-
+
-若要在模擬器中使用 **Uthernet II** 等網路卡硬體，在 Windows 環境下需要安裝 [Npcap](https://nmap.org/npcap/) (安裝時請勾選 "WinPcap compatible mode")。與 macOS 版本不同，Windows 是透過網卡驅動程式處理硬體存取，因此不需要額外的「權限修復 (Fix Permissions)」程序。
+若要在模擬器中使用 **Uthernet II** 等網路卡硬體，在 Windows 環境下需要安裝 [Npcap](https://nmap.org/npcap/) (安裝時請勾選 "WinPcap compatible mode")。與 macOS 版本不同，Windows 是透過網卡驅動程式處理硬體存取，因此不需要額外的「權限修復 (Fix Permissions)」程序。
-
+
-## 📂 Project Structure (專案結構)
+## 📂 Project Structure (專案結構)
-
+
-| 檔案/目錄 | 說明 |
+| 檔案/目錄 | 說明 |
-| :--- | :--- |
+| :--- | :--- |
-| **`AmpleWin.bat`** | **啟動腳本**。自動安裝依賴套件並執行主程式。 |
+| **`AmpleWin.bat`** | **啟動腳本**。自動安裝依賴套件並執行主程式。 |
-| `build_exe.bat` | **打包腳本**。使用 PyInstaller 建立無須 Python 的可攜式 EXE。 |
+| `build_exe.bat` | **打包腳本**。使用 PyInstaller 建立無須 Python 的可攜式 EXE。 |
-| `main.py` | 應用程式入口，處理 UI 渲染與主要邏輯。 |
+| `main.py` | 應用程式入口，處理 UI 渲染與主要邏輯。 |
-| `data_manager.py` | 負責解析 `.plist` 機器定義檔與 MAME `.xml` 軟體列表。 |
+| `data_manager.py` | 負責解析 `.plist` 機器定義檔與 MAME `.xml` 軟體列表。 |
-| `mame_launcher.py` | MAME 指令建構器與執行序管理器。 |
+| `mame_launcher.py` | MAME 指令建構器與執行序管理器。 |
-| `rom_manager.py` | 系統 ROM 的管理與多執行緒下載引擎。 |
+| `rom_manager.py` | 系統 ROM 的管理與多執行緒下載引擎。 |
-| `mame_downloader.py` | 自動化 MAME 核心與 VGM Mod 下載解壓工具。 |
+| `mame_downloader.py` | 自動化 MAME 核心與 VGM Mod 下載解壓工具。 |
-| `mame/` | 隔離的 MAME 工作目錄，存放執行檔、ROMs 與設定檔。 |
+| `mame/` | 隔離的 MAME 工作目錄，存放執行檔、ROMs 與設定檔。 |
-| `Agent.md` | 開發日誌與任務記錄。 |
+| `Agent.md` | 開發日誌與任務記錄。 |
-
+
-## 📦 打包發布版 (Portable EXE)
+## 📦 打包發布版 (Portable EXE)
-
+
-如果你想將程式打包成無需 Python 環境的可執行檔：
+如果你想將程式打包成無需 Python 環境的可執行檔：
-
+
-1.  執行 `AmpleWin` 資料夾下的 `build_exe.bat`。
+1.  執行 `AmpleWin` 資料夾下的 `build_exe.bat`。
-2.  腳本會自動安裝 PyInstaller 並打包應用程式，同時複製必要的資源檔。
+2.  腳本會自動安裝 PyInstaller 並打包應用程式，同時複製必要的資源檔。
-3.  打包完成後的程式位於 `AmpleWin\dist\AmpleWin`。
+3.  打包完成後的程式位於 `AmpleWin\dist\AmpleWin`。
-4.  將整個 `AmpleWin` 資料夾複製到任何位置即可執行，它是完全**可攜式 (Portable)** 的。
+4.  將整個 `AmpleWin` 資料夾複製到任何位置即可執行，它是完全**可攜式 (Portable)** 的。
-
+
-## 📝 致謝
+## 📝 致謝
-
+
-*   原始 macOS 版本開發者: [Kelvin Sherlock](https://github.com/ksherlock)
+*   原始 macOS 版本開發者: [Kelvin Sherlock](https://github.com/ksherlock)
-*   **Windows Port 開發者: anomixer + Antigravity**：致力於在 Windows 生態系中提供最極致的 Apple II / Macintosh 模擬體驗。
+*   **Windows Port 開發者: anomixer + Antigravity**：致力於在 Windows 生態系中提供最極致的 Apple II / Macintosh 模擬體驗。
 ---
 *免責聲明：AmpleWin 是一個獨立的開源專案，與 Apple Inc. 或本專案提及之任何其他公司均無任何隸屬、授權、維護或背書關係。所有產品及公司名稱均為其各自持有人的商標™或註冊®商標。*
@@ -1121,6 +1121,16 @@ class AmpleMainWindow(QMainWindow):
            # 不再於切換時立即填充軟體清單 (延遲加載以優化效能)
            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 @@ class AmpleMainWindow(QMainWindow):
                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 @@ class AmpleMainWindow(QMainWindow):
                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 @@ class AmpleMainWindow(QMainWindow):
            # 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 @@ class AmpleMainWindow(QMainWindow):
        # 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 @@ class AmpleMainWindow(QMainWindow):
            target_exe_path = args[0]
            if exe_cmd in ["mame", "mame.exe"]:
-                affected_macs = ["macpb160", "macpb180", "macpb165", "macpb165c", "macpb180c"]
+                target_exe_path = 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")
                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
            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):
@@ -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
+        # MAME official self-extracting EXE - Updated to 0.289
-        self.url = "https://github.com/mamedev/mame/releases/download/mame0288/mame0288b_x64.exe"
+        self.url = "https://github.com/mamedev/mame/releases/download/mame0289/mame0289b_x64.exe"
    def run(self):
        try:
@@ -0,0 +1,6 @@
 {
  "name": "AmpleWin",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {}
 }
@@ -40,6 +40,10 @@ class DownloadWorker(QRunnable):
                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 @@ class DownloadWorker(QRunnable):
        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 @@ class RomManager(QObject):
            {'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:
@@ -171,6 +171,9 @@ SLOTS = (
 	# lisa
 	"pp",
 	# sgi
 	"gio64_gfx",
 )
 SLOT_NAMES = {
@@ -289,6 +292,9 @@ SLOT_NAMES = {
 	# lisa
 	"pp":         "Parallel",
 	# sgi
 	"gio64_gfx":      "GIO64 Graphics",
 }
@@ -116,6 +116,7 @@ TREE = [
 	("Macintosh (LC)", None, mac_lc_children),
 	("Macintosh (Portable)", None, mac_portable_children),
 	("Macintosh (PowerBook)", None, mac_powerbook_children),
 	("Lisa", None, lisa_children),
 	("Acorn", None, acorn_children),
 	("Atari ST", "st", atari_st_children),
@@ -125,7 +126,6 @@ TREE = [
 ]
 TREE_EXTRA = TREE + [
 	("Lisa", None, lisa_children),
 	("Amiga", None, amiga_children),
 	("DEC VT", None, dec_vt_children),
Author	SHA1	Message	Date
Kelvin Sherlock	4e9088c41b	add gio64_gfx for SGI	2026-08-29 23:18:40 -04:00
Alexander Jacocks	23dee5bf2a	enable SGI Indigo2, Indy R4600, and Indy R5000, since they function. Add support for choosing graphics boards. (#55 )	2026-08-29 23:01:44 -04:00
Kelvin Sherlock	bd9d4972b5	move lisa from Ample lite to Ample	2026-08-07 22:41:40 -04:00
anomixer	4224a942ef	feat(AmpleWin/AmpleLinux): update MAME downloader & rom_manager to v0.289 (#56 ) * Fix slot persistence logic (AmpleWin/Linux) for upstream PR preparation. Implements robust None-aware slot initialization. * Fix: Explicitly pass empty string arguments for disabled slots (None) to prevent MAME using defaults * feat(core): update MAME to 0.288, fix compatibility bugs, add PowerBook fallbacks, and optimize download servers * feat(AmpleWin/AmpleLinux): update MAME to 0.289, remove PowerBook EASC fallbacks, prioritize CallApple server with dragon32 auto-patching and Laser series ROMs	2026-08-07 21:44:51 -04:00