Skip to content

linux.md

Latest commit

 

History

History
130 lines (105 loc) · 9.22 KB

linux.md

File metadata and controls

130 lines (105 loc) · 9.22 KB
Raw

LAS Recomp on Linux (x86-64, aarch64)

Status: builds and runs the game on Vulkan (with your own game files) on x86-64, checked before each release by make smoketest. aarch64 is experimental: cross-compiled, its start screen checked under emulation, the game itself untested on real hardware - community reports decide (see the end). make appimage / make appimages package the release AppImages.

Running the AppImage

chmod +x LAS.Recomp-<version>-linux-x86_64.AppImage
./LAS.Recomp-<version>-linux-x86_64.AppImage

Needs: a distribution with glibc 2.35 or newer (Ubuntu 22.04, Debian 12, Fedora 36, Arch, ...), a Vulkan 1.3 driver (Mesa RADV / ANV / NVK / Turnip / Asahi Honeykrisp, or NVIDIA's), and on x86-64 a CPU with AVX2 (2013 or newer). On Linux 6.7 or newer the renderer also gets page write tracking (userfaultfd + PAGEMAP_SCAN, as Windows' write watch): its vertex cache, and textures re-checked only where the game wrote. Older kernels run without it (the log says [plat] no page write tracking: ...); LARECOMP_WRITE_TRACKING=0 turns it off. The start screen asks for the folder with your own game files and sets them up.

Everything the app writes lives in ~/.local/share/lasrecomp ($XDG_DATA_HOME/lasrecomp): game files (extracted/), saves, seeds, settings (larecomp.ini), shader caches, imported fonts. Started without a terminal the log is ~/.local/share/lasrecomp/lasrecomp.log, always the latest run; up to five recent runs are kept as lasrecomp-backup-*.log (from a terminal it prints there instead). LARECOMP_DATA_ROOT=<dir> uses another folder.

