Integration of desktop related Minecraft mods into GTNH
  • Java 93.5%
  • Shell 5%
  • Python 1.5%
Find a file
lordtet 76448c927e
Some checks failed
Build / build (push) Failing after 1m1s
Document the rolling release as the PoC-phase choice
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 00:19:28 -05:00
.forgejo/workflows CI: version builds from git describe without the rolling tag 2026-11-16 21:14:05 -05:00
buildSrc Harness fixes, documentation updates. 2026-11-15 22:07:05 -05:00
docs Document the rolling release as the PoC-phase choice 2026-11-17 00:19:28 -05:00
gradle Init commit with gtnh template 2026-11-15 21:53:06 -05:00
gtnhShared Init commit with gtnh template 2026-11-15 21:53:06 -05:00
lwjgl3-bridge Rename the mod to DesktopNH 2026-11-16 19:33:30 -05:00
scripts Fix "-dirty" CI versions and the release asset name 2026-11-16 20:47:34 -05:00
src Rename the mod to DesktopNH 2026-11-16 19:33:30 -05:00
third_party Harness fixes, documentation updates. 2026-11-15 22:07:05 -05:00
.editorconfig Add repo dotfiles and a Forgejo Actions build workflow 2026-11-15 22:23:27 -05:00
.gitattributes Add repo dotfiles and a Forgejo Actions build workflow 2026-11-15 22:23:27 -05:00
.gitignore Add repo dotfiles and a Forgejo Actions build workflow 2026-11-15 22:23:27 -05:00
.gitmodules Harness fixes, documentation updates. 2026-11-15 22:07:05 -05:00
addon.gradle.kts Rename the mod to DesktopNH 2026-11-16 19:33:30 -05:00
build.gradle.kts Init commit with gtnh template 2026-11-15 21:53:06 -05:00
CLAUDE.md Rename the mod to DesktopNH 2026-11-16 19:33:30 -05:00
dependencies.gradle Add a terminal emulator setting and /wl term 2026-11-16 14:30:20 -05:00
dev Rename the mod to DesktopNH 2026-11-16 19:33:30 -05:00
gradle.properties Rename the mod to DesktopNH 2026-11-16 19:33:30 -05:00
gradlew Init commit with gtnh template 2026-11-15 21:53:06 -05:00
gradlew.bat Fix "-dirty" CI versions and the release asset name 2026-11-16 20:47:34 -05:00
LICENSE Init commit with gtnh template 2026-11-15 21:53:06 -05:00
README.md CI: publish the jar as a rolling "latest" release on pushes to main 2026-11-16 20:00:39 -05:00
repositories.gradle Init commit with gtnh template 2026-11-15 21:53:06 -05:00
settings.gradle.kts Init commit with gtnh template 2026-11-15 21:53:06 -05:00

DesktopNH

An interactive desktop inside GregTech: New Horizons. Phase 1 ports Waylandcraft's Wayland compositor to Minecraft 1.7.10 / GTNH 2.9 (Java 25 + lwjgl3ify), so real Linux application windows appear in the world. Phase 2 adds a reduced Vivecraft on OpenXR so you can use them in VR.

Status: phase 1 (flat Waylandcraft port) works: Linux apps run inside the game as windows in the world, with the crosshair as the mouse pointer and keyboard capture, on vanilla rendering and with Angelica. Proof-of-concept quality. See docs/feasibility-study.md and docs/dev-loop.md.

Getting it

Every push to main publishes the release jar as the latest pre-release on Forgejo (Releases → Latest build), replaced on each push. Drop it into a GTNH 2.9 instance running Java 25 with lwjgl3ify, or build and install from a checkout with ./dev deploy --instance <name>.

