rgame 0.2.0 → 0.3.0

data/ext/rgame_util/solid_grid.c

@@ -0,0 +1,58 @@
+/*
+ * solid_grid.c — the solidity store of a tile grid. Pure; see solid_grid.h.
+ */
+
+#include "solid_grid.h"
+
+#include <stdlib.h>
+
+bool rgame_solid_grid_size_ok(int64_t width, int64_t height) {
+    return width >= 0 && height >= 0 && (height == 0 || width <= INT32_MAX / height);
+}
+
+bool rgame_solid_grid_init(rgame_solid_grid *grid, int32_t width, int32_t height) {
+    if (!rgame_solid_grid_size_ok(width, height)) {
+        return false;
+    }
+    size_t count = (size_t)width * (size_t)height;
+    uint8_t *cells = NULL;
+    if (count > 0) {
+        cells = calloc(count, 1);
+        if (!cells) {
+            return false;
+        }
+    }
+    grid->width = width;
+    grid->height = height;
+    grid->cells = cells;
+    grid->revision = 0;
+    return true;
+}
+
+void rgame_solid_grid_free(rgame_solid_grid *grid) {
+    free(grid->cells);
+    grid->cells = NULL;
+    grid->width = 0;
+    grid->height = 0;
+}
+
+bool rgame_solid_grid_inside(const rgame_solid_grid *grid, int32_t col, int32_t row) {
+    return col >= 0 && row >= 0 && col < grid->width && row < grid->height;
+}
+
+bool rgame_solid_grid_solid(const rgame_solid_grid *grid, int32_t col, int32_t row) {
+    return rgame_solid_grid_inside(grid, col, row) && grid->cells[row * grid->width + col];
+}
+
+bool rgame_solid_grid_set(rgame_solid_grid *grid, int32_t col, int32_t row, bool solid) {
+    if (!rgame_solid_grid_inside(grid, col, row)) {
+        return false;
+    }
+    uint8_t *cell = &grid->cells[row * grid->width + col];
+    uint8_t value = solid ? 1 : 0;
+    if (*cell != value) {
+        *cell = value;
+        grid->revision++;
+    }
+    return true;
+}

data/ext/rgame_util/solid_grid.h

@@ -0,0 +1,49 @@
+#ifndef RGAME_SOLID_GRID_H
+#define RGAME_SOLID_GRID_H
+
+#include <stdbool.h>
+#include <stdint.h>
+
+/*
+ * Which cells of a tile grid are solid — pure, no Ruby, no SDL, no GL.
+ *
+ * This is the one store of a tile world's solidity: the blockers that stop a
+ * walker and the route search that plans one both read it, so a cell changed
+ * here is changed for both at once and the two cannot disagree about a wall.
+ *
+ * `revision` is how a reader that keeps something derived from the cells (a
+ * search's region labels) knows the cells have moved under it. It changes on
+ * every write that changes a cell and on no other, so a derived value keyed to
+ * it is rebuilt exactly when it has to be.
+ *
+ * Anything outside the grid is open, which is what a tile map answers past its
+ * edges.
+ */
+
+typedef struct {
+    int32_t width;
+    int32_t height;
+    uint8_t *cells;    /* width * height, row-major; 1 solid, 0 open */
+    uint64_t revision; /* moves whenever a cell changes, and only then — and 64
+                          bits, so it never wraps back onto a value a reader kept */
+} rgame_solid_grid;
+
+/* Whether a grid of this size can exist: neither side negative, and the cell
+ * count within int32_t, so every in-bounds flat index fits the type the search
+ * stores. Zero on either side is a valid, empty grid. */
+bool rgame_solid_grid_size_ok(int64_t width, int64_t height);
+
+/* Every cell open, revision 0. False — with nothing to free — for a size that is
+ * not ok or when allocation fails. */
+bool rgame_solid_grid_init(rgame_solid_grid *grid, int32_t width, int32_t height);
+void rgame_solid_grid_free(rgame_solid_grid *grid);
+
+bool rgame_solid_grid_inside(const rgame_solid_grid *grid, int32_t col, int32_t row);
+
+/* False outside the grid. */
+bool rgame_solid_grid_solid(const rgame_solid_grid *grid, int32_t col, int32_t row);
+
+/* False, changing nothing, for a cell outside the grid. */
+bool rgame_solid_grid_set(rgame_solid_grid *grid, int32_t col, int32_t row, bool solid);
+
+#endif /* RGAME_SOLID_GRID_H */

