hakuX - RetroBIOS¶
Technical notes
Original Xbox emulator for Android, package com.rfandango.haku_x, arm64-v8a, tuned for Adreno. A Kotlin front end carries the launcher, setup wizard, game library and settings, and drives a whole xemu tree built through CMake against SDL2 and QEMU 10.2.0, the tree branching off the day before xemu moved to SDL3. The imgui interface under ui/xui is filtered out of the source list and the HUD, monitor and snapshot entry points are stubbed, so that front end is the only interface. ES-DE starts .LauncherActivity with an intent VIEW whose data URI becomes the disc slot before emulation opens. ref: QEMU_VERSION, android/README.md:36-39, android/app/build.gradle.kts:33-34, android/app/src/main/AndroidManifest.xml:13-30, android/app/src/main/cpp/CMakeLists.txt:423-424, android/app/src/main/cpp/xemu_hud_stub.c, android/app/src/main/cpp/monitor_stub.c, android/app/src/main/cpp/xemu_snapshots_stub.c, android/app/src/main/java/com/rfandango/haku_x/LauncherActivity.kt:94-104
The wizard asks for three files through the Storage Access Framework and copies each into x1box under the external files directory of the package, renamed mcpx.bin, flash.bin and hdd.img. The pickers keep .bin, .rom and .img for the two ROMs and .qcow2 and .img for the disk, and each step stays blocked until its copy lands. Those three paths, the eeprom the wizard never asks for and the disc are written to x1box/xemu.toml under sys.files, and the launcher sends the user back through the wizard whenever one of them stops resolving. ref: android/app/src/main/java/com/rfandango/haku_x/SetupWizardActivity.kt:49-51, 53-120, 249-255, 350-378, android/app/src/main/java/com/rfandango/haku_x/LauncherActivity.kt:31-92, android/app/src/main/cpp/xemu_android.cpp:669-673, 709-711, 748-820
The flash image is the only one whose absence stops the run: it is passed as -bios and a path that cannot be opened clears autostart. Its size must be a non-zero multiple of 64 KB, otherwise 256 KB of 0xFF is mapped in its place. The MCPX image must be exactly 512 bytes, another size clears the path with an error, and the machine property is checked a second time and ends the process when it disagrees; the bytes are overlaid on the last 512 of the mirrored flash region. The EEPROM must be 256 bytes and is generated as XBOX_EEPROM_VERSION_R1 when the path does not exist. An empty disk path attaches no drive at index 0 at all, while the disc drive at index 1 is always attached and simply carries no media when no image is picked. ref: system/vl.c:2921-2964, 2998-3022, 3057-3072, 3078-3092, 3094-3113, hw/xbox/xbox.c:65-104, 144-166
Settings imports a dashboard tree from a ZIP or a folder into the FATX partitions of the configured disk image, C at 0x8CA80000 and E at 0xABE80000, moving the entries it overwrites to a backup folder first. A source that has neither a C nor an E directory goes to C whole. The tree is searched for a boot XBE beforehand and the best candidate is copied to C/xboxdash.xbe when that name is missing, xboxdash.xbe, default.xbe, evoxdash.xbe, avalaunch.xbe, unleashx.xbe, xbmc.xbe and nexgen.xbe scoring in that order. The status line probes C for xboxdash.xbe, msdash.xbe, xbox.xtf and the directories xodash, audio, fonts and xboxdashdata.*, and calls the install complete when the boot XBE sits beside at least one of the others. ref: android/app/src/main/cpp/xemu_fatx_import.c:51-54, 1704-1730, 1763-1862, 1864-1927, android/app/src/main/java/com/rfandango/haku_x/XboxInsigniaHelper.kt:10-53, android/app/src/main/java/com/rfandango/haku_x/SettingsActivity.kt:2523-2620, 2661-2708
Preparing Insignia networking turns the NAT backend on and writes the DNS 46.101.64.175 into the config sector of the disk image and into the EEPROM at 0xAC. Registration boots a Setup Assistant image the user picks, which is put in the disc slot like any other game. ref: android/app/src/main/java/com/rfandango/haku_x/XboxInsigniaHelper.kt:7-8, 56-86, android/app/src/main/java/com/rfandango/haku_x/XboxEepromEditor.kt:17, android/app/src/main/java/com/rfandango/haku_x/SettingsActivity.kt:1764-1766, 1830-1847
The disk tools format an image that is already configured and never create one: a retail layout needs at least 0x1DD156000 bytes and the extended F and G layouts need room past that boundary. The EEPROM editor rewrites language, video standard, resolution flags, aspect ratio and refresh rate in place, and recomputes both checksums. ref: android/app/src/main/java/com/rfandango/haku_x/XboxHddFormatter.kt:7-29, 47-79, android/app/src/main/java/com/rfandango/haku_x/XboxEepromEditor.kt:9-38, android/app/src/main/cpp/xemu_hdd_tools_jni.c:932-983
12 files | 3 required, 9 optional | 10 in repo, 2 missing
mcpx_1.0.bin required in repo
MCPX southbridge boot ROM
- Path:
x1box/mcpx.bin - Size: 512 B
- Validation: size
- Source:
system/vl.c:2998-3022,hw/xbox/xbox.c:144-172,android/app/src/main/java/com/rfandango/haku_x/SetupWizardActivity.kt:53-74,android/app/src/main/cpp/xemu_android.cpp:669,android/app/src/main/cpp/xemu_android.cpp:748-760 - Platforms: batocera, emudeck, recalbox, retrobat, retrodeck, rocknix, romm
- Config key:
sys.files.bootrom_path - Copied under the fixed name mcpx.bin from whatever .bin, .rom or .img file the wizard is pointed at, and named by bootrom_path in the config. A size other than 512 bytes empties the setting and the machine property is left off; when the property is set the loader checks the size again and ends the process rather than continue. The bytes are read over the last 512 of the flash image and the region stays writable so early retail kernels keep their cache quirk.
Complex_4627.bin required in repo
Xbox flash ROM
- Path:
x1box/flash.bin - Validation: size
- Source:
system/vl.c:3057-3072,hw/xbox/xbox.c:65-124,android/app/src/main/java/com/rfandango/haku_x/SetupWizardActivity.kt:76-97,android/app/src/main/cpp/xemu_android.cpp:670,android/app/src/main/cpp/xemu_android.cpp:761-773 - Platforms: batocera, recalbox, retrobat, retrodeck, romm
- Config key:
sys.files.flashrom_path - Size note: Any non-zero multiple of 65536; 256 KB is assumed when the image cannot be read.
- Size options: 256.0 KB, 512.0 KB, 1.0 MB
- Copied under the fixed name flash.bin and passed as -bios. A path that cannot be opened queues an error and clears autostart, so nothing runs without it. The image is mapped at 0xFF000000 and mirrored to the top of the address space; a size that is zero or not a multiple of 64 KB, or a short read, falls back to 256 KB filled with 0xFF. A retail image cannot launch unsigned code, so a debug or modified image is what boots a title.
xbox_hdd.qcow2 required in repo
Xbox hard disk image
- Path:
x1box/hdd.img - Source:
system/vl.c:3078-3092,android/app/src/main/java/com/rfandango/haku_x/SetupWizardActivity.kt:99-120,android/app/src/main/java/com/rfandango/haku_x/XboxHddFormatter.kt:7-29,android/app/src/main/java/com/rfandango/haku_x/XboxHddFormatter.kt:47-79,android/app/src/main/cpp/xemu_android.cpp:176-184,android/app/src/main/cpp/xemu_android.cpp:671-672,android/app/src/main/cpp/xemu_android.cpp:774-795 - Config key:
sys.files.hdd_path - Copied under the fixed name hdd.img, in qcow2 or raw form, and attached as index 0 with locked=on and cache=writethrough. An empty setting attaches no drive at all and an unopenable one only queues a message, but the launcher refuses to leave the wizard until the file resolves. The formatter builds FATX partitions inside an image that already exists and needs at least 0x1DD156000 bytes for the retail layout; it never creates the image. A qcow2 with a backing file is reported at load because the sectors it did not modify are read from that other file.
eeprom.bin optional in repo
Xbox EEPROM image
- Path:
x1box/eeprom.bin - Size: 256 B
- Validation: size
- Source:
system/vl.c:2921-2964,system/vl.c:3045-3055,android/app/src/main/cpp/xemu_android.cpp:671,android/app/src/main/cpp/xemu_android.cpp:711,android/app/src/main/java/com/rfandango/haku_x/SettingsActivity.kt:1264-1267 - Config key:
sys.files.eeprom_path - Always pointed at x1box/eeprom.bin, a path the wizard never asks for. Generated as XBOX_EEPROM_VERSION_R1 when it does not exist, so a dump is needed only to carry over a console serial, region or HDD key. It is attached through the smbus-storage device; a size other than 256 bytes, or a generation that fails, clears autostart. Preparing Insignia and the EEPROM editor write to it in place.
xboxdash.xbe optional in repo
Retail dashboard boot executable
- Path:
C/xboxdash.xbe - Source:
android/app/src/main/cpp/xemu_fatx_import.c:1796-1797,android/app/src/main/cpp/xemu_fatx_import.c:1842-1843,android/app/src/main/cpp/xemu_fatx_import.c:1864-1893,android/app/src/main/java/com/rfandango/haku_x/SettingsActivity.kt:2523-2563,android/app/src/main/java/com/rfandango/haku_x/SettingsActivity.kt:2584-2620 - Imported to the root of partition C from the C directory of a user dashboard tree. The import treats this name as the boot entry: when it is absent the best scoring .xbe of the tree is copied to it, and the retail boot counts as ready only once the name exists. The start path of the emulator never reads partition C, and preparing Insignia finishes with a warning when the name is missing.
msdash.xbe optional in repo
Retail dashboard executable kept beside the boot copy
- Path:
C/msdash.xbe - Source:
android/app/src/main/cpp/xemu_fatx_import.c:1798-1799,android/app/src/main/cpp/xemu_fatx_import.c:1844-1845,android/app/src/main/java/com/rfandango/haku_x/XboxInsigniaHelper.kt:13,android/app/src/main/java/com/rfandango/haku_x/XboxInsigniaHelper.kt:42-50 - Probed at the root of partition C and imported with the rest of the tree. Its presence beside the boot XBE is one of the marks the status line reads to call a dashboard install complete.
xbox.xtf optional in repo
Dashboard typeface
- Path:
C/xbox.xtf - Source:
android/app/src/main/cpp/xemu_fatx_import.c:1800-1801,android/app/src/main/cpp/xemu_fatx_import.c:1846-1847,android/app/src/main/cpp/xemu_fatx_import.c:1786-1794,android/app/src/main/java/com/rfandango/haku_x/XboxInsigniaHelper.kt:14-16 - Probed at the root of partition C and imported with the rest of the tree, alongside the xodash, audio, fonts and xboxdashdata.* directories the root scan looks for.
<driver>.zip optional missing
Replacement Vulkan driver package
- Source:
android/app/src/main/java/com/rfandango/haku_x/GpuDriverHelper.kt:19-35,android/app/src/main/java/com/rfandango/haku_x/GpuDriverHelper.kt:37-70,android/app/src/main/java/com/rfandango/haku_x/GpuDriverHelper.kt:72-99,android/app/src/main/java/com/rfandango/haku_x/GpuDriverHelper.kt:101-104,android/app/src/main/java/com/rfandango/haku_x/GpuDriverHelper.kt:138-165 - Imported through a picker into gpu_drivers under the external files directory, renamed after the name field of the meta.json it carries, then unpacked whole into gpu_driver in internal storage. The minApi field is compared against the device before the archive is kept. Loading is offered only when /dev/kgsl-3d0 exists, and clearing the install directory returns the app to the system driver.
<content hash>.png optional missing
Replacement texture
- Source:
hw/xbox/nv2a/pgraph/vk/texture_replace.c:227-320,hw/xbox/nv2a/pgraph/vk/texture_replace.c:331-377,hw/xbox/nv2a/pgraph/vk/texture_replace.c:388-435,android/app/src/main/java/com/rfandango/haku_x/GameLibraryActivity.kt:904-990,android/app/src/main/java/com/rfandango/haku_x/MainActivity.kt:105-113 - Taken from a folder of per-title subdirectories, copied into texture_replace in internal storage, and read back by the Vulkan renderer from the subdirectory named after the title id of the running XBE in eight hexadecimal digits. A name is kept only when the stem is sixteen hexadecimal digits, which is the content hash of the texture it replaces; each PNG is decoded to a .raw sidecar carrying width and height and mapped from there. Off unless the setting is on and the folder is set.
gamecontrollerdb.txt optional in repo bundled
SDL controller mapping database
- Source:
android/app/src/main/cpp/xemu_android.cpp:193-268 - Read from the assets of the package at startup and handed to SDL as a memory stream. The asset manager reads inside the archive and the path is a constant, so there is no search order and nothing outside the package replaces this copy; an added pad mapping goes in through controller_map.txt instead. The revision shipped here is 589031 bytes and is not the one other releases carry under this name.
X1_Covers.txt optional in repo bundled
Cover art index for the game library
- Source:
android/app/src/main/java/com/rfandango/haku_x/GameLibraryActivity.kt:59,android/app/src/main/java/com/rfandango/haku_x/GameLibraryActivity.kt:398-430 - Read from the assets and turned into a lookup from normalised game name to a URL under the X1_Covers repository, which the library fetches and caches per title. Only lines ending in .png are kept.
controller_map.txt optional in repo
Extra SDL controller mappings
- Source:
thirdparty/SDL2/src/joystick/SDL_gamecontroller.c:1873-1884,thirdparty/SDL2/src/joystick/SDL_gamecontroller.c:1890-1916,android/app/src/main/cpp/CMakeLists.txt:26-34 - SDL builds this path from the internal storage directory of the package when SDL_GAMECONTROLLERCONFIG_FILE is unset, which it is here, and reads it while the game controller subsystem starts, after the mappings compiled in and before the ones the environment carries. It is the one mapping file a user can add without rebuilding the package. The SDL2 tree in thirdparty is what the build compiles, the local checkout taking precedence over the release archive CMake would otherwise fetch.
Generated on 2026-08-23T16:12:06Z