diff --git a/README.md b/README.md index a7afdce..625429f 100644 --- a/README.md +++ b/README.md @@ -1,306 +1,169 @@ -# Theseus +[Theseus_Original](README_Theseus.md) -[![build](https://github.com/MrMilenko/Theseus/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/MrMilenko/Theseus/actions/workflows/build.yml) -[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](LICENSE) -[![Platform](https://img.shields.io/badge/platform-Xbox%20%7C%20macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](#) +# Theseus Project - BMK-Studio Modified Version -

- Vulkan -      - Metal -

+This is a modified version of the original Theseus Project, based on the Microsoft dashboard for the original Xbox. -Six years of reverse engineering the original Xbox dashboard. This repo is the result. +The goal of this version is to add new visual features, extra customization options, background music, panels, and new dashboard interactions while keeping the original Xbox dashboard feeling. -Theseus boots on modded Xbox hardware as a drop in replacement for the stock dashboard. The same engine compiles natively on macOS, Linux, and Windows, where it doubles as **UIX Desktop**: a 3D launcher and media center. The desktop build renders through [bgfx](https://github.com/bkaradzic/bgfx): Metal on macOS, Vulkan on Linux and Windows. - -The split is intentional. The Xbox build stays faithful to what you'd expect from the Xbox dashboard (or UIX Lite, if you've used a custom dashboard before). Everything that doesn't belong on an Xbox (Steam libraries, modern video playback, emulator-hosted ISOs, playlists, skin authoring tools) lives on the desktop side instead. Two projects, one engine. - -

- Xbox dashboard - UIX Desktop launcher -

-

- Media library - Custom skin -

-

- Steam tab in Title Maker - RetroArch tab in Title Maker -

- -## On Xbox - -A drop-in replacement for the stock Xbox dashboard on modded consoles. Same look and behavior, because that's what it is. Rebuilt plank by plank and still going. - -What works: -- Every original scene, animation, and skin slot -- UIX Lite skins drop in unchanged. Skin authors don't have to do anything -- Hot swap skins from settings, no reboot -- ISO / CCI launching from the harddrive menu, plus the original XBE flow -- Hundreds of titles scan in milliseconds -- Title icons auto populate from each game's XBE certificate -- Quick overlay (LT + B) for ISO loader, file manager, FTP / drive widgets -- FTP server, recovery / panic screen, MP3 soundtrack playback - -[Download for Xbox ->](https://github.com/MrMilenko/Theseus/releases) (or build from source, see below) - -## On the desktop (UIX Desktop) - -UIX Desktop is the Theseus engine compiled for your computer, with the modern features bolted on. macOS, Linux, Windows, Steam Deck friendly. - -- **3D launcher** for native PC games, Steam libraries, RetroArch ROMs, and Xbox ISOs via [xemu](https://xemu.app) -- **Media library** that scans your Movies and TV folders, pulls posters from [TMDB](https://www.themoviedb.org/), plays back through libmpv -- **Skin editor** with live XAP scripting and a scene inspector. Change a skin, see it instantly -- **Title Maker** for adding games and apps, with per launcher import flows for Steam and RetroArch -- **Xbox HDD browser** that opens qcow2 and FATX images -- **CRT post process** for the old TV look. Scanlines, curvature, phosphor, bloom, all tunable -- **Graphics knobs** in Settings -> Display: vsync mode, FPS cap, MSAA, hardware video decode -- **Controllers**: Xbox and PlayStation pads via SDL2 - -[Download for desktop ->](https://github.com/MrMilenko/Theseus/releases) - -## Quick Start - -### Xbox - -1. Grab the latest Xbox release (`default.xbe` + `uixdata/`) -2. Drop the XBE somewhere on the Xbox HDD, e.g. `E:\Dashboards\Theseus\default.xbe` -3. Copy `uixdata/` next to it -4. Copy `Configs/` to `C:\UIX Configs\` -5. Boot it. If something's missing, the panic screen tells you what. +--- -### Desktop +## Features -1. Grab the release for your OS -2. Run it. That's it. +### 1. BMK Controller Panel -The Windows release ships with the DLLs it needs. macOS and Linux dynamically link to system libraries, so you'll want these installed: +- Background Mesh +- Orbs +- Skins +- Visibility +- UIX Settings / Config -**macOS (Homebrew):** -``` -brew install sdl2 sdl2_mixer mpv curl -``` +--- -**Linux (Debian / Ubuntu):** -``` -sudo apt install libsdl2-2.0-0 libsdl2-mixer-2.0-0 libmpv2 libcurl4 -``` +### 2. Custom Orbs -(Some distros ship `libmpv1` instead of `libmpv2`. Either works.) +- Main Orb +- Setting Main Orb +- Emulator Orb +- Application Orb +- Game Orb +- Dashboard Orb -If you'd rather build from source, jump down to [Building](#building). +--- -## Adding games +### 3. skin.ini Support -Title Maker (F3 from the dashboard) is where you connect games to dashboard tiles. Three tabs: +- Custom background images +- Background image rotation +- Background image timer +- Custom SMAP +- SMAP rotation +- SMAP timer +- CellWall visibility -**Main** is the catch all. Every title you've added shows up here, regardless of which tab created it. This is also where you add the weird stuff that doesn't belong to a launcher: a Windows .exe, a .bat script, a macOS .command file, a shell one liner, anything that takes a path or command. Edit names, swap icons, tweak the launch line. Most of your time managing the library happens here. +--- -**Steam** auto detects your Steam install (Find button), or you point at it once. Hit Import Steam Library and your installed games come in with icons fetched from Valve's CDN. There's also a manual "Add by App ID" form for launching betas, demos, or games not in your normal library scan. +### 4. REZN8 Menu -**RetroArch** detects your RetroArch install the same way. Import Recent Titles pulls in everything you've recently played in RetroArch, with the right core auto resolved and boxart copied from RetroArch's thumbnail packs. You can also add manually: pick a ROM, pick a core from the dropdown, done. +- Integrated REZN8 quick menu +- Switch between M$Dash and REZN8 +- Access to main dashboard sections -If you don't use Steam or RetroArch, you can turn either tab off under Optional Tabs (top of Main). Anything you've already added stays in Main either way. +--- -## Customization +### 5. BMK ScreenSaver -**Skins.** Drop them into `Data/Skins/` (Xbox: `uixdata\Skins\`) and pick from settings. UIX Lite community skins work as is, no conversion needed. Hot swap, no reboot. +- Custom BMK ScreenSaver added -**Scene authoring** (for the people building dashboards from scratch). Scenes are XAP scripts packed into `.xip` archives. The desktop build has a live XAP editor (F2), scene inspector (F1), and asset reload so you can tweak and see results immediately. The XAP node interface is the contract; the C++ behind it can change but the node API is treated as sacred. Full reference in [`docs/xap-contract.md`](docs/xap-contract.md). +--- -## Controls (desktop) +### 6. Background Music -**Dashboard:** +- Automatic background music +- Random music mode +- Play / Pause support +- Soundtrack switching +- Song switching -| Key | Xbox button | Action | -|---|---|---| -| Arrow keys | D-pad | Navigate | -| Enter / Space | A | Select | -| Backspace | B | Back | -| X / Y | X / Y | Context actions | -| Tab | White | Play / Pause | -| ` (backtick) | Black | Stop | -| WASD | Left stick | Analog navigation | +--- -**Media playback:** +### 7. Music Panel -| Key | Action | -|---|---| -| Esc / Q | Stop, return to dashboard | -| Space | Pause / Resume | -| Left / Right | Seek 5s | -| `[` / `]` | Previous / Next in playlist | -| T | Track picker (audio + subtitles) | +- Current music title display +- Scrolling music text -**Tools (desktop only):** +--- -| Key | Action | -|---|---| -| F1 | Scene inspector | -| F2 | XAP script editor | -| F3 | Title Maker | -| F4 | Settings | -| F5 | Xbox HDD browser | -| F6 | Playlist Maker | -| F10 | Toggle menu bar | -| F11 | Toggle fullscreen | -| Ctrl+M | Mute | -| Ctrl+R | Restart dashboard | +### 8. Second Music Panel -Xbox and PlayStation controllers also work via SDL2 GameController. +- Active soundtrack +- Current track +- Track duration +- Remaining time --- -# For developers +### 9. Multi-Info Panel -The rest is build instructions, architecture notes, and the lineage. Skip if you just want to run it. +- IP address +- Free space E / F / G +- BIOS info +- Dashboard version +- Temperature info +- Fan speed -## Building +--- -Both builds live in this repo and use the same Makefile. +### 10. BMK Menu Animation -### Xbox +- Custom menu animation +- Pods animation +- Panels animation +- Animation mode: Off / UIX / BMK -Cross-compiles from macOS or Linux using clang + lld-link + cxbe. Requires: -- clang and lld-link (`brew install llvm` on macOS, `apt install clang lld` on Linux) -- [OXDK](https://github.com/MrMilenko/OXDK) cloned and built -- An Xbox SDK source tree (path passed as `XDK_BASE`) +--- -``` -git clone https://github.com/MrMilenko/OXDK ~/OXDK -cd ~/OXDK/tools/cxbe && make -cd /path/to/Theseus/build -make CONFIG=retail XDK_BASE=/path/to/xbox -``` +### 11. MemoryX MiniGame -Output lands at `~/builds/theseus/xbox-retail/default.xbe`. +- MemoryX mini-game integrated into the dashboard -### Desktop +--- -Same source tree, different Makefile target. Needs C++17, SDL2, SDL2_mixer, libmpv, libcurl. Rendering goes through bgfx: Metal on macOS, Vulkan on Linux and Windows. bgfx ships as a git submodule and the shaders compile from .sc source via `shaderc`. +### 12. Visibility Options -Init the submodules once before the first build: +- Show / hide dashboard elements +- Manage dashboard visual elements from BMK Controller Panel -``` -git submodule update --init --recursive -``` +--- -Then build the bgfx libraries (one time per platform) and compile shaders: +## Controls -``` -# macOS (Apple Silicon) -make -C theseus/third-party/bgfx -j osx-arm64 -make -C build shaders-bgfx +```text +A => Select -# Linux -make -C theseus/third-party/bgfx -j linux-release64 -make -C build shaders-bgfx-spirv +B => Back -# Windows (built from a MSYS2 mingw shell, or cross-compiled from Linux) -make -C theseus/third-party/bgfx -j mingw-gcc-release64 -make -C build shaders-bgfx-spirv -``` +X => NextClockInfoPanel +White(Tab)+(X) => MemoryX (MiniGame) -After that, the per-OS build commands: +Y => Play/Pause BackGroundMusic -**macOS:** -``` -brew install sdl2 sdl2_mixer mpv curl pkg-config -cd build && make desktop BGFX=1 -~/builds/theseus/desktop/theseus -``` +LeftThumbDown (W) => BMKControlerPanel -**Linux:** -``` -sudo apt install build-essential pkg-config libsdl2-dev libsdl2-mixer-dev \ - libvulkan-dev libx11-dev libmpv-dev libcurl4-openssl-dev -cd build && make desktop BGFX=1 -~/builds/theseus/desktop/theseus -``` +RightThumbDown (C) => Toggle beetween MusicPanel -**Windows (MSYS2 / MinGW64):** -``` -pacman -S make pkg-config mingw-w64-x86_64-gcc \ - mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_mixer \ - mingw-w64-x86_64-mpv mingw-w64-x86_64-curl \ - mingw-w64-x86_64-vulkan-headers mingw-w64-x86_64-vulkan-loader -cd build && make desktop-win64 BGFX=1 -``` +White (Tab) => Superkey -Cross-compiling for Windows from macOS / Linux, ARM64 Linux, or any of the more involved setups is in [`docs/desktop/`](docs/desktop/). The CI workflow runs all the build matrix combinations on every push, which is the closest thing to executable docs for the one-time setup. +Black -The legacy OpenGL backend still compiles by dropping the `BGFX=1` flag, useful for older hardware without Vulkan support. Shipped releases use the bgfx path. +LeftDown (A) => Screensaver_tHc +LeftDown White(Tab)+(A) => Screensaver_BMK -## How it works +RightDown (E) => Toggle Beetween M$Dash and Rezn8 -The engine is approximately 50 source files reconstructed from the retail and patched XBE's spanning 4920 to 5960, organized the same way the original dashboard was: script VM, scene graph, rendering, asset loading, UI framework, system integration, and launcher. Per-subsystem reverse engineering notes are in [`docs/decomp/`](docs/decomp/). +Up => MenuUp +White(Tab)+(Up) => BMKNextBackground Or BMKNextSmap -The XAP scripting layer is a custom JS-like bytecode VM. The scene graph is VRML97-inspired with runtime reflection via FND/PRD property tables. On the desktop side, D3D8 calls translate through a thin shim into bgfx, which targets Metal on macOS and Vulkan on Linux and Windows. Everything else compiles for both targets from the same shared source. +Down => MenuDown +White(Tab)+(Down) => BMKPreviousBackground Or BMKPreviousSmap -If you're poking around the source, the high-level layout: +Right => Next SoundTrack +White(Tab)+(Right) => Next Song +Left => Previous SoundTrack +White(Tab)+(Left) => Previous Song ``` -theseus/ - engine/ Pure logic (VM, nodes, math) - shared/ Cross-platform with Win32 types (file I/O, audio, settings) - render/ Scene graph, materials, shapes - xbox/ Xbox-only (XTL, modchip, kernel APIs) - desktop/ Desktop-only (SDL, bgfx, ImGui tools) - toolbox/ PrometheOS-derived FTP / drive / network (Xbox-only) -theseuslib/ Shared C library (xiso parser, xip parser) -``` - -Heavier docs index lives at [`docs/README.md`](docs/README.md). -## Heritage +--- -Theseus is part of the TeamUIX lineage. JbOnE created *User.Interface.X* (UIX), a source level modification of the original Xbox Dashboard, which we also poked around in via Ghidra to figure certain things out. Modern TeamUIX continues that tradition with [UIX Lite](https://github.com/OfficialTeamUIX/UIX-Lite) (a heavily patched retail XBE) and Theseus (this repository). +## Youtube -There's a circularity to it. UIX modified the dashboard at the source level. Theseus reaches the same destination from the other side of the river, rebuilding the codebase from binary analysis and untangling changes made to XIPs over 25 years of community modification. +https://www.youtube.com/watch?v=c1mkhrvneNI -For the broader UIX project narrative, see [UIX History](https://github.com/MrMilenko/UIX-History). +--- ## Credits -**Team UIX:** -- **Milenko**: primary RE and development, UIX Desktop port -- **BigJx**: UIX Lite XIPs (XAP scripts, skins, scene assets), testing, bug reports -- **Rocky5**: skin presets and the Colourizer XBE color patcher (technique descends from **ZogoChieftan**'s in-dashboard color patching in BlackStormX, circa 2004) -- **JbOnE**: original UIX, the lineage Theseus continues - -**Related projects:** -- [Team Resurgent](https://github.com/Team-Resurgent): [PrometheOS](https://github.com/Team-Resurgent/PrometheOS-Firmware) (the toolbox is forked from here via [UIX Lite Toolbox](https://github.com/OfficialTeamUIX/UIX-Lite-Toolbox)) and [Hermes](https://github.com/Team-Resurgent/Hermes) (ISO/CCI mount support) -- [xemu](https://xemu.app): Original Xbox emulator that the desktop launcher integrates with for ISO playback - -## Third-party libraries - -Xbox build: - -| Library | License | Purpose | -|---|---|---| -| [minimp3](https://github.com/lieff/minimp3) | CC0 | MP3 decoder for the music system | - -Desktop build: - -| Library | License | Purpose | -|---|---|---| -| [SDL2](https://www.libsdl.org/) | zlib | Window, input, audio | -| [SDL2_mixer](https://github.com/libsdl-org/SDL_mixer) | zlib | Sound playback | -| [libmpv](https://mpv.io/) | LGPL 2.1+ | Video playback | -| [libcurl](https://curl.se/libcurl/) | curl | HTTPS for TMDB metadata | -| [Dear ImGui](https://github.com/ocornut/imgui) | MIT | Developer tool UI | -| [ImGuiColorTextEdit](https://github.com/BalazsJako/ImGuiColorTextEdit) | MIT | XAP script editor with syntax highlighting | -| [stb_image](https://github.com/nothings/stb) | Public Domain | Image loading | -| [bgfx](https://github.com/bkaradzic/bgfx) | BSD 2-Clause | Cross-platform render abstraction (Metal, Vulkan) | -| [bx](https://github.com/bkaradzic/bx) | BSD 2-Clause | bgfx base library | -| [bimg](https://github.com/bkaradzic/bimg) | BSD 2-Clause | bgfx image utility library | -| [GLEW](https://glew.sourceforge.net/) | Modified BSD / MIT | OpenGL extension loader (legacy GL backend, Windows only) | - -Full catalog with attributions is in [`LICENSE-THIRD-PARTY.md`](LICENSE-THIRD-PARTY.md). - -## License - -Theseus is licensed under the **GNU General Public License, version 3 or later** (`GPL-3.0-or-later`). Full license text in [`LICENSE`](LICENSE). +Original Theseus Project by MrMilenko. -Inherited code keeps its origin license intact (`theseus/toolbox/` from PrometheOS via UIX Lite Toolbox is GPL-3.0; Hermes is GPL-3.0). The XIPs and skin assets shipped in `Data/` are TeamUIX's UIX Lite work and ship under GPL-3.0-or-later. +This version is a personal modified version made for testing, customization, and preservation of the original Xbox dashboard style. diff --git a/README_Theseus.md b/README_Theseus.md new file mode 100644 index 0000000..a7afdce --- /dev/null +++ b/README_Theseus.md @@ -0,0 +1,306 @@ +# Theseus + +[![build](https://github.com/MrMilenko/Theseus/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/MrMilenko/Theseus/actions/workflows/build.yml) +[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](LICENSE) +[![Platform](https://img.shields.io/badge/platform-Xbox%20%7C%20macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](#) + +

+ Vulkan +      + Metal +

+ +Six years of reverse engineering the original Xbox dashboard. This repo is the result. + +Theseus boots on modded Xbox hardware as a drop in replacement for the stock dashboard. The same engine compiles natively on macOS, Linux, and Windows, where it doubles as **UIX Desktop**: a 3D launcher and media center. The desktop build renders through [bgfx](https://github.com/bkaradzic/bgfx): Metal on macOS, Vulkan on Linux and Windows. + +The split is intentional. The Xbox build stays faithful to what you'd expect from the Xbox dashboard (or UIX Lite, if you've used a custom dashboard before). Everything that doesn't belong on an Xbox (Steam libraries, modern video playback, emulator-hosted ISOs, playlists, skin authoring tools) lives on the desktop side instead. Two projects, one engine. + +

+ Xbox dashboard + UIX Desktop launcher +

+

+ Media library + Custom skin +

+

+ Steam tab in Title Maker + RetroArch tab in Title Maker +

+ +## On Xbox + +A drop-in replacement for the stock Xbox dashboard on modded consoles. Same look and behavior, because that's what it is. Rebuilt plank by plank and still going. + +What works: +- Every original scene, animation, and skin slot +- UIX Lite skins drop in unchanged. Skin authors don't have to do anything +- Hot swap skins from settings, no reboot +- ISO / CCI launching from the harddrive menu, plus the original XBE flow +- Hundreds of titles scan in milliseconds +- Title icons auto populate from each game's XBE certificate +- Quick overlay (LT + B) for ISO loader, file manager, FTP / drive widgets +- FTP server, recovery / panic screen, MP3 soundtrack playback + +[Download for Xbox ->](https://github.com/MrMilenko/Theseus/releases) (or build from source, see below) + +## On the desktop (UIX Desktop) + +UIX Desktop is the Theseus engine compiled for your computer, with the modern features bolted on. macOS, Linux, Windows, Steam Deck friendly. + +- **3D launcher** for native PC games, Steam libraries, RetroArch ROMs, and Xbox ISOs via [xemu](https://xemu.app) +- **Media library** that scans your Movies and TV folders, pulls posters from [TMDB](https://www.themoviedb.org/), plays back through libmpv +- **Skin editor** with live XAP scripting and a scene inspector. Change a skin, see it instantly +- **Title Maker** for adding games and apps, with per launcher import flows for Steam and RetroArch +- **Xbox HDD browser** that opens qcow2 and FATX images +- **CRT post process** for the old TV look. Scanlines, curvature, phosphor, bloom, all tunable +- **Graphics knobs** in Settings -> Display: vsync mode, FPS cap, MSAA, hardware video decode +- **Controllers**: Xbox and PlayStation pads via SDL2 + +[Download for desktop ->](https://github.com/MrMilenko/Theseus/releases) + +## Quick Start + +### Xbox + +1. Grab the latest Xbox release (`default.xbe` + `uixdata/`) +2. Drop the XBE somewhere on the Xbox HDD, e.g. `E:\Dashboards\Theseus\default.xbe` +3. Copy `uixdata/` next to it +4. Copy `Configs/` to `C:\UIX Configs\` +5. Boot it. If something's missing, the panic screen tells you what. + +### Desktop + +1. Grab the release for your OS +2. Run it. That's it. + +The Windows release ships with the DLLs it needs. macOS and Linux dynamically link to system libraries, so you'll want these installed: + +**macOS (Homebrew):** +``` +brew install sdl2 sdl2_mixer mpv curl +``` + +**Linux (Debian / Ubuntu):** +``` +sudo apt install libsdl2-2.0-0 libsdl2-mixer-2.0-0 libmpv2 libcurl4 +``` + +(Some distros ship `libmpv1` instead of `libmpv2`. Either works.) + +If you'd rather build from source, jump down to [Building](#building). + +## Adding games + +Title Maker (F3 from the dashboard) is where you connect games to dashboard tiles. Three tabs: + +**Main** is the catch all. Every title you've added shows up here, regardless of which tab created it. This is also where you add the weird stuff that doesn't belong to a launcher: a Windows .exe, a .bat script, a macOS .command file, a shell one liner, anything that takes a path or command. Edit names, swap icons, tweak the launch line. Most of your time managing the library happens here. + +**Steam** auto detects your Steam install (Find button), or you point at it once. Hit Import Steam Library and your installed games come in with icons fetched from Valve's CDN. There's also a manual "Add by App ID" form for launching betas, demos, or games not in your normal library scan. + +**RetroArch** detects your RetroArch install the same way. Import Recent Titles pulls in everything you've recently played in RetroArch, with the right core auto resolved and boxart copied from RetroArch's thumbnail packs. You can also add manually: pick a ROM, pick a core from the dropdown, done. + +If you don't use Steam or RetroArch, you can turn either tab off under Optional Tabs (top of Main). Anything you've already added stays in Main either way. + +## Customization + +**Skins.** Drop them into `Data/Skins/` (Xbox: `uixdata\Skins\`) and pick from settings. UIX Lite community skins work as is, no conversion needed. Hot swap, no reboot. + +**Scene authoring** (for the people building dashboards from scratch). Scenes are XAP scripts packed into `.xip` archives. The desktop build has a live XAP editor (F2), scene inspector (F1), and asset reload so you can tweak and see results immediately. The XAP node interface is the contract; the C++ behind it can change but the node API is treated as sacred. Full reference in [`docs/xap-contract.md`](docs/xap-contract.md). + +## Controls (desktop) + +**Dashboard:** + +| Key | Xbox button | Action | +|---|---|---| +| Arrow keys | D-pad | Navigate | +| Enter / Space | A | Select | +| Backspace | B | Back | +| X / Y | X / Y | Context actions | +| Tab | White | Play / Pause | +| ` (backtick) | Black | Stop | +| WASD | Left stick | Analog navigation | + +**Media playback:** + +| Key | Action | +|---|---| +| Esc / Q | Stop, return to dashboard | +| Space | Pause / Resume | +| Left / Right | Seek 5s | +| `[` / `]` | Previous / Next in playlist | +| T | Track picker (audio + subtitles) | + +**Tools (desktop only):** + +| Key | Action | +|---|---| +| F1 | Scene inspector | +| F2 | XAP script editor | +| F3 | Title Maker | +| F4 | Settings | +| F5 | Xbox HDD browser | +| F6 | Playlist Maker | +| F10 | Toggle menu bar | +| F11 | Toggle fullscreen | +| Ctrl+M | Mute | +| Ctrl+R | Restart dashboard | + +Xbox and PlayStation controllers also work via SDL2 GameController. + +--- + +# For developers + +The rest is build instructions, architecture notes, and the lineage. Skip if you just want to run it. + +## Building + +Both builds live in this repo and use the same Makefile. + +### Xbox + +Cross-compiles from macOS or Linux using clang + lld-link + cxbe. Requires: +- clang and lld-link (`brew install llvm` on macOS, `apt install clang lld` on Linux) +- [OXDK](https://github.com/MrMilenko/OXDK) cloned and built +- An Xbox SDK source tree (path passed as `XDK_BASE`) + +``` +git clone https://github.com/MrMilenko/OXDK ~/OXDK +cd ~/OXDK/tools/cxbe && make +cd /path/to/Theseus/build +make CONFIG=retail XDK_BASE=/path/to/xbox +``` + +Output lands at `~/builds/theseus/xbox-retail/default.xbe`. + +### Desktop + +Same source tree, different Makefile target. Needs C++17, SDL2, SDL2_mixer, libmpv, libcurl. Rendering goes through bgfx: Metal on macOS, Vulkan on Linux and Windows. bgfx ships as a git submodule and the shaders compile from .sc source via `shaderc`. + +Init the submodules once before the first build: + +``` +git submodule update --init --recursive +``` + +Then build the bgfx libraries (one time per platform) and compile shaders: + +``` +# macOS (Apple Silicon) +make -C theseus/third-party/bgfx -j osx-arm64 +make -C build shaders-bgfx + +# Linux +make -C theseus/third-party/bgfx -j linux-release64 +make -C build shaders-bgfx-spirv + +# Windows (built from a MSYS2 mingw shell, or cross-compiled from Linux) +make -C theseus/third-party/bgfx -j mingw-gcc-release64 +make -C build shaders-bgfx-spirv +``` + +After that, the per-OS build commands: + +**macOS:** +``` +brew install sdl2 sdl2_mixer mpv curl pkg-config +cd build && make desktop BGFX=1 +~/builds/theseus/desktop/theseus +``` + +**Linux:** +``` +sudo apt install build-essential pkg-config libsdl2-dev libsdl2-mixer-dev \ + libvulkan-dev libx11-dev libmpv-dev libcurl4-openssl-dev +cd build && make desktop BGFX=1 +~/builds/theseus/desktop/theseus +``` + +**Windows (MSYS2 / MinGW64):** +``` +pacman -S make pkg-config mingw-w64-x86_64-gcc \ + mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_mixer \ + mingw-w64-x86_64-mpv mingw-w64-x86_64-curl \ + mingw-w64-x86_64-vulkan-headers mingw-w64-x86_64-vulkan-loader +cd build && make desktop-win64 BGFX=1 +``` + +Cross-compiling for Windows from macOS / Linux, ARM64 Linux, or any of the more involved setups is in [`docs/desktop/`](docs/desktop/). The CI workflow runs all the build matrix combinations on every push, which is the closest thing to executable docs for the one-time setup. + +The legacy OpenGL backend still compiles by dropping the `BGFX=1` flag, useful for older hardware without Vulkan support. Shipped releases use the bgfx path. + +## How it works + +The engine is approximately 50 source files reconstructed from the retail and patched XBE's spanning 4920 to 5960, organized the same way the original dashboard was: script VM, scene graph, rendering, asset loading, UI framework, system integration, and launcher. Per-subsystem reverse engineering notes are in [`docs/decomp/`](docs/decomp/). + +The XAP scripting layer is a custom JS-like bytecode VM. The scene graph is VRML97-inspired with runtime reflection via FND/PRD property tables. On the desktop side, D3D8 calls translate through a thin shim into bgfx, which targets Metal on macOS and Vulkan on Linux and Windows. Everything else compiles for both targets from the same shared source. + +If you're poking around the source, the high-level layout: + +``` +theseus/ + engine/ Pure logic (VM, nodes, math) + shared/ Cross-platform with Win32 types (file I/O, audio, settings) + render/ Scene graph, materials, shapes + xbox/ Xbox-only (XTL, modchip, kernel APIs) + desktop/ Desktop-only (SDL, bgfx, ImGui tools) + toolbox/ PrometheOS-derived FTP / drive / network (Xbox-only) +theseuslib/ Shared C library (xiso parser, xip parser) +``` + +Heavier docs index lives at [`docs/README.md`](docs/README.md). + +## Heritage + +Theseus is part of the TeamUIX lineage. JbOnE created *User.Interface.X* (UIX), a source level modification of the original Xbox Dashboard, which we also poked around in via Ghidra to figure certain things out. Modern TeamUIX continues that tradition with [UIX Lite](https://github.com/OfficialTeamUIX/UIX-Lite) (a heavily patched retail XBE) and Theseus (this repository). + +There's a circularity to it. UIX modified the dashboard at the source level. Theseus reaches the same destination from the other side of the river, rebuilding the codebase from binary analysis and untangling changes made to XIPs over 25 years of community modification. + +For the broader UIX project narrative, see [UIX History](https://github.com/MrMilenko/UIX-History). + +## Credits + +**Team UIX:** +- **Milenko**: primary RE and development, UIX Desktop port +- **BigJx**: UIX Lite XIPs (XAP scripts, skins, scene assets), testing, bug reports +- **Rocky5**: skin presets and the Colourizer XBE color patcher (technique descends from **ZogoChieftan**'s in-dashboard color patching in BlackStormX, circa 2004) +- **JbOnE**: original UIX, the lineage Theseus continues + +**Related projects:** +- [Team Resurgent](https://github.com/Team-Resurgent): [PrometheOS](https://github.com/Team-Resurgent/PrometheOS-Firmware) (the toolbox is forked from here via [UIX Lite Toolbox](https://github.com/OfficialTeamUIX/UIX-Lite-Toolbox)) and [Hermes](https://github.com/Team-Resurgent/Hermes) (ISO/CCI mount support) +- [xemu](https://xemu.app): Original Xbox emulator that the desktop launcher integrates with for ISO playback + +## Third-party libraries + +Xbox build: + +| Library | License | Purpose | +|---|---|---| +| [minimp3](https://github.com/lieff/minimp3) | CC0 | MP3 decoder for the music system | + +Desktop build: + +| Library | License | Purpose | +|---|---|---| +| [SDL2](https://www.libsdl.org/) | zlib | Window, input, audio | +| [SDL2_mixer](https://github.com/libsdl-org/SDL_mixer) | zlib | Sound playback | +| [libmpv](https://mpv.io/) | LGPL 2.1+ | Video playback | +| [libcurl](https://curl.se/libcurl/) | curl | HTTPS for TMDB metadata | +| [Dear ImGui](https://github.com/ocornut/imgui) | MIT | Developer tool UI | +| [ImGuiColorTextEdit](https://github.com/BalazsJako/ImGuiColorTextEdit) | MIT | XAP script editor with syntax highlighting | +| [stb_image](https://github.com/nothings/stb) | Public Domain | Image loading | +| [bgfx](https://github.com/bkaradzic/bgfx) | BSD 2-Clause | Cross-platform render abstraction (Metal, Vulkan) | +| [bx](https://github.com/bkaradzic/bx) | BSD 2-Clause | bgfx base library | +| [bimg](https://github.com/bkaradzic/bimg) | BSD 2-Clause | bgfx image utility library | +| [GLEW](https://glew.sourceforge.net/) | Modified BSD / MIT | OpenGL extension loader (legacy GL backend, Windows only) | + +Full catalog with attributions is in [`LICENSE-THIRD-PARTY.md`](LICENSE-THIRD-PARTY.md). + +## License + +Theseus is licensed under the **GNU General Public License, version 3 or later** (`GPL-3.0-or-later`). Full license text in [`LICENSE`](LICENSE). + +Inherited code keeps its origin license intact (`theseus/toolbox/` from PrometheOS via UIX Lite Toolbox is GPL-3.0; Hermes is GPL-3.0). The XIPs and skin assets shipped in `Data/` are TeamUIX's UIX Lite work and ship under GPL-3.0-or-later. diff --git a/build/Makefile b/build/Makefile index 626688c..0a06705 100644 --- a/build/Makefile +++ b/build/Makefile @@ -1130,6 +1130,8 @@ endif # Same source list as desktop. the compiler reads the same files. WIN64_OBJS = $(patsubst $(THESEUS_SRC)/%.cpp,$(WIN64_DIR)/%.o,$(WIN64_SRCS)) WIN64_DEPS = $(WIN64_OBJS:.o=.d) +WIN64_RES_RC = $(THESEUS_SRC)/desktop/resources/theseus.rc +WIN64_RES_OBJ = $(WIN64_DIR)/desktop/resources/theseus_res.o -include $(WIN64_DEPS) .PHONY: desktop-win64 desktop-win64-clean projectm-deps-win64 projectm-win64-clean @@ -1167,9 +1169,9 @@ $(PROJECTM_WIN64_MARKER): projectm-win64-clean: rm -rf $(PROJECTM_SRC)/build-win64 $(PROJECTM_WIN64_PREFIX) -$(WIN64_TARGET): $(WIN64_OBJS) +$(WIN64_TARGET): $(WIN64_OBJS) $(WIN64_RES_OBJ) @mkdir -p $(WIN64_DIR) - $(WIN64_CXX) -o $@ $(WIN64_OBJS) $(WIN64_LDFLAGS) + $(WIN64_CXX) -o $@ $(WIN64_OBJS) $(WIN64_RES_OBJ) $(WIN64_LDFLAGS) @# Bundle every DLL the exe needs so the build directory is a self- @# contained Windows drop. -static-libgcc -static-libstdc++ folds the @# core runtime in; SDL2 / SDL2_mixer / libmpv / libcurl / libwinpthread @@ -1206,6 +1208,11 @@ $(WIN64_TARGET): $(WIN64_OBJS) printf '[default]\nversion=%s\n' "$$STAMP" > "$$VFILE" @echo " (bundled DLLs + Configs/Data/Library + stamped version -> $(WIN64_DIR))" + +$(WIN64_RES_OBJ): $(WIN64_RES_RC) + @mkdir -p $(dir $@) + x86_64-w64-mingw32-windres -I$(THESEUS_SRC)/desktop/resources -i $< -o $@ + $(WIN64_DIR)/%.o: $(THESEUS_SRC)/%.cpp @mkdir -p $(dir $@) $(WIN64_CXX) $(WIN64_CFLAGS) -c -o $@ $< diff --git a/theseus/desktop/audio_sdl.cpp b/theseus/desktop/audio_sdl.cpp index a71f857..4697a73 100644 --- a/theseus/desktop/audio_sdl.cpp +++ b/theseus/desktop/audio_sdl.cpp @@ -801,6 +801,15 @@ static int MetadataLookup(mpv_node* meta, const char* key, std::string* out) return 0; } +static int ProbeSongDurationWithMixer(const std::string& path) +{ + Mix_Music* probe = Mix_LoadMUS(path.c_str()); + if (!probe) return 0; + double d = Mix_MusicDuration(probe); + Mix_FreeMusic(probe); + return (d > 0.0) ? (int)(d + 0.5) : 0; +} + static bool ProbeSong(mpv_handle* h, const std::string& path, Song& out) { if (!h) return false; @@ -820,6 +829,7 @@ static bool ProbeSong(mpv_handle* h, const std::string& path, Song& out) double dur = 0; mpv_get_property(h, "duration", MPV_FORMAT_DOUBLE, &dur); if (dur > 0) out.duration = (int)(dur + 0.5); + if (out.duration <= 0) out.duration = ProbeSongDurationWithMixer(path); mpv_node meta; memset(&meta, 0, sizeof(meta)); @@ -860,7 +870,7 @@ struct DBEntry { typedef std::map DBMap; static const uint32_t kMusicDBMagic = 0x42444D54; // 'TMDB' -static const uint32_t kMusicDBVersion = 2; +static const uint32_t kMusicDBVersion = 3; static void DB_WriteU32(FILE* fp, uint32_t v) { fwrite(&v, 4, 1, fp); } static void DB_WriteI32(FILE* fp, int32_t v) { fwrite(&v, 4, 1, fp); } @@ -1044,6 +1054,8 @@ int DashMusic_Scan(const char* musicRoot) if (!probeMpv) probeMpv = ProbeMpv_Create(); if (probeMpv && ProbeSong(probeMpv, fullPath, song)) probedCount++; + if (song.duration <= 0) + song.duration = ProbeSongDurationWithMixer(fullPath); } DBEntry e; SongToDB(song, e); diff --git a/theseus/desktop/menu_bar.cpp b/theseus/desktop/menu_bar.cpp index 308f44d..5e1675c 100644 --- a/theseus/desktop/menu_bar.cpp +++ b/theseus/desktop/menu_bar.cpp @@ -16,6 +16,9 @@ extern bool g_bWireframe; extern float g_masterVolume; +extern bool g_audioBackground; +extern void ApplyEffectiveMute_Public(); +extern void SaveDesktopSettings(); #include #include @@ -221,6 +224,11 @@ void RenderMainMenuBar() { DashAudio_SetMasterVolume(v); MediaPlayer_SetMasterVolume(v); } + + if (ImGui::Checkbox("Keep audio playing in background", &g_audioBackground)) { + ApplyEffectiveMute_Public(); + SaveDesktopSettings(); + } if (ImGui::IsItemDeactivatedAfterEdit()) { SaveDesktopSettings(); } diff --git a/theseus/desktop/resources/theseus.ico b/theseus/desktop/resources/theseus.ico new file mode 100644 index 0000000..fef8dc6 Binary files /dev/null and b/theseus/desktop/resources/theseus.ico differ diff --git a/theseus/desktop/resources/theseus.rc b/theseus/desktop/resources/theseus.rc new file mode 100644 index 0000000..48e6b1f --- /dev/null +++ b/theseus/desktop/resources/theseus.rc @@ -0,0 +1 @@ +1 ICON "theseus.ico" diff --git a/theseus/desktop/sdl_main.cpp b/theseus/desktop/sdl_main.cpp index 01651bf..6e3464e 100644 --- a/theseus/desktop/sdl_main.cpp +++ b/theseus/desktop/sdl_main.cpp @@ -348,7 +348,8 @@ static bool s_softRestartPending = false; // reinit after game exits // Audio mute state (Ctrl+M toggle, auto-muted during game launch) bool g_audioMuted = false; // user choice (Ctrl+M) -float g_masterVolume = 1.0f; // 0.0 - 1.0, applied to mixer + libmpv +float g_masterVolume = 1.0f; +bool g_audioBackground = false; // 0.0 - 1.0, applied to mixer + libmpv bool g_useMilkdropViz = false; // opt-in: replace legacy orb viz with projectM bool g_showAlbumCover = false; // when set + album.* present, replace orb viz with cover bool g_windowFocused = true; // SDL focus state @@ -361,7 +362,7 @@ static void ApplyEffectiveMute() extern bool g_mediaFullscreen; extern bool MilkdropWindow_IsOpen(); bool focusLost = !g_windowFocused && !MilkdropWindow_IsOpen(); - bool shouldMute = g_audioMuted || focusLost || g_mediaFullscreen; + bool shouldMute = g_audioMuted || (!g_audioBackground && focusLost) || g_mediaFullscreen; if (shouldMute) DashAudio_MuteAll(); else DashAudio_UnmuteAll(); } @@ -530,6 +531,9 @@ void LoadDesktopSettings() { if (v < 0.0f) v = 0.0f; if (v > 1.0f) v = 1.0f; g_masterVolume = v; } + else if (strncmp(line, "AudioBackground=", 16) == 0) { + g_audioBackground = atoi(line + 16) != 0; + } else if (strncmp(line, "UseMilkdropViz=", 15) == 0) g_useMilkdropViz = atoi(line + 15) != 0; else if (strncmp(line, "ShowAlbumCover=", 15) == 0) @@ -602,6 +606,7 @@ void SaveDesktopSettings() { fprintf(fp, "FpsCap=%d\n", g_fpsCap); fprintf(fp, "Hwdec=%d\n", g_hwdec ? 1 : 0); fprintf(fp, "MasterVolume=%.3f\n", g_masterVolume); + fprintf(fp, "AudioBackground=%d\n", g_audioBackground ? 1 : 0); fprintf(fp, "UseMilkdropViz=%d\n", g_useMilkdropViz ? 1 : 0); fprintf(fp, "ShowAlbumCover=%d\n", g_showAlbumCover ? 1 : 0); {