Lichii

https://github.com/zortos293/lichii
Admin
Lichii is an experimental, open-source Nintendo Switch and Switch 2 emulator written in C++.
Tokens:1,212,625
Snippets:6,810
Trust Score:9.4
License:GPL-3.0
Update:6 days ago
Show doc for...
Tokens:
Raw
### Install Docker on Ubuntu

Source: https://github.com/zortos293/lichii/blob/nx2/docs/user/ServerHosting.md

Update package lists, install Docker, enable and start the Docker service, then verify the installation.

```bash
apt update
```

```bash
apt install -y docker.io
```

```bash
systemctl enable --now docker
```

```bash
docker --version
```

--------------------------------

### Install QEMU on Debian

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Install QEMU on a Debian system to prepare for cross-compilation or testing NCE from an x86_64 system.

```sh
sudo pkg install qemu
```

--------------------------------

### Emerge crossdev on Gentoo

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Install crossdev on a Gentoo system to set up cross-compilation toolchains.

```sh
sudo emerge -a sys-devel/crossdev
```

--------------------------------

### Install Eden AppImage (optional)

Source: https://github.com/zortos293/lichii/blob/nx2/docs/user/ServerHosting.md

Make the Eden AppImage executable. Only needed if you want to manage Eden locally on a VPS.

```bash
chmod +x Eden-Linux*.AppImage
```

--------------------------------

### Create QEMU system disk

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Create a 30GB QEMU qcow2 disk image for the Debian ARM64 virtual machine.

```sh
qemu-img create -f qcow2 debian-13-arm64-ci.qcow2 30G
```

--------------------------------

### CURL command to get server address and port

Source: https://github.com/zortos293/lichii/blob/nx2/docs/user/Multiplayer.md

For MacOS/Linux users. Requires jq. Calls the API to get the address and port information, filters by room name, and outputs JSON. Replace <NAME> with the server name. Example output shows address and port.

```bash
# Calls the API to get the address and port information
curl -s "https://api.ynet-fun.xyz/lobby" | jq '.rooms[] | select(.name == "<NAME>") | {address, port}'

# Example Output
#{
#  "address": "118.208.233.90",
#  "port": 5001
#}
```

--------------------------------

### AddQt

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CPMUtil.md

Adds a customized Qt build from a repository. The usage and setup is subject to change.

```APIDOC
## AddQt

### Description
Adds a customized Qt build from a repository. The usage and setup is subject to change.

### Method
N/A (CMake function)

### Endpoint
N/A

### Parameters
#### Arguments
- **repository** (string) - Required - The repository containing the Qt build.
- **version** (string) - Required - The Qt version to use.

### Response
N/A

### Request Example
```cmake
AddQt(QDash-CI/Qt 6.11.1)
```
```

--------------------------------

### Install Java SDK on Debian

Source: https://github.com/zortos293/lichii/blob/nx2/docs/build/Android.md

Installs OpenJDK 17 on Debian-based systems. Required if a Java SDK is not already installed.

```sh
sudo apt install openjdk-17-jdk
```

--------------------------------

### Enable QEMU user targets USE flags

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Add USE flags to /etc/portage/package.use for app-emulation/qemu to enable static user and aarch64 user targets.

```txt
app-emulation/qemu static-user qemu_user_targets_aarch64
```

--------------------------------

### OpenIndiana: Install dependencies with sudo pkg

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required dependencies on OpenIndiana using sudo pkg.

```sh
sudo pkg install git cmake qt6 boost glslang libzip library/lz4 libusb-1 nlohmann-json openssl opus sdl3 zlib compress/zstd unzip pkg-config nasm autoconf mesa library/libdrm header-drm developer/fmt
```

--------------------------------

### Install yuzu target on Unix

Source: https://github.com/zortos293/lichii/blob/nx2/src/yuzu/CMakeLists.txt

Installs the yuzu executable when building on Unix (excluding Apple).

```cmake
if(UNIX AND NOT APPLE)
    install(TARGETS yuzu)
endif()
```

--------------------------------

### PowerShell command to get server address and port

Source: https://github.com/zortos293/lichii/blob/nx2/docs/user/Multiplayer.md

For Windows users. Calls the API to get the address and port information, filters by room name, and outputs JSON. Replace <NAME> with the server name. Example output shows address and port.

```powershell
# Calls the API to get the address and port information
(Invoke-RestMethod -Method Get -Uri "https://api.ynet-fun.xyz/lobby").rooms | Where-Object {$_.Name -eq '<NAME>'} | Select address,port | ConvertTo-Json

# Example Output
#{
#  "address": "118.208.233.90",
#  "port": 5001
#}
```

--------------------------------

### NetBSD: Install dependencies with pkgin

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required dependencies on NetBSD 10.1 or later using pkgin.

```sh
pkgin install git cmake boost fmtlib SDL3 catch2 libjwt spirv-headers spirv-tools ffmpeg7 libva nlohmann-json jq libopus qt6-qtbase qt6-qtcharts qt6-qtmultimedia qt6-qttools cpp-httplib lz4 vulkan-headers nasm autoconf enet pkg-config libusb1 libcxx frozen
```

--------------------------------

### Build script examples

Source: https://github.com/zortos293/lichii/blob/nx2/docs/build/Android.md

Example invocations of the build script: build legacy release with update checker, build standard release with debug info without update checker, and build optimized release with update checker for ChromeOS.

```sh
.ci/android/build.sh -r -t legacy
```

```sh
.ci/android/build.sh -b RelWithDebInfo
```

```sh
.ci/android/build.sh -c -r -t optimized
```

--------------------------------

### Install Xcode Command Line Tools on macOS

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Required to get Apple Clang on macOS. Run in Terminal.

```bash
xcode-select --install
```

