rgame 0.2.0 → 0.3.0

data/ext/rgame_core/ruby/locale_ext.c

@@ -0,0 +1,44 @@
+/*
+ * locale_ext.c — the Ruby binding for RGame::Core.preferred_locales.
+ *
+ *   RGame::Core.preferred_locales   # => ["de-AT", "en"]
+ *
+ * A module function rather than an App method because SDL answers without an
+ * app, or even SDL_Init. The reading is locale.c; this file only sizes a buffer
+ * and splits the list. Choosing a language from the answer is
+ * RGame::Engine::I18n.choose, which the glue calls.
+ */
+
+#include "ruby/core_ext.h"
+
+#include "rgame/core.h"
+
+/*
+ * The user's preferred locales as Strings, most preferred first, or [] when the
+ * OS names none. Never contains nil or an empty String.
+ */
+static VALUE core_preferred_locales(VALUE self) {
+    (void)self;
+
+    char stack[256];
+    size_t length = rgame_preferred_locales(stack, sizeof stack);
+    if (length < sizeof stack) {
+        return rb_str_split(rb_utf8_str_new(stack, (long)length), ",");
+    }
+
+    /* Too long for the stack. The environment is read on every call, so the
+     * list can grow between two of them: size again until what was written fits. */
+    for (;;) {
+        VALUE list = rb_utf8_str_new(NULL, (long)length);
+        size_t written = rgame_preferred_locales(RSTRING_PTR(list), length + 1);
+        if (written <= length) {
+            rb_str_set_len(list, (long)written);
+            return rb_str_split(list, ",");
+        }
+        length = written;
+    }
+}
+
+void rgame_init_locale(VALUE mCore) {
+    rb_define_module_function(mCore, "preferred_locales", core_preferred_locales, 0);
+}

data/ext/rgame_core/ruby/recording_ext.c

