The interface takes its compact navigation and PC cards from Moonlight Qt, with a library designed for a controller and a television. Select a PC to pair or open its apps. Game covers have separate captions, and a blue focus ring shows which card will open. Running apps carry a PLAYING badge. Missing artwork uses Lucide desktop or gamepad placeholders. Use the D-pad or left stick to navigate, A to select, B to go back and Y for host or app actions. Move up from the first PC row to reach Settings, Support and Add Host. With a keyboard, hold the arrows to navigate, use Enter to select, Esc to go back, and M for host or app actions. Button hints follow the keyboard or controller you are using. On the hosts page, Alt + F4 exits the client. PgUp / PgDn scroll the log viewer; hold Shift for faster scrolling. Backspace dismisses a notification or changes the log pane.
PCs use grayscale moon artwork inspired by One: a full moon for paired online PCs, a half moon for online PCs awaiting pairing, and a crescent for offline PCs. A separate orbit shows controller focus.
Settings categories have icons and the detail panel extends beside the page heading, with a fixed help area above its options so changing values keeps the list in place. Dialogs contain their controller actions. Number pads use compact centered columns. IPv4 entry has four sections with fixed periods: three digits advance automatically, and White / Black move between sections. A new digit replaces a section after switching to it; X deletes the last digit. Connection, pairing and save actions appear after a host address has been entered. Test Connection shows a spinning progress indicator while contacting the PC, then keeps the result visible until dismissed. The app menu uses checkboxes for Hide app and Set favorite.
Notifications stack above the footer. Brief confirmations disappear automatically; actionable errors stay until you press X to dismiss the newest card. Connection-test results stay in their dialog, and settings show their updated values inline.
The layout scales with the output resolution and leaves a five-percent inset for television overscan. Large libraries scroll to keep the selected game visible. Settings use a category list alongside options and help for the selected item.
Navigation icons use Lucide. CPM downloads the tagged source release declared in
package-lock.cmake; the inherited Renovate configuration updates its version.
Only the required SVGs and their license are packaged on the ISO.
No network connection or JavaScript runtime is needed to display the icons on the console.
Settings โ Display โ Video Presentation defaults to GPU, which uses NV2A color conversion and
scaling with automatic software fallback. Software combines the decoded video and overlay on the
CPU before displaying each frame. Moonlight keeps your selection in streaming.gpu_presentation.
Choose Settings โ Audio โ Audio Mode before starting or resuming a stream. Stereo keeps
left and right separate and is the default. Mono mixes the stereo stream locally and plays the
same signal through both outputs. The selection is saved as streaming.audio_mode with a value
of stereo or mono.
Play Audio on Xbox defaults to On. Turn it off to skip local audio decoding and playback. Play Audio on PC defaults to Off. Turn it on to request playback on the host during the stream. Saved choices take precedence. To check Xbox audio without a host, use the standalone audio probe.
The default stream profile is 640ร480 at 60 FPS and 3 Mbps. Saved settings take precedence. Changing Settings โ Display โ Stream Resolution or Stream Frame Rate resets Stream Bitrate to a default calculated with Moonlight Android's resolution factors and pixel-count interpolation, scaled by the selected FPS and rounded to whole Mbps. At 30 / 60 FPS, the defaults are 1 / 3 Mbps for 640x480, 2 / 3 Mbps for 720x480, 5 / 10 Mbps for 1280x720, and 10 / 20 Mbps for 1920x1080. Bitrates are displayed in Mbps. You can then adjust Stream Bitrate manually; the setting is saved until resolution or FPS changes again. These are starting values for image quality and bandwidth, not a guarantee of Xbox decoding performance.
Press Back/Select + Black + White (LB + RB) together on any connected controller to open stream controls. Release the buttons, select a choice with either stick, then press A to choose it. B resumes playback. A USB keyboard can open the same menu with Ctrl + Alt + Shift + Q; use Tab to cycle through all choices, arrows to select the left wheel, Enter to choose, and Esc to go back. Center the sticks and release the buttons before resuming gameplay. The same shortcut returns to the wheels from the keyboard, logs or exit confirmation.
| Stick | Up | Right | Down | Left |
|---|---|---|---|---|
| Left | Keyboard | Mouse mode | View logs | Exit |
| Right | Guide | Share | Screenshot | Enable / disable stats |
Exit opens a confirmation dialog: A / Enter disconnects, X / Q quits the host app and B / Esc cancels. Disconnect leaves the application running on the PC; select its pause-marked poster to resume. Its app action menu also offers Quit app. Quitting can lose unsaved progress.
Use D-pad / left stick to move around the on-screen keyboard, A to type, X for Backspace, Y for Space, and Start for host Enter. Right stick click applies Shift to the next key; left stick click toggles Caps. White / Black (LB / RB) move the host text cursor left / right. LT cycles through letters, symbols, and PC keys, including function keys and common shortcuts. Focus a shortcut to see its combination above the keys. RT moves the keyboard between the top and bottom of the screen; B returns to the wheels. Keys use the host's US keyboard layout. When using a physical keyboard, use Tab to change page, Shift for one-shot Shift, Caps Lock to toggle Caps, F2 to move the panel, Space / Backspace to send those keys, and Esc to return.
View logs shows live entries. Scroll upward to read older entries; return to the bottom to follow new entries. Guide and Share send their controller buttons to the PC; their behavior depends on the host's virtual controller and operating system.
Screenshots are saved as BMP files, excluding local menus and statistics. The default folder is
E:\UDATA\<title-id>\screenshots. Open Settings > Storage > Screenshot Folder to browse drives
and subfolders, select the current folder, or create a new folder with the on-screen keyboard or a
USB keyboard. Press Start / Enter to create a folder after entering its name.
Use default location restores the default folder. B / Esc cancels without changing the destination.
Open a game or app's action menu and choose Screenshots to view its captures. The viewer works offline and shows the newest capture first; use LB / RB, left / right or PgUp / PgDn to browse, and B / Esc to return. Use X / Backspace / Delete to delete the selected image after confirmation.
Screenshots save in the background. A popup shows progress, then the saved path or an error. The wheels close automatically after screenshot, Guide, Share, statistics and mouse-mode actions.
Mouse mode uses the invoking controller's left stick for movement and A / B for left / right clicks. Disable mouse mode through the wheels to use that controller for gameplay again. Other gamepads and physical keyboards and mice can be used at the same time.
Up to four gamepads are supported as separate controllers in Sunshine. Standard USB boot keyboards and three-button boot mice are supported through Xbox-to-USB adapters attached to the controller ports. Devices must support HID boot protocol; mouse wheels, extra buttons and nonstandard gaming devices may not work.
For xemu, open its Monitor with ~ and enter device_add usb-kbd,id=kbd or
device_add usb-mouse,id=mouse to attach an emulated USB device to an available port.
Remove them with device_del kbd and device_del mouse. See the
xemu keyboard setup guide for explicit controller-port selection.
When Sunshine and xemu run on the same PC, prevent Sunshine's virtual controllers from being attached to xemu. Disable automatic controller binding in Input, manually assign the physical controller, and leave ports used for keyboards or mice unassigned to controllers to avoid USB port conflicts.
Enable Settings โ Display โ Performance Stats for a live panel during playback and additional
performance details in the summary. The panel works with GPU and software presentation, refreshes
once per second, and shows N/A for unavailable measurements. It includes measured incoming,
decoded and rendered FPS, video bitrate, timing, frame drops, buffering and the presentation path.
The stream header shows the requested FPS; the three FPS counters show measured rates.
Network latency is round-trip time. Present measures CPU frame preparation and submission,
including any scanout wait.
The stream menu can toggle these statistics for the current session; the saved setting sets the
initial state of the next session.
Video decoding runs on the CPU. Every stream summary reports GPU and software frame counts. SOFTWARE FALLBACK USED includes the reason GPU presentation switched to software, even when Performance Stats is disabled.
-
Clone the repository with submodules, or update them after cloning.
git submodule update --init --recursive
-
Install nxdk prerequisites.
Note
You must use the mingw64 shell on Windows.
pacman -Syu
nxdk_dependencies=(
"bison"
"flex"
"git"
"make"
"mingw-w64-x86_64-cmake"
"mingw-w64-x86_64-clang"
"mingw-w64-x86_64-gcc"
"mingw-w64-x86_64-lld"
"mingw-w64-x86_64-llvm"
"mingw-w64-x86_64-make"
"mingw-w64-x86_64-nasm"
)
moonlight_dependencies=(
"mingw-w64-x86_64-doxygen"
"mingw-w64-x86_64-graphviz"
"mingw-w64-ucrt-x86_64-nodejs"
)
dependencies=("${nxdk_dependencies[@]}" "${moonlight_dependencies[@]}")
pacman -S "${dependencies[@]}"nxdk_dependencies=(
"bison"
"build-essential"
"clang"
"cmake"
"flex"
"git"
"lld"
"llvm"
"nasm"
)
moonlight_dependencies=(
"doxygen"
"graphviz"
"nodejs"
)
dependencies=("${nxdk_dependencies[@]}" "${moonlight_dependencies[@]}")
apt install "${dependencies[@]}"nxdk_dependencies=(
"cmake"
"coreutils"
"lld"
"llvm"
"nasm"
)
moonlight_dependencies=(
"doxygen"
"graphviz"
"node"
)
dependencies=("${nxdk_dependencies[@]}" "${moonlight_dependencies[@]}")
brew install "${dependencies[@]}"Configure the top-level project with the normal host toolchain. CMake uses the vendored third-party/nxdk checkout, copies its tracked sources and nested submodules into the build directory, bootstraps the required nxdk outputs there, builds the host-native tests with the standard compiler/linker, and drives the Xbox build through an internal child configure that reuses the stock nxdk toolchain.
For host and Xbox builds, CMake checks whether the compiler supports Clang's unused-but-set-global warning. When supported, this warning remains nonfatal for moonlight-common-c, whose debug counters are read only by assertions that are disabled in release builds. Other warnings retain the dependency's existing error policy.
cmake -S . -B cmake-build-release -DBUILD_DOCS=OFF -DCMAKE_BUILD_TYPE=ReleaseOptional Xbox build settings:
| CMake option | Default | Purpose |
|---|---|---|
MOONLIGHT_BUILD_VIDEO_EXPERIMENTS |
OFF |
Build the standalone video probes. |
MOONLIGHT_BUILD_AUDIO_EXPERIMENTS |
OFF |
Build the standalone audio playback probe. |
MOONLIGHT_INPUT_DIAGNOSTICS |
OFF |
Show controller state and event counters. Select Software presentation to see the debug strip. |
Pass these options when configuring. Existing build directories retain cached build options until explicitly reconfigured.
cmake --build cmake-build-releaseThis script takes care of everything, except installing the prerequisites.
./build.shThe default build directory is cmake-build-release. You can override it or force a clean build:
./build.sh --build-dir cmake-build-debug
./build.sh --clean
./build.sh cmake-build-custom cleanTo launch the same build from shells outside MSYS2 on Windows, use one of these wrappers:
build-mingw64.bat./build-mingw64.shThe Xbox executable cannot run directly on Windows, macOS, or Linux, so the top-level project builds test_moonlight natively while the Xbox binary is built by an internal child configure that uses the nxdk toolchain. Keep Xbox runtime code thin and move logic you want to test into platform-neutral sources that can be linked into test_moonlight.
From cmd.exe, configure, build, and run the host tests after the helper locates your local MSYS2 installation:
call scripts\find-msys2.cmd && "%MOONLIGHT_MSYS2_SHELL%" -defterm -here -no-start -mingw64 -c "cd /c/Users/%USERNAME%/Dev/git/Moonlight-XboxOG && cmake -S . -B cmake-build-host-tests -DBUILD_DOCS=OFF -DBUILD_TESTS=ON -DBUILD_XBOX=OFF -DCMAKE_BUILD_TYPE=Debug && cmake --build cmake-build-host-tests --target test_moonlight && ctest --test-dir cmake-build-host-tests --output-on-failure"If you are already inside a mingw64 shell, the equivalent commands are:
cmake -S . -B cmake-build-host-tests -DBUILD_DOCS=OFF -DBUILD_TESTS=ON -DBUILD_XBOX=OFF -DCMAKE_BUILD_TYPE=Debug
cmake --build cmake-build-host-tests --target test_moonlight
ctest --test-dir cmake-build-host-tests --output-on-failurecmake -S . -B cmake-build-host-tests -DBUILD_TESTS=ON -DBUILD_XBOX=OFF -DBUILD_DOCS=OFF
cmake --build cmake-build-host-tests --target test_moonlight
ctest --test-dir cmake-build-host-tests --output-on-failureCoverage should come from this host-native test build instead of the cross-compiled Xbox build.
The SDK submodule tracks upstream XboxDev/nxdk, including its upstream PDCLib. Moonlight's
Xbox adapters live in src/_nxdk_compat and are built by cmake/nxdk-compat.cmake.
All SDK libraries, host tools and generated lwIP files are built under the build
directory, including for direct Xbox presets. cmake/nxdk-toolchain.cmake prepares
that copy before compiler checks and then loads the stock nxdk toolchain. SDK
revision changes and local edits to tracked SDK files refresh the copy; unrelated
untracked files and existing build products are excluded. MOONLIGHT_NXDK_DIR
selects the source checkout; MOONLIGHT_NXDK_BUILD_DIR selects the build copy.
The local network target builds upstream lwIP with the streaming receive limits,
socket options and mDNS enabled. The network/nxdk-network.patch compatibility
patch is applied with git apply to build-directory copies, preserving thread
priorities and safe packet drops on receive-pool exhaustion. The submodule
sources stay unchanged. nxNetInit is compiled with the same settings so its
network-interface layout matches lwIP.
The compatibility layer provides real wall-clock, sleep and reentrant string helpers.
FFmpeg's unused POSIX descriptor/file helpers and OpenSSL's optional POSIX directory
and metadata queries fail explicitly with ENOSYS. Moonlight's Win32 file APIs,
standard stdio and custom OpenSSL socket BIO continue to handle saved data and pairing.
FFmpeg configure probes still link actual Xbox libraries and the local timing helpers.
OpenSSL disables POSIX descriptor I/O; its socket BIO leaves socket ownership with the caller. FFmpeg builds its original file helpers through its generic platform path, with memory mapping and temporary-file creation disabled.
The Windows preset in CMakePresets.json uses MinGW Makefiles for the host-native CLion build, auto-detects the local MSYS2 installation through cmake/host-mingw64-clang.cmake, and delegates the Xbox child build through a dedicated CMake driver that enters the vendored nxdk environment only for the child configure and build steps.
- Open the project in CLion and import the
nxdk-release (mingw64)preset fromCMakePresets.json. - Use the normal build button with that profile selected. The top-level build will compile
test_moonlightnatively and configure the Xbox child build automatically. - When you use CLion's Reset Cache and Reload Project, the next configure will clean the
nxdkbuild outputs and rebuild the requirednxdklibraries and tools. - Build the
moonlight_xboxtarget or the defaultalltarget. The generated ISO now lives atcmake-build-release/xbox/Moonlight.iso.
For the first xemu launch, you can either run the shared Setup portable xemu configuration or run the Windows wrapper manually:
scripts\setup-xemu.cmdThe repository now includes .run/Run xemu.run.xml, which launches scripts\run-xemu.cmd through C:\Windows\System32\cmd.exe without extra arguments and lets the launcher auto-discover a built Moonlight ISO.
If you create a local CLion run configuration that sets the working directory to a build output such as $CMakeCurrentBuildDir$/xbox, the Windows wrapper also treats that caller working directory as the xemu target path when no explicit launcher arguments or MOONLIGHT_XEMU_* overrides are provided.
The setup script downloads xemu and the emulator support files into .local/xemu, then refreshes launcher manifests used by scripts/run-xemu.sh. Existing files under .local/xemu are preserved by default so a local xemu install or support bundle is not overwritten unless you pass --force. The launcher accepts MOONLIGHT_XEMU_BUILD_DIR, MOONLIGHT_XEMU_ISO_PATH, --build-dir <cmake-build-dir>, --iso <iso-path>, or a single positional path that can point at either a build directory or an ISO file. If you do not pass a path, it falls back across available cmake-build-* outputs and prefers the newest built ISO.
When xemu runs with its default user-mode network, multicast mDNS traffic is not forwarded reliably, so automatic host discovery may not find your PC. For reliable discovery, launch xemu with --network tap --tap-ifname <adapter> or add the host manually from the Xbox UI.
If you only want the emulator without the ROM/HDD support bundle, run:
scripts\setup-xemu.cmd --skip-support-filesNote
You can set Xemu to use widescreen mode by using https://github.com/Ernegien/XboxEepromEditor but 1080i does not work in Xemu.
- Build
- Build in GitHub CI
- Build with CMake instead of Make, see https://github.com/Ryzee119/Xenium-Tools/blob/master/CMakeLists.txt and https://github.com/abaire/nxdk_pgraph_tests/blob/4b7934e6d612a6d17f9ec229a2d72601a5caefc4/CMakeLists.txt
- Get build environment working with CLion directly instead of using external terminal
- debugger, see https://github.com/abaire/xbdm_gdb_bridge
- Add a run config for CLion, see https://github.com/Subtixx/XSampleProject
- Automatically run built xiso in Xemu
- Add unit testing framework
- Separate main build and unit test builds, due to cross compiling, see https://stackoverflow.com/a/64335131/11214013
- Get tests to properly compile
- Enable codecov
- Enable sonarcloud
- Build moonlight-common-c
- Build custom enet
- Docs via doxygen
- Menus / Screens
- Loading/splash screen
- Initial loading screen, see https://github.com/XboxDev/nxdk/blob/master/samples/sdl_image/main.c
- Set video mode based on the best available mode
- dynamic splash screen (size based on current resolution)
- simplify (draw background color and overlay logo) to reduce total size
- Main/Home
- Settings
- Add Host
- Game/App Selection
- Host Details
- App Details
- Pause/Hotkey overlay
- Loading/splash screen
- Streaming
- Video - https://www.xbmc4xbox.org.uk/wiki/XBMC_Features_and_Supported_Formats#Xbox_supported_video_formats_and_resolutions
- Audio
- Mono
- Stereo
- Dolby Digital 5.1 output over optical S/PDIF
- Input
- Gamepad Input
- Keyboard Input
- Mouse Input
- Mouse Emulation via Gamepad
- Misc.
- Save config and pairing states
- Host pairing
- Auto host discovery
- Possibly, GPU overclocking, see https://github.com/GXTX/XboxOverclock