--------------------------------

### Pull request title examples

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Development.md

Examples of namespaced and optionally typed PR titles. Namespacing level is left to the committer, but hle may use up to four levels.

```txt
[cmake] refactor: CPM over submodules
[desktop] feat: implement firmware install from ZIP
[hle] stub fw20 functions
[core] test: raise maximum CPU cores to 6
[cmake, core] Unbreak FreeBSD Building Process
```

--------------------------------

### Run cross-compiled executable with QEMU

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Run the compiled executable using qemu-aarch64 with the sysroot.

```sh
qemu-aarch64 build/aarch64/bin/eden
```

--------------------------------

### NetBSD: Build glslang from source

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Caveats.md

glslang is not available on NetBSD, so build it manually. Requires python313 (installed via pkgin) and a C++ compiler. The commands clone the KhronosGroup/glslang repo, update sources, configure with CMake, build, and install.

```sh
pkgin python313
git clone --depth=1 https://github.com/KhronosGroup/glslang.git
cd glslang
python3.13 ./update_glslang_sources.py
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -- -j`nproc`
cmake --install build
```

--------------------------------

### AddQt to add a customized Qt build

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CPMUtil.md

Use AddQt(<repository> <version>) to add a customized Qt build from a repository. This usage and setup is subject to change. After calling, find_package(Qt6 ...) will pull Qt from the downloaded source.

```cmake
AddQt(QDash-CI/Qt 6.11.1)
```

--------------------------------

### OmniOS: Install dependencies with sudo pkgin

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required dependencies on OmniOS using sudo pkgin.

```sh
sudo pkgin install git cmake autoconf build-essential libusb-1 nasm gcc13
```

--------------------------------

### Download Debian 13 ARM64 ISO

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Download the Debian 13 ARM64 netinst ISO image for use in a QEMU virtual machine.

```sh
wget https://cdimage.debian.org/debian-cd/current/arm64/iso-cd/debian-13.0.0-arm64-netinst.iso
```

--------------------------------

### Run Debian ARM64 VM with QEMU

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Launch a QEMU virtual machine with Debian ARM64, using UEFI firmware, SCSI CD-ROM, virtio disk, GPU, USB, audio, and network devices.

```sh
qemu-system-aarch64 -M virt -m 2G -cpu max -bios /usr/local/share/qemu/edk2-aarch64-code.fd -drive if=none,file=debian-13.0.0-arm64-netinst.iso,format=raw,id=cdrom -device scsi-cd,drive=cdrom -drive if=none,file=debian-13-arm64-ci.qcow2,id=hd0,format=qcow2 -device virtio-blk-device,drive=hd0 -device virtio-gpu-pci -device usb-ehci -device usb-kbd -device intel-hda -device hda-output -nic user,model=virtio-net-pci
```

--------------------------------

### Install all dependencies on Gentoo Linux

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required packages on Gentoo. Note additional packages for specific architectures and USE flags mentioned in the source.

```sh
sudo emerge -a \
    app-arch/lz4 app-arch/zstd app-arch/unzip \
    dev-libs/libfmt dev-libs/libusb dev-libs/mcl dev-libs/sirit \
    dev-libs/boost dev-libs/openssl dev-libs/discord-rpc \
    dev-util/spirv-tools dev-util/spirv-headers dev-util/vulkan-headers \
    dev-util/vulkan-utility-libraries dev-util/glslang \
    media-gfx/renderdoc media-libs/libva media-libs/opus media-video/ffmpeg \
    media-libs/VulkanMemoryAllocator media-libs/libsdl3 media-libs/cubeb \
    net-libs/enet \
    sys-libs/zlib \
    dev-cpp/nlohmann_json dev-cpp/simpleini dev-cpp/cpp-httplib dev-cpp/cpp-jwt \
    games-util/gamemode \
    net-wireless/wireless-tools \
    dev-qt/qtbase:6 dev-libs/quazip \
    virtual/pkgconfig
```

--------------------------------

### Install aarch64 GDB on Arch

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Debug.md

Install GDB for aarch64 on Arch Linux to debug guest code.

```bash
sudo pacman -Syu aarch64-linux-gnu-gdb
```

--------------------------------

### Install dependencies on HaikuOS

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required packages for building on HaikuOS using pkgman. Includes Qt6, SDL3, FFmpeg, and other dependencies.

```sh
pkgman install git cmake patch libfmt_devel nlohmann_json lz4_devel opus_devel boost1.90_devel vulkan_devel qt6_base_devel qt6_declarative_devel libsdl3_devel ffmpeg7_devel libx11_devel enet_devel catch2_devel quazip1_qt5_devel qt6_5compat_devel glslang qt6_devel qt6_charts_devel cubeb_devel simpleini quazip_qt6_devel
```

--------------------------------

### OpenBSD: Update and install dependencies

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Updates package list and installs all required dependencies on OpenBSD.

```sh
pkg_add -u
pkg_add cmake nasm git boost unzip--iconv autoconf-2.72p0 bash ffmpeg glslang gmake qt6 jq fmt nlohmann-json enet boost vulkan-utility-libraries vulkan-headers spirv-headers spirv-tools catch2 sdl3 libusb1-1.0.29 quazip-qt6
```

--------------------------------

### Emerge minimal Qt dependencies for cross-compilation

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Emerge the minimal Qt dependencies (qtbase and qtcharts) for the aarch64 target using cross-emerge.

```sh
sudo emerge-aarch64-unknown-linux-gnu dev-qt/qtbase:6 dev-qt/qtcharts:6
```

--------------------------------

### Enable GURU in crossdev sysroot

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Create a Portage repository configuration file in the crossdev sysroot to enable the GURU overlay.

