rgame 0.1.0

data/ext/rgame_core/audio/vorbis_decoder.c

@@ -0,0 +1,282 @@
+/*
+ * vorbis_decoder.c — a miniaudio decoding backend over stb_vorbis.
+ * See vorbis_decoder.h for why it exists and why it has two entry points.
+ */
+
+#include "audio/vorbis_decoder.h"
+
+/* Declarations only. The code lives in stb_vorbis_impl.c, which is the one
+ * translation unit compiled without the project's warning flags; including it
+ * whole here would both duplicate every symbol and drag third-party code
+ * through -Wall -Wextra. */
+#define STB_VORBIS_HEADER_ONLY
+#include "vendor/stb_vorbis.c"
+
+/*
+ * One open ogg stream, as miniaudio sees it.
+ *
+ * `ma_data_source_base` must come first: miniaudio casts the pointer it is
+ * handed straight to its own base type, so anything before it would be read as
+ * the base and the first call would go somewhere unfortunate.
+ */
+typedef struct {
+    ma_data_source_base base;
+    stb_vorbis *vorbis;
+    ma_uint32 channels;
+    ma_uint32 sample_rate;
+    /* The compressed file, when it was opened from memory. stb_vorbis keeps
+     * reading from this for the life of the stream, so it is freed in uninit
+     * and not before. NULL when opened by filename. */
+    void *compressed;
+} rgame_vorbis_stream;
+
+/* ------------------------------------------------------------------------- *
+ * The data source: reading, seeking, and answering questions about the stream
+ * ------------------------------------------------------------------------- */
+
+static ma_result vorbis_read(ma_data_source *source, void *out, ma_uint64 frames_wanted,
+                             ma_uint64 *frames_read) {
+    rgame_vorbis_stream *stream = (rgame_vorbis_stream *)source;
+    float *destination = (float *)out;
+    ma_uint64 filled = 0;
+
+    /*
+     * Keep going until the buffer is full or the file really has run out.
+     *
+     * One call is not enough: stb_vorbis decodes a packet at a time and
+     * routinely hands back fewer frames than were asked for, in the middle of a
+     * perfectly healthy file. Callers read a short read as the end — miniaudio's
+     * streaming path does exactly that, marking the stream finished when a page
+     * comes back under-filled — so passing stb's partial counts straight up
+     * makes a streamed song stop after its first packet-run and never loop.
+     * That was a real bug here, and it looked like "looping does not work".
+     *
+     * stb counts in *samples*, one per channel per frame, while miniaudio counts
+     * in frames; the multiply below is that conversion, and getting it wrong
+     * plays everything at the wrong speed.
+     */
+    while (filled < frames_wanted) {
+        ma_uint64 remaining = frames_wanted - filled;
+        int got = stb_vorbis_get_samples_float_interleaved(
+            stream->vorbis, (int)stream->channels, destination + (filled * stream->channels),
+            (int)(remaining * stream->channels));
+
+        if (got <= 0) {
+            break; /* genuinely out of audio */
+        }
+        filled += (ma_uint64)got;
+    }
+
+    ma_uint64 got = filled;
+    *frames_read = got;
+
+    /*
+     * MA_AT_END rather than an error: running out is how a sound ends.
+     *
+     * Both halves of this are unobservable through miniaudio, and mutating
+     * either survives the suite — measured. miniaudio decides end-of-stream
+     * from `frames_read`, so a source that always claimed MA_SUCCESS still
+     * makes the decoder report MA_AT_END, and one that always claimed
+     * MA_AT_END is ignored while frames keep arriving. It says the true thing
+     * anyway: the contract is what a data source is supposed to report, and
+     * the next thing to read this code should not have to rediscover that
+     * miniaudio happens not to look.
+     */
+    return got > 0 ? MA_SUCCESS : MA_AT_END;
+}
+
+static ma_result vorbis_seek(ma_data_source *source, ma_uint64 frame) {
+    rgame_vorbis_stream *stream = (rgame_vorbis_stream *)source;
+    return stb_vorbis_seek(stream->vorbis, (unsigned int)frame) ? MA_SUCCESS : MA_ERROR;
+}
+
+static ma_result vorbis_data_format(ma_data_source *source, ma_format *format,
+                                    ma_uint32 *channels, ma_uint32 *sample_rate,
+                                    ma_channel *channel_map, size_t channel_map_capacity) {
+    rgame_vorbis_stream *stream = (rgame_vorbis_stream *)source;
+
+    if (format) {
+        /* Floats, because that is what stb_vorbis hands back and what
+         * miniaudio's graph works in — no conversion in the middle. */
+        *format = ma_format_f32;
+    }
+    if (channels) {
+        *channels = stream->channels;
+    }
+    if (sample_rate) {
+        *sample_rate = stream->sample_rate;
+    }
+    if (channel_map) {
+        ma_channel_map_init_standard(ma_standard_channel_map_default, channel_map,
+                                     channel_map_capacity, stream->channels);
+    }
+    return MA_SUCCESS;
+}
+
+static ma_result vorbis_cursor(ma_data_source *source, ma_uint64 *cursor) {
+    rgame_vorbis_stream *stream = (rgame_vorbis_stream *)source;
+    *cursor = (ma_uint64)stb_vorbis_get_sample_offset(stream->vorbis);
+    return MA_SUCCESS;
+}
+
+static ma_result vorbis_length(ma_data_source *source, ma_uint64 *length) {
+    rgame_vorbis_stream *stream = (rgame_vorbis_stream *)source;
+    *length = (ma_uint64)stb_vorbis_stream_length_in_samples(stream->vorbis);
+    return MA_SUCCESS;
+}
+
+static ma_data_source_vtable vorbis_data_source_vtable = {
+    vorbis_read, vorbis_seek, vorbis_data_format, vorbis_cursor, vorbis_length,
+    NULL, /* onSetLooping: miniaudio handles looping above this level */
+    0
+};
+
+/* ------------------------------------------------------------------------- *
+ * Opening
+ * ------------------------------------------------------------------------- */
+
+/* Shared tail of both entry points: an open stb handle becomes a data source. */
+static ma_result finish_open(rgame_vorbis_stream *stream, void *compressed,
+                             const ma_allocation_callbacks *allocations,
+                             ma_data_source **out) {
+    stb_vorbis_info info = stb_vorbis_get_info(stream->vorbis);
+    stream->channels = (ma_uint32)info.channels;
+    stream->sample_rate = info.sample_rate;
+    stream->compressed = compressed;
+
+    ma_data_source_config config = ma_data_source_config_init();
+    config.vtable = &vorbis_data_source_vtable;
+
+    if (ma_data_source_init(&config, &stream->base) != MA_SUCCESS) {
+        stb_vorbis_close(stream->vorbis);
+        ma_free(compressed, allocations);
+        ma_free(stream, allocations);
+        return MA_ERROR;
+    }
+
+    *out = (ma_data_source *)stream;
+    return MA_SUCCESS;
+}
+
+static ma_result vorbis_init_file(void *user_data, const char *path,
+                                  const ma_decoding_backend_config *config,
+                                  const ma_allocation_callbacks *allocations,
+                                  ma_data_source **out) {
+    (void)user_data;
+    (void)config;
+
+    rgame_vorbis_stream *stream = ma_malloc(sizeof(rgame_vorbis_stream), allocations);
+    if (!stream) {
+        return MA_OUT_OF_MEMORY;
+    }
+
+    int error = 0;
+    stream->vorbis = stb_vorbis_open_filename(path, &error, NULL);
+    if (!stream->vorbis) {
+        ma_free(stream, allocations);
+        /* Not an error worth distinguishing: a missing file and a file that is
+         * not an ogg both mean "this is not a sound", and the caller reports
+         * the path either way. */
+        return MA_INVALID_FILE;
+    }
+
+    return finish_open(stream, NULL, allocations, out);
+}
+
+/*
+ * The callback path, which is the one `ma_engine` uses.
+ *
+ * stb_vorbis cannot read through callbacks, so the whole compressed file is
+ * pulled in and opened from memory. See the header for why that is the right
+ * trade against the pushdata API.
+ */
+static ma_result vorbis_init(void *user_data, ma_read_proc on_read, ma_seek_proc on_seek,
+                             ma_tell_proc on_tell, void *read_seek_tell_user_data,
+                             const ma_decoding_backend_config *config,
+                             const ma_allocation_callbacks *allocations,
+                             ma_data_source **out) {
+    (void)user_data;
+    (void)config;
+
+    /* Seek to the end to find the size, then back. There is no "how big is
+     * this" callback; this is the only way to ask. */
+    if (on_seek(read_seek_tell_user_data, 0, ma_seek_origin_end) != MA_SUCCESS) {
+        return MA_ERROR;
+    }
+    ma_int64 size = 0;
+    /* The `size <= 0` half is belt and braces: stb_vorbis refuses a zero-length
+     * buffer on its own, so removing it survives the suite. It stays because
+     * `ma_malloc(0)` and a zero-length read are not worth reasoning about at
+     * every call site downstream. */
+    if (on_tell(read_seek_tell_user_data, &size) != MA_SUCCESS || size <= 0) {
+        return MA_ERROR;
+    }
+    if (on_seek(read_seek_tell_user_data, 0, ma_seek_origin_start) != MA_SUCCESS) {
+        return MA_ERROR;
+    }
+
+    void *compressed = ma_malloc((size_t)size, allocations);
+    if (!compressed) {
+        return MA_OUT_OF_MEMORY;
+    }
+
+    size_t got = 0;
+    if (on_read(read_seek_tell_user_data, compressed, (size_t)size, &got) != MA_SUCCESS ||
+        got != (size_t)size) {
+        ma_free(compressed, allocations);
+        return MA_ERROR;
+    }
+
+    rgame_vorbis_stream *stream = ma_malloc(sizeof(rgame_vorbis_stream), allocations);
+    if (!stream) {
+        ma_free(compressed, allocations);
+        return MA_OUT_OF_MEMORY;
+    }
+
+    int error = 0;
+    stream->vorbis = stb_vorbis_open_memory(compressed, (int)size, &error, NULL);
+    if (!stream->vorbis) {
+        ma_free(compressed, allocations);
+        ma_free(stream, allocations);
+        return MA_INVALID_FILE;
+    }
+
+    /* `compressed` is handed over here, not freed: stb_vorbis keeps pointing
+     * into it. */
+    return finish_open(stream, compressed, allocations, out);
+}
+
+static void vorbis_uninit(void *user_data, ma_data_source *source,
+                          const ma_allocation_callbacks *allocations) {
+    (void)user_data;
+    if (!source) {
+        return;
+    }
+
+    rgame_vorbis_stream *stream = (rgame_vorbis_stream *)source;
+
+    /* Close first, free second. Swapping them survives the suite and even the
+     * sanitizer, because stb_vorbis_close only releases its own allocations and
+     * never looks at the input buffer again — but that is a fact about today's
+     * stb_vorbis, not a promise, and the order that cannot be wrong costs
+     * nothing. */
+    stb_vorbis_close(stream->vorbis);
+    ma_free(stream->compressed, allocations); /* NULL when opened by filename */
+    ma_data_source_uninit(&stream->base);
+    ma_free(stream, allocations);
+}
+
+/*
+ * Both entry points, though only one is strictly required: with `onInitFile`
+ * absent miniaudio falls back to opening the file itself and calling `onInit`,
+ * so removing it survives the suite. It stays because that fallback buffers the
+ * whole compressed file, and opening by name lets stb_vorbis read from disk
+ * instead — which for a music track is a few megabytes not held in memory.
+ */
+ma_decoding_backend_vtable rgame_vorbis_decoding_backend = {
+    vorbis_init,
+    vorbis_init_file,
+    NULL, /* onInitFileW: the engine has no wide-character paths */
+    NULL, /* onInitMemory: nothing loads an ogg from a Ruby string yet */
+    vorbis_uninit
+};

