README.md — sigil-app

1# sigil-desktop

3The desktop host layer for Sigil games and interactive programs: a window

4with an OpenGL context, keyboard and mouse state, a frame clock, and a

5quit request, behind the `(sigil desktop)` library. Drawing is

6[sigil-graphics](https://codeberg.org/sigil/sigil-graphics), which builds

7on this package; sound is

8[sigil-audio](https://codeberg.org/sigil/sigil-audio).

10The window comes from [GLFW](https://www.glfw.org) 3.5.1, vendored as

11source under `vendor/glfw` (no local patches; see `vendor/glfw/VENDOR.md`).

12On Linux one binary runs as a native Wayland client or under X11, picked

13when the program starts; on Windows it is a Win32 window; the macOS files

14are vendored and not yet built. Every platform library (libwayland-client,

15libxkbcommon, libX11, libEGL, libGL, ...) is loaded at run time by GLFW,

16so a game links none of them.

18This package was `sigil-app` through 0.9.x, when the window was sokol_app

19(X11 only on Linux); the Codeberg repository is `sigil/sigil-desktop`

20since 2026-09-20 (renamed in place, the old URL redirects). The

21`(sigil app)` library still exists in 0.10 as a re-export of

22`(sigil desktop)` so a consumer can relock first and rename its imports

23second; it goes away in 0.11.

25## Use

27```scheme

28(import (sigil desktop) (sigil graphics))

30(define (game)

31 (gfx-setup)

32 (let loop ()

33 (let ((dt (wait-frame)))

34 (begin-frame)

35 (clear-screen 0.0 0.0 0.0)

36 ;; draw with (frame-width) x (frame-height) pixels to work with

37 (end-frame)

38 (cond ((key-pressed? 'escape) (request-quit))

39 ((quit-requested?) #t)

40 (else (loop)))))

41 (gfx-shutdown))

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

44```

46`run-game` runs the thunk in a coroutine; `(wait-frame)` yields to the

47host and returns the frame's delta time in seconds when the next frame

48starts. Below it, `app-run` takes init, frame and cleanup procedures

49directly.

51The exports: `app-run`, `run-game`, `wait-frame`, `frame-width`,

52`frame-height`, `frame-time`, `time-elapsed`, `mouse-x`, `mouse-y`,

53`mouse-down?`, `mouse-pressed?`, `mouse-released?`, `key-down?`,

54`key-pressed?`, `key-released?`, `quit-requested?`, `request-quit`.

56Sizes and positions are framebuffer pixels: on a scaled Wayland output a

57window asked for at 960x720 has a framebuffer of 1920x1440 at scale 2 (or

581440x1080 at 1.5), `frame-width` says so, and `mouse-x`/`mouse-y` are in

59the same pixels. Key symbols: `a`..`z`, `0`..`9`, `space`, `return` (or

60`enter`), `escape` (or `esc`), `tab`, `backspace`, `left`, `right`, `up`,

61`down`, `shift`, `ctrl` (or `control`), `alt`. Mouse buttons: `left`,

62`right`, `middle`. `key-pressed?` is true for the one frame after the key

63went down (a held key repeating does not re-fire it); `key-down?` reports

64the state after that frame's events.

66## Environment

68- `SIGIL_DESKTOP_PLATFORM=wayland|x11|win32|cocoa` forces the platform.

69 Otherwise GLFW follows `XDG_SESSION_TYPE` and `WAYLAND_DISPLAY`/`DISPLAY`,

70 trying Wayland before X11.

71- `SIGIL_DESKTOP_VERBOSE=1` prints the platform, window and framebuffer

72 sizes and content scale on startup and on every resize, and which

73 directory each runtime library was found in when the loader needed help.

74- `SIGIL_LIBRARY_PATH=dir:dir` adds directories the runtime loader looks in

75 for the platform libraries (see below).

77## Guix and Nix

79GLFW loads its platform libraries by bare soname, and on Guix and Nix a

80profile's `lib/` is on no default loader path. `src/c/dl-search.c`

81defines `dlopen` in the executable: it tries the name as the loader would,

82and only when that fails looks under, in order, `SIGIL_LIBRARY_PATH`,

83`$GUIX_ENVIRONMENT/lib`, `$buildInputs`/`$nativeBuildInputs` (each `/lib`,

84inside a nix-shell), `$NIX_LD_LIBRARY_PATH`, `~/.guix-home/profile/lib`,

85`~/.guix-profile/lib`, `~/.nix-profile/lib`,

86`/etc/profiles/per-user/$USER/lib`, `/run/current-system/profile/lib`,

87`/run/current-system/sw/lib`. Every row is walked on every machine (Guix

88and Nix can coexist); the first hit wins and `SIGIL_DESKTOP_VERBOSE` says

89which. `test/dl-search-test.sh` exercises it against fake profiles.

91Manifests under `guix/`: `run-wayland.scm` (mesa, wayland, libxkbcommon)

92and `run-x11.scm` (mesa, libx11) are what a game needs at run time;

93`build.scm` is the headers a build needs. Keep `libglvnd` out of a run

94manifest: Guix's mesa is built without it and a vendorless `libGLX.so.0`

95breaks GLX.

97## Building

99```sh

100guix shell -m guix/build.scm -- sh -c 'CPATH=$GUIX_ENVIRONMENT/include sigil build'

101sigil build --config windows-amd64 # cross, through zig

102```

103

104The C surface other packages use is `include/sigil-desktop.h`

105(framebuffer size, GL proc loader, platform name).