```sh
mkdir -p /usr/aarch64-unknown-linux-gnu/etc/portage/repos.conf
cat << EOF > /usr/aarch64-unknown-linux-gnu/etc/portage/repos.conf/guru.conf
[guru]
location = /var/db/repos/guru
auto-sync = no
priority = 1
EOF
```

--------------------------------

### DragonFlyBSD: Install dependencies with pkg

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required dependencies on DragonFlyBSD using pkg.

```sh
pkg install gcc14 git cmake unzip nasm autoconf bash pkgconf ffmpeg glslang gmake jq nlohmann-json enet spirv-tools sdl3 vulkan-utility-libraries vulkan-headers catch2 libfmt openssl liblz4 boost-libs cpp-httplib qt6-base qt6-charts quazip-qt6 libva-vdpau-driver libva-utils libva-intel-driver
```

--------------------------------

### Install aarch64 GDB on Gentoo

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Debug.md

Install GDB for aarch64 on Gentoo using crossdev. Requires crossdev and then crossdev to create the toolchain.

```bash
sudo emerge --ask crossdev
```

```bash
sudo crossdev -t aarch64-unknown-linux-gnu --ex-gdb
```

--------------------------------

### Install dependencies on AlmaLinux (with YUZU_USE_CPM=ON)

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required packages on AlmaLinux. Requires RPM Fusion for ffmpeg-devel. Includes enabling CRB repos for Qt6 private GUI.

```sh
# vvv - Only if RPMfusion is not installed or EPEL isn't either
sudo dnf install epel-release dnf-utils
# (run rpmfusion installation afterwards)
# vvv - This will work for most systems
sudo dnf install autoconf cmake libtool libudev cmake gcc gcc-c++ qt6-qtbase-devel zlib-devel openssl-devel boost SDL3 ffmpeg-devel libdrm glslang jq patch
# Qt6 private GUI must be taken from CRB repos
sudo dnf config-manager --enable crb
sudo dnf install qt6-qtbase-private-devel
```

--------------------------------

### Install dependencies on Ubuntu, Debian, Mint Linux

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required packages on Ubuntu/Debian/Mint. Requires Ubuntu 26.04, Linux Mint 22.3, or Debian 13 or later. To enable QT Web Engine, add -DYUZU_USE_QT_WEB_ENGINE=ON when running CMake.

```sh
sudo apt-get install autoconf cmake g++ gcc git glslang-tools libglu1-mesa-dev libhidapi-dev libpulse-dev libtool libudev-dev libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-xinerama0 libxcb-xkb1 libxext-dev libxkbcommon-x11-0 mesa-common-dev nasm ninja-build qt6-base-private-dev catch2 libfmt-dev liblz4-dev nlohmann-json3-dev libzstd-dev libssl-dev libavfilter-dev libavcodec-dev libswscale-dev pkg-config zlib1g-dev libva-dev libvdpau-dev qt6-tools-dev qt6-charts-dev libvulkan-dev spirv-tools spirv-headers libusb-1.0-0-dev libxbyak-dev libboost-dev libboost-fiber-dev libboost-context-dev libsdl3-dev libopus-dev libasound2t64 vulkan-utility-libraries-dev
```

--------------------------------

### FreeBSD: Install dependencies as root

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required dependencies on FreeBSD as root. For FreeBSD 12 or prior, use devel/pkg-config instead.

```sh
pkg install devel/cmake devel/sdl3 devel/boost-libs devel/catch2 devel/libfmt devel/nlohmann-json devel/ninja devel/nasm devel/autoconf devel/pkgconf devel/qt6-base x11-toolkits/qt6-charts devel/simpleini net/enet multimedia/ffnvcodec-headers multimedia/ffmpeg audio/opus archivers/liblz4 lang/gcc12 graphics/glslang graphics/vulkan-utility-libraries graphics/spirv-tools www/cpp-httplib graphics/vulkan-utility-libraries graphics/vulkan-headers graphics/spirv-headers quazip-qt6
```

--------------------------------

### Build yuzu-cmd target

Source: https://github.com/zortos293/lichii/blob/nx2/NX2_NOTES.md

Builds the yuzu-cmd target, producing build/bin/eden-cli.exe.

```shell
cmake --build build --target yuzu-cmd
```

--------------------------------

### Set up crossdev for aarch64

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Create a cross-compilation toolchain for the aarch64 target architecture using crossdev.

```sh
sudo crossdev aarch64
```

--------------------------------

### Dump NPDM header with npdm_info.py

Source: https://github.com/zortos293/lichii/blob/nx2/NX2_NOTES.md

Dumps the META/ACI0 header, services, and kernel caps from a main.npdm file.

```shell
tools/nx2/npdm_info.py <main.npdm>
```

--------------------------------

### Install dependencies on Arch Linux

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required packages on Arch. Requires GCC 11 or later. Optional packages for QT Web Engine and Wayland support are mentioned.

```sh
sudo pacman -Syu --needed base-devel boost catch2 cmake enet ffmpeg fmt git glslang libzip lz4 ninja nlohmann-json openssl opus qt6-base qt6-multimedia qt6-charts sdl3 zlib zstd zip unzip vulkan-headers vulkan-utility-libraries libusb spirv-tools spirv-headers
```

--------------------------------

### Void Linux: Install dependencies with xbps-install

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required dependencies on Void Linux using xbps-install. Note that nlohmann-json is named json-c++ in this distribution.

```sh
xbps-install -Su git make cmake clang pkg-config patch SPIRV-Tools-devel SPIRV-Headers lz4 liblz4-devel boost-devel ffmpeg6-devel catch2 Vulkan-Utility-Libraries Vulkan-Headers glslang openssl-devel SDL3-devel quazip-qt6-devel qt6-base-devel qt6-qt5compat-devel qt6-charts-devel fmt-devel json-c++ libenet-devel libusb-devel
```