data/ext/rgame_core/audio/vorbis_decoder.h

@@ -0,0 +1,45 @@
+#ifndef RGAME_VORBIS_DECODER_H
+#define RGAME_VORBIS_DECODER_H
+
+#include "vendor/miniaudio.h"
+
+/*
+ * Ogg Vorbis for miniaudio, over vendored stb_vorbis.
+ *
+ * miniaudio cannot read Ogg Vorbis. It decodes wav, mp3 and flac, and vorbis is
+ * expected to arrive as a *custom decoding backend* — a small vtable the caller
+ * registers. miniaudio ships a reference one, but it uses **system libvorbis**,
+ * which would hand back the very dependency the engine avoided by vendoring
+ * miniaudio in the first place — the whole reason miniaudio was chosen over
+ * SDL_mixer is that it needs nothing installed (vendor/README.md has the
+ * comparison). So this is that backend, over stb_vorbis, which is already here
+ * and adds no dependency either.
+ *
+ * ---------------------------------------------------------------------------
+ * Why there are two ways in
+ * ---------------------------------------------------------------------------
+ *
+ * A decoding backend can offer `onInitFile`, which is handed a path, and
+ * `onInit`, which is handed read/seek/tell callbacks. Both are needed, and
+ * finding that out is unpleasant: `ma_decoder_init_file` uses the first, but
+ * `ma_engine` — where voices, streaming and mixing live — reads everything
+ * through its own virtual file system and calls the second. A backend with only
+ * `onInitFile` loads perfectly through `ma_decoder` and then fails inside the
+ * engine with a bare `MA_INVALID_FILE` and no indication why.
+ *
+ * stb_vorbis has no callback-based open: it offers filename, memory, and a
+ * pushdata API. So the callback path reads the whole *compressed* file into
+ * memory and opens that. For a music track that is a few megabytes — against
+ * roughly forty for a full PCM decode of the same three minutes — and the
+ * pushdata API, which would avoid even that, is a great deal more machinery
+ * than the difference is worth.
+ */
+
+/*
+ * The backend to hand miniaudio, via `ma_decoder_config.ppCustomBackendVTables`
+ * or `ma_resource_manager_config.ppCustomDecodingBackendVTables`. Registering
+ * it is what makes every `.ogg` path in the engine work.
+ */
+extern ma_decoding_backend_vtable rgame_vorbis_decoding_backend;
+
+#endif /* RGAME_VORBIS_DECODER_H */

