gemba 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dcf53136583f20d749d7f78ac8069b846420d899256599f1e57525ee63bf1cd
-  data.tar.gz: 2396347707db1872322af8e4a01e3c47aaceaa2e7aeb1f2f6bc8eb084d6ef09e
+  metadata.gz: 3b7478522afdccb445e067ff5e812f499cf7e8aec5f0708d4d12c9ee81224f4a
+  data.tar.gz: 83ae429789c3beb4c6cb173a8bffdfd5d5a70c7a3451621e21507ef040ccb484
 SHA512:
-  metadata.gz: fa22b34dcd284934c27ea67ea1500a079e4f275964eb7f24b97ebdc8ac9baca79234217e4748287a0855ba33beb14b3392b0b350bb057eae994e00d16ea57313
-  data.tar.gz: d31bebb679d3d27d6e3928306e9af936a4bdf15e750d2690ae631a446059ad973394db8101490599919bf284de338b58d987aefdbd77359a2d8215e4cad9ca51
+  metadata.gz: dbe2fdbf8ce938a595df9c071aeae5f61d15be4cf18a5e3d2cf1331ca3d4a65ac2af931b2828f777c2fa9661de73b2ea7b5f135e35732a040ddf420ef7d4a4d5
+  data.tar.gz: ff4e86a1702acf27651991fe7f43a66272287dcf801fe58baab3bf0ebb76e8cc0988168ff6c6ae281f67006d611232319bdcbdad583cae95de3d0365562ce152

data/THIRD_PARTY_NOTICES

@@ -1,5 +1,40 @@
-gemba bundles the following third-party fonts in the assets/ directory.
-Both are licensed under the SIL Open Font License, Version 1.1.
+gemba bundles the following third-party libraries and fonts.
+
+================================================================================
+rcheevos
+================================================================================
+
+Copyright (c) 2018 RetroAchievements.org
+https://github.com/RetroAchievements/rcheevos
+
+Licensed under the MIT License.
+
+Used for: RetroAchievements runtime — achievement condition evaluation,
+Rich Presence string evaluation, and rcheevos network protocol helpers.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================================
+Fonts (assets/ directory)
+================================================================================
+
+Both fonts below are licensed under the SIL Open Font License, Version 1.1.
 
 ================================================================================
 JetBrains Mono NL

data/bin/gemba

@@ -1,9 +1,9 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# When running from a development checkout (not installed as a gem),
+# When running from a development checkout (not installed as a gem or packed by premo),
 # add lib/ to the load path and activate Bundler for gem dependencies.
-if File.exist?(File.expand_path("../lib/gemba.rb", __dir__))
+if File.exist?(File.expand_path("../.git", __dir__))
   require "bundler/setup"
   path = File.expand_path("../lib", __dir__)
   $LOAD_PATH.unshift(path) unless $LOAD_PATH.include?(path)

data/ext/gemba/extconf.rb

@@ -181,6 +181,28 @@ unless find_mgba
   MSG
 end
 
-$srcs = ['gemba_ext.c']
+rcheevos_root = File.expand_path('../../vendor/rcheevos', __dir__)
+abort "vendor/rcheevos submodule not initialised — run: git submodule update --init" \
+  unless File.exist?("#{rcheevos_root}/src/rcheevos/runtime.c")
+
+$INCFLAGS << " -I#{rcheevos_root}/include"
+$INCFLAGS << " -I#{rcheevos_root}/src/rcheevos"
+$INCFLAGS << " -I#{rcheevos_root}/src"
+
+# Tell mkmf where to find the rcheevos source files.
+$VPATH << "#{rcheevos_root}/src/rcheevos"
+$VPATH << "#{rcheevos_root}/src"
+$VPATH << "#{rcheevos_root}/src/rhash"
+
+# Core evaluation engine + md5 (needed by runtime.c / runtime_progress.c).
+# Excludes HTTP client, ROM hash, and rapi.
+$srcs = %w[
+  gemba_ext.c
+  alloc.c condition.c condset.c format.c lboard.c memref.c
+  operand.c richpresence.c runtime.c runtime_progress.c
+  trigger.c value.c
+  rc_compat.c rc_util.c
+  md5.c
+]
 
 create_makefile('gemba_ext')