--------------------------------

### Example Error Message Entry in Windows Event Viewer

Source: https://github.com/zortos293/lichii/blob/nx2/docs/user/Troubleshoot.md

Shows the error log entry format for Eden failing to launch on Windows, with exception code 0xc0000005 and ntdll.dll as the faulting module.

```text
Faulting application name: eden.exe, version: 0.0.0.0, time stamp: 0x6795dc3c
Faulting module name: ntdll.dll, version: 10.0.26100.3037, time stamp: 0x95e6c489
Exception code: 0xc0000005
Fault offset: 0x0000000000014778
Faulting process id: 0x2AF0
Faulting application start time: 0x1DB7C30D2972402
Faulting application path: C:\temp\Eden-Windows\eden.exe
Faulting module path: C:\WINDOWS\SYSTEM32\ntdll.dll
Report Id: 4c8a6e13-9637-438c-b4d0-e802d279af66
Faulting package full name: 
Faulting package-relative application ID:
```

--------------------------------

### MSYS2: Install dependencies with pacman

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required dependencies in the MSYS2 MinGW 64-bit shell. The script builds a package list for either x86_64 or clang-aarch64 (Windows on ARM) and runs pacman.

```sh
BASE="git make autoconf libtool automake-wrapper jq patch"
MINGW="qt6-base qt6-charts qt6-tools qt6-translations qt6-svg cmake toolchain clang python-pip openssl vulkan-memory-allocator vulkan-devel glslang boost fmt lz4 nlohmann-json zlib zstd enet opus libusb openssl SDL3"
# Either x86_64 or clang-aarch64 (Windows on ARM)
packages="$BASE"
for pkg in $MINGW; do
    packages="$packages mingw-w64-x86_64-$pkg"
    #packages="$packages mingw-w64-clang-aarch64-$pkg"
done
pacman -Syuu --needed --noconfirm $packages
```

--------------------------------

### Qt tr() with %n for plural handling

Source: https://github.com/zortos293/lichii/blob/nx2/dist/english_plurals/README.md

Shows how to use Qt's translation rule for plurals with the %n placeholder. The example demonstrates that for i=1 the output is 'Building: 1 shader' and for i=2 it becomes 'Building: 2 shaders'.

```cpp
    // Take a source line like
    tr("Building: %n shader(s)", "", i)

    // i = 1:
    Building: 1 shader
    // i = 2:
    Building: 2 shaders
```

--------------------------------

### Build cross-compiled project

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Build the project using the configured CMake build directory.

```sh
cmake --build build/aarch64
```

--------------------------------

### VSCode settings.json for CMake build

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Development.md

Copy to `.vscode/settings.json` to configure editor tab size, file associations, and Git signing. Requires CMake tools extension; optionally install Qt Extension Pack for Qt builds.

```json
{
    "editor.tabSize": 4,
    "files.watcherExclude": {
        "**/target": true
    },
    "files.associations": {
      "*.inc": "cpp"
    },
    "git.enableCommitSigning": true,
    "git.alwaysSignOff": true
}
```

--------------------------------

### Enable GURU repository on Gentoo Linux

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Required before installing dependencies on Gentoo. Enables the GURU repository and syncs it.

```sh
sudo emerge -a app-eselect/eselect-repository
sudo eselect repository enable guru
sudo emaint sync -r guru
```

--------------------------------

### Run verification tests with ctest and test binaries

Source: https://github.com/zortos293/lichii/blob/nx2/docs/bananza-upstream-comparison.md

Rerun the full test suite and focused test groups after building with the diagnostic guide configuration. The first command runs all tests, the second runs storage-buffer, native-reset, Ampere, and async-draw tests, and the third runs frame-trace tests with the EDEN_DKB_FRAME_TRACE environment variable set to 1.

```sh
ctest --test-dir build --output-on-failure
```

```sh
build/bin/tests '[shader][storage_buffer],[native_reset],[video_core][ampere],[async_draw]'
```

```sh
EDEN_DKB_FRAME_TRACE=1 build/bin/tests '[dkb_frame_trace]'
```

--------------------------------

### Launch title 1 with frame capture: EDEN_NX2_FRAME_CAPTURE

Source: https://github.com/zortos293/lichii/blob/nx2/NX2_NOTES.md

Launches title 1 with frame capture, auto-stub, and shader dump. The command sets environment variables and runs eden-cli.exe with the game path. Use for debugging rendering issues like colour cast and missing geometry.

```bash
EDEN_NX2_FRAME_CAPTURE=C:/dev/frames_t1x EDEN_NX2_AUTO_STUB=1 EDEN_NX2_SHADER_DUMP=C:/dev/shaders_title1 ./eden-cli.exe -g "C:/switch/first switch game/exefs/main"
```

--------------------------------

### Add license headers with push

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Development.md

Run the license header script and push the changes. Requires fetching the master branch first.

```sh
git fetch origin master:master
.ci/license-header.sh -u -c
git push
```

--------------------------------

### Set log filter for one run

Source: https://github.com/zortos293/lichii/blob/nx2/NX2_NOTES.md

Sets the log filter for a single run, e.g. to get module load addresses with '*:Info Loader:Debug'.

```shell
eden-cli --filter "<log filter>"
```

--------------------------------

### Run Eden CLI in portable mode

Source: https://github.com/zortos293/lichii/blob/nx2/NX2_NOTES.md

Runs eden-cli.exe in portable mode with a Switch 2 title's ExeFS main file. Config and logs are stored in build/bin/user/; no keys or firmware are installed.

```shell
eden-cli.exe -g "<title>\exefs\main"
```

--------------------------------

### Run Eden lobby Docker container

