Include NVIDIA's pinned DLSS library for Linux in the AppImage, and place it beside the built game.

On Linux the game looks for libnvidia-ngx-dlss.so.<version> beside the executable, and the driver brings
only NGX's core, so the DLSS modes did nothing in every Linux build. tools/dlss_pin.py pins the Linux
library of the DLSS version it pins for Windows, with its own size and SHA-256; tools/make_appimage.py
puts it in the kit's bin/ with its notice (downloaded from NVIDIA's DLSS SDK repository and checked, or
--dlss; --no-dlss leaves it out), and tools/make_game.py copies it beside the game on Linux as it copies
the DLL on Windows, keeping a library the player put there.

Pull request #297 by mooki000, taken as it is; the builder's description is merged with the button art
option that came with the release workflow. On Windows place_dlss does what it did. No NVIDIA file is in
the repository.

tests/launcher_test.py passes with its two new tests (112 tests, Python 3.12 on Windows); the AppImage
was not built here.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
chrg6
2026-11-10 06:38:02 -05:00
parent ff4b6772f9
commit 32ee021905
6 changed files with 219 additions and 43 deletions

View File

@@ -1,12 +1,15 @@
"""NVIDIA's DLSS library (nvngx_dlss.dll) for the releases: tools/make_launcher.py and tools/make_kit.py put it in the
release's bin/ beside AMD's FSR 3.1 library, and tools/make_game.py copies it beside the game, where NGX loads it
(runtime/vk_dlaa.c). Without it DLSS runs only where the NVIDIA driver supplies the model itself.
"""NVIDIA's DLSS library for the releases: nvngx_dlss.dll for Windows, libnvidia-ngx-dlss.so.<version> for Linux.
tools/make_launcher.py and tools/make_kit.py put the DLL in the release's bin/ beside AMD's FSR 3.1 library,
tools/make_appimage.py puts the Linux library in the AppImage's kit bin/, and tools/make_game.py copies either beside
the game, where NGX loads it (runtime/vk_dlaa.c). Without it DLSS runs only where the NVIDIA driver supplies the model
itself (Windows), and on Linux not at all (runtime/resolution.c dlss_dll).
The file is NVIDIA's own build from the DLSS SDK repository at a pinned tag, unmodified and checked against its size
and SHA-256. NVIDIA's RTX SDKs License lets an application ship it in object form; the notice written beside it names
the version and the licence that covers it.
the version and the licence that covers it. Both platforms' files are published under the one licence file of that tag.
"""
from pathlib import Path
from typing import NamedTuple
NAME = 'nvngx_dlss.dll'
NOTICE = 'nvngx_dlss-NOTICE.txt' # beside the DLL; make_game.py reads its sha256 line
@@ -14,18 +17,41 @@ VERSION = '310.9.1'
URL = f'https://raw.githubusercontent.com/NVIDIA/DLSS/v{VERSION}/lib/Windows_x86_64/rel/{NAME}'
SIZE = 58956912
SHA256 = '3975567b8943c53acce397f2b72380092f84f162d00b0d2c7d08a1025c563983'
# The Linux library of the same release. Its name ends in the DLSS version; NGX finds it by that name beside the
# executable (runtime/resolution.c dlss_dll looks for the prefix).
LINUX_NAME = f'libnvidia-ngx-dlss.so.{VERSION}'
LINUX_NOTICE = 'libnvidia-ngx-dlss-NOTICE.txt' # beside the library; make_game.py reads its sha256 line
LINUX_URL = f'https://raw.githubusercontent.com/NVIDIA/DLSS/v{VERSION}/lib/Linux_x86_64/rel/{LINUX_NAME}'
LINUX_SIZE = 59481944
LINUX_SHA256 = '7561f16cab74e2b7ccf791bf44bb9cc43abb44bcf78f33c5663520ad4e857e02'
LICENSE_URL = f'https://github.com/NVIDIA/DLSS/blob/v{VERSION}/LICENSE.txt'
def notice_text():
return (f'{NAME} is NVIDIA DLSS {VERSION}, unmodified, as published in NVIDIA\'s DLSS SDK\n'
class Pin(NamedTuple):
name: str
notice: str
url: str
size: int
sha256: str
def pin(linux=False):
"""The pinned file of a platform."""
if linux:
return Pin(LINUX_NAME, LINUX_NOTICE, LINUX_URL, LINUX_SIZE, LINUX_SHA256)
return Pin(NAME, NOTICE, URL, SIZE, SHA256)
def notice_text(linux=False):
p = pin(linux)
return (f'{p.name} is NVIDIA DLSS {VERSION}, unmodified, as published in NVIDIA\'s DLSS SDK\n'
f'(https://github.com/NVIDIA/DLSS, tag v{VERSION}). Copyright NVIDIA Corporation.\n'
'\n'
'It is not part of NX2navi and NX2navi\'s licence does not cover it. It is distributed under the\n'
f'NVIDIA RTX SDKs License, and its use is subject to that licence: {LICENSE_URL}\n'
'NVIDIA licenses DLSS only for use on systems with NVIDIA GPUs.\n'
'\n'
f'sha256 {SHA256}\n')
f'sha256 {p.sha256}\n')
def sha256_file(path):
@@ -37,30 +63,31 @@ def sha256_file(path):
return h.hexdigest()
def resolve(local, cache_dir):
"""The pinned DLL: local when given (it must be the pinned file), else the copy in cache_dir, downloaded when
missing (launcher/net.py: resumed, checked against the size and SHA-256)."""
def resolve(local, cache_dir, linux=False):
"""The pinned library: local when given (it must be the pinned file), else the copy in cache_dir, downloaded when
missing (launcher/net.py: resumed, checked against the size and SHA-256). linux: the Linux library, else the DLL."""
p = pin(linux)
if local:
local = Path(local)
if not local.is_file():
raise SystemExit(f'{local} does not exist')
if local.stat().st_size != SIZE or sha256_file(local) != SHA256:
if local.stat().st_size != p.size or sha256_file(local) != p.sha256:
raise SystemExit(f'{local} is not NVIDIA DLSS {VERSION} (size or SHA-256 differ); a newer DLSS needs '
'VERSION, SIZE and SHA256 in tools/dlss_pin.py changed first')
return local
import sys
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from launcher import net
dest = Path(cache_dir) / f'nvngx_dlss-{VERSION}.dll'
if not (dest.is_file() and sha256_file(dest) == SHA256):
print(f'download {URL}', flush=True)
net.download(URL, dest, sha256=SHA256, size=SIZE)
dest = Path(cache_dir) / (p.name if linux else f'nvngx_dlss-{VERSION}.dll')
if not (dest.is_file() and sha256_file(dest) == p.sha256):
print(f'download {p.url}', flush=True)
net.download(p.url, dest, sha256=p.sha256, size=p.size)
return dest
def place(src, bin_dir):
"""The DLL and its notice into a release's bin/."""
def place(src, bin_dir, linux=False):
"""The library and its notice into a release's or the kit's bin/."""
import shutil
bin_dir = Path(bin_dir)
shutil.copy2(src, bin_dir / NAME)
(bin_dir / NOTICE).write_text(notice_text(), encoding='utf-8')
p, bin_dir = pin(linux), Path(bin_dir)
shutil.copy2(src, bin_dir / p.name)
(bin_dir / p.notice).write_text(notice_text(linux), encoding='utf-8')