Controllers work as on the other systems (SDL3's gamepad support, bundled): Xbox, PlayStation (DualShock 4, DualSense), Switch Pro / Joy-Con, 8BitDo and other pads through the kernel's drivers, plugged in or paired while the game runs; the button prompts follow the controller. For SDL's own drivers (rumble, LEDs and gyro on PlayStation / Switch pads) the user needs access to /dev/hidraw*, which most distributions give with Steam's udev rules (steam-devices, or Steam installed); without them the controller still works through the kernel driver. Started from Steam with Steam Input on, the game sees Steam's virtual Xbox controller (Xbox prompts).

If the AppImage won't start with a FUSE error, install your distribution's fuse3 package, or run it with APPIMAGE_EXTRACT_AND_RUN=1. On a Steam Deck, put APPIMAGE_EXTRACT_AND_RUN=1 %command% in the game's launch options.

Building from source

Ubuntu / Debian packages (other distributions: the same libraries under their names). SDL3 must be 3.4 or newer (LAS Recomp loads and saves PNGs through it); where the distribution ships an older one (Debian 13 has 3.2), build SDL3 3.4 from source first - tools/linux/build_deps.sh builds the pinned version the AppImage uses (into build/linux/<arch>/deps).

sudo apt install clang lld make pkg-config python3-venv libsdl3-dev libavformat-dev libavcodec-dev \
    libavutil-dev libswscale-dev libvulkan-dev libshaderc-dev libvulkan-memory-allocator-dev glslc vulkan-tools

shaderc is linked the way its pkg-config file says (libshaderc_shared on Arch, Fedora, AOSC...); to choose yourself: make SHADERC=-lshaderc_shared (or -lshaderc).

Then from the repo root:

python3 -m venv tools/venv && tools/venv/bin/pip install lz4 capstone unicorn
make -j         # the start screen only (no game code yet): set up the game files there, or put extracted/ here
make gen        # once: recompile the game from your own game files
make -j         # -> build/lasrecomp and the game code library build/lasgame.so

Run ./build/lasrecomp from the repo root: with extracted/ in the starting folder it uses that folder for everything (dev mode) instead of ~/.local/share/lasrecomp.

ARCH picks the target, separately from the OS: the generated code differs per arch (aarch64 runs the guest's FP/SIMD as inline asm, like Apple Silicon; x86-64 lowers it to C with -march=x86-64-v3, like Windows). make gen passes the matching --simd. A cross build (ARCH=aarch64 on an x86-64 machine, SYSROOT=<arm64 root filesystem>) keeps its own generated-aarch64/ and build/aarch64/. Distributions that name shaderc's library libshaderc_shared.so need SHADERC=-lshaderc_shared.

The randomizer from a source checkout uses LAS-Randomizer's own venv (Python 3.12):

python3.12 -m venv third_party/LAS-Randomizer/venv
third_party/LAS-Randomizer/venv/bin/pip install -r third_party/LAS-Randomizer/requirements.txt

AppImages

Needs podman, and for the other arch's AppImage QEMU user emulation with binfmt (sudo apt install podman qemu-user qemu-user-binfmt).

make appimage                # this machine's arch -> build/dist/LAS Recomp-<version>-linux-<arch>.AppImage
make appimage ARCH=aarch64   # on x86-64: cross-compiled
make appimages               # both

Everything is built in Ubuntu 22.04 containers (tools/linux/Containerfile), so the result runs on glibc 2.35+: SDL3, an LGPL-only FFmpeg (only the movie codecs, as on Windows / macOS), and shaderc from pinned sources (tools/linux/build_deps.sh), then the game against them (tools/linux/package.sh). This machine's arch is built natively in one container of that arch (the release does both archs that way, on an arm64 runner for aarch64). aarch64 on an x86-64 machine is cross-compiled in the amd64 container against the arm64 image's root filesystem (build/linux/aarch64/sysroot), with only the seed generator helper (tools/linux/rando_helper.sh, PyInstaller builds for the machine it runs on) frozen in the arm64 container under QEMU, where pip also builds oead and keystone-engine from source the first time (no arm64 wheels on PyPI; cached in build/linux/aarch64/wheels). The generated game code comes from the host (generated/, generated-aarch64/; make appimage runs make gen for it when missing).

Release check of the x86-64 AppImage (make smoketest, tools/linux/smoketest.sh, ~7 minutes on this kind of machine): three launches of the AppImage itself - the start screen; a session from a test save warping to four overworld spots and every dungeon's entrance; and a seed generated from the in-game Randomizer tab, switched to live, the save loaded on it, then deleted. Each step is checked in the log and by a screenshot. build/smoke/report.txt ends with READY FOR RELEASE or NOT READY; build/smoke/sheet.png shows every screenshot. It needs extracted/ in the checkout and a test save outside git (~/.local/share/lasrecomp-smoketest/save, or LARECOMP_SMOKE_SAVE): copy save/ from any build after starting a new game once.

The AppImage holds lasrecomp, rando-gen/, the start screen font and the bundled libraries (SDL3, FFmpeg, shaderc). Not bundled: glibc, libstdc++, the Vulkan loader and the GPU drivers (always the system's). No game files or fonts.

Differences from macOS / Windows

  • Platform layer runtime/platform/linux.c: like macOS, the guest window (0x70_0000_0000..0x73_2000_0000) is one read/write mapping (MAP_NORESERVE), crashes are caught with sigaction on an alternate stack.
  • The HLE / service / reset tables are ELF sections found through the linker's __start_ / __stop_ symbols.
  • Renderer: the Windows Vulkan backend unchanged.
  • Without the user's Switch fonts the game text uses the bundled BIZ UDPGothic (third_party/fonts/BIZUDPGothic), sized like the console's font, where macOS / Windows use Hiragino / Yu Gothic; the in-game menu and button letters use DejaVu Sans, the system's or the bundled copy (third_party/fonts/DejaVu). TrueType is required; the game's font engine can't use CFF fonts such as Noto Sans CJK.
  • Pages: 4K and 16K kernels (Asahi) work; 64K-page kernels (some ARM servers) are not supported.

Testing on ARM (aarch64): what to report

The aarch64 AppImage is experimental: built on x86-64, only its start screen has run (emulated): reports from real hardware (Asahi Linux, Snapdragon laptops, Raspberry Pi 5 and other boards) are what tells whether it works. Please include:

  1. Distribution and kernel: cat /etc/os-release | head -3; uname -r; getconf PAGESIZE

  2. GPU and Vulkan driver: vulkaninfo --summary (package vulkan-tools); at least the devices section with deviceName, driverName and driverInfo.

  3. What happened: start screen? extraction? in game? where it stopped, any visual problems (screenshots help). With a controller: its model, and whether it works (the log names it: [input] gamepad: ...).

  4. The log: ~/.local/share/lasrecomp/lasrecomp.log (or the terminal output when started from a terminal). A crash writes *** signal ... and a backtrace there; attach the whole file (or if the problem was in an earlier run, that run's lasrecomp-backup-*.log, by date modified).

  5. A crash backtrace with gdb when the log's isn't enough:

    ./LAS.Recomp-<version>-linux-aarch64.AppImage --appimage-extract    # -> squashfs-root/
cd ~/.local/share/lasrecomp
gdb -batch -ex 'handle SIGSEGV nostop noprint pass' -ex run -ex 'thread apply all bt 20' \
    --args ~/squashfs-root/usr/bin/lasrecomp > gdb.txt 2>&1

    (Adjust the squashfs-root path to where you extracted it. The game itself uses SIGSEGV for memory watches, hence the handle line; a real crash still ends in the backtrace. Attach gdb.txt.)