sigil-desktop

The desktop host layer for Sigil games and interactive programs: a window with an OpenGL context, keyboard and mouse state, a frame clock, and a quit request, behind the (sigil desktop) library. Drawing is sigil-graphics, which builds on this package; sound is sigil-audio.

The window comes from GLFW 3.5.1, vendored as source under vendor/glfw (no local patches; see vendor/glfw/VENDOR.md). On Linux one binary runs as a native Wayland client or under X11, picked when the program starts; on Windows it is a Win32 window; the macOS files are vendored and not yet built. Every platform library (libwayland-client, libxkbcommon, libX11, libEGL, libGL, ...) is loaded at run time by GLFW, so a game links none of them.

This package was sigil-app through 0.9.x, when the window was sokol_app (X11 only on Linux); the Codeberg repository is sigil/sigil-desktop since 2026-09-20 (renamed in place, the old URL redirects). The (sigil app) library still exists in 0.10 as a re-export of (sigil desktop) so a consumer can relock first and rename its imports second; it goes away in 0.11.

Use

(import (sigil desktop) (sigil graphics))

(define (game)
  (gfx-setup)
  (let loop ()
    (let ((dt (wait-frame)))
      (begin-frame)
      (clear-screen 0.0 0.0 0.0)
      ;; draw with (frame-width) x (frame-height) pixels to work with
      (end-frame)
      (cond ((key-pressed? 'escape) (request-quit))
            ((quit-requested?) #t)
            (else (loop)))))
  (gfx-shutdown))

(run-game "My Game" 960 720 game)

run-game runs the thunk in a coroutine; (wait-frame) yields to the host and returns the frame's delta time in seconds when the next frame starts. Below it, app-run takes init, frame and cleanup procedures directly.

The exports: app-run, run-game, wait-frame, frame-width, frame-height, frame-time, time-elapsed, mouse-x, mouse-y, mouse-down?, mouse-pressed?, mouse-released?, key-down?, key-pressed?, key-released?, quit-requested?, request-quit.

Sizes and positions are framebuffer pixels: on a scaled Wayland output a window asked for at 960x720 has a framebuffer of 1920x1440 at scale 2 (or 1440x1080 at 1.5), frame-width says so, and mouse-x/mouse-y are in the same pixels. Key symbols: a..z, 0..9, space, return (or enter), escape (or esc), tab, backspace, left, right, up, down, shift, ctrl (or control), alt. Mouse buttons: left, right, middle. key-pressed? is true for the one frame after the key went down (a held key repeating does not re-fire it); key-down? reports the state after that frame's events.

Environment

SIGIL_DESKTOP_PLATFORM=wayland|x11|win32|cocoa forces the platform. Otherwise GLFW follows XDG_SESSION_TYPE and WAYLAND_DISPLAY/DISPLAY, trying Wayland before X11.
SIGIL_DESKTOP_VERBOSE=1 prints the platform, window and framebuffer sizes and content scale on startup and on every resize, and which directory each runtime library was found in when the loader needed help.
SIGIL_LIBRARY_PATH=dir:dir adds directories the runtime loader looks in for the platform libraries (see below).

Guix and Nix

GLFW loads its platform libraries by bare soname, and on Guix and Nix a profile's lib/ is on no default loader path. src/c/dl-search.c defines dlopen in the executable: it tries the name as the loader would, and only when that fails looks under, in order, SIGIL_LIBRARY_PATH, $GUIX_ENVIRONMENT/lib, $buildInputs/$nativeBuildInputs (each /lib, inside a nix-shell), $NIX_LD_LIBRARY_PATH, ~/.guix-home/profile/lib, ~/.guix-profile/lib, ~/.nix-profile/lib, /etc/profiles/per-user/$USER/lib, /run/current-system/profile/lib, /run/current-system/sw/lib. Every row is walked on every machine (Guix and Nix can coexist); the first hit wins and SIGIL_DESKTOP_VERBOSE says which. test/dl-search-test.sh exercises it against fake profiles.

Manifests under guix/: run-wayland.scm (mesa, wayland, libxkbcommon) and run-x11.scm (mesa, libx11) are what a game needs at run time; build.scm is the headers a build needs. Keep libglvnd out of a run manifest: Guix's mesa is built without it and a vendorless libGLX.so.0 breaks GLX.

Building

guix shell -m guix/build.scm -- sh -c 'CPATH=$GUIX_ENVIRONMENT/include sigil build'
sigil build --config windows-amd64      # cross, through zig

The C surface other packages use is include/sigil-desktop.h (framebuffer size, GL proc loader, platform name).