Port to Basic - FNF (Psych Engine) mod to Scratch porting tool with GUI
=====================================================================

Converts Friday Night Funkin' mods (Psych Engine format) into a playable
Scratch project (.sb3). Includes a modern dark GUI, a live porting overlay,
save/cancel support, TurboWarp preview, and macOS .app packaging.

EASY START (GUI)
----------------
- Windows: double-click start_gui.bat
- macOS / Linux (from the repo): run ./start_gui.sh
- macOS app (no repo needed on the target Mac):
    1. Build the bundle once: ./build_macos_app.sh
    2. Copy dist/PortToBasic.app to the MacBook (e.g. /Applications)
    3. First launch: right-click the app -> Open (Gatekeeper),
       or run once: xattr -dr com.apple.quarantine PortToBasic.app
       The bundle creates its own virtual environment and installs
       dependencies on first run; check
       PortToBasic.app/Contents/Resources/launcher.log if it stalls.
    4. macOS extras (recommended): brew install python-tk cairo
       (python-tk for the GUI, cairo for the Pico SVG character)

The launcher creates a local virtual environment on first run, installs the
dependencies, and starts the GUI. Nothing is installed globally.

PORTING OVERLAY
---------------
While a port runs, a black full-screen overlay shows:
- a white progress bar at the bottom plus the current step caption,
- a randomly picked character looping in the bottom-right corner,
- a "LogBox" panel on the left-center: one random artwork from
  assets/Porting/LogsBoxes per run with the live log rendered inside it
  (newest 12 lines, color-coded by kind),
- the Log button (top-left) that opens the full colorized log window,
- the Exit button (top-right) that cancels the port (or, when no port is
  running, closes the overlay again).

Preview the overlay without running a port:
    ./start_gui.sh --port-screen        (or: venv/bin/python gui.py --port-screen)

Music: the overlay plays assets/Music while porting; on Windows/Linux it
uses mpv/ffplay, and on macOS the native afplay player (auto-detected).

USAGE (GUI)
-----------
1. Click "Select Mod Folder" and pick the root of the mod (marked by
   pack.png for Psych Engine mods). The tool auto-copies the missing scripts and the
   blank engine into the mod folder, then runs each conversion step in
   order.
2. Choose the base engine in the "Base engine (.sb3)" dropdown — this selects
   which Scratch template the build step starts from. Drop extra .sb3 files
   next to this app and they appear in the dropdown.
3. Press Run. The final .sb3 is written next to the blank template as
   built_<template>.sb3 inside the mod folder.
4. Open the generated .sb3 in Scratch or Turbowarp to play.

MANUAL / CLI USE
----------------
1. Copy the files from this folder into the root of the mod
   (marked by pack.png).
2. Install Python and dependencies:
     pip install audioop-lts Pillow pydub mutagen customtkinter cairosvg
   (On Windows, install Python 3.13 from the Microsoft Store.)
3. Install FFmpeg:
     winget install Gyan.FFmpeg
4. Run:
     python port.py

REQUIREMENTS
------------
- Python 3.10+ (3.13 recommended on Windows)
- FFmpeg on PATH (used for OGG -> MP3 conversion)
- No global installs needed when using start_gui.sh / start_gui.bat