0 Fork 0

mirror of https://github.com/ksherlock/ample.git synced 2026-10-25 13:02:57 +00:00

Files

T

anomixerandUser fdd02b9d5b Pull Request: Add native Windows (AmpleWin) and Linux (AmpleLinux) ports (#46 )

* Initialize and finalize AmpleWin: Full-featured Windows Port with Adaptive UI, optimized engine, and internationalized documentation

* Update media args

* AmpleWin: Finalized Windows Port with Adaptive UI, Optimized Engine, VGM Recording, and Shared Directory Support

* Fix NameError: subprocess not defined in main.py

* UI: Remove redundant MAME path label from Paths tab

* UI: Implement smart slot validation for disabled options and click-to-browse Shared Directory

* feat(win): editable console, launch logic fixes & doc updates

* Fix path quoting issues, add file selectors for A/V, and normalize shared dir path

* feat: sync with Ample v0.285 resources, update to MAME 0.285, and add ROM search filter

* v0.285: Expand ROM library, implement download failover, and advanced SCSI sub-slot emulation

* Adjust ROM download priority: prefer callapple.org for stability, mdk.cab as fallback

* Sync roms.plist with upstream/master

* docs(agent): record upstream synchronization session

* refactor: rename mame_bin to mame directory

* chore: update .gitignore for mame directory rename

* fix(main): update download and detection paths to 'mame'

* fix(main): robust path resolution for pyinstaller builds

* docs(readme): add build_exe.bat to project structure

* fix(build): remove creation of empty mame directory to avoid confusion

* feat(build): auto-generate application icon from Assets.xcassets

* Add AmpleLinux - Linux Port of Ample (Apple II/Mac emulator frontend)

- Ported from AmpleWin with ~20 Linux-specific adaptations
- Replaced winreg with gsettings/KDE dark mode detection
- Replaced os.startfile with xdg-open
- Removed MAME auto-download (users install via package manager)
- Added system-wide MAME detection (PATH, /usr/bin, /usr/games)
- Removed all .exe suffixes from binary references
- Created AmpleLinux.sh launcher script
- Dual-language READMEs (English + Traditional Chinese)

* Fix: use python3 -m pip instead of pip3/pip for modern Linux compatibility

* feat(linux): Finalize AmpleLinux port documentation and build scripts

* Fix formatting for Windows and Linux user notes

Updated user guidance for Windows and Linux users.

* feat(linux): interactive .desktop install, runtime icon loading, updated docs

* docs(linux): clarify mame_downloader.py usage status

* docs: add PR draft template

* fix(linux): add binutils dependency check for pyinstaller

* Update: mame 0.286

---------

Co-authored-by: User <user@example.com>

2026-03-07 21:57:26 -05:00

5.8 KiB

Raw Blame History

AmpleLinux - Linux Port (Legacy Apple Emulator Frontend)

English | 繁體中文

This is a port of the macOS native Ample project to the Linux platform, based on the AmpleWin Windows Port.

Important

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

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

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

🌟 Key Features

🍏 Faithful Mac Experience (Feature Parity)

Visual Precision: Precision support for Window 1x-4x modes with machine-specific aspect ratio heuristics.
Software Library: Smart filtering, search overlay, and compatibility checking.
Advanced Slot Emulation: Full support for nested sub-slots (e.g. SCSI cards).
ROM Management: Real-time search, multi-server failover download, extended library.
Shared Directory: Full parity with -share_directory argument.

🐧 Linux-Specific Features

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

⚠️ Known Limitations

VGM Mod: The "Generate VGM" feature is currently disabled on Linux because the required MAME VGM Mod binary is only available for Windows.

🛠️ Quick Start

Prerequisites

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

Installation

Install System Dependencies:
- MAME: Install via your package manager (e.g., sudo apt install mame).
- Python 3: Ensure Python 3.9+ is installed (sudo apt install python3-full).
- X11 Support: Required for GUI (sudo apt install libxcb-cursor0).
Launch Ample:
```
cd AmpleLinux
chmod +x AmpleLinux.sh
./AmpleLinux.sh
```
The script will automatically create a virtual environment (.venv), install PySide6 and other dependencies via pip, and launch the app. No manual pip install required.
Fast Deployment:
- Ubuntu Users: If MAME is not found, the app will offer to install it via snap.
- Click 🎮 ROMs to download system firmware.
- Go to ⚙️ Settings to verify MAME is detected.
- Select a machine and Launch MAME!

📦 Building for Release

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

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

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

4. Desktop Integration (Icon Fix)

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

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

Then search for "AmpleLinux" in your applications menu.

📂 Project Structure

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

🔧 Troubleshooting

MAME Not Detected

If the app can't find MAME:

Ubuntu: The app will offer to run sudo snap install mame.
Manual: Go to ⚙️ Settings > Select MAME... to browse to the binary.
PATH: Verify which mame returns a path.
Common paths: /usr/bin/mame, /usr/games/mame, /var/lib/snapd/snap/bin/mame

Theme Detection

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

📝 Acknowledgments

Original macOS version developer: Kelvin Sherlock
Windows Port Developers: anomixer + Antigravity
Linux Port: Adapted from AmpleWin by anomixer + Antigravity

5.8 KiB Raw Blame History