rgame 0.1.0

data/ext/rgame_core/vendor/stb_vorbis_impl.c

@@ -0,0 +1,29 @@
+/*
+ * stb_vorbis_impl.c — the one translation unit that instantiates stb_vorbis.
+ *
+ * The odd one out among the vendored implementation files: stb_vorbis ships as
+ * a `.c` rather than a `.h`. The split still works the same way, because it
+ * honours `STB_VORBIS_HEADER_ONLY` — this file includes it *without* that macro
+ * to emit the code, and vorbis_decoder.c includes it *with* the macro to get
+ * only the declarations. Without that split both translation units would define
+ * every symbol and the link would fail.
+ *
+ * Decoding only. stb_vorbis has a pushdata API for streaming from a callback,
+ * which the engine does not use — see vorbis_decoder.c for why it buffers the
+ * compressed file instead.
+ *
+ * Licence: stb_vorbis is public domain / MIT. See vendor/README.md.
+ */
+
+/*
+ * No integer-decode path: the decoder hands miniaudio 32-bit floats, which is
+ * what its data sources speak. It guards only the integer-output functions,
+ * none of which vorbis_decoder.c calls, so the declarations it sees without
+ * this macro still match what is compiled here.
+ */
+#define STB_VORBIS_NO_INTEGER_CONVERSION
+
+/* stdio stays in: opening by filename is one of the decoder's two entry
+ * points. */
+
+#include "vendor/stb_vorbis.c"

data/ext/rgame_util/color.c

@@ -0,0 +1,19 @@
+#include "color.h"
+
+static int clamp_component(int value) {
+    if (value < 0) {
+        return 0;
+    }
+    if (value > 255) {
+        return 255;
+    }
+    return value;
+}
+
+rgame_color rgame_color_rgba(int r, int g, int b, int a) {
+    return ((rgame_color)clamp_component(r) << 24) |
+           ((rgame_color)clamp_component(g) << 16) |
+           ((rgame_color)clamp_component(b) << 8) |
+           (rgame_color)clamp_component(a);
+}
+

data/ext/rgame_util/color.h

@@ -0,0 +1,60 @@
+#ifndef RGAME_COLOR_H
+#define RGAME_COLOR_H
+
+#include <stdint.h>
+
+/*
+ * RGBA colour packing — pure arithmetic, no Ruby, no SDL, no GL.
+ *
+ * A colour is a *value*: four bytes, no handle, nothing to release. That is why
+ * it lives in the graphics-free half of the project even though the renderer is
+ * its main consumer — the engine layer may hold Util values as attributes but
+ * may not name RGame::Core at all, so a colour in Core would be out of reach of
+ * the scene nodes that want to store one. See CLAUDE.md, "Value objects go in
+ * Util; only handle-owners go in Core".
+ *
+ * The packed form is 0xRRGGBBAA, which is how a human writes a colour and how
+ * `Color#packed` reads back.
+ */
+
+typedef uint32_t rgame_color;
+
+/* Components outside 0..255 are clamped, so this is total: there is no way to
+ * call it wrong. The Ruby wrapper is stricter and raises instead, because a
+ * Ruby caller passing 300 has a bug worth hearing about. */
+rgame_color rgame_color_rgba(int r, int g, int b, int a);
+
+/*
+ * The accessors are `static inline` in the header rather than functions in the
+ * .c, because the engine half of the project needs them too — the renderer
+ * writes these four bytes into every vertex. Core and Util are separate shared
+ * objects, so a real function would mean linking one into the other; an inline
+ * definition costs nothing and keeps a single source of truth for the byte
+ * order, which is the part that must not drift.
+ */
+static inline int rgame_color_r(rgame_color color) { return (int)((color >> 24) & 0xFFu); }
+static inline int rgame_color_g(rgame_color color) { return (int)((color >> 16) & 0xFFu); }
+static inline int rgame_color_b(rgame_color color) { return (int)((color >> 8) & 0xFFu); }
+static inline int rgame_color_a(rgame_color color) { return (int)(color & 0xFFu); }
+
+/*
+ * Writes the four components into `out` in R, G, B, A order — the order
+ * OpenGL reads them with glColorPointer(4, GL_UNSIGNED_BYTE, ...).
+ *
+ * Use this rather than copying the packed uint32 into a vertex. The two are not
+ * interchangeable: on a little-endian machine the bytes of 0xRRGGBBAA come out
+ * A, B, G, R, so GL would read the alpha as red. Going through bytes sidesteps
+ * the question entirely and is endian-independent.
+ */
+static inline void rgame_color_bytes(rgame_color color, unsigned char out[4]) {
+    out[0] = (unsigned char)rgame_color_r(color);
+    out[1] = (unsigned char)rgame_color_g(color);
+    out[2] = (unsigned char)rgame_color_b(color);
+    out[3] = (unsigned char)rgame_color_a(color);
+}
+
+#define RGAME_COLOR_WHITE ((rgame_color)0xFFFFFFFFu)
+#define RGAME_COLOR_BLACK ((rgame_color)0x000000FFu)
+#define RGAME_COLOR_TRANSPARENT ((rgame_color)0x00000000u)
+
+#endif /* RGAME_COLOR_H */