data/ext/gemba/gemba_ext.c

@@ -1,4 +1,5 @@
 #include "gemba_ext.h"
+#include "rc_runtime.h"
 #include <mgba/core/config.h>
 #include <mgba/core/serialize.h>
 #include <ruby/thread.h>
@@ -19,6 +20,7 @@ void blip_set_rates(struct blip_t *, double clock_rate, double sample_rate);
 
 VALUE mGemba;
 static VALUE cCore;
+static VALUE ra_empty_array; /* frozen [] returned by do_frame when nothing triggered */
 
 /* No-op logger — prevents segfault when mGBA tries to log
  * without a logger configured (the default is NULL). */
@@ -259,8 +261,8 @@ get_mgba_core(VALUE self)
 static VALUE
 mgba_core_initialize(int argc, VALUE *argv, VALUE self)
 {
-    VALUE rom_path, save_dir;
-    rb_scan_args(argc, argv, "11", &rom_path, &save_dir);
+    VALUE rom_path, save_dir, bios_path;
+    rb_scan_args(argc, argv, "12", &rom_path, &save_dir, &bios_path);
 
     struct mgba_core *mc;
     TypedData_Get_Struct(self, struct mgba_core, &mgba_core_type, mc);
@@ -324,9 +326,53 @@ mgba_core_initialize(int argc, VALUE *argv, VALUE self)
         mDirectorySetMapOptions(&core->dirs, &opts);
     }
 
+    /* 7b. Load BIOS if provided (must be before reset) */
+    if (!NIL_P(bios_path)) {
+        Check_Type(bios_path, T_STRING);
+        struct VFile *bvf = VFileOpen(StringValueCStr(bios_path), O_RDONLY);
+        if (bvf) {
+            if (!core->loadBIOS(core, bvf, 0)) {
+                bvf->close(bvf);
+            }
+        }
+    }
+
     /* 8. Reset */
     core->reset(core);
 
+    /* 8b. Re-query dimensions now that the ROM is loaded and the board
+     * pointer is populated.  For GB/GBC, the pre-load query returns the
+     * SGB frame size (256x224) because core->board is NULL at that point.
+     * After reset the real model is known, so desiredVideoDimensions
+     * returns the correct 160x144 for non-SGB games.  When the
+     * dimensions shrink we must reallocate and call setVideoBuffer so
+     * the stride matches the actual width. */
+    {
+        unsigned w2, h2;
+        core->desiredVideoDimensions(core, &w2, &h2);
+        if (w2 != w || h2 != h) {
+            color_t *new_vbuf = calloc((size_t)w2 * h2, sizeof(color_t));
+            uint32_t *new_prev = calloc((size_t)w2 * h2, sizeof(uint32_t));
+            if (!new_vbuf || !new_prev) {
+                free(new_vbuf);
+                free(new_prev);
+                free(mc->video_buffer);
+                mc->video_buffer = NULL;
+                free(mc->prev_frame);
+                mc->prev_frame = NULL;
+                core->deinit(core);
+                rb_raise(rb_eNoMemError, "failed to reallocate video buffer");
+            }
+            free(mc->video_buffer);
+            free(mc->prev_frame);
+            mc->video_buffer = new_vbuf;
+            mc->prev_frame = new_prev;
+            core->setVideoBuffer(core, mc->video_buffer, w2);
+        }
+        mc->width  = (int)w2;
+        mc->height = (int)h2;
+    }
+
     /* 9. Autoload save file (.sav alongside ROM, or in save_dir).
      * Creates the .sav if it doesn't exist yet. */
     mCoreAutoloadSave(core);
@@ -603,6 +649,50 @@ mgba_core_maker_code(VALUE self)
 }
 
 /* --------------------------------------------------------- */
