# Unforged Alchemy 4.0 — Build Kit v147.23

This is the **cross-platform build kit** for **v147.23 / 8.11.21-rc1**. It packages the same Player source shipped in the Windows beta and adds one PyInstaller build script per target OS (macOS, Windows, Linux), so you can freeze a standalone build on whichever machine you're on.

## Folder layout

The build kit root is intentionally kept simple:

- **build_mac_dmg.sh** — build the Player as a macOS `.app` + `.dmg`.
- **build_windows_exe.bat** — build the Player as a Windows `.exe`.
- **build_linux.sh** — build the Player as a Linux binary + `.tar.gz`.
- **requirements-build.txt** — PySide6 + Pillow (same versions on every platform) plus PyInstaller.
- **BUILD_KIT_README.md** — this guide.
- **app_files/** — program code, catalogs, recipe seeds, internal metadata, and test/runtime support files. This is the same source as the Windows beta's `app_files/`; you normally do not need to open this folder.
- **site/** — a hostable download page for this kit (Astro page + plain HTML equivalent + a bundled copy of this zip), for publishing on your own website or a subdomain. See `site/README.md`.

Each build script automatically enters `app_files` before running PyInstaller, so moving the internal files there does not change Player behavior on any platform.

## Quick heads-up before you start

This is a pure Python + PySide6 (Qt) app on every platform — there's no separate native codebase to build per OS. All three scripts use the same tool, **PyInstaller** (already listed in `requirements-qt.txt` as the intended freezing tool), run from a terminal on the target machine. PyInstaller can't cross-compile, so each script has to be run **on that platform** — a Mac produces the Mac build, a Windows PC produces the Windows build, and so on. I can't run any of these for you from here since I'm working from a Linux sandbox; what's packaged is everything you need to run each build yourself in a few terminal commands.

## Quick start on macOS

1. Copy this whole folder to a Mac.
2. Install Xcode Command Line Tools if you don't already have them: `xcode-select --install`. This is a lightweight download, not the full Xcode app — it just provides `codesign`, `hdiutil`, and the C compiler some Python wheels need. You never open an Xcode project or write Swift.
3. Open Terminal, `cd` into this folder, and run:
   ```
   chmod +x build_mac_dmg.sh
   ./build_mac_dmg.sh
   ```
4. When it finishes you'll have `dist/Unforged Alchemy Player.app` (double-click to run it directly) and `Unforged_Alchemy_Player_v147.23.dmg` (the installer-style disk image, in the same folder as the script).

The build script ad-hoc signs the app so it runs without extra prompts on the Mac you built it on. Sharing the `.dmg` with someone else will still trigger an "unidentified developer" Gatekeeper warning (right-click → Open bypasses it) unless you notarize it with a paid Apple Developer ID — a separate step from this build.

## Quick start on Windows

1. Copy this whole folder to a Windows PC.
2. Extract the ZIP to a normal folder if you haven't already.
3. Open Command Prompt, `cd` into this folder, and run: `build_windows_exe.bat`
4. When it finishes you'll have `dist\Unforged Alchemy Player\Unforged Alchemy Player.exe`.

`build_windows_exe.bat` is the only Windows build launcher included in this kit. PyInstaller's `--windowed` mode produces a folder rather than a single file, so share the whole `dist\Unforged Alchemy Player\` folder (zip it first) — not just the `.exe`. Windows Defender SmartScreen may warn on first run of an unsigned `.exe`; that's expected for an unsigned build and isn't specific to this app.

## Quick start on Linux

1. Copy this whole folder to a Linux machine.
2. Open a terminal, `cd` into this folder, and run:
   ```
   chmod +x build_linux.sh
   ./build_linux.sh
   ```
3. When it finishes you'll have `dist/Unforged Alchemy Player/Unforged Alchemy Player` (the binary, inside its build folder) and `Unforged_Alchemy_Player_v147.23_linux.tar.gz`.

PySide6's Qt libraries need some system packages present on the build (and usually the runtime) machine. If the build or the frozen binary fails to launch, install `libgl1 libegl1 libxkbcommon0 libdbus-1-3` (Debian/Ubuntu package names; adjust for your distro). Like Windows, this is a folder build, which is why the script also packs a `.tar.gz` for sharing.

## Why PyInstaller instead of py2app / a separate Windows toolchain

The codebase's own resource-loading code (`runtime_paths.py`) already special-cases `sys._MEIPASS`, which is PyInstaller's marker for "this is a frozen build." Using PyInstaller on every platform keeps the app's file-loading logic identical across macOS, Windows, and Linux instead of introducing a second, different freezing tool for any one of them.

## What's shared across platforms

`app_files/` is the same Player source on all three builds. The app already detects macOS at runtime (`qt_frontend.py`) to offer the native "Mac Native" skin — San Francisco system font, rounded hairline-bordered panels, Aqua-style accent colors — alongside the existing Alchemy Dark/Glow, Vaporwave, Retro Terminal, Clay Tablet, Green Pixel, Cyan Hologram, ASCII Survival Terminal, Minimal, and High Contrast skins. Windows and Linux keep the previous Segoe UI-based styling. No AI-generated or borrowed raster artwork is shipped, per `UI_ASSET_POLICY.md`.

## If a build fails or the app crashes on launch

Two things to check first:
- Run the frozen executable directly from a terminal (instead of double-clicking) so you can see any Python traceback:
  - macOS: `"dist/Unforged Alchemy Player.app/Contents/MacOS/Unforged Alchemy Player"`
  - Windows: `dist\Unforged Alchemy Player\Unforged Alchemy Player.exe`
  - Linux: `dist/Unforged Alchemy Player/Unforged Alchemy Player`
- If it complains about a missing file, that file likely needs its own `--add-data` line in the relevant build script — send back the exact error and I can add it.

`RULE_SOURCE_AUTHORITY.md` (inside `app_files/`) records the current rules/project rulings. `UI_ASSET_POLICY.md` records the programmatic-art policy.

## AI assistance disclosure

The three platform build scripts (`build_mac_dmg.sh`, `build_windows_exe.bat`, `build_linux.sh`), `requirements-build.txt`, this README, `.gitignore`, `CLAUDE.md`, and the `site/` download page (both `index.html` and `build-kit.astro`) were put together with Claude's help, based on the original macOS build kit and the Windows Player beta package. The `app_files/` source itself is the existing Player codebase, unchanged by this AI assistance beyond the platform-detection font/skin logic already noted in the "What's shared across platforms" section above (also AI-assisted, on request, when the Mac build kit was first created). Review the build scripts before running them on a machine you care about, same as you would for any script from an unfamiliar source.