Source: https://github.com/zortos293/lichii/blob/nx2/docs/user/ServerHosting.md

Starts the Eden lobby server in the background, maps UDP port 24872, and sets room settings including name, password, max members, and preferred game.

```bash
docker run -d --name eden-lobby --restart unless-stopped -p 24872:24872/udp ikuzen/yuzu-hdr-multiplayer-dedicated --room-name "My Eden Room" --password "MySecurePass2025" --max-members 8 --preferred-game "Mario Kart 8 Deluxe" --preferred-game-id "01000ABF0C84C000" --web-api-url "api.ynet-fun.xyz"
```

--------------------------------

### Copy nx2_switches.txt to build output

Source: https://github.com/zortos293/lichii/blob/nx2/src/yuzu/CMakeLists.txt

Adds a POST_BUILD custom command to copy the nx2_switches.txt file from the dist directory to the target output directory. The file is read at startup and a user copy in %APPDATA%\eden overrides it.

```cmake
add_custom_command(TARGET yuzu POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
        "${PROJECT_SOURCE_DIR}/dist/nx2_switches.txt" "$<TARGET_FILE_DIR:yuzu>/nx2_switches.txt"
    VERBATIM)
```

--------------------------------

### Scripted input: EDEN_NX2_KEY_SCRIPT

Source: https://github.com/zortos293/lichii/blob/nx2/NX2_NOTES.md

Sets a timed key script for scripted runs. The sequence uses time:value pairs (e.g., 50:4, 50.5:-4) to simulate inputs. Used to start a new game after moving title-4 saves to C:\dev\save_backups.

```bash
EDEN_NX2_KEY_SCRIPT="50:4,50.5:-4,55:79,55.4:-79,57:4,57.5:-4"
```

--------------------------------

### Install Dynarmic with CMake package config

Source: https://github.com/zortos293/lichii/blob/nx2/src/dynarmic/CMakeLists.txt

Installs the dynarmic target, exports it with the dynarmic:: namespace, generates and installs package config files, and installs headers when DYNARMIC_INSTALL is enabled.

```cmake
if (DYNARMIC_INSTALL)
    include(GNUInstallDirs)
    include(CMakePackageConfigHelpers)

    install(TARGETS dynarmic EXPORT dynarmicTargets)
    install(EXPORT dynarmicTargets
        NAMESPACE dynarmic::
        DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/dynarmic"
    )

    configure_package_config_file(CMakeModules/dynarmicConfig.cmake.in
        dynarmicConfig.cmake
        INSTALL_DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/dynarmic"
    )
    write_basic_package_version_file(dynarmicConfigVersion.cmake
        COMPATIBILITY SameMajorVersion
    )
    install(FILES
        "${CMAKE_CURRENT_BINARY_DIR}/dynarmicConfig.cmake"
        "${CMAKE_CURRENT_BINARY_DIR}/dynarmicConfigVersion.cmake"
        DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/dynarmic"
    )

    install(DIRECTORY src/dynarmic TYPE INCLUDE FILES_MATCHING PATTERN "*.h")
endif()
```

--------------------------------

### Run compatibility report tests with preview and screenshot options

Source: https://github.com/zortos293/lichii/blob/nx2/docs/compatibility-report.md

Runs the compatibility report test binary with a synthetic dialog using fake transport. The preview preloads synthetic experience text for visual inspection; the screenshot option uses offscreen platform. Do not submit synthetic fixtures to the live website.

```sh
build/compatibility-report/compatibility_report_tests --preview
QT_QPA_PLATFORM=offscreen build/compatibility-report/compatibility_report_tests \
  --screenshot /tmp/compatibility-report.png
```

--------------------------------

### Enable EDEN_DKB_INDIRECT_READBACK and launch eden.exe

Source: https://github.com/zortos293/lichii/blob/nx2/docs/bananza-diagnostics.md

Run in PowerShell for a second run focused on the black image. This copies actual GPU indirect arguments instead of potentially stale guest-memory copies. It adds render-pass breaks and transfer barriers, so use the first run for timing comparisons. If enabling readback changes the symptom, report that fact; the readback is diagnostic, not a rendering fix.

```powershell
$env:EDEN_DKB_INDIRECT_READBACK = "1"
& .\eden.exe
```

--------------------------------

### Run adapter with --call for single requests

Source: https://github.com/zortos293/lichii/blob/nx2/docs/nx2/debug-mcp.md

Uses native Windows Python to run the adapter. --call sends one request, prints JSON result, and saves PNG to --out. On failure prints {"error": ...} and exits with status 1.

```bash
PY=/c/Users/Zortos/AppData/Local/Programs/Python/Python314/python.exe
$PY -I C:/lx/src/tools/nx2/debug_mcp.py --server 127.0.0.1:6545 --call '{"method":"status"}'
$PY -I C:/lx/src/tools/nx2/debug_mcp.py --server 127.0.0.1:6545 \
    --call '{"method":"screenshot","params":{"height":1080}}' --out C:/lx/shot.png
$PY -I C:/lx/src/tools/nx2/debug_mcp.py --server 127.0.0.1:6545 \
    --call '{"method":"reject_shaders","params":{"hashes":["3ddfb1d7621c4755"]}}'
$PY -I C:/lx/src/tools/nx2/debug_mcp.py --server 127.0.0.1:6545 \
    --call '{"method":"input_sequence","params":{"steps":[{"right_stick":[1,0],"frames":60},{"frames":30}]}}'
```

--------------------------------

### Configure Eden build with CMake

Source: https://github.com/zortos293/lichii/blob/nx2/NX2_NOTES.md

Configures the Eden build using CMake with Ninja and MSVC. Uses a short intermediate directory strategy to avoid PDB path length issues (C1041). Disables Qt, web service, room, tests, Werror, and update checker.