Using it

  • /wl <command line> starts a program on the in-game compositor, e.g. /wl foot. Its window appears two blocks in front of you. Output goes to <game dir>/desktopnh/apps.log. If the program fails, or exits without opening a window, chat says so.
  • App launcher: /wl apps, or bind a key under Controls → DesktopNH → Open app launcher. A list of your applications appears in front of you with the keyboard captured: type to filter, ↑/↓ and Enter to launch, Esc to close. Release the keyboard (Right Alt) to pick with the crosshair instead: look at an app and click, scroll with the wheel. Apps come from your desktop entries plus *.desktop files in <game dir>/desktopnh/applications/. /wl run <app id> starts one directly (tab completes).
  • /wl term [command line] opens a terminal, or runs a terminal program in one (/wl term vim). The terminal emulator is detected on first use ($TERMINAL, xdg-terminal-exec, KDE's default terminal, then common terminals on PATH) and saved in config/desktopnh.cfg.
  • /wl config shows the settings; /wl config <name> <value> changes one, /wl config <name> reset restores it: terminal (reset detects it again), terminalArgs, grabHoldMs.
  • Look at a window to point at it: clicks and the scroll wheel go to the window instead of the game.
  • Right Alt (rebindable: Controls → DesktopNH) captures the keyboard for the window you look at (or the last one you clicked). Esc or Right Alt again releases it. While it's captured you can't move, and the mouse cursor is the pointer: point, click, drag and scroll on any window or the launcher; clicking another window moves the keyboard there; clicking the world does nothing.
  • /wl list lists windows and panels with short ids. /wl here [id | app id | title] moves one in front of you; without an argument, the one you were looking at when you opened chat, else the last focused window.
  • Moving windows by hand: bind Controls → DesktopNH → Grab window. Tap it while looking at a window to pick it up: it stays in front of you as you turn and walk; scroll to push it away or pull it closer; tap again (or left-click) to drop it. Or hold the key to drag and let go to drop. The tap/hold threshold is /wl config grabHoldMs <ms> (default 300).
  • X11 apps need xwayland-satellite installed; Wayland apps work out of the box.

Known limitations

  • Single-instance apps can open on your desktop instead of in the game. Apps that hand off to an already running copy (over D-Bus or a socket) do so even when started with /wl, and the new window then belongs to the copy on your desktop. Seen with LibreWolf/Firefox (their launcher sets MOZ_DBUS_REMOTE=1 on Wayland); Chromium-based browsers, many KDE (KDBusService::Unique) and GNOME (GApplication) apps behave the same way. Workarounds: close the desktop copy first (then launches from the desktop open in the game until you close it), or start a separate instance, e.g. for Firefox-family browsers: /wl mkdir -p ~/.local/share/desktopnh/librewolf && librewolf --new-instance --profile ~/.local/share/desktopnh/librewolf. An opt-in way to give /wl apps their own D-Bus session may come later.
  • X11 apps need xwayland-satellite; without it /wl starts them with no DISPLAY, so they fail instead of opening on the desktop.
  • No window moving/resizing by dragging, drag and drop, clipboard or cursor shapes yet, and window placement isn't saved across restarts.

Requirements

  • Linux with a Mesa GPU driver, Wayland session (headless runs use kwin_wayland --virtual)
  • JDK 25. runClient25 requests a JetBrains Runtime 25 toolchain (for enhanced hotswap); if Gradle can't find or provision one, install JBR 25 or point org.gradle.java.installations.paths at it
  • Rust toolchain (builds third_party/waylandcraft/native; git submodule update --init first)
  • System xkbcommon >= 1.11

Build and run

./gradlew build                                      # mod jar in build/libs
./gradlew runClient25                                # dev client on Java 25 + lwjgl3ify
./gradlew runClient25 -Pdesktopnh.probe.exit=true    # EGL/dmabuf probe, then exit
./gradlew runClient25 -PwithAngelica=true            # with GTNH's renderer stack

Install into a GTNH instance

./dev deploy --instance gtnh2.9          # Prism instance name, or a path to an instance/game dir
DESKTOPNH_INSTANCE=gtnh2.9 ./dev deploy  # same, via the environment
./dev deploy --instance gtnh2.9 --dry-run

Builds the release jar (build/libs/desktopnh-<version>.jar: reobfuscated, with the bridge and libwaylandcraft.so inside), checks the instance, and replaces any previous desktopnh-*.jar in its mods/. The instance needs lwjgl3ify 3.x, Java 25+, and the environment variable SDL_VIDEODRIVER=wayland (Prism: Edit instance → Settings → Environment variables); the script refuses to install over the first two and warns about the third.

Built from the GTNH ExampleMod 1.7.10 template.

License

GPL-3.0 (inherited from Waylandcraft). Vivecraft-derived code (LGPL-3.0) is compatible.