data/ext/rgame_core/example.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+# Manual/visual smoke test for the core extension (layer 3 — the real
+# SDL/GL path). Build it first, then run this from the project root:
+#
+#   make ext-core
+#   ruby ext/rgame_core/example.rb
+#
+# It opens a window with one of each drawing primitive in it. Arrow keys (or a
+# controller's dpad/stick) move the marker; Escape or closing the window quits.
+# This is the Ruby-side mirror of src/main.c, and it exists to exercise every
+# callback and every draw call the engine offers.
+#
+# Pass a sound file (Ogg Vorbis or WAV) to check audio as well:
+#
+#   ruby ext/rgame_core/example.rb assets/theme.ogg
+#
+# Space plays it as a one-shot sample, Return starts and stops it as looping
+# music. There is no asset here to default to, and that is on purpose: this is
+# the only place a *real* sound device is driven — every automated test runs
+# against a null or offline one — so what it is worth checking is your own
+# file, out of your own speakers.
+#
+# The load path points at lib/, not at this directory: `make ext-core`
+# copies the built core_ext.so to lib/rgame/, so this runs against exactly
+# the layout a user of the library would see.
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'rgame'
+require 'rgame/core'
+
+# An App subclass overrides only the hooks it needs; the rest are inherited
+# no-ops, so this class is the smallest useful driver of the engine.
+class Example < RGame::Core::App
+  Controls = RGame::Util::Controls
+  Color = RGame::Util::Color
+
+  RED = Color.new(224, 64, 64)
+  GREEN = Color.new(64, 224, 96)
+  BLUE = Color.new(64, 96, 224)
+  YELLOW = Color.new(224, 192, 64)
+  TRANSLUCENT_WHITE = Color.new(255, 255, 255, 128)
+
+  # Frozen and chosen between rather than built: #draw runs sixty times a
+  # second, and a string per frame is a garbage collection waiting to happen.
+  AUDIO_HINT_NONE = 'audio: pass a sound file on the command line to try it'
+  AUDIO_HINT_STOPPED = 'audio: Space plays a sample, Return starts the music'
+  AUDIO_HINT_PLAYING = 'audio: Space plays a sample, Return stops the music'
+
+  attr_reader :frames, :ticks, :cursor_x, :cursor_y
+
+  def initialize(sound_path = nil)
+    super(width: 800, height: 600, caption: 'rgame via Ruby')
+    @input = RGame::Core::Input.new(self)
+    @pads = RGame::Core::Gamepad.new(self)
+    @renderer = RGame::Core::Renderer.new(self)
+    @frames = 0
+    @ticks = 0
+    @cursor_x = 400.0
+    @cursor_y = 300.0
+    @spin = 0.0
+    @baked = nil
+    @device = Controls::KEYBOARD
+
+    # The device is opened whether or not there is anything to play through it,
+    # so that starting with no sound card takes the same path as starting with
+    # one. Nothing here is tied to the window: audio has no GL context and
+    # survives one being recreated.
+    @audio = RGame::Core::Audio.new
+    puts "audio backend: #{@audio.backend}"
+    return unless sound_path
+
+    @sample = RGame::Core::Sample.new(@audio, sound_path)
+    @song = RGame::Core::Song.new(@audio, sound_path)
+  end
+
+  # Once per frame, before the tick batch: pick which device to read. Doing it
+  # here rather than per tick is the pattern the engine is shaped around — one
+  # sample per frame, reused by however many catch-up ticks follow.
+  def frame_begin
+    # Poll rather than track: Gamepad answers straight from the engine, so
+    # there is no local copy of the connection state to keep in step.
+    @device = @pads.connected?(0) ? @pads.device(0) : Controls::KEYBOARD
+  end
+
+  # One fixed simulation tick. dt is always the engine's fixed step.
+  def update(dt)
+    @ticks += 1
+    @spin += dt * 45.0
+    speed = 200.0 * dt
+    @cursor_x -= speed if @input.down?(:left, device: @device)
+    @cursor_x += speed if @input.down?(:right, device: @device)
+    @cursor_y -= speed if @input.down?(:up, device: @device)
+    @cursor_y += speed if @input.down?(:down, device: @device)
+
+    # Analog sticks are additive on top of the dpad; the keyboard reads 0.0.
+    @cursor_x += @input.axis(:move_x, device: @device) * speed
+    @cursor_y += @input.axis(:move_y, device: @device) * speed
+  end
+
+  # One of everything, so a look at the window checks the whole drawing path.
+  # Colours are RGame::Util::Color values rather than arrays: a Color is frozen
+  # and allocates nothing when it is drawn, which is what per-frame code wants.
+  def draw
+    r = @renderer
+
+    # Baked on the first frame and replayed after that: forty rectangles cost
+    # one call per frame instead of forty. A real game bakes its tile layers
+    # this way. Recording has to happen inside #draw, which is why it is here
+    # rather than in initialize.
+    @baked ||= r.record do
+      40.times { |i| r.rect(i * 18, 0, 12, 12, color: GREEN, z: 0) }
+    end
+    # Scrolls with the same value the spinning square turns by, so it is
+    # visibly the *replay* moving and not a rebake.
+    @baked.draw((@spin % 18) - 18, 560)
+    r.rect(40, 40, 160, 100, color: RED, z: 0)
+    # Higher z wins wherever they overlap, whatever order the calls came in.
+    r.rect(120, 90, 160, 100, color: TRANSLUCENT_WHITE, z: 1)
+    r.triangle(400, 40, 480, 180, 320, 180, color: GREEN, z: 0)
+    r.circle(620, 110, 70, color: BLUE, z: 0)
+    r.line(40, 240, 760, 240, thickness: 6, color: YELLOW, z: 0)
+
+    # The transform stack: a square turning about its own centre.
+    r.rotated(@spin, 400, 380) { r.rect(340, 320, 120, 120, color: GREEN, z: 0) }
+
+    # The clip stack: the rectangle is twice the size of what shows.
+    r.clipped(60, 480, 200, 80) { r.rect(60, 440, 400, 160, color: RED, z: 0) }
+
+    # The cursor the arrow keys move.
+    r.debug_box(@cursor_x - 8, @cursor_y - 8, 16, 16)
+
+    # Text, including accents and punctuation the shipped font has to cover, so
+    # a look at the window checks kerning and coverage at once. The second line
+    # is centred using text_width, which is what a UI actually does with it.
+    r.text('rgame — Grüße, œuvre, 5 €', 40, 270, color: YELLOW)
+    label = format('%d fps', fps)
+    r.text(label, 400 - (r.text_width(label) / 2), 270 + r.text_height)
+    r.text(audio_status, 40, 270 + (r.text_height * 2), color: YELLOW)
+
+    @frames += 1
+  end
+
+  def button_down(id)
+    case id
+    when Controls::KEY_ESCAPE then close
+    # Held down, this is the overlap check: each press is another voice rather
+    # than a restart, so a fast run of them should pile up rather than stutter.
+    when Controls::KEY_SPACE then @sample&.play
+    when Controls::KEY_RETURN then toggle_music
+    end
+  end
+
+  # Return is a toggle, so one key covers both transitions and the "play after
+  # stop starts from the beginning" behaviour is audible by pressing it twice.
+  def toggle_music
+    return unless @song
+
+    @song.playing? ? @song.stop : @song.play(looping: true)
+  end
+
+  def audio_status
+    return AUDIO_HINT_NONE unless @song
+
+    @song.playing? ? AUDIO_HINT_PLAYING : AUDIO_HINT_STOPPED
+  end
+
+  # The callbacks are for reacting to the change; the polling above is for
+  # reading the current state. Slots are stable across a replug, so a pad that
+  # falls out and returns comes back as the same player.
+  def gamepad_connected(slot)
+    puts "controller connected in slot #{slot}: #{@pads.name(slot)}"
+  end
+
+  def gamepad_disconnected(slot)
+    puts "controller disconnected from slot #{slot}"
+  end
+
+  def resize(width, height)
+    puts "resized to #{width}x#{height}"
+  end
+end
+
+app = Example.new(ARGV[0])
+app.run
+
+puts format('drew %d frames, ran %d ticks, cursor at (%.1f, %.1f), last fps: %.1f',
+            app.frames, app.ticks, app.cursor_x, app.cursor_y, app.fps)