```shell
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INTERMEDIATE_DIR_STRATEGY=SHORT -DENABLE_QT=OFF -DYUZU_CMD=ON -DENABLE_WEB_SERVICE=OFF -DYUZU_ROOM=OFF -DYUZU_TESTS=OFF -DENABLE_WERROR=OFF -DENABLE_UPDATE_CHECKER=OFF
```

--------------------------------

### Set Visual Studio startup project based on ENABLE_QT

Source: https://github.com/zortos293/lichii/blob/nx2/CMakeLists.txt

Sets the default startup project in Visual Studio to 'yuzu' when ENABLE_QT is enabled, otherwise 'yuzu-cmd'.

```cmake
if(ENABLE_QT)
    set_property(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTY VS_STARTUP_PROJECT yuzu)
else()
    set_property(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTY VS_STARTUP_PROJECT yuzu-cmd)
endif()
```

--------------------------------

### Run eden-cli with GDB stub

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Debug.md

Run the emulator with GDB stub enabled. Replace <path to your config file> and <path to game> with actual paths.

```bash
./build/bin/eden-cli -c <path to your config file (see logs where you run Eden normally to see where it is)> -d -g <path to game>
```

--------------------------------

### Build yuzu-cmd and tests

Source: https://github.com/zortos293/lichii/blob/nx2/docs/bananza-diagnostics.md

Builds the yuzu-cmd and tests targets in parallel using Ninja.

```sh
cmake --build build --target yuzu-cmd tests --parallel "$(nproc)"
```

--------------------------------

### macOS: Install additional MoltenVK dependencies

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs additional dependencies required to run with MoltenVK on macOS.

```sh
brew install molten-vk
```

--------------------------------

### Install dependencies on RedoxOS

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs required packages for building on RedoxOS. Note that SDL3 is not supported and must be compiled manually.

```sh
sudo pkg install git cmake ffmpeg6 zlib llvm18
```

--------------------------------

### Configure and build with Aftermath SDK enabled

Source: https://github.com/zortos293/lichii/blob/nx2/docs/STARFOX_AFTERMATH_DIAGNOSTIC.md

Sets the process-local NSIGHT_AFTERMATH_SDK environment variable, then creates and runs a modified configure script that changes the build directory to C:/lx/build-aftermath and adds -DENABLE_NSIGHT_AFTERMATH:BOOL=ON. Finally builds with cmake --build C:/lx/build-aftermath --parallel 12. Requires the SDK headers (include/GFSDK_Aftermath_GpuCrashDump.h) in the SDK directory; the ordinary Windows build does not define HAS_NSIGHT_AFTERMATH.

```sh
export NSIGHT_AFTERMATH_SDK='C:/lx/deps/nsight-aftermath-2026.3.0'
sed \
  -e 's@-B C:/lx/build @-B C:/lx/build-aftermath @' \
  -e 's@-DCMAKE_BUILD_TYPE=RelWithDebInfo@-DCMAKE_BUILD_TYPE=RelWithDebInfo -DENABLE_NSIGHT_AFTERMATH:BOOL=ON@' \
  C:/lx/configure.sh > C:/lx/configure-aftermath.sh
bash C:/lx/configure-aftermath.sh
cmake --build C:/lx/build-aftermath --parallel 12
```

--------------------------------

### Build and package a fix (build-fix.sh)

Source: https://github.com/zortos293/lichii/blob/nx2/AGENTS.md

One command to build and package a fix on the owner's PC. Arguments: <branch>, <build-name>, a quoted description like "<Game> - <fix>", optional environment variables ("ENV=VAL ..."), and an optional log filter.

```bash
bash C:/lx/build-fix.sh <branch> <build-name> "<Game> - <fix>" ["ENV=VAL ..."] ["log filter"]
```

--------------------------------

### macOS: Install dependencies with Homebrew

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required dependencies on macOS using Homebrew. For Intel Macs or Rosetta Homebrew, replace /opt/homebrew with /usr/local.

```sh
brew install autoconf automake boost ffmpeg fmt glslang hidapi libtool libusb lz4 ninja nlohmann-json openssl pkg-config qt@6 sdl3 speexdsp zlib zstd cmake Catch2 molten-vk vulkan-loader spirv-tools vulkan-utility-libraries
```

--------------------------------

### Deploy Qt DLLs and plugins for Windows

Source: https://github.com/zortos293/lichii/blob/nx2/src/yuzu/CMakeLists.txt

Copies Qt DLLs and plugins next to the executable on Windows when not using bundled Qt. Uses windeployqt, generating a qt.conf file and a POST_BUILD command. Warns if windeployqt is not found.

```cmake
if (WIN32 AND NOT YUZU_USE_BUNDLED_QT)
    # Copy the Qt DLLs and plugins next to the executable. WINDEPLOYQT_EXECUTABLE was never set, so
    # this step ran the emulator itself with windeployqt's arguments and failed every build that
    # uses an installed Qt (the Windows release workflow).
    if (TARGET Qt6::windeployqt)
        set(WINDEPLOYQT_EXECUTABLE "$<TARGET_FILE:Qt6::windeployqt>")
    else()
        find_program(WINDEPLOYQT_EXECUTABLE NAMES windeployqt6 windeployqt
                     HINTS "${QT_HOST_PATH}/bin" "${QT_TARGET_PATH}/bin")
    endif()
    file(GENERATE OUTPUT "$<TARGET_FILE_DIR:yuzu>/qt.conf"
         CONTENT "[Paths]\nPrefix=.\nPlugins=plugins\n")
    if (WINDEPLOYQT_EXECUTABLE)
        set(YUZU_EXE_DIR "$<TARGET_FILE_DIR:yuzu>")
        add_custom_command(TARGET yuzu POST_BUILD COMMAND ${WINDEPLOYQT_EXECUTABLE} "$<TARGET_FILE:yuzu>" --dir "${YUZU_EXE_DIR}" --libdir "${YUZU_EXE_DIR}" --plugindir "${YUZU_EXE_DIR}/plugins" --no-compiler-runtime --no-opengl-sw --no-system-d3d-compiler --no-translations --verbose 0)
    else()
        message(WARNING "windeployqt not found: copy the Qt DLLs next to the executable yourself")
    endif()
endif()
```

