Start the episode from the right directory, and fit the window

Three things v0.2.0 got wrong, all of which someone hit within minutes of
downloading it.

The launcher drew its menu and then could not start anything. Inside a bundle
SDL_GetBasePath() returns Contents/Resources, not Contents/MacOS, so the
episode programs were looked for among the artwork. The data lookup had been
landing in the right place by luck, since the data really is in Resources.
Where the programs are is now worked out separately from where the data is, and
the two are no longer assumed to be the same place.

The window opened at three times 640x400, corrected for aspect: 1920x1440,
which is taller than a 1080p screen and puts the title bar out of reach. The
scale is now the largest whole multiple that leaves room for the window's own
frame, and COSMO_SCALE overrides it.

The Windows archive showed four executables where one would do. They cannot be
merged -- the episodes differ by preprocessor conditionals that include whole
actor implementations, so each is genuinely different code -- but they can be
kept out of the way, so the episodes now live in a subdirectory and the
launcher looks there first.

A smoke test runs the packaged game with no window and no sound and insists on
seeing timer interrupts delivered, which only the game's own loop produces. It
fails against the v0.2.0 archive and passes against this one. A screenshot of a
menu is not evidence that a game starts, which is the whole reason this was
missed.

Author: digows

.github/scripts/package.sh

@@ -53,16 +53,22 @@ macos)
     ;;
 
 linux)
-    cp "$build/cosmo" "$build/cosmo1" "$build/cosmo2" "$build/cosmo3" "$root/"
+    # Only the launcher sits at the top. The episodes are programs in their own
+    # right, but nobody needs to see four of them to play one.
+    mkdir -p "$root/episodes"
+    cp "$build/cosmo" "$root/"
+    cp "$build/cosmo1" "$build/cosmo2" "$build/cosmo3" "$root/episodes/"
     cp "$repo/gamedata/COSMO1.STN" "$repo/gamedata/COSMO1.VOL" "$root/"
-    chmod +x "$root"/cosmo*
+    chmod +x "$root/cosmo" "$root/episodes"/cosmo*
     docs "$root"
     (cd "$staging" && tar czf "$dist/$name.tar.gz" "$name")
     ;;
 
 windows)
-    cp "$build/cosmo.exe" "$build/cosmo1.exe" "$build/cosmo2.exe" \
-       "$build/cosmo3.exe" "$root/"
+    mkdir -p "$root/episodes"
+    cp "$build/cosmo.exe" "$root/"
+    cp "$build/cosmo1.exe" "$build/cosmo2.exe" "$build/cosmo3.exe" \
+       "$root/episodes/"
     cp "$repo/gamedata/COSMO1.STN" "$repo/gamedata/COSMO1.VOL" "$root/"
     docs "$root"
     (cd "$staging" && zip -qr "$dist/$name.zip" "$name")

.github/scripts/smoke-test.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+#
+# Start the packaged game and check that it actually runs.
+#
+#   smoke-test.sh <macos|linux> <archive>
+#
+# v0.2.0 shipped a macOS bundle whose launcher drew its menu and then could not
+# start an episode: SDL_GetBasePath() returns Contents/Resources inside a
+# bundle, and the episode programs are in Contents/MacOS. Everything looked
+# right in a screenshot of the menu, which is exactly why a screenshot of the
+# menu is not enough.
+#
+# So this unpacks what is about to be published, runs it with no window and no
+# sound, and insists on evidence that the game itself is running: the timer
+# interrupt being delivered is something only the game's own loop produces.
+set -euo pipefail
+
+platform="${1:?platform}"
+archive="${2:?archive}"
+
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+case "$archive" in
+*.tar.gz) tar xzf "$archive" -C "$work" ;;
+*.zip)    unzip -q "$archive" -d "$work" ;;
+*)        echo "unknown archive: $archive" >&2; exit 1 ;;
+esac
+
+case "$platform" in
+macos) program="$(find "$work" -type f -path '*/Cosmo.app/Contents/MacOS/Cosmo')" ;;
+linux) program="$(find "$work" -type f -name cosmo -perm -u+x | head -1)" ;;
+*)     echo "unknown platform: $platform" >&2; exit 1 ;;
+esac
+
+if [ -z "$program" ] || [ ! -x "$program" ]; then
+    echo "no launcher found in $archive" >&2
+    exit 1
+fi
+
+echo "running $program"
+
+log="$work/run.log"
+
+# Episode 1 by name, so the launcher hands straight over rather than waiting on
+# a menu nobody is watching.
+(
+    cd "$(dirname "$program")"
+    SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy COSMO_DEBUG=1 \
+        "$program" 1 > "$log" 2>&1
+) &
+pid=$!
+
+sleep 20
+kill -9 "$pid" 2>/dev/null || true
+wait "$pid" 2>/dev/null || true
+
+echo "--- output"
+cat "$log" || true
+echo "---"
+
+if grep -q 'cannot start' "$log"; then
+    echo "the launcher could not start the episode" >&2
+    exit 1
+fi
+
+if grep -q 'No episode data' "$log"; then
+    echo "the game did not find its data" >&2
+    exit 1
+fi
+
+# "delivered=" counts timer interrupts the game's own loop consumed. A number
+# above zero means the 1992 code is running, not merely that a process started.
+delivered="$(grep -o 'delivered=[0-9]*' "$log" | tail -1 | cut -d= -f2 || true)"
+
+if [ -z "$delivered" ] || [ "$delivered" -le 0 ]; then
+    echo "the game never ran: no timer interrupts were delivered" >&2
+    exit 1
+fi
+
+echo "the game ran, and consumed $delivered timer interrupts"

