# UIX Desktop — Public Beta

**2026-04-26**

A cross-platform desktop preview of the Xbox dashboard, decompiled from
the 5960 retail binary using Ghidra and binary analysis. Native on
macOS, Linux, and Windows through SDL2 + OpenGL, with an asset
filesystem (`xboxfs/`) that maps Xbox drive letters to host directories.

This is a public beta. Expect rough edges. Bug reports welcome.

---

## Builds

| Platform | Zip                                                | Binary           |
|----------|----------------------------------------------------|------------------|
| macOS    | `UIX-Desktop-macOS-Public_Beta_2026-04-26.zip`     | `theseus`        |
| Linux    | `UIX-Desktop-Linux-Public_Beta_2026-04-26.zip`     | `theseus`        |
| Windows  | `UIX-Desktop-Windows-Public_Beta_2026-04-26.zip`   | `theseus.exe`    |

The Windows drop ships SDL2.dll, SDL2_mixer.dll, and libwinpthread-1.dll
alongside the .exe — keep them together. macOS and Linux dynamically
link to system SDL2 / OpenGL.

All three platforms expect the `xboxfs/` directory to sit next to the
binary. That's where the dashboard finds its skins, fonts, audio,
language files, and XIP archives at runtime.

---

## What's new in 2026-04-26

### Unified launch dispatcher

Five separate launch sites had drifted into platform-specific snippets
that handled different subsets of the things you might want to launch.
Consolidated into one helper used by every site:

- **`steam://...`** — Linux invokes `steam` directly to bypass KIO.
  KDE/Plasma's URL handler chain doesn't always resolve the `steam`
  scheme; this avoids the "Unknown protocol" error path entirely.
  macOS and Windows still go through their native URL handlers, which
  work fine there.
- **Other URLs** (`http://`, `https://`, `file://`, ...) — system URL
  opener.
- **Anything else** — runs through the shell. Raw executables, paths
  with arguments, bash scripts, `.bat` files, `firefox --new-window URL`
  style commands — all just work.

Title Maker's "Launch" field accepts any of the above. Type or paste
a command, click Test Launch.

### CLI flags

| Flag             | What it does                                            |
|------------------|---------------------------------------------------------|
| `--scale N`      | UI scale factor for the ImGui debug overlay (e.g. 1.5, 2.0). Useful on high-DPI displays. |
| `--fullscreen`   | Borderless fullscreen at native resolution.             |
| `--4k`           | Convenience: `--fullscreen` + `--scale 2.0`.            |
| `--no-toolbar`   | Start with the menu bar hidden. Toggle back with F10.   |
| `--dashboard`    | Start in dashboard mode (skip the preloader picker).    |
| `--development`  | Start in development mode.                              |
| `--muted`        | Start with audio muted.                                 |

### Menu bar visibility

| Trigger                       | Effect                          |
|-------------------------------|---------------------------------|
| **F10**                       | Toggle the menu bar in/out.     |
| **File → Hide Menu Bar**      | Same, from the menu (use F10 to bring it back once it's gone). |
| **`--no-toolbar`** at startup | Start hidden.                   |

On a 4K monitor, try `./theseus --4k`. Knock the scale back with
`--scale 1.5` if 2× feels too big.

### Title Maker

- Free-form Launch field (paths, scripts, command lines, URLs)
- File browser with no type filter — pick any binary or script
- Test Launch button now uses the unified dispatcher and is
  fire-and-forget (won't tear down the dashboard)

### Windows refresh (later in the day)

The first Windows zip cut had three Windows-specific gaps that the
macOS / Linux builds didn't share. All resolved in the current zip:

- **Virtual games from `games.ini` weren't appearing in the dashboard.**
  Title Maker showed the entries fine, but the dashboard's directory
  scan went through real Win32 `FindFirstFile` and never injected the
  virtual entries. Fixed by wrapping the find handle and walking real
  entries first, virtual entries after. A wildcard-matching glitch
  (treating `*.*` literally as "name with a dot in it") meant testers
  whose game names had no dots saw zero of N — fixed by collapsing
  `*.*` to `*` on Windows the same way POSIX does it.
- **Black console window popped open on launch.** Switched the PE to
  Windows subsystem with `mainCRTStartup` as the entry; explorer
  launches are clean now. `AttachConsole(ATTACH_PARENT_PROCESS)`
  at startup keeps stdout/stderr flowing when the binary is launched
  from a `cmd` / PowerShell window, so diagnostic logs still work for
  testers running from a terminal.
- **Steam Import wasn't downloading icons.** The icon resize step
  shelled out to ImageMagick's `convert`, which isn't installed on
  stock Windows. Fixed by skipping the resize on Windows and copying
  the Steam CDN icon as-is — the dashboard scales at render time
  anyway. To pick up icons for entries that were already imported by
  the broken version, delete those entries in Title Maker and
  re-import from Steam.

---

## Quickstart

### macOS

```sh
unzip UIX-Desktop-macOS-Public_Beta_2026-04-26.zip
cd UIX-Desktop-macOS-Public_Beta_2026-04-26
./theseus
```

If macOS Gatekeeper complains: `xattr -dr com.apple.quarantine theseus`,
or right-click → Open the first time.

### Linux

```sh
unzip UIX-Desktop-Linux-Public_Beta_2026-04-26.zip
cd UIX-Desktop-Linux-Public_Beta_2026-04-26
./theseus
```

Needs SDL2 and SDL2_mixer installed (`apt install libsdl2-2.0-0
libsdl2-mixer-2.0-0` on Debian/Ubuntu, `pacman -S sdl2 sdl2_mixer` on
Arch). OpenGL is part of any Mesa install.

### Windows

Unzip, then run `theseus.exe` from inside the unzipped folder. The
DLLs and `xboxfs/` need to stay next to it.

---

## Known issues

- **`Unable to load texture file (background.xbx) and fallback failed`** on
  startup is benign if the active XIP set doesn't include that asset.
  The dashboard continues without it.
- **Save game delete confirmation** is currently a no-op — the submenu
  opens but the delete action doesn't fire. Status of fix unknown.
- **Working directory matters.** Run from inside the unzipped folder;
  running from elsewhere won't find `xboxfs/`.
- **Linux + KDE/Plasma**: if `steam://` games still don't launch after
  this build, your `steam.desktop` may not be on `PATH`. Verify with
  `which steam`. The build invokes the binary directly, so `steam`
  needs to be resolvable. If KDE still refuses to hand off `steam://`
  URLs, register the handler explicitly:

  ```sh
  xdg-mime default steam.desktop x-scheme-handler/steam
  ```

---

## Reporting issues

Include:
- Platform + version (e.g. CachyOS + KDE Plasma 6.x, macOS 14.5, Win11)
- Output of running with no flags from a terminal (the binary prints
  diagnostics to stderr)
- What you were trying to do
- Whether it's a regression vs. a previous build