View File

@@ -2,15 +2,17 @@
player's PC from their own dump with tools/make_game.py, as NX2navi-Setup.exe does on Windows.
python3 tools/make_appimage.py --python <standalone CPython 3.14> --appimagetool <appimagetool> [--out dist]
[--dlss libnvidia-ngx-dlss.so.<version> | --no-dlss]
The AppImage holds no game files: the kit's tools/, recomp/, runtime/ and docs, the shader translator built by
tools/build_xlate.py (bin/nx2navi_xlate), the pinned Vulkan Memory Allocator header, and a relocatable CPython 3.14
(python-build-standalone, as `uv python install 3.14` puts in ~/.local/share/uv/python) with numpy, lz4, zstandard,
fonttools and pillow, and with --prompt-art the button art make_game.py's prompts step draws from (as make_kit.py
--prompt-art: the pictures tools/prompt_art.py art_files names, into the kit's prompt-art folder; without it that step
is skipped and the game keeps the Switch prompts). zbic, the GPL package that unpacks the game's program files, is not
bundled: the AppImage installs it with pip into ~/.local/share/nx2navi/pydeps the first time it runs, as the Windows
launcher downloads it.
tools/build_xlate.py (bin/nx2navi_xlate), NVIDIA's DLSS library with its notice (bin/, tools/dlss_pin.py: downloaded
from NVIDIA's DLSS SDK repository and checked, or --dlss; not with --no-dlss), the pinned Vulkan Memory Allocator
header, and a relocatable CPython 3.14 (python-build-standalone, as `uv python install 3.14` puts in
~/.local/share/uv/python) with numpy, lz4, zstandard, fonttools and pillow, and with --prompt-art the button art
make_game.py's prompts step draws from (as make_kit.py --prompt-art: the pictures tools/prompt_art.py art_files names,
into the kit's prompt-art folder; without it that step is skipped and the game keeps the Switch prompts). zbic, the GPL
package that unpacks the game's program files, is not bundled: the AppImage installs it with pip into
~/.local/share/nx2navi/pydeps the first time it runs, as the Windows launcher downloads it.
The compiler and the libraries come from the system (README-BuildKit.md, "Linux"): the AppImage checks for clang,
clang++, lld and the headers before it starts, and names the packages for Arch, Fedora and Debian/Ubuntu.
@@ -134,6 +136,9 @@ def main():
ap.add_argument('--python', type=Path, required=True,
help='a relocatable CPython 3.14 folder (python-build-standalone, ~/.local/share/uv/python/cpython-3.14*)')
ap.add_argument('--appimagetool', type=Path, required=True, help='appimagetool-x86_64.AppImage')
ap.add_argument('--dlss', type=Path, help="NVIDIA's libnvidia-ngx-dlss.so.<version> from disk instead of "
"downloading it from NVIDIA's DLSS SDK repository")
ap.add_argument('--no-dlss', action='store_true', help='leave NVIDIA DLSS out of the AppImage')
ap.add_argument('--out', type=Path, default=ROOT / 'dist', help='where the AppImage goes (default dist/)')
ap.add_argument('--prompt-art', type=Path, nargs='+', metavar='FOLDER',
help='folders holding XGamepad, P5Gamepad and Keyboard_Mouse (or those folders): the button art, as '
@@ -146,12 +151,14 @@ def main():
a.python / 'bin' / 'python3'):
if not need.exists():
sys.exit(f'{need} is missing (tools/build_xlate.py builds the translator; tools/build_game.py fetches VMA)')
sys.path.insert(0, str(ROOT / 'tools'))
import dlss_pin
dlss = None if a.no_dlss else dlss_pin.resolve(a.dlss, ROOT / 'build' / 'dl', linux=True)
app = ROOT / 'build' / 'appimage' / 'NX2navi.AppDir'
shutil.rmtree(app, ignore_errors=True)
kit = app / 'usr' / 'kit'
kit.mkdir(parents=True)
sys.path.insert(0, str(ROOT / 'tools'))
import build_shaders
build_shaders.build(ROOT / 'runtime') # the image carries the runtime's shaders compiled (runtime/*_spv.h)
for d in KIT_DIRS:
@@ -164,6 +171,8 @@ def main():
(kit / 'bin').mkdir()
for f in ('nx2navi_xlate', 'nx2navi_xlate.id'):
shutil.copy2(xlate / f, kit / 'bin' / f)
if dlss: # DLSS: NGX loads it from beside the game (runtime/vk_dlaa.c); make_game.py copies it there
dlss_pin.place(dlss, kit / 'bin', linux=True)
(kit / 'toolchain' / 'vma').mkdir(parents=True)
shutil.copy2(ROOT / 'toolchain' / 'vma' / 'vk_mem_alloc.h', kit / 'toolchain' / 'vma' / 'vk_mem_alloc.h')
if a.prompt_art:

View File

@@ -554,6 +554,9 @@ def copy_if_changed(src, dst):
DLSS_DLL, DLSS_NOTICE = 'nvngx_dlss.dll', 'nvngx_dlss-NOTICE.txt' # tools/dlss_pin.py, in the kit's bin/
# The Linux library's name ends in the DLSS version (tools/dlss_pin.py): it is found by its prefix, as the runtime
# finds it beside the game (runtime/resolution.c dlss_dll).
DLSS_SO_PREFIX, DLSS_SO_NOTICE = 'libnvidia-ngx-dlss.so.', 'libnvidia-ngx-dlss-NOTICE.txt'
# DLSS Frame Generation (runtime/vk_dlssg.c) loads these from beside the game: nx2navi_dlssg.dll (runtime/dlssg/,
# tools/build_dlssg.py), NVIDIA Streamline's interposer and the plugins it uses, and NGX's frame generation library.
# A release carries them with their licence texts in bin/dlssg/ (tools/make_launcher.py --dlssg); without the whole set
@@ -564,7 +567,7 @@ DLSSG_FILES = ('nx2navi_dlssg.dll', 'sl.interposer.dll', 'sl.common.dll', 'sl.dl
def notice_sha256(path):
"""The sha256 line of a DLSS notice: the DLL a kit placed beside the game."""
"""The sha256 line of a DLSS notice: the library a kit placed beside the game."""
try:
for line in path.read_text(encoding='utf-8').splitlines():
if line.startswith('sha256 '):
@@ -574,22 +577,35 @@ def notice_sha256(path):
return None
def place_dlss(out):
def dlss_files(folder, linux):
"""The DLSS libraries in folder, by name: nvngx_dlss.dll, or on Linux every libnvidia-ngx-dlss.so.<version>."""
return sorted(p for p in folder.glob(DLSS_SO_PREFIX + '*' if linux else DLSS_DLL) if p.is_file())
def place_dlss(out, linux=False):
"""NVIDIA's DLSS library from the kit's bin/ beside the game, where NGX loads it (runtime/vk_dlaa.c), with its
notice. A different nvngx_dlss.dll the player put there (another DLSS version) is kept; the one an earlier build
placed, named by the notice beside it, is replaced. Returns a line for the build's log when it kept the player's."""
src, dst, note = KIT / 'bin' / DLSS_DLL, out / DLSS_DLL, KIT / 'bin' / DLSS_NOTICE
if not src.is_file():
notice. A different library the player put there (another DLSS version) is kept; the one an earlier build placed,
named by the notice beside it, is replaced. linux: the Linux library, whose name carries the DLSS version, so a
kit with another version replaces the earlier build's file under its old name. Returns a line for the build's
log when it kept the player's."""
note_name = DLSS_SO_NOTICE if linux else DLSS_NOTICE
srcs, note = dlss_files(KIT / 'bin', linux), KIT / 'bin' / note_name
if not srcs:
return None
if dst.is_file():
src = srcs[-1]
beside = dlss_files(out, linux)
for dst in beside:
s, d = os.stat(src), os.stat(dst)
if d.st_size != s.st_size or int(d.st_mtime) != int(s.st_mtime):
if dst.name != src.name or d.st_size != s.st_size or int(d.st_mtime) != int(s.st_mtime):
have = sha256_file(dst)
if have != notice_sha256(out / DLSS_NOTICE) and have != sha256_file(src):
return f"{DLSS_DLL} kept: the one already beside the game is not the kit's (another DLSS version)"
copy_if_changed(src, dst)
if note.is_file() and (not (out / DLSS_NOTICE).is_file() or (out / DLSS_NOTICE).read_bytes() != note.read_bytes()):
shutil.copy2(note, out / DLSS_NOTICE) # by content: two versions' notices can share size and second
if have != notice_sha256(out / note_name) and have != sha256_file(src):
return f"{dst.name} kept: the one already beside the game is not the kit's (another DLSS version)"
copy_if_changed(src, out / src.name)
for dst in beside:
if not dst.samefile(out / src.name): # another version's library, placed by an earlier build: replaced
dst.unlink()
if note.is_file() and (not (out / note_name).is_file() or (out / note_name).read_bytes() != note.read_bytes()):
shutil.copy2(note, out / note_name) # by content: two versions' notices can share size and second
return None
@@ -1331,7 +1347,7 @@ def step_compile(out, cache_dir, msys, jobs, romfs_job=None, update=False):
copy_if_changed(xlate / name, out / name)
if (KIT / 'bin' / 'amd_fidelityfx_vk.dll').is_file(): # FSR 3.1 (runtime/vk_ffx.cpp)
copy_if_changed(KIT / 'bin' / 'amd_fidelityfx_vk.dll', out / 'amd_fidelityfx_vk.dll')
kept = place_dlss(out) if WIN else None # NVIDIA DLSS (runtime/vk_dlaa.c): its library is a Windows DLL
kept = place_dlss(out, linux=not WIN) # NVIDIA DLSS (runtime/vk_dlaa.c): this platform's library from the kit
if kept:
say(f' {kept}')
if WIN and place_dlssg(out): # DLSS Frame Generation (runtime/vk_dlssg.c): Windows DLLs too