data/ext/rgame_util/solid_grid_ext.c

@@ -0,0 +1,161 @@
+/*
+ * solid_grid_ext.c — the Ruby binding for RGame::Util::SolidGrid.
+ *
+ * The store lives in solid_grid.{c,h}, which includes no ruby.h and is covered
+ * directly by the Check suite. This file is argument checking and wrapping.
+ *
+ * A grid's size is fixed at construction and there is no allocator to reach it
+ * any other way: a RouteSearch keeps a pointer into the grid it was built over,
+ * sized to its cells, so a grid that could be re-initialized or copied into a
+ * different size would leave that search indexing past the end.
+ */
+
+#include "util_ext.h"
+
+#include "solid_grid.h"
+
+static long live_grids = 0;
+
+static void solid_grid_free(void *ptr) {
+    rgame_solid_grid_free(ptr);
+    xfree(ptr);
+    live_grids--;
+}
+
+static size_t solid_grid_memsize(const void *ptr) {
+    const rgame_solid_grid *grid = ptr;
+    return sizeof(*grid) + (size_t)grid->width * (size_t)grid->height;
+}
+
+static const rb_data_type_t solid_grid_data_type = {
+    .wrap_struct_name = "rgame_solid_grid",
+    .function = {
+        .dmark = NULL, /* no Ruby objects inside */
+        .dfree = solid_grid_free,
+        .dsize = solid_grid_memsize,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+rgame_solid_grid *rgame_util_solid_grid(VALUE value) {
+    return rb_check_typeddata(value, &solid_grid_data_type);
+}
+
+/*
+ * A cell coordinate: an Integer, or a TypeError. An Integer too large for the
+ * grid's index type is not an error but a cell outside the grid, answered like
+ * any other — which is why a Bignum is checked for before converting, where
+ * NUM2INT would raise RangeError instead.
+ */
+bool rgame_util_cell_coordinate(VALUE value, int32_t *out) {
+    if (FIXNUM_P(value)) {
+        long long number = NUM2LL(value);
+        if (number < INT32_MIN || number > INT32_MAX) {
+            return false;
+        }
+        *out = (int32_t)number;
+        return true;
+    }
+    if (RB_TYPE_P(value, T_BIGNUM)) {
+        return false;
+    }
+    rb_raise(rb_eTypeError, "a cell coordinate must be an Integer, got %" PRIsVALUE,
+             rb_obj_class(value));
+}
+
+static int64_t dimension(VALUE value, const char *name) {
+    if (RB_TYPE_P(value, T_BIGNUM)) {
+        rb_raise(rb_eArgError, "%s is too large for a grid", name);
+    }
+    if (!FIXNUM_P(value)) {
+        rb_raise(rb_eTypeError, "%s must be an Integer, got %" PRIsVALUE, name, rb_obj_class(value));
+    }
+    return NUM2LL(value);
+}
+
+/* SolidGrid.new(width, height) — every cell open.
+ *
+ * Refuses a negative size, and one whose cell count passes 2**31 - 1, with
+ * ArgumentError. A zero size is an empty grid with no inside. */
+static VALUE solid_grid_s_new(VALUE klass, VALUE width_value, VALUE height_value) {
+    int64_t width = dimension(width_value, "width");
+    int64_t height = dimension(height_value, "height");
+    if (width < 0 || height < 0) {
+        rb_raise(rb_eArgError, "a grid cannot be %lldx%lld", (long long)width, (long long)height);
+    }
+    if (!rgame_solid_grid_size_ok(width, height)) {
+        rb_raise(rb_eArgError, "a %lldx%lld grid has more cells than it can index", (long long)width,
+                 (long long)height);
+    }
+
+    rgame_solid_grid *grid;
+    VALUE object = TypedData_Make_Struct(klass, rgame_solid_grid, &solid_grid_data_type, grid);
+    live_grids++;
+    if (!rgame_solid_grid_init(grid, (int32_t)width, (int32_t)height)) {
+        rb_memerror();
+    }
+    return object;
+}
+
+static VALUE solid_grid_width(VALUE self) { return INT2NUM(rgame_util_solid_grid(self)->width); }
+static VALUE solid_grid_height(VALUE self) { return INT2NUM(rgame_util_solid_grid(self)->height); }
+
+/* A count of the changes made to the grid: it moves whenever a cell changes and
+ * only then, so something derived from the cells can tell whether it is stale. */
+static VALUE solid_grid_revision(VALUE self) {
+    return ULL2NUM(rgame_util_solid_grid(self)->revision);
+}
+
+/* solid?(col, row) — false outside the grid. */
+static VALUE solid_grid_solid_p(VALUE self, VALUE col_value, VALUE row_value) {
+    int32_t col = 0;
+    int32_t row = 0;
+    bool col_fits = rgame_util_cell_coordinate(col_value, &col);
+    bool row_fits = rgame_util_cell_coordinate(row_value, &row);
+    return col_fits && row_fits && rgame_solid_grid_solid(rgame_util_solid_grid(self), col, row)
+               ? Qtrue
+               : Qfalse;
+}
+
+/* set_solid(col, row, solid) — raises IndexError for a cell outside the grid,
+ * since a write that silently went nowhere is a wall that is not there. */
+static VALUE solid_grid_set_solid(VALUE self, VALUE col_value, VALUE row_value, VALUE solid) {
+    int32_t col = 0;
+    int32_t row = 0;
+    bool col_fits = rgame_util_cell_coordinate(col_value, &col);
+    bool row_fits = rgame_util_cell_coordinate(row_value, &row);
+    rgame_solid_grid *grid = rgame_util_solid_grid(self);
+    if (!col_fits || !row_fits || !rgame_solid_grid_set(grid, col, row, RTEST(solid))) {
+        rb_raise(rb_eIndexError, "cell (%" PRIsVALUE ", %" PRIsVALUE ") is outside a %dx%d grid",
+                 col_value, row_value, grid->width, grid->height);
+    }
+    return solid;
+}
+
+static VALUE solid_grid_inspect(VALUE self) {
+    rgame_solid_grid *grid = rgame_util_solid_grid(self);
+    return rb_sprintf("#<%" PRIsVALUE " %dx%d revision=%llu>", rb_obj_class(self), grid->width,
+                      grid->height, (unsigned long long)grid->revision);
+}
+
+/* SolidGrid.debug_live_grids — how many grids are holding cells. Test-only, and
+ * named so: it is what lets a spec see a grid's cells freed with it. */
+static VALUE solid_grid_s_debug_live_grids(VALUE klass) {
+    (void)klass;
+    return LONG2NUM(live_grids);
+}
+
+void rgame_init_solid_grid(VALUE mUtil) {
+    VALUE cSolidGrid = rb_define_class_under(mUtil, "SolidGrid", rb_cObject);
+
+    rb_undef_alloc_func(cSolidGrid);
+    rb_define_singleton_method(cSolidGrid, "new", solid_grid_s_new, 2);
+    rb_define_singleton_method(cSolidGrid, "debug_live_grids", solid_grid_s_debug_live_grids, 0);
+
+    rb_define_method(cSolidGrid, "width", solid_grid_width, 0);
+    rb_define_method(cSolidGrid, "height", solid_grid_height, 0);
+    rb_define_method(cSolidGrid, "revision", solid_grid_revision, 0);
+    rb_define_method(cSolidGrid, "solid?", solid_grid_solid_p, 2);
+    rb_define_method(cSolidGrid, "set_solid", solid_grid_set_solid, 3);
+    rb_define_method(cSolidGrid, "inspect", solid_grid_inspect, 0);
+}

data/ext/rgame_util/tile_sweep.c

@@ -0,0 +1,164 @@
+/*
+ * tile_sweep.c — a box against a solid grid's tiles. Pure; see tile_sweep.h.
+ */
+
+#include "tile_sweep.h"
+
+#include <math.h>
+
+#ifdef __clang__
+#pragma STDC FP_CONTRACT OFF
+#endif
+
+/* How far inside an edge a box's far side is measured, so a box resting flush
+ * against a tile does not count as overlapping it. */
+static const double EDGE_EPS = 1e-9;
+
+/* A travel window's stride, as a fraction of a tile. A window spans two strides. */
+static const double STRIDE = 0.25;
+
+static bool tile_index(double edge, double tile_size, int32_t count, int32_t *out) {
+    double index = floor(edge / tile_size);
+    if (!(index >= 0.0 && index < (double)count)) {
+        return false;
+    }
+    *out = (int32_t)index;
+    return true;
+}
+
+static bool tile_span(double near_edge, double far_edge, double tile_size, int32_t count, int32_t *first,
+                      int32_t *last) {
+    double low = floor(near_edge / tile_size);
+    double high = floor(far_edge / tile_size);
+    if (isnan(low) || isnan(high)) {
+        return false;
+    }
+    if (low < 0.0) {
+        low = 0.0;
+    }
+    if (high > (double)count - 1.0) {
+        high = (double)count - 1.0;
+    }
+    if (low > high) {
+        return false;
+    }
+    *first = (int32_t)low;
+    *last = (int32_t)high;
+    return true;
+}
+
+static bool solid_in_column(const rgame_solid_grid *grid, int32_t col, int32_t first_row, int32_t last_row) {
+    for (int32_t row = first_row; row <= last_row; row++) {
+        if (grid->cells[row * grid->width + col]) {
+            return true;
+        }
+    }
+    return false;
+}
+
+static bool solid_in_row(const rgame_solid_grid *grid, int32_t row, int32_t first_col, int32_t last_col) {
+    for (int32_t col = first_col; col <= last_col; col++) {
+        if (grid->cells[row * grid->width + col]) {
+            return true;
+        }
+    }
+    return false;
+}
+
+double rgame_tile_sweep_resolve_x(const rgame_tile_sweep *sweep, double x, double y, double w, double h,
+                                  double dx) {
+    double landed = x + dx;
+    if (dx == 0.0) {
+        return landed;
+    }
+
+    const rgame_solid_grid *grid = sweep->grid;
+    int32_t first_row = 0;
+    int32_t last_row = 0;
+    if (!tile_span(y, y + h - EDGE_EPS, sweep->tile_height, grid->height, &first_row, &last_row)) {
+        return landed;
+    }
+
+    int32_t col = 0;
+    if (dx > 0.0) {
+        if (tile_index(landed + w - EDGE_EPS, sweep->tile_width, grid->width, &col) &&
+            solid_in_column(grid, col, first_row, last_row)) {
+            return col * sweep->tile_width - w;
+        }
+    } else if (tile_index(landed, sweep->tile_width, grid->width, &col) &&
+               solid_in_column(grid, col, first_row, last_row)) {
+        return (col + 1) * sweep->tile_width;
+    }
+    return landed;
+}
+
+double rgame_tile_sweep_resolve_y(const rgame_tile_sweep *sweep, double x, double y, double w, double h,
+                                  double dy) {
+    double landed = y + dy;
+    if (dy == 0.0) {
+        return landed;
+    }
+
+    const rgame_solid_grid *grid = sweep->grid;
+    int32_t first_col = 0;
+    int32_t last_col = 0;
+    if (!tile_span(x, x + w - EDGE_EPS, sweep->tile_width, grid->width, &first_col, &last_col)) {
+        return landed;
+    }
+
+    int32_t row = 0;
+    if (dy > 0.0) {
+        if (tile_index(landed + h - EDGE_EPS, sweep->tile_height, grid->height, &row) &&
+            solid_in_row(grid, row, first_col, last_col)) {
+            return row * sweep->tile_height - h;
+        }
+    } else if (tile_index(landed, sweep->tile_height, grid->height, &row) &&
+               solid_in_row(grid, row, first_col, last_col)) {
+        return (row + 1) * sweep->tile_height;
+    }
+    return landed;
+}
+
+/* Short of the intended landing: behind it, in the direction of travel. A
+ * landing past it is not short, which is how CollisionSystem reads a source. */
+static bool short_of(double landed, double intended, double delta) {
+    return delta > 0.0 ? landed < intended : delta < 0.0 && landed > intended;
+}
+
+static bool window_clear(const rgame_tile_sweep *sweep, double x, double y, double w, double h, double dx,
+                         double dy) {
+    return !short_of(rgame_tile_sweep_resolve_x(sweep, x, y, w, h, dx), x + dx, dx) &&
+           !short_of(rgame_tile_sweep_resolve_y(sweep, x + dx, y, w, h, dy), y + dy, dy) &&
+           !short_of(rgame_tile_sweep_resolve_y(sweep, x, y, w, h, dy), y + dy, dy) &&
+           !short_of(rgame_tile_sweep_resolve_x(sweep, x, y + dy, w, h, dx), x + dx, dx);
+}
+
+double rgame_tile_sweep_travel_windows(const rgame_tile_sweep *sweep, double dx, double dy) {
+    double across = ceil(fabs(dx) / (sweep->tile_width * STRIDE));
+    double down = ceil(fabs(dy) / (sweep->tile_height * STRIDE));
+    if (isnan(across) || isnan(down)) {
+        return NAN;
+    }
+    double steps = across > down ? across : down;
+    return steps > 1.0 ? steps : 1.0;
+}
+
+bool rgame_tile_sweep_travel(const rgame_tile_sweep *sweep, double x, double y, double w, double h, double dx,
+                             double dy) {
+    double steps = rgame_tile_sweep_travel_windows(sweep, dx, dy);
+    if (!(steps <= (double)INT32_MAX)) {
+        return false;
+    }
+    int32_t count = (int32_t)steps;
+    double step_x = dx / count;
+    double step_y = dy / count;
+    int32_t span = count < 2 ? count : 2;
+
+    for (int32_t sample = 0; sample <= count - span; sample++) {
+        if (!window_clear(sweep, x + step_x * sample, y + step_y * sample, w, h, step_x * span,
+                          step_y * span)) {
+            return false;
+        }
+    }
+    return true;
+}

data/ext/rgame_util/tile_sweep.h

@@ -0,0 +1,62 @@
+#ifndef RGAME_TILE_SWEEP_H
+#define RGAME_TILE_SWEEP_H
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#include "solid_grid.h"
+
+/*
+ * An axis-aligned box against the solid tiles of a grid — pure, no Ruby, no
+ * SDL, no GL.
+ *
+ * Two questions, answered by one piece of arithmetic so they cannot disagree:
+ *
+ * - **Resolve**: where does the box's left (top) edge land moving dx (dy)? A
+ *   step that would enter a solid tile snaps the box flush against that tile's
+ *   edge. Each axis is resolved on its own; feeding one axis the other's result
+ *   (and so sliding along walls) is the caller's order to choose.
+ * - **Travel**: can the box move by (dx, dy) without any resolve along the way
+ *   falling short of where it was heading? This is how a route is checked
+ *   against the same resolver that will stop the walker on it.
+ *
+ * Resolving assumes a step smaller than a tile: a longer one can pass through a
+ * tile without seeing it. Travel is built for exactly that limit. It sweeps the
+ * box in overlapping windows half a tile long at a quarter-tile stride, and
+ * resolves each window X-then-Y and Y-then-X. Both orders together cover every
+ * position between a window's ends, and the overlap covers a walker's own
+ * X-then-Y step straddling two windows — so travel is sound for a walker whose
+ * step is under a quarter tile.
+ *
+ * Anything outside the grid is open. Tile ranges are clamped to the grid before
+ * any conversion to an integer, so no coordinate, however large, is undefined
+ * behaviour or a long loop. A NaN coordinate reads as open ground; callers that
+ * need to refuse one (the Ruby binding does) check before calling.
+ */
+
+typedef struct {
+    const rgame_solid_grid *grid; /* must outlive the sweep */
+    double tile_width;            /* > 0 */
+    double tile_height;           /* > 0 */
+} rgame_tile_sweep;
+
+/* Where the box's left edge lands moving dx. dx of zero returns x unchanged. */
+double rgame_tile_sweep_resolve_x(const rgame_tile_sweep *sweep, double x, double y, double w, double h,
+                                  double dx);
+
+/* Where the box's top edge lands moving dy. dy of zero returns y unchanged. */
+double rgame_tile_sweep_resolve_y(const rgame_tile_sweep *sweep, double x, double y, double w, double h,
+                                  double dy);
+
+/* How many windows a travel of (dx, dy) sweeps — at least 1, or NaN for a NaN
+ * delta. Exposed so a caller can refuse a travel too long to sweep before
+ * starting it. */
+double rgame_tile_sweep_travel_windows(const rgame_tile_sweep *sweep, double dx, double dy);
+
+/* Whether the box at (x, y, w, h) travels (dx, dy) with no resolve along the
+ * way falling short of the landing it was heading for. A NaN delta, or a travel
+ * of more than INT32_MAX windows, is answered false without sweeping. */
+bool rgame_tile_sweep_travel(const rgame_tile_sweep *sweep, double x, double y, double w, double h, double dx,
+                             double dy);
+
+#endif /* RGAME_TILE_SWEEP_H */

data/ext/rgame_util/tile_sweep_ext.c

@@ -0,0 +1,155 @@
+/*
+ * tile_sweep_ext.c — the Ruby binding for RGame::Util::TileSweep.
+ *
+ * The arithmetic lives in tile_sweep.{c,h}, pure and covered by the Check
+ * suite. What this file adds is lifetime and refusals: the C sweep holds a
+ * pointer into the SolidGrid it reads, so the Ruby object holds the grid too
+ * and marks it; and a coordinate crosses into C through NUM2DBL, so anything
+ * but a number is a TypeError.
+ *
+ * resolve_x and resolve_y run once per axis per frame for every mover blocked
+ * by tiles, so they convert and call and nothing else — no allocation, and a
+ * Float comes back as an immediate value.
+ */
+
+#include "util_ext.h"
+
+#include <math.h>
+
+#include "tile_sweep.h"
+
+typedef struct {
+    VALUE grid;
+    rgame_tile_sweep sweep;
+} tile_sweep_ref;
+
+static long live_sweeps = 0;
+
+static void tile_sweep_mark(void *ptr) {
+    tile_sweep_ref *ref = ptr;
+    rb_gc_mark(ref->grid);
+}
+
+static void tile_sweep_free(void *ptr) {
+    xfree(ptr);
+    live_sweeps--;
+}
+
+static size_t tile_sweep_memsize(const void *ptr) {
+    (void)ptr;
+    return sizeof(tile_sweep_ref);
+}
+
+static const rb_data_type_t tile_sweep_data_type = {
+    .wrap_struct_name = "rgame_tile_sweep",
+    .function = {
+        .dmark = tile_sweep_mark,
+        .dfree = tile_sweep_free,
+        .dsize = tile_sweep_memsize,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static tile_sweep_ref *unwrap(VALUE self) {
+    tile_sweep_ref *ref;
+    TypedData_Get_Struct(self, tile_sweep_ref, &tile_sweep_data_type, ref);
+    return ref;
+}
+
+static double tile_size(VALUE value, const char *name) {
+    double size = NUM2DBL(value);
+    if (!(isfinite(size) && size > 0.0)) {
+        rb_raise(rb_eArgError, "%s must be a positive, finite size, got %" PRIsVALUE, name, value);
+    }
+    return size;
+}
+
+/* TileSweep.new(grid, tile_width, tile_height) — a sweep over a SolidGrid's
+ * cells at that tile size, which keeps the grid alive. TypeError for anything
+ * but a grid; ArgumentError for a tile size that is not positive and finite. */
+static VALUE tile_sweep_s_new(VALUE klass, VALUE grid, VALUE tile_width, VALUE tile_height) {
+    rgame_solid_grid *cells = rgame_util_solid_grid(grid);
+    double width = tile_size(tile_width, "tile_width");
+    double height = tile_size(tile_height, "tile_height");
+
+    tile_sweep_ref *ref;
+    VALUE object = TypedData_Make_Struct(klass, tile_sweep_ref, &tile_sweep_data_type, ref);
+    live_sweeps++;
+    ref->grid = grid;
+    ref->sweep = (rgame_tile_sweep){ .grid = cells, .tile_width = width, .tile_height = height };
+    return object;
+}
+
+static VALUE tile_sweep_grid(VALUE self) { return unwrap(self)->grid; }
+static VALUE tile_sweep_tile_width(VALUE self) { return DBL2NUM(unwrap(self)->sweep.tile_width); }
+static VALUE tile_sweep_tile_height(VALUE self) { return DBL2NUM(unwrap(self)->sweep.tile_height); }
+
+static void refuse_non_finite(double values[], int count) {
+    for (int i = 0; i < count; i++) {
+        if (!isfinite(values[i])) {
+            rb_raise(rb_eFloatDomainError, "a box cannot be resolved at %f", values[i]);
+        }
+    }
+}
+
+/* A step with no movement returns the box where it is, whatever the numbers;
+ * any other step through a non-finite number is a FloatDomainError. */
+static VALUE resolve(VALUE self, VALUE x, VALUE y, VALUE w, VALUE h, VALUE delta,
+                     double (*axis)(const rgame_tile_sweep *, double, double, double, double, double)) {
+    double values[] = { NUM2DBL(x), NUM2DBL(y), NUM2DBL(w), NUM2DBL(h), NUM2DBL(delta) };
+    if (values[4] != 0.0) {
+        refuse_non_finite(values, 5);
+    }
+    return DBL2NUM(axis(&unwrap(self)->sweep, values[0], values[1], values[2], values[3], values[4]));
+}
+
+/* resolve_x(x, y, w, h, dx) — where the box's left edge lands moving dx,
+ * snapped flush against a solid tile it would enter. Always a Float. */
+static VALUE tile_sweep_resolve_x(VALUE self, VALUE x, VALUE y, VALUE w, VALUE h, VALUE dx) {
+    return resolve(self, x, y, w, h, dx, rgame_tile_sweep_resolve_x);
+}
+
+/* resolve_y(x, y, w, h, dy) — the mirror of resolve_x. */
+static VALUE tile_sweep_resolve_y(VALUE self, VALUE x, VALUE y, VALUE w, VALUE h, VALUE dy) {
+    return resolve(self, x, y, w, h, dy, rgame_tile_sweep_resolve_y);
+}
+
+/* travel?(x, y, w, h, dx, dy) — whether the box travels (dx, dy) without any
+ * resolve along the way falling short of where it was heading. Sound for a
+ * walker stepping under a quarter tile at a time. FloatDomainError for a
+ * non-finite number; ArgumentError for a travel too long to sweep. */
+static VALUE tile_sweep_travel_p(VALUE self, VALUE x, VALUE y, VALUE w, VALUE h, VALUE dx, VALUE dy) {
+    double values[] = { NUM2DBL(x), NUM2DBL(y), NUM2DBL(w), NUM2DBL(h), NUM2DBL(dx), NUM2DBL(dy) };
+    refuse_non_finite(values, 6);
+
+    rgame_tile_sweep *sweep = &unwrap(self)->sweep;
+    double windows = rgame_tile_sweep_travel_windows(sweep, values[4], values[5]);
+    if (windows > (double)INT32_MAX) {
+        rb_raise(rb_eArgError, "a travel of (%f, %f) is too long to sweep", values[4], values[5]);
+    }
+    return rgame_tile_sweep_travel(sweep, values[0], values[1], values[2], values[3], values[4], values[5])
+               ? Qtrue
+               : Qfalse;
+}
+
+/* TileSweep.debug_live_sweeps — how many sweeps are allocated. Test-only, and
+ * named so. */
+static VALUE tile_sweep_s_debug_live_sweeps(VALUE klass) {
+    (void)klass;
+    return LONG2NUM(live_sweeps);
+}
+
+void rgame_init_tile_sweep(VALUE mUtil) {
+    VALUE cTileSweep = rb_define_class_under(mUtil, "TileSweep", rb_cObject);
+
+    rb_undef_alloc_func(cTileSweep);
+    rb_define_singleton_method(cTileSweep, "new", tile_sweep_s_new, 3);
+    rb_define_singleton_method(cTileSweep, "debug_live_sweeps", tile_sweep_s_debug_live_sweeps, 0);
+
+    rb_define_method(cTileSweep, "grid", tile_sweep_grid, 0);
+    rb_define_method(cTileSweep, "tile_width", tile_sweep_tile_width, 0);
+    rb_define_method(cTileSweep, "tile_height", tile_sweep_tile_height, 0);
+    rb_define_method(cTileSweep, "resolve_x", tile_sweep_resolve_x, 5);
+    rb_define_method(cTileSweep, "resolve_y", tile_sweep_resolve_y, 5);
+    rb_define_method(cTileSweep, "travel?", tile_sweep_travel_p, 6);
+}

data/ext/rgame_util/util_ext.c

@@ -24,4 +24,7 @@ void Init_util_ext(void) {
 
     rgame_init_tensor(mUtil);
     rgame_init_color(mUtil);
+    rgame_init_solid_grid(mUtil);
+    rgame_init_route_search(mUtil);
+    rgame_init_tile_sweep(mUtil);
 }

data/ext/rgame_util/util_ext.h

@@ -12,5 +12,20 @@
 
 void rgame_init_tensor(VALUE mUtil);
 void rgame_init_color(VALUE mUtil);
+void rgame_init_solid_grid(VALUE mUtil);
+void rgame_init_route_search(VALUE mUtil);
+void rgame_init_tile_sweep(VALUE mUtil);
+
+/*
+ * The two things a RouteSearch needs from the SolidGrid binding: the grid
+ * behind a Ruby object (TypeError for anything else), and the one reading of a
+ * cell coordinate both classes share — an Integer or a TypeError, and false
+ * for an Integer too large to be inside any grid.
+ */
+#include <stdbool.h>
+#include "solid_grid.h"
+
+rgame_solid_grid *rgame_util_solid_grid(VALUE value);
+bool rgame_util_cell_coordinate(VALUE value, int32_t *out);
 
 #endif /* RGAME_UTIL_EXT_H */