# HANDOFF — muguet Windows port + `--import-url`

Fork of [c22dev/muguet](https://github.com/c22dev/muguet) (GPL-3.0-or-later, keep it GPL):
native host that runs the existing `game.wasm` via wasmtime + wgpu instead of
a browser. No game assets in this repo — you supply `data/` + `b/<build>/`.

## What was done (on a Linux box, Oct 2026)

1. **Mirror analysis** (`playgta5.com/` next to this repo): Emscripten pthread
   build — `game.wasm` (61 MB) + `game.js` glue, `loader.js` spawns
   `wgpu_worker.js` (GPU command ring) + `io_worker.js` (HTTP Range reads,
   OPFS cache). Needs COOP/COEP, SharedArrayBuffer, ~600 MB boot fetch.
2. **Smoke test**: `game.wasm` parses under wasmtime with muguet's exact
   engine flags (memory64/threads/shared, 17 GB reservation) in ~18 s;
   headless Vulkan (Lavapipe) brings up a device with BC +
   depth32float-stencil8. WASM + GPU path proven good.
3. **Windows port** (this repo, all in `src/` + `Cargo.toml`):
   - `Cargo.toml`: `objc2*` moved to Apple-only targets.
   - `app.rs` / `gpu.rs`: `Backends::METAL` → `Backends::PRIMARY`.
   - `fs.rs` / `io.rs`: portable positional I/O
     (`read_at` on unix, `seek_read`/`seek_write` loops on Windows),
     portable stat times.
   - `main.rs`: Apple QoS / `proc_pid_rusage` / `rlimit` cfg-gated out.
   - `config.rs`: `%APPDATA%\Muguet` support dir on Windows, log-redirect
     unix-only.
   - `pad.rs`: GameController backend Apple-only, stub elsewhere
     (keyboard+mouse is the path for now).
4. **New: `--import-url <base> <build>`** (`src/import_url.rs`, `ureq`
   dep): fetches the game.zip layout over HTTP from a server YOU operate
   (your own converted copy) — `data/manifest.json` + files (same
   `env_test`/`verityradio` skipping + manifest/`dlcList` pruning as zip
   import), `game.wasm`, `shaders/index.json` + every `.wgsl` (+ selective
   `.consts.json`), pack `.bin`s and `pipelines*.json` best-effort, 4x retry
   per file. Verified end-to-end against a local dummy server (exit 0,
   layout + pruning + packs all correct).
5. **Verified**: `cargo check` clean on Linux (only warnings fixed).
   `muguet-windows-port.zip` next to this repo = this source, no `target/`.

## Continue on Windows

```
# needs: Rust stable (rustup), no system deps (cpal uses WASAPI, no ALSA)
cd muguet
cargo build --release
.\target\release\muguet.exe --import game.zip
# ...or from your own server (same layout as the zip contents):
.\target\release\muguet.exe --import-url https://files.example.com/gta5 <build>
```

First launch compiles the 61 MB wasm once (~minutes), then caches it.
Useful env: `MUGUET_SCALE=0.5`, `MUGUET_RES=1280x720`,
`MUGUET_FULLSCREEN=0`. Config/save dir: `%APPDATA%\Muguet`.

## NOT done / watch out

- `cfg(windows)` branches were reviewed but never compiled here (no mingw
  on the Linux box) — first `cargo build` on Windows is the real check.
- Full boot never attempted here (2.5 GB free, headless). Black screen with
  ticking presents = success milestone; rendering comes after.
- This mirror's `b/<build>/shaders/` lacks `index.json` (live host has it)
  — re-mirror it or every shader resolves to null (black screen by design).
- Check `texture-compression-bc` on your GPU; without it expect missing
  textures regardless of RAM.
- Gamepad is stubbed on Windows; touch overlay doesn't exist yet.
- Upstream is 5 commits / single author — expect drift; rebase carefully.
- Legal: never bundle `data/` or `game.wasm`. Engine-only distribution +
  user-supplied data, same as upstream's zip flow.