.github/workflows/release.yml

@@ -53,6 +53,12 @@ jobs:
       - name: Package
         run: bash .github/scripts/package.sh macos build "${{ github.ref_name }}"
 
+      # Unpack what is about to be published and make sure the game actually
+      # starts from it. A menu that draws is not the same as an episode that
+      # runs, which v0.2.0 proved the hard way.
+      - name: Start the packaged game
+        run: bash .github/scripts/smoke-test.sh macos dist/*
+
       - uses: actions/upload-artifact@v7
         with:
           name: package-macos
@@ -88,6 +94,12 @@ jobs:
       - name: Package
         run: bash .github/scripts/package.sh linux build "${{ github.ref_name }}"
 
+      # Unpack what is about to be published and make sure the game actually
+      # starts from it. A menu that draws is not the same as an episode that
+      # runs, which v0.2.0 proved the hard way.
+      - name: Start the packaged game
+        run: bash .github/scripts/smoke-test.sh linux dist/*
+
       - uses: actions/upload-artifact@v7
         with:
           name: package-linux

PLAYING.txt

@@ -51,6 +51,34 @@ is written on the way out, exactly as it was on DOS, where killing the program
 lost it the same way.
 
 
+The window
+----------
+
+It opens at the largest whole multiple of the original 640x400 that fits your
+screen, so the title bar always stays reachable. To choose the size yourself:
+
+    COSMO_SCALE=2 ./cosmo        (1 is the original size, 3 is large)
+
+Resizing is fine. The picture is letterboxed rather than stretched, so it never
+distorts.
+
+
+What is in this folder
+----------------------
+
+    cosmo          the launcher, and the only thing you need to run
+    episodes/      one program per episode
+    COSMO1.*       Episode 1's data
+
+The episodes are separate programs rather than one with a switch. They differ
+by preprocessor conditionals that include or exclude whole actor
+implementations, so each compiles to genuinely different code -- Apogee shipped
+three executables for the same reason. They sit in a subdirectory so there is
+one obvious thing to run.
+
+On macOS all of that is inside Cosmo.app, where none of it needs looking at.
+
+
 Episodes 2 and 3
 ----------------
 

include/cosmo/paths.h

@@ -37,6 +37,15 @@ const char *paths_data_dir(void);
  */
 const char *paths_write_dir(void);
 
+/*
+ * Where the episode programs sit.
+ *
+ * Not the same as where the data is, and not what SDL_GetBasePath() returns
+ * either: inside a macOS bundle that hands back Contents/Resources, while the
+ * executables live one directory across in Contents/MacOS.
+ */
+const char *paths_program_dir(void);
+
 /*
  * Copy an episode's two group files into the data directory, given the path of
  * either one of them. Used when someone points the launcher at a copy of an

src/launcher.c

@@ -368,18 +368,37 @@ static int replace_process(const char *program, char *argv[])
 
 static int run_episode(int number)
 {
-    const char *base = SDL_GetBasePath();
+    /*
+     * The episode programs are looked for in a subdirectory first and beside
+     * the launcher second.
+     *
+     * They cannot be merged into one executable: the episodes differ by
+     * preprocessor conditionals that include or exclude whole actor
+     * implementations, so each is genuinely different code with its own copy of
+     * the game's globals. What can be done is to keep them out of the way, so
+     * an unpacked folder shows one program to run rather than four.
+     */
+    static const char *const WHERE[] = {"episodes/", ""};
     char program[1024];
     char *child_argv[2];
+    SDL_PathInfo info;
+    size_t i;
+    bool found = false;
 