+/* Core#bus_read8(address)                                   */
+/* Read one byte from the GBA address bus.                   */
+/* Returns 0..255 as an Integer.                             */
+/* Primarily used by the achievement subsystem to evaluate   */
+/* memory conditions (IWRAM, EWRAM, registers).              */
+/* --------------------------------------------------------- */
+
+static VALUE
+mgba_core_bus_read8(VALUE self, VALUE addr)
+{
+    struct mgba_core *mc = get_mgba_core(self);
+    uint32_t address = (uint32_t)NUM2UINT(addr);
+    uint8_t val = (uint8_t)mc->core->busRead8(mc->core, address);
+    return UINT2NUM(val);
+}
+
+/* Core#bus_read16(address)                                  */
+/* Read two bytes (little-endian) from the GBA address bus.  */
+/* Returns 0..65535 as an Integer.                           */
+/* --------------------------------------------------------- */
+
+static VALUE
+mgba_core_bus_read16(VALUE self, VALUE addr)
+{
+    struct mgba_core *mc = get_mgba_core(self);
+    uint32_t address = (uint32_t)NUM2UINT(addr);
+    uint16_t val = (uint16_t)mc->core->busRead16(mc->core, address);
+    return UINT2NUM(val);
+}
+
+/* Core#bus_read32(address)                                  */
+/* Read four bytes (little-endian) from the GBA address bus. */
+/* Returns 0..4294967295 as an Integer.                      */
+/* --------------------------------------------------------- */
+
+static VALUE
+mgba_core_bus_read32(VALUE self, VALUE addr)
+{
+    struct mgba_core *mc = get_mgba_core(self);
+    uint32_t address = (uint32_t)NUM2UINT(addr);
+    uint32_t val = mc->core->busRead32(mc->core, address);
+    return UINT2NUM(val);
+}
+
 /* Core#save_state_to_file(path)                             */
 /* Save the complete emulator state to a file.               */
 /* Returns true on success, false on failure.                */
@@ -985,10 +1075,313 @@ mgba_count_changed_pixels(VALUE mod, VALUE delta)
     return LONG2NUM(changed);
 }
 