--------------------------------

### screenshot

Source: https://github.com/zortos293/lichii/blob/nx2/docs/nx2/debug-mcp.md

Requests a 16:9 layout and captures the presented framebuffers as a PNG image. The result is returned as MCP image content.

```APIDOC
## screenshot

### Description
Requests a 16:9 layout and captures the presented framebuffers as a PNG image. The result is returned as MCP image content.

### Parameters
#### Request Body
- `height` (number) - Optional - The height of the screenshot.
- `save` (boolean) - Optional - Whether to save the screenshot.
- `timeout_s` (number) - Optional - The timeout in seconds.

### Response
#### Success Response (200)
- `image` (image) - The PNG image content.

```

--------------------------------

### Alpine Linux: Enable community repo and install dependencies

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Enables the community repository and installs all required build dependencies for the project on Alpine Linux.

```sh
# Enable the community repository
setup-apkrepos -c
# Install
apk add g++ git cmake make mesa-dev qt6-qtbase-dev qt6-qtbase-private-dev libquazip1-qt6 ffmpeg-dev qt6-charts-dev libusb-dev libtool boost-dev sdl3-dev zstd-dev vulkan-utility-libraries spirv-tools-dev openssl-dev nlohmann-json lz4-dev opus-dev jq patch
```

--------------------------------

### Configure headless build with CMake

Source: https://github.com/zortos293/lichii/blob/nx2/docs/bananza-diagnostics.md

Use CMake 3.31 or newer and a Clang version that accepts -mtls-dialect=gnu2. The cloud check uses Clang 20 because Ubuntu's Clang 18 rejects that flag. ENABLE_WERROR=OFF is required for pre-existing Clang warnings in the audio tests.

```sh
cmake -S . -B build -G Ninja \
  -DCMAKE_C_COMPILER=clang-20 -DCMAKE_CXX_COMPILER=clang++-20 \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo -DENABLE_QT=OFF \
  -DYUZU_CMD=ON -DYUZU_TESTS=ON -DENABLE_LTO=OFF \
  -DENABLE_WEB_SERVICE=OFF -DUSE_DISCORD_PRESENCE=OFF -DENABLE_WERROR=OFF
```

--------------------------------

### OpenIndiana: Create cc wrapper for dependencies

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Caveats.md

Creates a local `cc` wrapper that calls `gcc` and adds it to PATH. Needed for some dependencies that call cc directly (e.g., tz).

```sh
echo '#!/bin/sh -e' >cc
echo 'gcc $@' >>cc
chmod +x cc
export PATH="$PATH:$PWD"
```

--------------------------------

### Install dependencies on Fedora

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Installs all required packages on Fedora. Requires Fedora 32 or later. For Fedora 36+ with GCC 12, configure CMake with clang as described.

```sh
sudo dnf install autoconf cmake fmt-devel gcc{,-c++} glslang hidapi-devel json-devel libtool libusb1-devel libzstd-devel lz4-devel nasm ninja-build openssl-devel pulseaudio-libs-devel qt6-linguist qt6-qtbase{-private,}-devel qt6-qtwebengine-devel qt6-qtmultimedia-devel qt6-charts-devel speexdsp-devel wayland-devel zlib-devel ffmpeg-devel libXext-devel boost jq
```

--------------------------------

### Create eden.sh launcher script for EmuDeck

Source: https://github.com/zortos293/lichii/blob/nx2/docs/user/SteamROM.md

Paste this shell script into the eden.sh file created in the EmuDeck tools/launchers directory. It initializes the emulator, finds the Eden AppImage, makes it executable, launches it, and performs cloud sync cleanup.

```bash
#!/bin/sh -e
emuName="eden" #parameterize me

. "$HOME/.config/EmuDeck/backend/functions/all.sh"
emulatorInit "$emuName"

# find full path to emulator appimage
appimage=$(find "$emusFolder" -iname "${emuName}*.AppImage" -print -quit 2>/dev/null)

# make sure the appimage is executable
	chmod +x "$appimage"
	set -- "$appimage" "$@"

echo "Launching ${emuName} with:" "$@"
"$@"

cloud_sync_uploadForced
rm -rf "$savesPath/.gaming"
```

--------------------------------

### Replay failed compute pipeline with shader-sweep

Source: https://github.com/zortos293/lichii/blob/nx2/docs/kirby-white-world.md

Set EDEN_NX2_SHADER_DUMP to a writable directory and EDEN_NX2_RENDER_TRACE=1, then use log filter '*:Info HW.GPU:Debug Render.Vulkan:Debug Shader:Debug'. Replay the failed compute environment with this command.

```sh
build/shader-sweep/shader-sweep \
  --environment failed-compute-1175573eed7481a4-v49.env --cache-version 49 \
  --output shader.spv
```

--------------------------------

### Set EDEN_DKB_FRAME_TRACE and launch eden.exe

Source: https://github.com/zortos293/lichii/blob/nx2/docs/bananza-diagnostics.md

Run in PowerShell to enable frame tracing and disable indirect readback before launching the diagnostic executable. Restart the emulator after setting environment variables and launch from the same shell. Use the executable's actual filename if it differs.