@@ -176,7 +176,7 @@ void rgame_init_recording(VALUE mCore) {
 
     rb_define_alloc_func(cRecording, recording_alloc);
     rb_define_singleton_method(cRecording, "new", recording_s_new, -1);
-    rb_define_method(cRecording, "draw_at", recording_draw_at, 4);
+    rb_define_private_method(cRecording, "draw_at", recording_draw_at, 4);
     rb_define_method(cRecording, "batch_count", recording_batch_count, 0);
     rb_define_method(cRecording, "vertex_count", recording_vertex_count, 0);
     rb_define_method(cRecording, "empty?", recording_empty_p, 0);

data/ext/rgame_core/ruby/renderer_ext.c

@@ -374,26 +374,26 @@ void rgame_init_renderer(VALUE mCore) {
     rb_define_method(cRenderer, "drawing?", renderer_drawing_p, 0);
     rb_define_method(cRenderer, "app", renderer_app, 0);
 
-    rb_define_method(cRenderer, "draw_rect", renderer_draw_rect, 6);
-    rb_define_method(cRenderer, "draw_quad", renderer_draw_quad, -1);
-    rb_define_method(cRenderer, "draw_triangle", renderer_draw_triangle, -1);
-    rb_define_method(cRenderer, "draw_line", renderer_draw_line, -1);
-    rb_define_method(cRenderer, "draw_circle", renderer_draw_circle, -1);
-    rb_define_method(cRenderer, "draw_image", renderer_draw_image, 5);
-    rb_define_method(cRenderer, "draw_image_scaled", renderer_draw_image_scaled, -1);
-    rb_define_method(cRenderer, "draw_image_rot", renderer_draw_image_rot, -1);
-    rb_define_method(cRenderer, "draw_text", renderer_draw_text, -1);
-
-    rb_define_method(cRenderer, "push_translate", renderer_push_translate, 2);
-    rb_define_method(cRenderer, "push_rotate", renderer_push_rotate, 3);
-    rb_define_method(cRenderer, "push_scale", renderer_push_scale, 2);
-    rb_define_method(cRenderer, "push_clip", renderer_push_clip, 4);
-    rb_define_method(cRenderer, "push_layer", renderer_push_layer, 1);
+    rb_define_private_method(cRenderer, "draw_rect", renderer_draw_rect, 6);
+    rb_define_private_method(cRenderer, "draw_quad", renderer_draw_quad, -1);
+    rb_define_private_method(cRenderer, "draw_triangle", renderer_draw_triangle, -1);
+    rb_define_private_method(cRenderer, "draw_line", renderer_draw_line, -1);
+    rb_define_private_method(cRenderer, "draw_circle", renderer_draw_circle, -1);
+    rb_define_private_method(cRenderer, "draw_image", renderer_draw_image, 5);
+    rb_define_private_method(cRenderer, "draw_image_scaled", renderer_draw_image_scaled, -1);
+    rb_define_private_method(cRenderer, "draw_image_rot", renderer_draw_image_rot, -1);
+    rb_define_private_method(cRenderer, "draw_text", renderer_draw_text, -1);
+
+    rb_define_private_method(cRenderer, "push_translate", renderer_push_translate, 2);
+    rb_define_private_method(cRenderer, "push_rotate", renderer_push_rotate, 3);
+    rb_define_private_method(cRenderer, "push_scale", renderer_push_scale, 2);
+    rb_define_private_method(cRenderer, "push_clip", renderer_push_clip, 4);
+    rb_define_private_method(cRenderer, "push_layer", renderer_push_layer, 1);
     rb_define_method(cRenderer, "layer", renderer_layer, 0);
-    rb_define_method(cRenderer, "next_layer_slot", renderer_next_layer_slot, 1);
-    rb_define_method(cRenderer, "pop", renderer_pop, 0);
+    rb_define_private_method(cRenderer, "next_layer_slot", renderer_next_layer_slot, 1);
+    rb_define_private_method(cRenderer, "pop", renderer_pop, 0);
 
-    rb_define_method(cRenderer, "begin_record", renderer_begin_record, 0);
-    rb_define_method(cRenderer, "end_record", renderer_end_record, 0);
-    rb_define_method(cRenderer, "cancel_record", renderer_cancel_record, 0);
+    rb_define_private_method(cRenderer, "begin_record", renderer_begin_record, 0);
+    rb_define_private_method(cRenderer, "end_record", renderer_end_record, 0);
+    rb_define_private_method(cRenderer, "cancel_record", renderer_cancel_record, 0);
 }

data/ext/rgame_util/extconf.rb

@@ -1,27 +1,9 @@
 # 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.
+$CFLAGS << ' -ffp-contract=off'
+
 create_makefile('rgame/util_ext')

data/ext/rgame_util/route_search.c

@@ -0,0 +1,305 @@
+/*
+ * route_search.c — regions and A* over a solid grid. Pure; see route_search.h.
+ *
+ * Costs are doubles and are never contracted into fused multiply-adds: two
+ * routes of equal cost are told apart by comparing sums, and a compiler that
+ * fused one of them would pick a different, equally cheap route on one machine
+ * than on another.
+ */
+
+#include "route_search.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+#ifdef __clang__
+#pragma STDC FP_CONTRACT OFF
+#endif
+
+static const double DIAGONAL = 1.4142135623730951;
+static const double DIAGONAL_EXTRA = 1.4142135623730951 - 1.0;
+
+bool rgame_route_search_init(rgame_route_search *search, const rgame_solid_grid *grid) {
+    memset(search, 0, sizeof(*search));
+    search->grid = grid;
+    search->cell_count = grid->width * grid->height;
+
+    size_t count = search->cell_count > 0 ? (size_t)search->cell_count : 1;
+    search->regions = malloc(count * sizeof(int32_t));
+    search->flood = malloc(count * sizeof(int32_t));
+    search->cost = malloc(count * sizeof(double));
+    search->parent = malloc(count * sizeof(int32_t));
+    search->seen = calloc(count, sizeof(uint32_t));
+    search->closed = calloc(count, sizeof(uint32_t));
+    search->route = malloc(count * sizeof(int32_t));
+
+    if (!search->regions || !search->flood || !search->cost || !search->parent || !search->seen ||
+        !search->closed || !search->route) {
+        rgame_route_search_free(search);
+        return false;
+    }
+    return true;
+}
+
+void rgame_route_search_free(rgame_route_search *search) {
+    free(search->regions);
+    free(search->flood);
+    free(search->cost);
+    free(search->parent);
+    free(search->seen);
+    free(search->closed);
+    free(search->heap_cell);
+    free(search->heap_total);
+    free(search->heap_remaining);
+    free(search->route);
+    memset(search, 0, sizeof(*search));
+}
+
+int rgame_route_neighbours(const rgame_solid_grid *grid, int32_t index, int32_t cells[8],
+                           double steps[8]) {
+    int32_t width = grid->width;
+    int32_t col = index % width;
+    const uint8_t *solid = grid->cells;
+    bool west = col > 0 && !solid[index - 1];
+    bool east = col < width - 1 && !solid[index + 1];
+    bool north = index >= width && !solid[index - width];
+    bool south = index < grid->width * grid->height - width && !solid[index + width];
+
+    int count = 0;
+    if (west) { cells[count] = index - 1; steps[count++] = 1.0; }
+    if (east) { cells[count] = index + 1; steps[count++] = 1.0; }
+    if (north) { cells[count] = index - width; steps[count++] = 1.0; }
+    if (south) { cells[count] = index + width; steps[count++] = 1.0; }
+    if (north && west && !solid[index - width - 1]) { cells[count] = index - width - 1; steps[count++] = DIAGONAL; }
+    if (north && east && !solid[index - width + 1]) { cells[count] = index - width + 1; steps[count++] = DIAGONAL; }
+    if (south && west && !solid[index + width - 1]) { cells[count] = index + width - 1; steps[count++] = DIAGONAL; }
+    if (south && east && !solid[index + width + 1]) { cells[count] = index + width + 1; steps[count++] = DIAGONAL; }
+    return count;
+}
+
+/* --- regions --- */
+
+static void claim(rgame_route_search *search, int32_t index, int32_t label, int32_t *top) {
+    if (search->grid->cells[index] || search->regions[index] != -1) {
+        return;
+    }
+    search->regions[index] = label;
+    search->flood[(*top)++] = index;
+}
+
+static void label_regions(rgame_route_search *search) {
+    const rgame_solid_grid *grid = search->grid;
+    int32_t width = grid->width;
+    int32_t count = search->cell_count;
+    for (int32_t index = 0; index < count; index++) {
+        search->regions[index] = -1;
+    }
+
+    int32_t label = 0;
+    for (int32_t seed = 0; seed < count; seed++) {
+        if (grid->cells[seed] || search->regions[seed] != -1) {
+            continue;
+        }
+        int32_t top = 0;
+        claim(search, seed, label, &top);
+        while (top > 0) {
+            int32_t index = search->flood[--top];
+            int32_t col = index % width;
+            if (col > 0) { claim(search, index - 1, label, &top); }
+            if (col < width - 1) { claim(search, index + 1, label, &top); }
+            if (index >= width) { claim(search, index - width, label, &top); }
+            if (index < count - width) { claim(search, index + width, label, &top); }
+        }
+        label++;
+    }
+
+    search->labelled = true;
+    search->labelled_at = grid->revision;
+}
+
+int32_t rgame_route_region(rgame_route_search *search, int32_t col, int32_t row) {
+    if (!rgame_solid_grid_inside(search->grid, col, row)) {
+        return -1;
+    }
+    if (!search->labelled || search->labelled_at != search->grid->revision) {
+        label_regions(search);
+    }
+    return search->regions[row * search->grid->width + col];
+}
+
+/* --- the heap: parallel arrays, ordered by total then remaining --- */
+
+static bool heap_reserve(rgame_route_search *search) {
+    if (search->heap_size < search->heap_capacity) {
+        return true;
+    }
+    size_t capacity = search->heap_capacity ? search->heap_capacity * 2 : 64;
+    int32_t *cells = realloc(search->heap_cell, capacity * sizeof(int32_t));
+    if (!cells) {
+        return false;
+    }
+    search->heap_cell = cells;
+    double *totals = realloc(search->heap_total, capacity * sizeof(double));
+    if (!totals) {
+        return false;
+    }
+    search->heap_total = totals;
+    double *remainings = realloc(search->heap_remaining, capacity * sizeof(double));
+    if (!remainings) {
+        return false;
+    }
+    search->heap_remaining = remainings;
+    search->heap_capacity = capacity;
+    return true;
+}
+
+static bool push(rgame_route_search *search, int32_t index, double total, double remaining) {
+    if (!heap_reserve(search)) {
+        return false;
+    }
+    int32_t *cell = search->heap_cell;
+    double *totals = search->heap_total;
+    double *remainings = search->heap_remaining;
+    size_t slot = search->heap_size++;
+    while (slot > 0) {
+        size_t up = (slot - 1) >> 1;
+        if (totals[up] < total || (totals[up] == total && remainings[up] <= remaining)) {
+            break;
+        }
+        cell[slot] = cell[up];
+        totals[slot] = totals[up];
+        remainings[slot] = remainings[up];
+        slot = up;
+    }
+    cell[slot] = index;
+    totals[slot] = total;
+    remainings[slot] = remaining;
+    return true;
+}
+
+static int32_t pop(rgame_route_search *search) {
+    int32_t *cell = search->heap_cell;
+    double *totals = search->heap_total;
+    double *remainings = search->heap_remaining;
+    int32_t top = cell[0];
+    size_t size = --search->heap_size;
+    if (size == 0) {
+        return top;
+    }
+
+    int32_t index = cell[size];
+    double total = totals[size];
+    double remaining = remainings[size];
+    size_t slot = 0;
+    size_t child;
+    while ((child = (slot << 1) + 1) < size) {
+        size_t right = child + 1;
+        if (right < size && (totals[right] < totals[child] ||
+                             (totals[right] == totals[child] && remainings[right] < remainings[child]))) {
+            child = right;
+        }
+        if (total < totals[child] || (total == totals[child] && remaining <= remainings[child])) {
+            break;
+        }
+        cell[slot] = cell[child];
+        totals[slot] = totals[child];
+        remainings[slot] = remainings[child];
+        slot = child;
+    }
+    cell[slot] = index;
+    totals[slot] = total;
+    remainings[slot] = remaining;
+    return top;
+}
+
+/* --- A* --- */
+
+static void next_generation(rgame_route_search *search) {
+    if (++search->generation == 0) {
+        size_t count = search->cell_count > 0 ? (size_t)search->cell_count : 1;
+        memset(search->seen, 0, count * sizeof(uint32_t));
+        memset(search->closed, 0, count * sizeof(uint32_t));
+        search->generation = 1;
+    }
+}
+
+static bool relax(rgame_route_search *search, int32_t from, int32_t to, double cost, int32_t goal_col,
+                  int32_t goal_row) {
+    uint32_t generation = search->generation;
+    if (search->closed[to] == generation) {
+        return true;
+    }
+    if (search->seen[to] == generation && search->cost[to] <= cost) {
+        return true;
+    }
+
+    search->seen[to] = generation;
+    search->cost[to] = cost;
+    search->parent[to] = from;
+    int32_t width = search->grid->width;
+    int32_t dx = abs(to % width - goal_col);
+    int32_t dy = abs(to / width - goal_row);
+    double remaining = dx < dy ? (double)dy + DIAGONAL_EXTRA * dx : (double)dx + DIAGONAL_EXTRA * dy;
+    return push(search, to, cost + remaining, remaining);
+}
+
+static rgame_route_result search_route(rgame_route_search *search, int32_t start, int32_t goal,
+                                       int32_t goal_col, int32_t goal_row) {
+    next_generation(search);
+    search->heap_size = 0;
+    if (!relax(search, -1, start, 0.0, goal_col, goal_row)) {
+        return RGAME_ROUTE_NO_MEMORY;
+    }
+
+    int32_t cells[8];
+    double steps[8];
+    while (search->heap_size > 0) {
+        int32_t index = pop(search);
+        if (search->closed[index] == search->generation) {
+            continue;
+        }
+        if (index == goal) {
+            return RGAME_ROUTE_FOUND;
+        }
+
+        search->closed[index] = search->generation;
+        int count = rgame_route_neighbours(search->grid, index, cells, steps);
+        double cost = search->cost[index];
+        for (int i = 0; i < count; i++) {
+            if (!relax(search, index, cells[i], cost + steps[i], goal_col, goal_row)) {
+                return RGAME_ROUTE_NO_MEMORY;
+            }
+        }
+    }
+    /* Unreachable once regions agree the two ends are joined. */
+    return RGAME_ROUTE_NONE;
+}
+
+static void collect_route(rgame_route_search *search, int32_t goal) {
+    int32_t length = 0;
+    for (int32_t index = goal; index != -1; index = search->parent[index]) {
+        length++;
+    }
+    int32_t slot = length;
+    for (int32_t index = goal; index != -1; index = search->parent[index]) {
+        search->route[--slot] = index;
+    }
+    search->route_length = length;
+}
+
+rgame_route_result rgame_route_find(rgame_route_search *search, int32_t from_col, int32_t from_row,
+                                    int32_t to_col, int32_t to_row) {
+    search->route_length = 0;
+    int32_t from_region = rgame_route_region(search, from_col, from_row);
+    if (from_region == -1 || from_region != rgame_route_region(search, to_col, to_row)) {
+        return RGAME_ROUTE_NONE;
+    }
+
+    int32_t width = search->grid->width;
+    int32_t goal = to_row * width + to_col;
+    rgame_route_result result = search_route(search, from_row * width + from_col, goal, to_col, to_row);
+    if (result == RGAME_ROUTE_FOUND) {
+        collect_route(search, goal);
+    }
+    return result;
+}

data/ext/rgame_util/route_search.h

@@ -0,0 +1,86 @@
+#ifndef RGAME_ROUTE_SEARCH_H
+#define RGAME_ROUTE_SEARCH_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "solid_grid.h"
+
+/*
+ * Connected regions and A* routes over a solid grid — pure, no Ruby, no SDL.
+ *
+ * A search reads its grid and never writes it. Everything it keeps between
+ * queries lives in the search, so any number of searches may read one grid —
+ * which is what lets many walkers plan over the one store a tile world's
+ * blockers also read.
+ *
+ * The grid is 8-connected with octile costs (1 straight, sqrt 2 diagonal), and a
+ * diagonal step is allowed only when both orthogonal cells beside it are open,
+ * so a route never cuts the corner of a solid cell. That rule is
+ * rgame_route_neighbours, and every search over the grid goes through it.
+ *
+ * Regions are labelled by an orthogonal flood fill the first time one is asked
+ * for, and again whenever the grid's revision has moved since — so an
+ * unreachable goal, the answer A* is slowest to give, is a lookup, and it stays
+ * right when the grid changes.
+ *
+ * A search allocates its per-cell buffers once, at init, and marks which
+ * entries are current with a generation stamp, so a query costs nothing
+ * proportional to the grid. The heap grows to the largest query seen and never
+ * shrinks: a repeated query allocates nothing.
+ */
+
+typedef enum {
+    RGAME_ROUTE_FOUND,
+    RGAME_ROUTE_NONE,     /* an end is solid, outside, or in another region */
+    RGAME_ROUTE_NO_MEMORY /* the heap could not grow; the search is still usable */
+} rgame_route_result;
+
+typedef struct {
+    const rgame_solid_grid *grid;
+    int32_t cell_count;
+
+    int32_t *regions; /* per cell; -1 solid */
+    int32_t *flood;   /* the flood fill's stack */
+    bool labelled;
+    uint64_t labelled_at; /* the grid revision the labels describe */
+
+    double *cost;
+    int32_t *parent;
+    uint32_t *seen;
+    uint32_t *closed;
+    uint32_t generation; /* stamps; wrapping clears them */
+
+    int32_t *heap_cell;
+    double *heap_total;
+    double *heap_remaining;
+    size_t heap_size;
+    size_t heap_capacity; /* grows, never shrinks */
+
+    int32_t *route; /* flat indices, start first, after RGAME_ROUTE_FOUND */
+    int32_t route_length;
+} rgame_route_search;
+
+/* The grid must outlive the search. False, with nothing to free, when
+ * allocation fails. */
+bool rgame_route_search_init(rgame_route_search *search, const rgame_solid_grid *grid);
+void rgame_route_search_free(rgame_route_search *search);
+
+/* The cells one step from `index` may reach, in the order a search relaxes them
+ * (west, east, north, south, then the four diagonals), each with its step cost.
+ * Returns how many were written, at most 8. */
+int rgame_route_neighbours(const rgame_solid_grid *grid, int32_t index, int32_t cells[8],
+                           double steps[8]);
+
+/* The region label of a cell — two walkable cells share one exactly when a
+ * route joins them — or -1 for a solid cell or one outside the grid. */
+int32_t rgame_route_region(rgame_route_search *search, int32_t col, int32_t row);
+
+/* The cheapest route from start to goal, both included, into search->route.
+ * Ties between equally cheap routes go to the entry with the smaller remaining
+ * estimate, so the same query always returns the same route. */
+rgame_route_result rgame_route_find(rgame_route_search *search, int32_t from_col, int32_t from_row,
+                                    int32_t to_col, int32_t to_row);
+
+#endif /* RGAME_ROUTE_SEARCH_H */

data/ext/rgame_util/route_search_ext.c

@@ -0,0 +1,150 @@
+/*
+ * route_search_ext.c — the Ruby binding for RGame::Util::RouteSearch.
+ *
+ * The search lives in route_search.{c,h}, pure and covered by the Check suite.
+ * What this file adds is lifetime: the C search holds a pointer into the
+ * SolidGrid it reads, so the Ruby object holds the grid too and marks it, and
+ * the grid cannot be collected while a search over it is alive.
+ */
+
+#include "util_ext.h"
+
+#include "route_search.h"
+
+typedef struct {
+    VALUE grid;
+    rgame_route_search search;
+    bool ready;
+} route_search_ref;
+
+static long live_searches = 0;
+
+static void route_search_mark(void *ptr) {
+    route_search_ref *ref = ptr;
+    rb_gc_mark(ref->grid);
+}
+
+static void route_search_free(void *ptr) {
+    route_search_ref *ref = ptr;
+    if (ref->ready) {
+        rgame_route_search_free(&ref->search);
+    }
+    xfree(ref);
+    live_searches--;
+}
+
+static size_t route_search_memsize(const void *ptr) {
+    const route_search_ref *ref = ptr;
+    size_t cells = ref->ready ? (size_t)ref->search.cell_count : 0;
+    size_t per_cell = 4 * sizeof(int32_t) + sizeof(double) + 2 * sizeof(uint32_t);
+    size_t per_entry = sizeof(int32_t) + 2 * sizeof(double);
+    return sizeof(*ref) + cells * per_cell + ref->search.heap_capacity * per_entry;
+}
+
+static const rb_data_type_t route_search_data_type = {
+    .wrap_struct_name = "rgame_route_search",
+    .function = {
+        .dmark = route_search_mark,
+        .dfree = route_search_free,
+        .dsize = route_search_memsize,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static rgame_route_search *unwrap(VALUE self) {
+    route_search_ref *ref;
+    TypedData_Get_Struct(self, route_search_ref, &route_search_data_type, ref);
+    return &ref->search;
+}
+
+/* RouteSearch.new(grid) — a search over a SolidGrid, which it keeps alive. */
+static VALUE route_search_s_new(VALUE klass, VALUE grid) {
+    rgame_solid_grid *cells = rgame_util_solid_grid(grid);
+
+    route_search_ref *ref;
+    VALUE object = TypedData_Make_Struct(klass, route_search_ref, &route_search_data_type, ref);
+    live_searches++;
+    ref->grid = grid;
+    if (!rgame_route_search_init(&ref->search, cells)) {
+        rb_memerror();
+    }
+    ref->ready = true;
+    return object;
+}
+
+static VALUE route_search_grid(VALUE self) {
+    route_search_ref *ref;
+    TypedData_Get_Struct(self, route_search_ref, &route_search_data_type, ref);
+    return ref->grid;
+}
+
+/* region(col, row) — an Integer label two walkable cells share exactly when a
+ * route joins them, or nil for a solid cell or one outside the grid. Labels are
+ * recomputed on the first ask after the grid changes. */
+static VALUE route_search_region(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);
+    if (!col_fits || !row_fits) {
+        return Qnil;
+    }
+    int32_t region = rgame_route_region(unwrap(self), col, row);
+    return region == -1 ? Qnil : INT2NUM(region);
+}
+
+/* find(from_col, from_row, to_col, to_row) — the cheapest route, both ends
+ * included, as [[col, row], ...]; nil when either end is solid, outside the
+ * grid, or in another region. Equally cheap routes are told apart the same way
+ * every time. */
+static VALUE route_search_find(VALUE self, VALUE from_col_value, VALUE from_row_value,
+                               VALUE to_col_value, VALUE to_row_value) {
+    int32_t from_col = 0;
+    int32_t from_row = 0;
+    int32_t to_col = 0;
+    int32_t to_row = 0;
+    bool fits = rgame_util_cell_coordinate(from_col_value, &from_col);
+    fits = rgame_util_cell_coordinate(from_row_value, &from_row) && fits;
+    fits = rgame_util_cell_coordinate(to_col_value, &to_col) && fits;
+    fits = rgame_util_cell_coordinate(to_row_value, &to_row) && fits;
+    if (!fits) {
+        return Qnil;
+    }
+
+    rgame_route_search *search = unwrap(self);
+    switch (rgame_route_find(search, from_col, from_row, to_col, to_row)) {
+    case RGAME_ROUTE_NONE:
+        return Qnil;
+    case RGAME_ROUTE_NO_MEMORY:
+        rb_memerror();
+    case RGAME_ROUTE_FOUND:
+        break;
+    }
+
+    int32_t width = search->grid->width;
+    VALUE route = rb_ary_new_capa(search->route_length);
+    for (int32_t i = 0; i < search->route_length; i++) {
+        int32_t index = search->route[i];
+        rb_ary_push(route, rb_assoc_new(INT2FIX(index % width), INT2FIX(index / width)));
+    }
+    return route;
+}
+
+/* RouteSearch.debug_live_searches — how many searches are holding buffers.
+ * Test-only, and named so. */
+static VALUE route_search_s_debug_live_searches(VALUE klass) {
+    (void)klass;
+    return LONG2NUM(live_searches);
+}
+
+void rgame_init_route_search(VALUE mUtil) {
+    VALUE cRouteSearch = rb_define_class_under(mUtil, "RouteSearch", rb_cObject);
+
+    rb_undef_alloc_func(cRouteSearch);
+    rb_define_singleton_method(cRouteSearch, "new", route_search_s_new, 1);
+    rb_define_singleton_method(cRouteSearch, "debug_live_searches", route_search_s_debug_live_searches, 0);
+
+    rb_define_method(cRouteSearch, "grid", route_search_grid, 0);
+    rb_define_method(cRouteSearch, "region", route_search_region, 2);
+    rb_define_method(cRouteSearch, "find", route_search_find, 4);
+}