data/ext/rgame_util/color_ext.c

@@ -0,0 +1,156 @@
+/*
+ * color_ext.c — the Ruby binding for RGame::Util::Color.
+ *
+ * The arithmetic lives in color.{c,h}, which includes no ruby.h and is covered
+ * directly by the Check suite. This file is only the wrapper: argument
+ * checking, and the value semantics Ruby expects of a value object.
+ *
+ * Instances are frozen. A colour is a value, and a mutable one shared between
+ * two sprites would be a bug waiting for someone to tint one of them.
+ */
+
+#include "util_ext.h"
+
+#include "color.h"
+
+/*
+ * TypedData lets a Ruby object own a raw C value. The payload here is a single
+ * uint32, small enough that it could have been an instance variable — but
+ * going through TypedData keeps the unwrap a pointer read rather than an ivar
+ * lookup, and matches how every other C-backed class in the project is built.
+ */
+static const rb_data_type_t color_data_type = {
+    .wrap_struct_name = "rgame_color",
+    .function = {
+        .dmark = NULL, /* no Ruby objects inside */
+        .dfree = RUBY_TYPED_DEFAULT_FREE,
+        .dsize = NULL,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static rgame_color color_unwrap(VALUE self) {
+    rgame_color *color;
+    TypedData_Get_Struct(self, rgame_color, &color_data_type, color);
+    return *color;
+}
+
+static VALUE color_wrap(VALUE klass, rgame_color value) {
+    rgame_color *storage;
+    VALUE object = TypedData_Make_Struct(klass, rgame_color, &color_data_type, storage);
+    *storage = value;
+    return rb_obj_freeze(object);
+}
+
+/* Ruby is stricter than the C layer, which clamps: a Ruby caller passing 300
+ * has a bug, and silently turning it into 255 hides it. */
+static int component(VALUE value, const char *name) {
+    int number = NUM2INT(value);
+    if (number < 0 || number > 255) {
+        rb_raise(rb_eArgError, "%s must be in 0..255, got %d", name, number);
+    }
+    return number;
+}
+
+/* Color.new(r, g, b, a = 255) */
+static VALUE color_s_new(int argc, VALUE *argv, VALUE klass) {
+    VALUE r, g, b, a;
+    rb_scan_args(argc, argv, "31", &r, &g, &b, &a);
+
+    return color_wrap(klass,
+                      rgame_color_rgba(component(r, "red"), component(g, "green"),
+                                       component(b, "blue"),
+                                       NIL_P(a) ? 255 : component(a, "alpha")));
+}
+
+/* Color.from_packed(0xRRGGBBAA) */
+static VALUE color_s_from_packed(VALUE klass, VALUE packed) {
+    unsigned long value = NUM2ULONG(packed);
+    if (value > 0xFFFFFFFFul) {
+        rb_raise(rb_eArgError, "packed colour must fit in 32 bits");
+    }
+    return color_wrap(klass, (rgame_color)value);
+}
+
+/*
+ * Color.coerce(nil | [r,g,b] | [r,g,b,a] | Color) -> Color
+ *
+ * Every draw call accepts a colour in any of those forms, so the conversion
+ * lives in one place rather than being repeated in each primitive. nil means
+ * white, matching what an untinted draw has always meant.
+ */
+static VALUE color_s_coerce(VALUE klass, VALUE value) {
+    if (NIL_P(value)) {
+        return rb_const_get(klass, rb_intern("WHITE"));
+    }
+    if (rb_obj_is_kind_of(value, klass)) {
+        return value;
+    }
+    if (RB_TYPE_P(value, T_ARRAY)) {
+        long length = RARRAY_LEN(value);
+        if (length != 3 && length != 4) {
+            rb_raise(rb_eArgError, "colour array must be [r, g, b] or [r, g, b, a], got %ld elements",
+                     length);
+        }
+        VALUE alpha = length == 4 ? rb_ary_entry(value, 3) : INT2FIX(255);
+        VALUE args[4] = { rb_ary_entry(value, 0), rb_ary_entry(value, 1),
+                          rb_ary_entry(value, 2), alpha };
+        return color_s_new(4, args, klass);
+    }
+    rb_raise(rb_eTypeError, "cannot coerce %" PRIsVALUE " into a colour", rb_obj_class(value));
+}
+
+static VALUE color_r(VALUE self) { return INT2FIX(rgame_color_r(color_unwrap(self))); }
+static VALUE color_g(VALUE self) { return INT2FIX(rgame_color_g(color_unwrap(self))); }
+static VALUE color_b(VALUE self) { return INT2FIX(rgame_color_b(color_unwrap(self))); }
+static VALUE color_a(VALUE self) { return INT2FIX(rgame_color_a(color_unwrap(self))); }
+
+/* The 0xRRGGBBAA form. This is what the renderer hands to C — note it is *not*
+ * what goes into a vertex byte-for-byte; see rgame_color_bytes in color.h. */
+static VALUE color_packed(VALUE self) { return UINT2NUM(color_unwrap(self)); }
+
+/* Value semantics: two colours with the same components are the same colour,
+ * and eql?/hash follow so a Color works as a Hash key. */
+static VALUE color_equal(VALUE self, VALUE other) {
+    if (!rb_obj_is_kind_of(other, rb_obj_class(self))) {
+        return Qfalse;
+    }
+    return color_unwrap(self) == color_unwrap(other) ? Qtrue : Qfalse;
+}
+
+static VALUE color_hash(VALUE self) {
+    return rb_hash(UINT2NUM(color_unwrap(self)));
+}
+
+static VALUE color_inspect(VALUE self) {
+    rgame_color color = color_unwrap(self);
+    return rb_sprintf("#<RGame::Util::Color r=%d g=%d b=%d a=%d>", rgame_color_r(color),
+                      rgame_color_g(color), rgame_color_b(color), rgame_color_a(color));
+}
+
+void rgame_init_color(VALUE mUtil) {
+    VALUE cColor = rb_define_class_under(mUtil, "Color", rb_cObject);
+
+    /* No alloc func: a Color is always built through one of these, so there is
+     * no half-initialized state to guard against. */
+    rb_undef_alloc_func(cColor);
+    rb_define_singleton_method(cColor, "new", color_s_new, -1);
+    rb_define_singleton_method(cColor, "rgba", color_s_new, -1);
+    rb_define_singleton_method(cColor, "from_packed", color_s_from_packed, 1);
+    rb_define_singleton_method(cColor, "coerce", color_s_coerce, 1);
+
+    rb_define_method(cColor, "r", color_r, 0);
+    rb_define_method(cColor, "g", color_g, 0);
+    rb_define_method(cColor, "b", color_b, 0);
+    rb_define_method(cColor, "a", color_a, 0);
+    rb_define_method(cColor, "packed", color_packed, 0);
+    rb_define_method(cColor, "==", color_equal, 1);
+    rb_define_method(cColor, "eql?", color_equal, 1);
+    rb_define_method(cColor, "hash", color_hash, 0);
+    rb_define_method(cColor, "inspect", color_inspect, 0);
+    rb_define_alias(cColor, "to_s", "inspect");
+
+    rb_define_const(cColor, "WHITE", color_wrap(cColor, RGAME_COLOR_WHITE));
+    rb_define_const(cColor, "BLACK", color_wrap(cColor, RGAME_COLOR_BLACK));
+    rb_define_const(cColor, "TRANSPARENT", color_wrap(cColor, RGAME_COLOR_TRANSPARENT));
+}

data/ext/rgame_util/extconf.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# extconf.rb — mkmf script for the `rgame/util_ext` extension.
+#
+# This is the deliberately minimal half of the project's two extensions. Unlike
+# ext/rgame_core/extconf.rb (which links SDL2 + OpenGL for the engine), the
+# util extension is pure data: RGame::Util::Tensor and future pure-logic helpers
+# that must NOT drag SDL/GL into the process just to be required. So there is no
+# pkg_config, no -lGL — only the C standard + warning flags.
+#
+# That split is the rule for deciding where new code goes: anything depending on
+# SDL/OpenGL (or on something that does) belongs under RGame::Core in
+# ../rgame_core; everything else belongs here under RGame::Util.
+
+require 'mkmf'
+
+# Match the project's C standard and warning flags. gnu17 (not plain c17) because
+# Ruby's headers lean on GNU extensions; gnu17 is a superset so the code still
+# compiles as c17. Same choice as ext/rgame_core/extconf.rb.
+$CFLAGS << ' -std=gnu17 -Wall -Wextra'
+
+# "rgame/util_ext" -> the built object is loaded via `require "rgame/util_ext"`
+# and its entry point is Init_util_ext (the basename). Naming it under rgame/
+# (rather than plain "util_ext") keeps it namespaced alongside the engine's
+# rgame/core_ext.so and off the top of the load path, leaving the bare name
+# "rgame" to lib/rgame.rb.
+create_makefile('rgame/util_ext')

data/ext/rgame_util/tensor.c

@@ -0,0 +1,186 @@
+/*
+ * tensor.c — RGame::Util::Tensor, a C-backed re-implementation of what used to
+ * live in lib/rgame/util/tensor.rb.
+ *
+ * A fixed-size 3-D grid backed by a single flat C array, addressed as [x, y, z].
+ * Layout is x-fastest then y then z, so one z-slice ([*, *, z]) is a contiguous
+ * run — same layout the Ruby version documented.
+ *
+ * This is a *pure data* extension: it includes only <ruby.h>, never SDL/GL, so
+ * requiring it costs nothing but the Ruby object machinery. It is a separate
+ * .so from the SDL-linked engine extension for exactly that reason.
+ *
+ * The one genuinely C-extension-specific concern here is the garbage collector.
+ * Each cell holds an arbitrary Ruby object (nil, an Integer, a Symbol, ...). If
+ * we stash those VALUEs in a plain C array, the GC has no idea they're reachable
+ * and will happily collect them out from under us. TypedData lets us register a
+ * `mark` function so the GC walks our array and keeps every stored value alive.
+ */
+
+#include "util_ext.h"
+
+/*
+ * The C struct each RGame::Util::Tensor Ruby object wraps. `data` is a flat
+ * array of `size` VALUEs (size == plane * depth, plane == width * height).
+ * Dimensions are `long` to match Ruby's integer width and NUM2LONG.
+ */
+typedef struct {
+    long width;
+    long height;
+    long depth;
+    long plane; /* width * height — cached, one z-slice's worth of cells */
+    long size;  /* plane * depth — total cell count / length of `data` */
+    VALUE *data;
+} rgame_tensor;
+
+/*
+ * GC mark: tell the collector every Ruby object we're holding is still alive.
+ * Called during GC while this Tensor is reachable. rb_gc_mark_locations marks a
+ * contiguous [start, end) range of VALUEs in one call, which is exactly our
+ * layout. Guard against data == NULL for a half-initialized object (allocated
+ * but #initialize not yet run / failed).
+ */
+static void tensor_mark(void *ptr) {
+    rgame_tensor *t = ptr;
+    if (t->data) {
+        rb_gc_mark_locations(t->data, t->data + t->size);
+    }
+}
+
+/* Free the backing array and the struct itself when the Tensor is collected. */
+static void tensor_free(void *ptr) {
+    rgame_tensor *t = ptr;
+    xfree(t->data); /* xfree(NULL) is safe */
+    xfree(t);
+}
+
+/* Report how much memory we own, for ObjectSpace / GC accounting. */
+static size_t tensor_memsize(const void *ptr) {
+    const rgame_tensor *t = ptr;
+    return sizeof(rgame_tensor) + (t->data ? (size_t)t->size * sizeof(VALUE) : 0);
+}
+
+static const rb_data_type_t tensor_data_type = {
+    .wrap_struct_name = "RGame::Util::Tensor",
+    .function = {
+        .dmark = tensor_mark,
+        .dfree = tensor_free,
+        .dsize = tensor_memsize,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+/* Pull the C struct back out of a Tensor Ruby object. */
+static rgame_tensor *tensor_unwrap(VALUE self) {
+    rgame_tensor *t;
+    TypedData_Get_Struct(self, rgame_tensor, &tensor_data_type, t);
+    return t;
+}
+
+/*
+ * alloc: make the wrapper object with a zero-filled struct (TypedData_Make_Struct
+ * zeroes it), so data == NULL until #initialize allocates it. Splitting alloc
+ * from initialize is the standard Ruby way and means a failure mid-initialize
+ * still leaves a valid, freeable object.
+ */
+static VALUE tensor_alloc(VALUE klass) {
+    rgame_tensor *t;
+    return TypedData_Make_Struct(klass, rgame_tensor, &tensor_data_type, t);
+}
+
+/*
+ * RGame::Util::Tensor.new(width, height, depth, initial: nil)
+ *
+ * rb_scan_args "30:" = 3 required positional args plus a trailing keyword/options
+ * hash (the ":"). We read :initial out of that hash; an absent key yields nil via
+ * rb_hash_aref, which matches the Ruby default of `initial: nil`.
+ */
+static VALUE tensor_initialize(int argc, VALUE *argv, VALUE self) {
+    VALUE width, height, depth, opts;
+    rb_scan_args(argc, argv, "30:", &width, &height, &depth, &opts);
+
+    long w = NUM2LONG(width);
+    long h = NUM2LONG(height);
+    long d = NUM2LONG(depth);
+    if (w < 0 || h < 0 || d < 0) {
+        rb_raise(rb_eArgError, "tensor dimensions must be non-negative");
+    }
+
+    VALUE initial = Qnil;
+    if (!NIL_P(opts)) {
+        initial = rb_hash_aref(opts, ID2SYM(rb_intern("initial")));
+    }
+
+    rgame_tensor *t = tensor_unwrap(self);
+    t->width = w;
+    t->height = h;
+    t->depth = d;
+    t->plane = w * h;
+    t->size = t->plane * d;
+    t->data = ALLOC_N(VALUE, t->size); /* ALLOC_N(_, 0) returns a valid pointer */
+    for (long i = 0; i < t->size; i++) {
+        t->data[i] = initial;
+    }
+
+    return self;
+}
+
+/*
+ * Flat index for [x, y, z], with bounds checking. The Ruby version leaned on
+ * Array#[] semantics (nil past the end, negative-index wrap); on a raw C array
+ * those would be out-of-bounds reads, so instead we range-check every coordinate
+ * and raise IndexError — a clean, safe contract for a fixed-size grid.
+ */
+static long tensor_offset(rgame_tensor *t, VALUE x, VALUE y, VALUE z) {
+    long xi = NUM2LONG(x);
+    long yi = NUM2LONG(y);
+    long zi = NUM2LONG(z);
+    if (xi < 0 || xi >= t->width ||
+        yi < 0 || yi >= t->height ||
+        zi < 0 || zi >= t->depth) {
+        rb_raise(rb_eIndexError,
+                 "index (%ld, %ld, %ld) out of bounds for tensor "
+                 "(%ld, %ld, %ld)",
+                 xi, yi, zi, t->width, t->height, t->depth);
+    }
+    return (zi * t->plane) + (yi * t->width) + xi;
+}
+
+static VALUE tensor_aref(VALUE self, VALUE x, VALUE y, VALUE z) {
+    rgame_tensor *t = tensor_unwrap(self);
+    return t->data[tensor_offset(t, x, y, z)];
+}
+
+static VALUE tensor_aset(VALUE self, VALUE x, VALUE y, VALUE z, VALUE value) {
+    rgame_tensor *t = tensor_unwrap(self);
+    t->data[tensor_offset(t, x, y, z)] = value;
+    return value; /* Ruby returns the assigned value from []= regardless */
+}
+
+static VALUE tensor_width(VALUE self) {
+    return LONG2NUM(tensor_unwrap(self)->width);
+}
+
+static VALUE tensor_height(VALUE self) {
+    return LONG2NUM(tensor_unwrap(self)->height);
+}
+
+static VALUE tensor_depth(VALUE self) {
+    return LONG2NUM(tensor_unwrap(self)->depth);
+}
+
+/*
+ * Class init, called by Init_util_ext in util_ext.c. Splitting the entry point
+ * out means adding another Util class does not mean editing this file.
+ */
+void rgame_init_tensor(VALUE mUtil) {
+    VALUE cTensor = rb_define_class_under(mUtil, "Tensor", rb_cObject);
+
+    rb_define_alloc_func(cTensor, tensor_alloc);
+    rb_define_method(cTensor, "initialize", tensor_initialize, -1);
+    rb_define_method(cTensor, "[]", tensor_aref, 3);
+    rb_define_method(cTensor, "[]=", tensor_aset, 4);
+    rb_define_method(cTensor, "width", tensor_width, 0);
+    rb_define_method(cTensor, "height", tensor_height, 0);
+    rb_define_method(cTensor, "depth", tensor_depth, 0);
+}

data/ext/rgame_util/util_ext.c

@@ -0,0 +1,27 @@
+/*
+ * util_ext.c — entry point for the graphics-free extension.
+ *
+ * Ruby calls Init_<basename of the required path> when the .so is loaded; we
+ * require it as "rgame/util_ext", so this must be Init_util_ext, matching
+ * create_makefile("rgame/util_ext") in extconf.rb.
+ *
+ * Its only job is to hand the RGame::Util module to each class's init
+ * function. Nothing here links SDL or OpenGL, and nothing ever should: the
+ * whole point of this extension is that `require "rgame"` costs no graphics
+ * libraries. See CLAUDE.md, "The Core / Util split".
+ */
+
+#include "util_ext.h"
+
+void Init_util_ext(void) {
+    /*
+     * rb_define_module is idempotent — it returns the existing RGame if some
+     * other extension or Ruby file defined it first, so load order between the
+     * two extensions doesn't matter.
+     */
+    VALUE mRGame = rb_define_module("RGame");
+    VALUE mUtil = rb_define_module_under(mRGame, "Util");
+
+    rgame_init_tensor(mUtil);
+    rgame_init_color(mUtil);
+}

data/ext/rgame_util/util_ext.h

@@ -0,0 +1,16 @@
+#ifndef RGAME_UTIL_EXT_H
+#define RGAME_UTIL_EXT_H
+
+#include <ruby.h>
+
+/*
+ * Each Ruby-visible class in this extension exposes one init function, and
+ * util_ext.c calls them all. Adding a class means adding a file and one line
+ * there — rather than editing an unrelated class's file, which is where
+ * Init_util_ext used to live.
+ */
+
+void rgame_init_tensor(VALUE mUtil);
+void rgame_init_color(VALUE mUtil);
+
+#endif /* RGAME_UTIL_EXT_H */

data/lib/rgame/boot.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Turns on YJIT, Ruby's JIT compiler, for a meaningful speedup in the game loop.
+#
+# Required by RGame::Game rather than left to each game to remember, because a
+# game loop is the case JIT was built for and forgetting costs frames silently.
+# It is deliberately *not* required by `rgame` or `rgame/core`: enabling a JIT
+# is a decision about the whole process, and a library has no business making
+# it for a host that only wanted a Color.
+#
+# Guarded, so the project still runs on a Ruby built without YJIT — it just runs
+# unaccelerated instead of crashing.
+RubyVM::YJIT.enable if defined?(RubyVM::YJIT) && RubyVM::YJIT.respond_to?(:enable)

data/lib/rgame/core/app.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# RGame::Core::App is implemented in C — see ext/rgame_core/. It wraps the
+# engine's public API (ext/rgame_core/include/rgame/core.h): an SDL window plus
+# OpenGL context, and a fixed-timestep main loop that drives callbacks.
+#
+# App is meant to be subclassed. The engine calls back into methods on the
+# object itself, so a game overrides the hooks it needs and inherits no-ops for
+# the rest:
+#
+#   class MyGame < RGame::Core::App
+#     def initialize = super(width: 800, height: 600, caption: 'my game')
+#
+#     def frame_begin; end     # once per frame, before that frame's ticks
+#     def update(dt); end      # one fixed simulation tick; dt is always the
+#                              # fixed step, never wall-clock frame time
+#     def needs_redraw?; end   # false skips the draw (simulation still runs)
+#     def draw; end            # render one frame
+#     def button_down(id); end # discrete key press (no repeats)
+#     def button_up(id); end
+#     def resize(w, h); end
+#   end
+#
+#   MyGame.new.run
+#
+# Also inherited: #close (stops the loop; safe from inside a callback), #width,
+# #height, #caption, #caption=, #ticks_ms (monotonic ms since startup) and #fps.
+#
+# The loop owns the fixed-timestep accumulator, so #update is called once per
+# whole tick and may run zero or several times per rendered frame. #frame_begin
+# is the place to sample input once and reuse it across every tick of that
+# frame.
+#
+# If a callback raises, the exception is carried out of #run with its original
+# class, message and backtrace, and the loop shuts down cleanly first. A
+# non-local exit (throw/break/return) out of a callback cannot be carried
+# across the C loop and is reported as a RuntimeError instead — use #close to
+# stop the loop.
+#
+# Loading this .so pulls SDL2 and OpenGL into the process — see
+# lib/rgame/core.rb for why that's kept off the default `require "rgame"`.
+# It loads from lib/rgame/core_ext.so, which the build (`make ext-core`)
+# copies out of ext/rgame_core/.
+require 'rgame/core_ext'
+
+module RGame
+  module Core
+    # The two things a game needs one of, owned by the app that needs them and
+    # built on first use.
+    #
+    # Lazily, and that is the point on both counts: an app that draws only
+    # primitives builds no asset manager, and one that never plays a sound never
+    # opens a device — which is also the right moment to open it, since asking
+    # for a sound is the first thing that needs one.
+    class App
+      # This app's asset manager, rooted at the `media_root:` it was made with.
+      #
+      #   class MyGame < RGame::Core::App
+      #     def initialize = super(width: 640, height: 480, caption: 'demo', media_root: MEDIA)
+      #   end
+      #
+      #   app.assets.image('space.png')
+      #
+      # A game never constructs one. An `Image` belongs to one GL context and
+      # has to be told which, so *something* has to hold the app — and since the
+      # asset manager is the only thing in the engine that loads from a path,
+      # that something is here, once, rather than threaded through every
+      # constructor that ends up owning an image.
+      def assets = @assets ||= AssetManager.new(root: @media_root, app: self)
+
+      # This app's sound device. Not tied to the window in any way — audio has
+      # no GL context and survives one being recreated — it lives here because
+      # a game wants exactly one, the same way it wants one asset manager.
+      def audio = @audio ||= Audio.new
+
+      # Where #assets resolves relative paths from. Set once, as a keyword to
+      # the constructor; there is deliberately no writer, because changing it
+      # after an asset has loaded would leave a cache keyed against two roots.
+      attr_reader :media_root
+    end
+  end
+end