+/* --------------------------------------------------------- */
+/* Core#bios_loaded?                                         */
+/* Returns true if a BIOS VFile is attached to this core.   */
+/* GBA only; returns false for other platforms.             */
+/* --------------------------------------------------------- */
+
+static VALUE
+mgba_core_bios_loaded_p(VALUE self)
+{
+    struct mgba_core *mc = get_mgba_core(self);
+    if (mc->core->platform(mc->core) != mPLATFORM_GBA) {
+        return Qfalse;
+    }
+    struct GBA *gba = (struct GBA *)mc->core->board;
+    return gba->biosVf ? Qtrue : Qfalse;
+}
+
+/* --------------------------------------------------------- */
+/* Gemba::RARuntime — thin wrapper around rc_runtime_t       */
+/*                    (RetroAchievements/rcheevos)           */
+/* --------------------------------------------------------- */
+
+/* Achievement IDs arrive from Ruby as numeric strings ("12345").
+ * rcheevos uses uint32_t internally.  ra_id_to_u32 parses them;
+ * ra_id_to_str converts back for the do_frame return array. */
+static uint32_t
+ra_id_to_u32(VALUE rb_id)
+{
+    Check_Type(rb_id, T_STRING);
+    return (uint32_t)strtoul(StringValueCStr(rb_id), NULL, 10);
+}
+
+/* GBA RA-address-space → mGBA bus address.
+ *   0x000000–0x07FFFF → IWRAM  0x03000000
+ *   0x080000+         → EWRAM  0x02000000 + (addr - 0x080000)
+ * rcheevos passes raw RA addresses to the peek callback. */
+static inline uint32_t
+ra_to_gba_addr(uint32_t ra_addr)
+{
+    if (ra_addr < 0x08000)
+        return 0x03000000 + ra_addr;
+    else
+        return 0x02000000 + (ra_addr - 0x08000);
+}
+
+/* rcheevos peek callback — called by rc_runtime_do_frame for every
+ * memory read.  Translates RA addresses to GBA bus addresses and
+ * reads 1, 2, or 4 bytes in little-endian order. */
+static uint32_t
+ra_peek(uint32_t ra_addr, uint32_t num_bytes, void *ud)
+{
+    struct mCore *core = (struct mCore *)ud;
+    uint32_t gba = ra_to_gba_addr(ra_addr);
+    switch (num_bytes) {
+    case 1: return (uint32_t)core->busRead8(core,  gba);
+    case 2: return (uint32_t)core->busRead16(core, gba);
+    case 4: return           core->busRead32(core, gba);
+    default: return 0;
+    }
+}
+
+/* Triggered-ID collection for do_frame.
+ * rc_runtime_event_handler_t has no userdata parameter, so we stash
+ * a pointer to frame-local storage in a static before each call and
+ * clear it after.  Ruby's GVL ensures single-threaded execution here. */
+typedef struct {
+    uint32_t ids[256];
+    int      count;
+} ra_frame_ctx_t;
+
+static ra_frame_ctx_t *s_ra_frame_ctx = NULL;
+
+static void
+ra_event_handler(const rc_runtime_event_t *event)
+{
+    if (!s_ra_frame_ctx) return;
+    if (event->type == RC_RUNTIME_EVENT_ACHIEVEMENT_TRIGGERED &&
+        s_ra_frame_ctx->count < 256)
+        s_ra_frame_ctx->ids[s_ra_frame_ctx->count++] = event->id;
+}
+
+/* Wrapper struct — embeds rc_runtime_t by value so a single allocation
+ * covers both our bookkeeping and the rcheevos runtime internals. */
+typedef struct {
+    rc_runtime_t rc;
+    int          count; /* number of currently activated achievements */
+} ra_wrapper_t;
+
+static void
+ra_wrapper_free(void *ptr)
+{
+    ra_wrapper_t *w = (ra_wrapper_t *)ptr;
+    rc_runtime_destroy(&w->rc);
+    xfree(w);
+}
+
+static VALUE cRARuntime;
+
+static const rb_data_type_t ra_runtime_type = {
+    .wrap_struct_name = "Gemba::RARuntime",
+    .function = {
+        .dmark = NULL,
+        .dfree = ra_wrapper_free,
+        .dsize = NULL,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+ra_runtime_alloc(VALUE klass)
+{
+    ra_wrapper_t *w = ALLOC(ra_wrapper_t);
+    rc_runtime_init(&w->rc);
+    w->count = 0;
+    return TypedData_Wrap_Struct(klass, &ra_runtime_type, w);
+}
+
+static ra_wrapper_t *
+get_ra_wrapper(VALUE self)
+{
+    ra_wrapper_t *w;
+    TypedData_Get_Struct(self, ra_wrapper_t, &ra_runtime_type, w);
+    return w;
+}
+
+/*
+ * RARuntime#activate(id, memaddr) → nil
+ * Parse memaddr and register the achievement in the rcheevos runtime.
+ * Raises ArgumentError if rcheevos rejects the condition string.
+ */
+static VALUE
+ra_runtime_rb_activate(VALUE self, VALUE rb_id, VALUE rb_memaddr)
+{
+    Check_Type(rb_memaddr, T_STRING);
+    ra_wrapper_t *w  = get_ra_wrapper(self);
+    uint32_t      id = ra_id_to_u32(rb_id);
+    int rc = rc_runtime_activate_achievement(&w->rc, id,
+                                             StringValueCStr(rb_memaddr),
+                                             NULL, 0);
+    if (rc != RC_OK)
+        rb_raise(rb_eArgError,
+                 "RARuntime: rcheevos rejected memaddr (err %d): %s",
+                 rc, StringValueCStr(rb_memaddr));
+    w->count++;
+    return Qnil;
+}
+
+/*
+ * RARuntime#deactivate(id) → nil
+ */
+static VALUE
+ra_runtime_rb_deactivate(VALUE self, VALUE rb_id)
+{
+    ra_wrapper_t *w = get_ra_wrapper(self);
+    rc_runtime_deactivate_achievement(&w->rc, ra_id_to_u32(rb_id));
+    if (w->count > 0) w->count--;
+    return Qnil;
+}
+
+/*
+ * RARuntime#reset_all → nil
+ * Reset every achievement to WAITING state (as if freshly activated).
+ * Call this after loading a save state so delta/prior histories are
+ * discarded and achievements can't fire spuriously.
+ */
+static VALUE
+ra_runtime_rb_reset_all(VALUE self)
+{
+    rc_runtime_reset(&get_ra_wrapper(self)->rc);
+    return Qnil;
+}
+
+/*
+ * RARuntime#clear → nil
+ * Destroy all achievements and reinitialise the runtime from scratch.
+ */
+static VALUE
+ra_runtime_rb_clear(VALUE self)
+{
+    ra_wrapper_t *w = get_ra_wrapper(self);
+    rc_runtime_destroy(&w->rc);
+    rc_runtime_init(&w->rc);
+    w->count = 0;
+    return Qnil;
+}
+
+/*
+ * RARuntime#do_frame(core) → Array<String>
+ * Evaluate all active achievements against current emulator memory.
+ * Returns an array of string IDs for achievements that triggered.
+ */
+static VALUE
+ra_runtime_rb_do_frame(VALUE self, VALUE rb_core)
+{
+    struct mgba_core *mc;
+    TypedData_Get_Struct(rb_core, struct mgba_core, &mgba_core_type, mc);
+    if (mc->destroyed || !mc->core)
+        rb_raise(rb_eRuntimeError, "mGBA core has been destroyed");
+
+    ra_wrapper_t    *w   = get_ra_wrapper(self);
+    ra_frame_ctx_t   ctx = { .count = 0 };
+
+    s_ra_frame_ctx = &ctx;
+    rc_runtime_do_frame(&w->rc, ra_event_handler, ra_peek, mc->core, NULL);
+    s_ra_frame_ctx = NULL;
+
+    if (ctx.count == 0) return ra_empty_array;
+
+    VALUE result = rb_ary_new_capa(ctx.count);
+    char  buf[16];
+    for (int i = 0; i < ctx.count; i++) {
+        snprintf(buf, sizeof(buf), "%u", ctx.ids[i]);
+        rb_ary_push(result, rb_str_new_cstr(buf));
+    }
+    return result;
+}
+
+/*
+ * RARuntime#count → Integer
+ * Number of currently activated achievements.
+ */
+static VALUE
+ra_runtime_rb_count(VALUE self)
+{
+    return INT2NUM(get_ra_wrapper(self)->count);
+}
+
+/*
+ * RARuntime#activate_richpresence(script) → true | false
+ * Load a Rich Presence script into the runtime.
+ * Returns true on success, false if the script failed to parse.
+ */
+static VALUE
+ra_runtime_rb_activate_richpresence(VALUE self, VALUE rb_script)
+{
+    ra_wrapper_t *w = get_ra_wrapper(self);
+    const char   *script = StringValueCStr(rb_script);
+    int           rc;
+
+    rc = rc_runtime_activate_richpresence(&w->rc, script, NULL, 0);
+    return rc == RC_OK ? Qtrue : Qfalse;
+}
+
+/*
+ * RARuntime#get_richpresence(core) → String | nil
+ * Evaluate the active Rich Presence script against current memory and
+ * return the display string, or nil if no script is loaded / empty result.
+ */
+static VALUE
+ra_runtime_rb_get_richpresence(VALUE self, VALUE rb_core)
+{
+    ra_wrapper_t    *w = get_ra_wrapper(self);
+    struct mgba_core *mc;
+    char             buf[512];
+    int              len;
+
+    TypedData_Get_Struct(rb_core, struct mgba_core, &mgba_core_type, mc);
+    len = rc_runtime_get_richpresence(&w->rc, buf, sizeof(buf), ra_peek, mc->core, NULL);
+    if (len <= 0)
+        return Qnil;
+    return rb_str_new(buf, len);
+}
+
 /* --------------------------------------------------------- */
 /* Init                                                      */
 /* --------------------------------------------------------- */
 
+/* --------------------------------------------------------- */
+/* Core#load_bios(path)                                      */
+/* Load a BIOS file from path. Must be called before reset.  */
+/* Returns true on success, false on failure.                */
+/* --------------------------------------------------------- */
+
+static VALUE
+mgba_core_load_bios(VALUE self, VALUE rb_path)
+{
+    struct mgba_core *mc = get_mgba_core(self);
+    Check_Type(rb_path, T_STRING);
+    const char *path = StringValueCStr(rb_path);
+
+    struct VFile *vf = VFileOpen(path, O_RDONLY);
+    if (!vf) {
+        return Qfalse;
+    }
+
+    bool ok = mc->core->loadBIOS(mc->core, vf, 0);
+    if (!ok) {
+        vf->close(vf);
+    }
+    /* mGBA takes ownership of vf on success; do not close */
+    return ok ? Qtrue : Qfalse;
+}
+
+/* --------------------------------------------------------- */
+/* Gemba.gba_bios_checksum(bytes)                            */
+/* Compute GBA BIOS checksum (mGBA algorithm) on raw bytes.  */
+/* --------------------------------------------------------- */
+
+static VALUE
+mgba_gba_bios_checksum(VALUE self, VALUE rb_bytes)
+{
+    Check_Type(rb_bytes, T_STRING);
+    long len = RSTRING_LEN(rb_bytes);
+    uint32_t result = GBAChecksum((uint32_t *)RSTRING_PTR(rb_bytes), (size_t)(len / 4));
+    return UINT2NUM(result);
+}
+
 void
 Init_gemba_ext(void)
 {
@@ -1029,6 +1422,16 @@ Init_gemba_ext(void)
     rb_define_method(cCore, "rewind_count",  mgba_core_rewind_count, 0);
     rb_define_method(cCore, "destroy",     mgba_core_destroy, 0);
     rb_define_method(cCore, "destroyed?",  mgba_core_destroyed_p, 0);
+    rb_define_method(cCore, "load_bios",    mgba_core_load_bios, 1);
+    rb_define_method(cCore, "bios_loaded?", mgba_core_bios_loaded_p, 0);
+    rb_define_method(cCore, "bus_read8",    mgba_core_bus_read8, 1);
+    rb_define_method(cCore, "bus_read16",   mgba_core_bus_read16, 1);
+    rb_define_method(cCore, "bus_read32",   mgba_core_bus_read32, 1);
+
+    /* BIOS checksum utility */
+    rb_define_module_function(mGemba, "gba_bios_checksum", mgba_gba_bios_checksum, 1);
+    rb_define_const(mGemba, "GBA_BIOS_CHECKSUM",    UINT2NUM(GBA_BIOS_CHECKSUM));
+    rb_define_const(mGemba, "GBA_DS_BIOS_CHECKSUM", UINT2NUM(GBA_DS_BIOS_CHECKSUM));
 
     /* GBA key constants (bitmask values for set_keys) */
     rb_define_const(mGemba, "KEY_A",      INT2NUM(1 << GEMBA_KEY_A));
@@ -1042,6 +1445,37 @@ Init_gemba_ext(void)
     rb_define_const(mGemba, "KEY_R",      INT2NUM(1 << GEMBA_KEY_R));
     rb_define_const(mGemba, "KEY_L",      INT2NUM(1 << GEMBA_KEY_L));
 
+    /* GBA button name → bitmask hash (shared by KeyboardMap and GamepadMap) */
+    VALUE btn_bits = rb_hash_new();
+    rb_hash_aset(btn_bits, ID2SYM(rb_intern("a")),      INT2NUM(1 << GEMBA_KEY_A));
+    rb_hash_aset(btn_bits, ID2SYM(rb_intern("b")),      INT2NUM(1 << GEMBA_KEY_B));
+    rb_hash_aset(btn_bits, ID2SYM(rb_intern("l")),      INT2NUM(1 << GEMBA_KEY_L));
+    rb_hash_aset(btn_bits, ID2SYM(rb_intern("r")),      INT2NUM(1 << GEMBA_KEY_R));
+    rb_hash_aset(btn_bits, ID2SYM(rb_intern("up")),     INT2NUM(1 << GEMBA_KEY_UP));
+    rb_hash_aset(btn_bits, ID2SYM(rb_intern("down")),   INT2NUM(1 << GEMBA_KEY_DOWN));
+    rb_hash_aset(btn_bits, ID2SYM(rb_intern("left")),   INT2NUM(1 << GEMBA_KEY_LEFT));
+    rb_hash_aset(btn_bits, ID2SYM(rb_intern("right")),  INT2NUM(1 << GEMBA_KEY_RIGHT));
+    rb_hash_aset(btn_bits, ID2SYM(rb_intern("start")),  INT2NUM(1 << GEMBA_KEY_START));
+    rb_hash_aset(btn_bits, ID2SYM(rb_intern("select")), INT2NUM(1 << GEMBA_KEY_SELECT));
+    OBJ_FREEZE(btn_bits);
+    rb_define_const(mGemba, "GBA_BTN_BITS", btn_bits);
+
+    /* Frozen empty array returned by RARuntime#do_frame when nothing triggered */
+    ra_empty_array = rb_ary_freeze(rb_ary_new_capa(0));
+    rb_gc_register_mark_object(ra_empty_array);
+
+    /* Gemba::RARuntime — RA condition evaluator */
+    cRARuntime = rb_define_class_under(mGemba, "RARuntime", rb_cObject);
+    rb_define_alloc_func(cRARuntime, ra_runtime_alloc);
+    rb_define_method(cRARuntime, "activate",              ra_runtime_rb_activate,              2);
+    rb_define_method(cRARuntime, "deactivate",            ra_runtime_rb_deactivate,            1);
+    rb_define_method(cRARuntime, "reset_all",             ra_runtime_rb_reset_all,             0);
+    rb_define_method(cRARuntime, "clear",                 ra_runtime_rb_clear,                 0);
+    rb_define_method(cRARuntime, "do_frame",              ra_runtime_rb_do_frame,              1);
+    rb_define_method(cRARuntime, "count",                 ra_runtime_rb_count,                 0);
+    rb_define_method(cRARuntime, "activate_richpresence", ra_runtime_rb_activate_richpresence, 1);
+    rb_define_method(cRARuntime, "get_richpresence",      ra_runtime_rb_get_richpresence,      1);
+
     /* Toast background generator */
     rb_define_module_function(mGemba, "toast_background", mgba_toast_background, 3);
 

data/ext/gemba/gemba_ext.h

@@ -7,6 +7,8 @@
 #include <mgba/core/directories.h>
 #include <mgba/core/log.h>
 #include <mgba-util/vfs.h>
+#include <mgba/internal/gba/bios.h>
+#include <mgba/internal/gba/gba.h>
 
 extern VALUE mGemba;
 

data/gemba.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/jamescook/gemba"
   spec.licenses      = ["MIT"]
 
-  spec.files         = Dir.glob("{lib,ext,test,assets,bin}/**/*").select { |f|
+  spec.files         = Dir.glob("{lib,ext,test,assets,bin,vendor/rcheevos}/**/*").select { |f|
                          File.file?(f) && f !~ /\.(bundle|so|o|log)$/ &&
                            !f.include?('.dSYM/') && File.basename(f) != 'Makefile'
                        } + %w[gemba.gemspec THIRD_PARTY_NOTICES]
@@ -21,8 +21,9 @@ Gem::Specification.new do |spec|
   spec.extensions    = ["ext/gemba/extconf.rb"]
   spec.required_ruby_version = ">= 3.2"
 
-  spec.add_dependency "teek", ">= 0.1.2"
-  spec.add_dependency "teek-sdl2", ">= 0.1.3"
+  spec.add_dependency "teek", ">= 0.1.5"
+  spec.add_dependency "teek-sdl2", ">= 0.2.1"
+  spec.add_dependency "zeitwerk", "~> 2.7"
 
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rake-compiler", "~> 1.0"
@@ -32,6 +33,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "listen", "~> 3.0"
 
   spec.requirements << "libmgba development headers"
+  spec.add_development_dependency "webmock", "~> 3.0"
   spec.add_development_dependency "rubyzip", ">= 2.4"
 
   spec.requirements << "rubyzip gem >= 2.4 (optional, for loading ROMs from .zip files)"

data/lib/gemba/achievements/achievement.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gemba
+  module Achievements
+    # Represents a single achievement (earned or unearned).
+    #
+    # @attr [String]  id          Unique identifier (string, arbitrary)
+    # @attr [String]  title       Short display name
+    # @attr [String]  description What the player must do to earn it
+    # @attr [Integer] points      RA point value (or custom weight)
+    # @attr [Time, nil] earned_at When it was unlocked; nil if unearned
+    Achievement = Data.define(:id, :title, :description, :points, :earned_at) do
+      def earned?
+        !earned_at.nil?
+      end
+
+      # Return a copy marked as earned right now.
+      def earn
+        with(earned_at: Time.now)
+      end
+    end
+  end
+end