```powershell
$env:EDEN_DKB_FRAME_TRACE = "1"
Remove-Item Env:EDEN_DKB_INDIRECT_READBACK -ErrorAction SilentlyContinue
& .\eden.exe
```

--------------------------------

### ES-DE es_systems.xml command for Eden (Standalone)

Source: https://github.com/zortos293/lichii/blob/nx2/docs/user/ThirdParty.md

Add this command line to es_systems.xml under the switch system entries to launch Eden as a standalone emulator from ES-DE.

```xml
<command label="Eden (Standalone)">%EMULATOR_EDEN% %ACTION%=android.nfc.action.TECH_DISCOVERED %DATA%=%ROMPROVIDER%</command>
```

--------------------------------

### Alias qemu-aarch64 with sysroot

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Create an alias for qemu-aarch64 to use the cross-emerged sysroot at /usr/aarch64-unknown-linux-gnu.

```sh
alias qemu-aarch64="qemu-aarch64 -L /usr/aarch64-unknown-linux-gnu"
```

--------------------------------

### Update package list on RedoxOS

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Deps.md

Updates the package list on RedoxOS using pkg. Required before installing dependencies.

```sh
sudo pkg update
```

--------------------------------

### Add domains to Zapret list-general.txt

Source: https://github.com/zortos293/lichii/blob/nx2/docs/user/Multiplayer.md

Add these domains to lists/list-general.txt to bypass ISP blocking.

```plaintext
api.ynet-fun.xyz
ynet-fun.xyz
```

--------------------------------

### Build and test commands for verification

Source: https://github.com/zortos293/lichii/blob/nx2/docs/VideoPlaybackUpstreamAudit.md

Commands to configure, build, and run tests for the port. Uses clang 20 because clang 18 rejects the existing -mtls-dialect=gnu2 flag. The focused H.264 and mapping selection runs eight cases and 1,089 assertions.

```sh
cmake -S . -B build -G Ninja \
  -DCMAKE_C_COMPILER=clang-20 -DCMAKE_CXX_COMPILER=clang++-20 \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DENABLE_QT=OFF -DYUZU_CMD=ON -DYUZU_TESTS=ON -DENABLE_WERROR=OFF
cmake --build build --parallel "$(nproc)"
ctest --test-dir build --output-on-failure -V
build/bin/tests '[h264],[nx2_mapping]'
```

--------------------------------

### AddDependentPackages CMake command

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CPMUtil.md

CMake command to declare dependent packages. Takes a list of JSON package keys that must all be installed or all bundled.

```cmake
AddDependentPackages(vulkan-headers vulkan-utility-libraries)
```

--------------------------------

### Get system thread count

Source: https://github.com/zortos293/lichii/blob/nx2/externals/ffmpeg/CMakeLists.txt

Runs nproc to determine the number of system threads for parallel make.

```cmake
execute_process(
    COMMAND
        nproc
    OUTPUT_VARIABLE
        SYSTEM_THREADS)
```

--------------------------------

### Create ZFS dataset with zstd compression

Source: https://github.com/zortos293/lichii/blob/nx2/docs/user/Storage.md

Creates a ZFS dataset named zroot/switch and enables zstd compression. The dataset is then available at /zroot/switch and can be added as a game directory. Ensure proper permissions with chmod 755 /zroot/switch/*.

```sh
sudo zfs create zroot/switch`
sudo zfs set compression=zstd zroot/switch
```

--------------------------------

### Enable RenderDoc capture on Windows PowerShell

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Debug.md

Sets the ENABLE_VULKAN_RENDERDOC_CAPTURE environment variable to '1' and launches eden.exe so RenderDoc can attach before the Vulkan device is created. The default Windows capture folder is %LOCALAPPDATA%\Temp\RenderDoc.

```powershell
$env:ENABLE_VULKAN_RENDERDOC_CAPTURE='1'
.\eden.exe
```

--------------------------------

### Configure CMake for cross-compilation

Source: https://github.com/zortos293/lichii/blob/nx2/docs/CrossCompile.md

Configure the project with CMake using the Gentoo cross toolchain file, setting CROSS_TARGET and disabling OpenGL.

```sh
cmake -S . -B build/aarch64 -DCMAKE_TOOLCHAIN_FILE=CMakeModules/toolchains/GentooCross.cmake -GNinja -DCROSS_TARGET=aarch64 -DENABLE_OPENGL=OFF
```

--------------------------------

### Add license headers with amend commit

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Development.md

Alternative to the push workflow: run the script without -c and amend the last commit. Requires fetching the master branch first.

```sh
git fetch origin master:master
.ci/license-header.sh
git commit --amend -a --no-edit
```

--------------------------------

### Build Eglantine with CMake and Ninja

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Build.md

Configure and build Eglantine in Release mode using CMake with the Ninja generator. Requires a development environment with dependencies installed.

```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -G Ninja
cmake --build build
```

--------------------------------

### Build glslang on OmniOS

Source: https://github.com/zortos293/lichii/blob/nx2/docs/Caveats.md

Required on OmniOS because dependencies are missing. Do not use `-t glslang`; it causes installation to fail. Use `--parallel` with caution due to a CMake bug on OmniOS.

```sh
sudo pkg install python-313
git clone --depth=1 https://github.com/KhronosGroup/glslang.git
cd glslang
python3.13 ./update_glslang_sources.py
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -- -j `nproc`
cmake --install build
```

--------------------------------

### Manage the Docker container

Source: https://github.com/zortos293/lichii/blob/nx2/docs/user/ServerHosting.md

Stop, start, or remove the Eden lobby container. To change the lobby name, stop and remove the container, then rerun the updated run command.

```bash
docker stop eden-lobby
```

```bash
docker start eden-lobby
```

```bash
docker rm -f eden-lobby
```
Tokens:
Raw