-    if (!base) {
-        fprintf(stderr, "cosmo: cannot locate the episode programs (%s)\n",
-                SDL_GetError());
-        return 1;
+    for (i = 0; i < SDL_arraysize(WHERE) && !found; i++) {
+        int written = snprintf(program, sizeof program, "%s/%scosmo%d%s",
+                               paths_program_dir(), WHERE[i], number,
+                               EPISODE_PROGRAM_SUFFIX);
+        if (written < 0 || (size_t)written >= sizeof program) continue;
+
+        found = SDL_GetPathInfo(program, &info);
     }
 
-    snprintf(program, sizeof program, "%scosmo%d%s",
-             base, number, EPISODE_PROGRAM_SUFFIX);
+    if (!found) {
+        fprintf(stderr, "cosmo: episode %d is not installed beside the "
+                        "launcher\n", number);
+        return 1;
+    }
 
     /* Give up the window before the process image is replaced. */
     video_shutdown();

src/platform/paths.c

@@ -18,6 +18,7 @@
 
 static char data_dir[MAX_PATH_LEN];
 static char write_dir[MAX_PATH_LEN];
+static char program_dir[MAX_PATH_LEN];
 
 /* The extensions an episode's two group files carry. */
 static const char *const GROUP_EXTENSIONS[] = {"STN", "VOL"};
@@ -67,6 +68,40 @@ static bool group_path(char *dest, size_t size, const char *dir, int episode,
     return path_join(dest, size, dir, leaf);
 }
 
+/*
+ * Work out where sibling executables are, from where SDL says the application's
+ * files are.
+ *
+ * In a bundle those are two different places. SDL_GetBasePath() points at
+ * Contents/Resources, because that is where an application's data belongs, but
+ * the programs are in Contents/MacOS. Reading the first as though it were the
+ * second is how the launcher came to look for the episodes among the artwork.
+ */
+static void resolve_program_dir(const char *base)
+{
+    static const char RESOURCES[] = "/Contents/Resources";
+    size_t base_length, suffix_length = sizeof RESOURCES - 1;
+
+    if (!base || !path_copy(program_dir, sizeof program_dir, base)) {
+        path_copy(program_dir, sizeof program_dir, ".");
+        return;
+    }
+
+    base_length = SDL_strlen(program_dir);
+    while (base_length > 1 && (program_dir[base_length - 1] == '/' ||
+                               program_dir[base_length - 1] == '\\')) {
+        program_dir[--base_length] = '\0';
+    }
+
+    if (base_length > suffix_length &&
+        SDL_strcasecmp(program_dir + base_length - suffix_length, RESOURCES) == 0)
+    {
+        /* Swap the last component: Contents/Resources -> Contents/MacOS. */
+        program_dir[base_length - suffix_length] = '\0';
+        SDL_strlcat(program_dir, "/Contents/MacOS", sizeof program_dir);
+    }
+}
+
 static bool dir_has_any_episode(const char *dir)
 {
     int episode;
@@ -178,6 +213,8 @@ bool paths_init(void)
     const char *prefs;
     int i, episode;
 
+    resolve_program_dir(SDL_GetBasePath());
+
     /* Used in place when the data sits somewhere that takes the saves too. */
     for (i = 0; i < count; i++) {
         if (dir_has_any_episode(shipped[i]) && dir_is_writable(shipped[i])) {
@@ -228,6 +265,11 @@ const char *paths_write_dir(void)
     return write_dir;
 }
 
+const char *paths_program_dir(void)
+{
+    return program_dir;
+}
+
 bool paths_import_episode(const char *chosen_file, int episode)
 {
     char folder[MAX_PATH_LEN];

src/platform/video.c

@@ -108,6 +108,46 @@ bool video_write_png(const char *path, int scale)
     return ok;
 }
 
+/*
+ * The largest whole-number scale that leaves the window on the screen.
+ *
+ * Three times 640x400, corrected for the aspect the pixels had, is 1920x1440 --
+ * taller than a 1080p display, which puts the title bar above the top of the
+ * screen where it cannot be reached. The scale is chosen to fit instead, and
+ * COSMO_SCALE overrides it for anyone who wants a particular size.
+ */
+#define WINDOW_FRAME_ALLOWANCE 64
+
+static int fitting_scale(int wanted)
+{
+    const char *requested = SDL_getenv("COSMO_SCALE");
+    SDL_Rect usable;
+    SDL_DisplayID display;
+    int scale;
+
+    if (requested) {
+        int value = SDL_atoi(requested);
+        if (value >= 1) return value;
+    }
+
+    display = SDL_GetPrimaryDisplay();
+    if (!display || !SDL_GetDisplayUsableBounds(display, &usable)) return wanted;
+
+    for (scale = wanted; scale > 1; scale--) {
+        int w = EGA_SCREEN_W * scale;
+        int h = (int)(EGA_SCREEN_H * scale * PIXEL_ASPECT);
+
+        /*
+         * The usable bounds already exclude the taskbar or menu bar; what they
+         * do not account for is the window's own title bar, which is what ends
+         * up off the top of the screen when the window is too tall.
+         */
+        if (w <= usable.w && h <= usable.h - WINDOW_FRAME_ALLOWANCE) break;
+    }
+
+    return scale;
+}
+
 bool video_init(const char *title, int scale)
 {
     int w, h;
@@ -119,6 +159,8 @@ bool video_init(const char *title, int scale)
         return false;
     }
 
+    scale = fitting_scale(scale);
+
     w = EGA_SCREEN_W * scale;
     h = (int)(EGA_SCREEN_H * scale * PIXEL_ASPECT);