data/ext/rgame_core/extconf.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+# extconf.rb — run by `ruby extconf.rb` to generate a Makefile via mkmf.
+#
+# mkmf is Ruby's "make makefile" library. It probes the system (headers,
+# libraries, pkg-config) and writes a Makefile that knows how to compile a
+# loadable extension (`core_ext.so`) against the running Ruby's headers.
+# This is the same tool that `gem install` uses under the hood, which is why the
+# root Makefile was written to look like what mkmf emits — the mental model
+# carries straight over.
+#
+# This is the SDL/OpenGL half of the project: everything under RGame::Core.
+# The graphics-free half lives in ../rgame_util (RGame::Util) and links none of
+# these libraries.
+
+require 'mkmf'
+
+# The engine sources live in this directory rather than a top-level src/:
+# `gem install` unpacks the gem and runs this script, and an extension must be
+# buildable from its own directory.
+#
+# They are grouped into subdirectories by subsystem (app, graphics, text, input,
+# audio) plus ruby/ for the Ruby-facing glue and vendor/ for third-party code.
+# mkmf's default is to compile every .c in the extension's *own* directory and
+# nothing deeper, so the source list has to be spelled out — which is what
+# $srcs and $VPATH below do.
+#
+#   $srcs  — what to compile. mkmf names each object after the source's
+#            *basename*, so the .o files land flat in this directory no matter
+#            how deep the .c was. Basenames therefore have to be unique across
+#            the subdirectories; mkmf aborts with "source files duplication" if
+#            they ever aren't, so that rule enforces itself.
+#   $VPATH — where make looks for a source when a rule names it by basename.
+#            The generic `.c.o` rule mkmf emits does exactly that, so without
+#            this every object would come up as a missing prerequisite.
+#
+# vendor/ contributes only its <name>_impl.c translation units. The libraries
+# themselves are #included *by* those files (stb_vorbis even ships as a .c), so
+# compiling them separately would duplicate every symbol in them.
+SOURCE_DIRS = %w[app graphics text input audio ruby].freeze
+
+# Dir.glob sorts its results, so the object list is the same on every machine.
+$srcs = SOURCE_DIRS.flat_map { |dir| Dir.glob("#{$srcdir}/#{dir}/*.c") } +
+        Dir.glob("#{$srcdir}/vendor/*_impl.c")
+
+(SOURCE_DIRS + %w[vendor]).each { |dir| $VPATH << "$(srcdir)/#{dir}" }
+
+# The extension directory itself, so a cross-subsystem include names the folder
+# it comes from: graphics/canvas.c says `#include "graphics/clip.h"`, and text/
+# reaching into graphics/ is visible in the source rather than hidden in a
+# search path. It is also what resolves `#include "vendor/stb_image.h"`.
+# $(srcdir) stays literal here — make expands it, not Ruby.
+$INCFLAGS << ' -I$(srcdir)'
+
+# Public API header (include/rgame/core.h), so `#include "rgame/core.h"`
+# resolves.
+$INCFLAGS << ' -I$(srcdir)/include'
+
+# RGame::Util's colour header, for the RGBA byte order the renderer writes into
+# every vertex. It is header-only (static inline), so this creates no link
+# dependency between the two extensions — they stay separate .so files. Both
+# directories ship together in the gem, so the relative path holds there too.
+$INCFLAGS << ' -I$(srcdir)/../rgame_util'
+
+# SDL2: pkg_config("sdl2") shells out to pkg-config and folds the resulting
+# cflags and libs into mkmf's globals ($CFLAGS/$libs) for us. Returns nil if
+# SDL2 isn't found, so we can fail with a clear message instead of a confusing
+# later compile error.
+abort 'SDL2 not found (pkg-config --exists sdl2 failed). Install libsdl2-dev.' unless pkg_config('sdl2')
+
+# OpenGL + libm, matching the link line in the root Makefile. append_library
+# adds `-lGL`/`-lm` in the right spot on the link command.
+#
+# Checked rather than assumed, unlike in the root Makefile. This script is what
+# runs on someone else's machine during `gem install`, and a missing OpenGL
+# development package is a routine thing to hit there. Without a check it
+# surfaces as a linker error about an undefined `glClear` at the end of a long
+# build; with one, the install stops on a sentence naming the package to
+# install. Same reasoning as the SDL2 abort above.
+#
+# The header probed is the one the sources actually include — SDL's own
+# <SDL2/SDL_opengl.h>, which resolves to GL/gl.h or OpenGL/gl.h per platform, so
+# probing GL/gl.h directly would ask the wrong question off Linux. It needs
+# SDL's cflags, which pkg_config folded into $CFLAGS just above.
+abort 'SDL2 OpenGL header not found (SDL2/SDL_opengl.h). Install libsdl2-dev.' unless have_header('SDL2/SDL_opengl.h')
+
+# `-lGL` is how OpenGL is linked on Linux and the BSDs; macOS wants
+# `-framework OpenGL` instead. Only the first is implemented — as in the root
+# Makefile, which hardcodes -lGL — so this aborts on a platform it cannot link
+# rather than emitting undefined symbols for every gl* call. have_library
+# appends -lGL to $libs itself when the probe succeeds.
+unless have_library('GL', 'glClear')
+  abort 'OpenGL library not found (-lGL). Install libgl1-mesa-dev. ' \
+        '(macOS needs -framework OpenGL, which is not implemented yet.)'
+end
+
+$libs = append_library($libs, 'm')
+
+# miniaudio's threading, and the dlopen it uses to find ALSA or PulseAudio at
+# runtime — the property that makes audio cost no new system dependency. Both
+# live in glibc on Linux/BSD. Windows and macOS need neither, and appending them
+# unconditionally would fail the link there, so each is probed first.
+$libs = append_library($libs, 'pthread') if have_library('pthread')
+$libs = append_library($libs, 'dl') if have_library('dl')
+
+# Match the project's C standard and warning flags. Note: gnu17, not plain
+# c17 — Ruby's headers occasionally lean on GNU extensions, and gnu17 is a
+# superset of c17 so core.c (which targets c17) still compiles fine.
+$CFLAGS << ' -std=gnu17 -Wall -Wextra'
+
+# Emits the Makefile. "rgame/core_ext" -> loaded via
+# `require "rgame/core_ext"`, entry point Init_core_ext (the basename)
+# in core_ext.c. Namespacing it under rgame/ mirrors rgame/util_ext, keeps
+# both extensions off the top of the load path, and — importantly — leaves the
+# bare name "rgame" to lib/rgame.rb, which is the pure-Ruby entry point.
+create_makefile('rgame/core_ext')
+
+# The vendored implementations, compiled with warnings off (see
+# vendor/README.md). mkmf has no per-file flag setting, so the rules are
+# appended to the Makefile it just wrote. An explicit rule for a specific
+# target beats mkmf's generic .c.o suffix rule, so these are what get used for
+# those objects and nothing else.
+#
+# Written from one list rather than one block per library: a second hand-copied
+# rule is how the first one drifts. They are explicit rules rather than a `%`
+# pattern because mkmf's Makefiles are meant to work with whatever `make` the
+# platform has, and pattern rules are a GNU extension.
+#
+# `-w` comes last on the command line and switches every warning back off,
+# which is simpler and more robust than trying to subtract -Wall -Wextra from
+# $(CFLAGS) — everything else about how the extension compiles stays identical.
+# Each vendored library's implementation TU (<name>_impl.c) and the file it
+# instantiates. stb_vorbis is the odd one out: it ships as a .c, not a .h.
+VENDORED = {
+  'stb_image' => 'stb_image.h',
+  'stb_truetype' => 'stb_truetype.h',
+  'stb_vorbis' => 'stb_vorbis.c',
+  'miniaudio' => 'miniaudio.h'
+}.freeze
+
+File.open('Makefile', 'a') do |makefile|
+  VENDORED.each do |name, source|
+    makefile.puts <<~MAKE
+
+      #{name}_impl.#{$OBJEXT}: $(srcdir)/vendor/#{name}_impl.c $(srcdir)/vendor/#{source}
+      \t$(ECHO) compiling vendored #{name} with warnings off
+      \t$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) -w $(COUTFLAG)$@ -c $(srcdir)/vendor/#{name}_impl.c
+    MAKE
+  end
+
+  # Rebuild everything when any of our headers changes.
+  #
+  # mkmf emits `$(OBJS): $(HDRS)` for this, but it builds HDRS by globbing the
+  # extension's own directory only — with the headers a level down in
+  # graphics/, text/ and the rest, HDRS comes out empty and editing a header
+  # rebuilds *nothing*. That failure is silent: the build succeeds and links
+  # objects compiled against the previous version of the struct.
+  #
+  # One coarse dependency rather than a real per-object dependency scan, for the
+  # same reason the root Makefile treats the vendored sources as one list: this
+  # is a small project where a full rebuild costs seconds, and a hand-maintained
+  # dependency graph is a thing to get quietly wrong.
+  headers = SOURCE_DIRS.flat_map { |dir| Dir.glob("#{$srcdir}/#{dir}/*.h") }
+                       .map { |path| "$(srcdir)/#{path.delete_prefix("#{$srcdir}/")}" }
+
+  makefile.puts "\n$(OBJS): #{headers.join(' ')}"
+end