rgame 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54caa0772adc1eb3211edbd694540c196be0018d6482089447d727f5c871e19a
-  data.tar.gz: 16b3d1de8baefc2579bbf5a89fb7b42041d174567b6c7059d5c967f2598621f5
+  metadata.gz: 5e39a6f27c3dea363873399361aa98c3b24c9de748f54ae635f93d9fef82dcfc
+  data.tar.gz: 89933482a0d7d99167ad7b725cf5eb0d8c503000bf4596893cf597e44e0ec6b4
 SHA512:
-  metadata.gz: ab441100a4d86c34d93efed615b350a7d65ad819d3b7929e868e709c6a9790b9c78a956b9860632e62750f0880ca9656a1f7f6c98cc3df6c1b19f7d229e40919
-  data.tar.gz: e98b7a96d21700bf0533f0155be99ffc9f480e35fda2375aaee4b8b2a7bb65b871d0a70a1f2486873b32e28a83aaa4abfc91a14991226153f57959b0d62237b4
+  metadata.gz: edfe6650fc2f6e36988ed687ca7685e049b2e341f685d534e4c2a535adc4549441676ebf3126857c340bb846191623e3fd94edfa6d0d132639c3f0b349eff374
+  data.tar.gz: 64ba08460681639d8c53923874844527348b4a1490ff85085060051e3c2f66d9a33b959e846f29a1ca5386f542c55497982bdc84936fee91e200b51eaef9e71e

data/CHANGELOG.md

@@ -12,6 +12,27 @@ index, not the argument.
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-16
+
+### Added
+
+- **`gem install rgame` needs no compiler and no SDL2 on a common desktop.**
+  Apple Silicon Macs, x86-64 Linux and 64-bit Windows get a gem whose two
+  extensions are already built, with SDL2 linked into them. Every other machine,
+  and every Ruby but 4.0, installs the source gem and compiles it as before.
+- **A virtual gamepad for tests.** `RGame::Core::VirtualGamepad.new` plugs a
+  synthetic controller into a running `App`, which seats it and reads it like a
+  real pad; `set_button`, `set_axis` and `detach` drive it. See
+  [docs/api/input.md](docs/api/input.md#rgamecorevirtualgamepad).
+
+## [0.3.1] - 2026-09-15
+
+### Fixed
+
+- `require "rgame"` failed under Bundler with `cannot load such file --
+  rexml/document`. The gem now declares `rexml` as a dependency, which Ruby 4.0
+  no longer loads without one.
+
 ## [0.3.0] - 2026-09-15
 
 ### Added
@@ -222,7 +243,9 @@ First release, and the first version that runs a game end to end.
 - **`RGame::Game`** — the entry point that wires the two halves together.
 - Examples: `14_asteroids`, `15_tiled_world`, `16_hello_world`.
 
-[Unreleased]: https://github.com/psuessenb/rgame/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/psuessenb/rgame/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/psuessenb/rgame/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/psuessenb/rgame/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/psuessenb/rgame/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/psuessenb/rgame/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/psuessenb/rgame/releases/tag/v0.1.0

data/README.md

@@ -36,9 +36,15 @@ bundle exec rspec     # the game logic, headless — no window needed
 ruby main.rb          # the game itself
 ```
 
-What it writes is small — a game class, a root node, a spec and the usual configuration — but it is laid out the way the engine wants to be used: one file loads SDL, everything else stays graphics-free and therefore testable with no display. [The `rgame` command](docs/api/cli.md) explains the layout and why it matters.
+It's just a small skeleton — a game class, a root node, a spec and the usual configuration — but it is laid out the way the engine wants to be used: one file loads SDL, everything else stays graphics-free and therefore testable with no display. [The `rgame` command](docs/api/cli.md) explains the layout and the reasoning. This is also sets you up with a Rubocop configuration already geared towards RGame and game development in general.
 
-`gem install` compiles two C extensions, so the [requirements](#requirements) below have to be in place first. That's the one big hurdle at the moment: This gem ships source-only, so you have to compile a lot of C _on your machine_ to get this running.
+**On a common desktop that first line needs nothing else** — no compiler, no SDL2, no header files. `gem install rgame` fetches a gem whose two C extensions are already built, with SDL2 linked into them:
+
+- macOS 11 or later on Apple Silicon
+- x86-64 Linux with glibc 2.29 or later
+- 64-bit Windows, on a RubyInstaller Ruby
+
+All three need Ruby 4.0. Anywhere else — an Intel Mac, a Raspberry Pi, Ruby 4.1 — `gem install` falls back to the gem that ships the C and compiles it on your machine. That one needs [a compiler and SDL2](#building-from-source).
 
 ## Hello world
 
@@ -94,9 +100,11 @@ You can learn more about how it works in the [documentation](docs/api/README.md)
 | [localization](docs/api/examples.md#localization) | The same screen in two languages, switched and remembered |
 | [pathfinding](docs/api/examples.md#pathfinding) | Setting a target for an actor and let if find its way there |
 
-## Requirements
+## Building from source
+
+**This section is for two readers: anyone on a platform the binary gems miss, and anyone working on RGame itself.** Installing on one of the three platforms above needs none of it.
 
-At the moment this gem ships only source-code and no precompiled binaries, which unfortunately means you need to compile a bunch of C code on your locale machine. This _also_ means you need to install some system libaries and have header files present.
+Compiling the C engine needs a compiler and the system libraries it links against. A source install of the gem needs the compiler, `pkg-config`, SDL2 and OpenGL from the list below. The rest is for running rgame's own suites.
 
 ### C engine
 
@@ -125,7 +133,7 @@ fixture and needs `libvorbisenc` to run.
   (Debian/Ubuntu). These are what `extconf.rb` compiles against.
 - **Bundler**, then `bundle install` for the dev/test gems (RSpec, RuboCop).
 
-Nothing else — the engine has no runtime Ruby dependencies, and the `Gemfile` holds only development gems.
+Nothing else. The engine's one runtime gem is `rexml`, which Bundler installs with it, and the `Gemfile` holds only development gems.
 
 All three platforms below are built and tested on every push by
 [CI](.github/workflows/ci.yml) - with that people have usually at home, so Apple Silicon and not Apple Intel, etc.
@@ -259,23 +267,35 @@ ruby ext/rgame_core/example.rb
 Both extensions and the Ruby layer ship as one gem, built from `rgame.gemspec` and published at [rubygems.org/gems/rgame](https://rubygems.org/gems/rgame):
 
 ```
-gem install rgame               # from RubyGems; compiles both extensions here
+gem install rgame               # from RubyGems; compiles nothing on a covered platform
 ```
 
-Or from a checkout, which is the same gem built locally:
+Or from a checkout, which builds the source gem locally:
 
 ```
 rake build                      # package into pkg/rgame-<version>.gem
 gem install pkg/rgame-*.gem     # compiles both extensions on this machine
 ```
 
-`gem install` runs each `extconf.rb` and installs the resulting `.so` into the
-gem's own `lib/rgame/`, which is the same layout `make ext` produces in a
-checkout — so `require "rgame"` and `require "rgame/core"` behave identically
-either way, including the guarantee that the first of those loads no graphics
-libraries. The system dependencies are the same ones the C engine needs
-(SDL2, OpenGL, pkg-config, a compiler); `extconf.rb` aborts with the package to
-install if one is missing, rather than failing later at the link step.
+**RubyGems holds two kinds of gem for each version.** The source gem carries the
+C and compiles on install. Three platform gems carry `core_ext` and `util_ext`
+already built, with SDL2 linked statically into `core_ext`; they ship no `.c`,
+no `extconf.rb` and declare no extensions, so they compile nothing. `gem
+install` picks by platform and Ruby version on its own.
+
+CI builds and publishes all four. `tools/platform_gem.rake` builds a platform
+gem, `tools/check_platform_gem.rb` checks it against nine rules before it may be
+published, and the `smoke` job installs it on a runner with no SDL2 and plays
+the examples out of it.
+
+Installing the source gem runs each `extconf.rb` and installs the resulting
+`.so` into the gem's own `lib/rgame/`, which is the same layout `make ext`
+produces in a checkout — so `require "rgame"` and `require "rgame/core"` behave
+identically whichever gem you got, including the guarantee that the first of
+those loads no graphics libraries. Its system dependencies are the ones the C
+engine needs (SDL2, OpenGL, pkg-config, a compiler); `extconf.rb` aborts with
+the package to install if one is missing, rather than failing later at the link
+step.
 
 What ships is a glob over `lib/`, `ext/` and `docs/api/`, not a hand-written
 list: a new C source or a runtime asset dropped into either tree is packaged

data/docs/api/README.md

@@ -11,7 +11,7 @@ or write C.
 | [The `rgame` command](cli.md) | `rgame new NAME` — starting a project, and the layout it gives you |
 | [App](app.md) | `RGame::Core::App` — the window and the frame loop |
 | [Game](game.md) | `RGame::Game` — the entry point that wires both halves together |
-| [Input](input.md) | `RGame::Core::Input`, `RGame::Util::Controls`, `RGame::Core::Gamepad` |
+| [Input](input.md) | `RGame::Core::Input`, `RGame::Util::Controls`, `RGame::Core::Gamepad`, `RGame::Core::VirtualGamepad` |
 | [Drawing](drawing.md) | `RGame::Core::Renderer` — shapes, images, transforms, clipping, recordings |
 | [Images](images.md) | `RGame::Core::Image` — loading PNGs, subimages, tiles |
 | [Text](text.md) | `RGame::Core::Font` and `Renderer#text` |
@@ -67,8 +67,14 @@ The Core spec suite does this to load exactly one layer.
 `rgame/core` also loads `RGame::Util::Controls`, the input id vocabulary,
 because the input classes need it.
 
-`gem install rgame` compiles both extensions. In a checkout of the repository,
-compile them before you require anything:
+**Your install either compiled both extensions or arrived with them built.** On
+Apple Silicon macOS, x86-64 Linux and 64-bit Windows, `gem install rgame` fetches
+a gem that already holds `core_ext` and `util_ext`, with SDL2 inside `core_ext`,
+and compiles nothing. Every other machine gets the gem that ships the C and
+builds both on install, against a system SDL2. Either way the two land in the
+same place and the three requires above behave the same.
+
+In a checkout of the repository, compile them before you require anything:
 
 ```
 make ext        # builds both, copies them into lib/rgame/
@@ -82,7 +88,7 @@ and `Core`. `Engine` holds what a game is written in.
 | | `RGame::Util` | `RGame::Core` | `RGame::Engine` |
 |---|---|---|---|
 | Contains | shareable *values* — no window, no GPU, nothing to release | things owning a window, GPU or OS handle | game concepts: the scene graph a game is written in |
-| Classes | `Color`, `Tensor`, `Controls`, `Z`, `SolidGrid`, `RouteSearch`, `TileSweep`, `SaveFile` | `App`, `Input`, `Gamepad`, `Image`, `Renderer`, `Recording`, `Font`, `Audio`, `SpriteSheet`, `NineSlice`, `UiAtlas`, `TileMapRenderer`, `AssetManager` | `Node2D`, components, systems, signals, `TileMap`, `Player`, `InputMap`, `UI::Menu` |
+| Classes | `Color`, `Tensor`, `Controls`, `Z`, `SolidGrid`, `RouteSearch`, `TileSweep`, `SaveFile` | `App`, `Input`, `Gamepad`, `VirtualGamepad`, `Image`, `Renderer`, `Recording`, `Font`, `Audio`, `SpriteSheet`, `NineSlice`, `UiAtlas`, `TileMapRenderer`, `AssetManager` | `Node2D`, components, systems, signals, `TileMap`, `Player`, `InputMap`, `UI::Menu` |
 | Loading it costs | nothing | SDL2 + OpenGL in your process | nothing |
 
 **A value goes in `Util`; only a handle-owner goes in `Core`.** A colour is a

data/docs/api/input.md

@@ -436,3 +436,41 @@ end
 
 When a controller is unplugged mid-press, the engine clears its buttons and axes.
 A button held at that moment does not stay stuck down.
+
+## `RGame::Core::VirtualGamepad`
+
+**`VirtualGamepad` plugs a synthetic controller into a running `App`, for tests
+that need the gamepad path with no hardware.** SDL fabricates the device inside
+the process. The `App` seats it and calls `gamepad_connected` on its next frame,
+as it would for a real pad, and `Input` reads its buttons and axes. It serves
+tests, not gameplay; rgame's own Core suite drives its gamepad and hot-plug specs
+through it.
+
+```ruby
+pad = RGame::Core::VirtualGamepad.new   # raises RuntimeError unless an App is open
+
+pad.set_button(0, true)                  # button 0, which Input reads as Controls::PAD_A
+pad.set_axis(0, -32_768)                 # axis 0 is Controls::AXIS_LEFT_X, fully left
+pad.button_down?(0)                      # the raw button, before controller mapping
+pad.game_controller?                     # does SDL have a mapping for it?
+pad.attached?                            # is it still a live device?
+pad.detach                               # the App calls gamepad_disconnected
+
+RGame::Core::VirtualGamepad.pump         # apply pad state SDL has not applied yet
+RGame::Core::VirtualGamepad.sdl_error    # what SDL last said
+```
+
+**Buttons and axes take SDL's own numbers.** A button number is a `Controls` pad
+id minus `Controls::BUTTON_GAMEPAD_FIRST`. An axis number is the `Controls` axis
+id itself. `set_axis` takes -32768 to 32767 and raises `RangeError` outside it.
+
+`set_button` and `set_axis` return true when SDL accepts the change. SDL may
+still apply a change later: outside an `App`'s frame loop a press reads back
+only after one `VirtualGamepad.pump`. A test that must see a press land checks
+`button_down?` and pumps until it does.
+
+`detach` does nothing when called a second time. A pad that is never detached
+stays plugged in until the last `App` is destroyed, because collecting the
+object does not unplug it. SDL shuts down with the last `App` and takes every
+virtual pad with it. After that every method except `detach` raises
+`RuntimeError`.

data/ext/README.md

@@ -151,6 +151,37 @@ ruby ext/rgame_core/example.rb   # opens a window; Esc or close to quit
 `require "rgame/core_ext"` / `require "rgame/util_ext"` find it — mirroring
 how rake-compiler installs a compiled extension into `lib/<gem>/`.
 
+`rgame_core` links the system's SDL2 by default. To link SDL2 statically
+instead, the way a platform gem does, build the pinned release first:
+
+```
+rake sdl2                          # SDL2 as a static library, in build/sdl2
+make ext SDL2_STATIC=build/sdl2    # extconf.rb --with-sdl2-static=<prefix>
+```
+
+This needs CMake, and Ninja on Windows. Switching between the two rebuilds the
+whole extension.
+
+A platform gem ships both extensions precompiled, with that SDL2 linked in. It
+builds from a checkout with no `make ext` objects in `ext/`:
+
+```
+make ext-clean
+rake -f tools/platform_gem.rake platform_gem   # pkg/rgame-<version>-<platform>.gem
+```
+
+On Linux it runs inside the rake-compiler-dock image, as CI does, so that the
+binaries load on older glibc versions.
+
+What the gem does once installed is a different question, and the answer only
+counts on a machine that did not build it — no SDL2, no compiler, no checkout on
+the load path:
+
+```
+gem install --local pkg/rgame-<version>-<platform>.gem
+ruby tools/check_installed_gem.rb    # nothing compiled, and require finds the gem
+```
+
 ## Ruby API
 
 ```ruby

data/ext/rgame_core/app/app.c

@@ -21,6 +21,7 @@
 
 #include "rgame/core.h"
 #include "app/app_gl.h"
+#include "app/sdl_session.h"
 #include "graphics/canvas.h"
 #include "text/font_internal.h"
 #include "app/frame_loop.h"
@@ -52,6 +53,13 @@
  */
 static int rgame_live_apps = 0;
 
+/* Counts the times SDL has started from no live apps; see sdl_session.h. */
+static unsigned rgame_sdl_sessions = 0;
+
+unsigned rgame_sdl_session(void) {
+    return rgame_live_apps > 0 ? rgame_sdl_sessions : 0;
+}
+
 struct rgame_app {
     SDL_Window *window;
     SDL_GLContext gl_context;
@@ -138,7 +146,9 @@ rgame_app *rgame_app_create(int width, int height, const char *title, int fullsc
 
     SDL_GL_SetSwapInterval(1); /* vsync */
 
-    rgame_live_apps++;
+    if (rgame_live_apps++ == 0) {
+        rgame_sdl_sessions++;
+    }
 
     app->running = 1;
     app->refs = 1;

data/ext/rgame_core/app/sdl_session.h

@@ -0,0 +1,18 @@
+#ifndef RGAME_SDL_SESSION_H
+#define RGAME_SDL_SESSION_H
+
+/*
+ * Which run of SDL is current. app.c starts SDL when the first app opens and
+ * shuts it down when the last one goes, and SDL_Quit frees every handle SDL
+ * gave out. A handle that can outlive every app — a virtual gamepad — records
+ * the session it was made in and compares, rather than handing SDL a pointer
+ * SDL has already freed.
+ *
+ * Private to the engine, like app_gl.h.
+ */
+
+/* Non-zero while SDL is running, and different for every run; 0 when no app is
+ * alive. */
+unsigned rgame_sdl_session(void);
+
+#endif /* RGAME_SDL_SESSION_H */

data/ext/rgame_core/extconf.rb

@@ -15,7 +15,21 @@ $INCFLAGS << ' -I$(srcdir)/include'
 
 $INCFLAGS << ' -I$(srcdir)/../rgame_util'
 
-abort 'SDL2 not found (pkg-config --exists sdl2 failed). Install libsdl2-dev.' unless pkg_config('sdl2')
+static_sdl2 = with_config('sdl2-static')
+
+if static_sdl2
+  static_sdl2 = File.expand_path(static_sdl2)
+  pc_dir = File.join(static_sdl2, 'lib', 'pkgconfig')
+  abort "No SDL2 under #{static_sdl2}. Run: rake sdl2" unless File.exist?(File.join(pc_dir, 'sdl2.pc'))
+
+  ENV['PKG_CONFIG_LIBDIR'] = pc_dir
+  abort "pkg-config could not read #{pc_dir}/sdl2.pc" unless pkg_config('sdl2')
+
+  static_only = Shellwords.shellwords(pkg_config('sdl2', 'libs', 'static').to_s) - Shellwords.shellwords($libs)
+  $libs += " #{static_only.shelljoin}" unless static_only.empty?
+else
+  abort 'SDL2 not found (pkg-config --exists sdl2 failed). Install libsdl2-dev.' unless pkg_config('sdl2')
+end
 
 abort 'SDL2 OpenGL header not found (SDL2/SDL_opengl.h). Install libsdl2-dev.' unless have_header('SDL2/SDL_opengl.h')
 
@@ -44,6 +58,18 @@ $libs = append_library($libs, 'dl') if have_library('dl')
 
 $CFLAGS << ' -std=gnu17 -Wall -Wextra'
 
+if static_sdl2
+  case RbConfig::CONFIG['host_os']
+  when /linux/ then $LDFLAGS << ' -Wl,--exclude-libs,ALL'
+  when /darwin/ then $LDFLAGS << ' -Wl,-exported_symbol,_Init_core_ext'
+  end
+end
+
+unless enable_config('libruby-link', true) || RbConfig::CONFIG['host_os'].match?(/mingw|mswin|cygwin/)
+  $LIBRUBYARG = ''
+  $DEFLIBPATH.delete('$(libdir)')
+end
+
 create_makefile('rgame/core_ext')
 
 VENDORED = {

data/ext/rgame_core/include/rgame/core.h

@@ -335,6 +335,68 @@ const char *rgame_app_gamepad_name(const rgame_app *app, int slot);
 /* How many controllers are currently connected. */
 int rgame_app_gamepad_count(const rgame_app *app);
 
+/*
+ * A synthetic game controller, for tests that need the real gamepad path with
+ * no hardware. SDL fabricates it in-process: it reports itself as a game
+ * controller and raises genuine device-added and device-removed events, so an
+ * app seats it and fires its hot-plug callbacks exactly as it would a real pad.
+ *
+ * It lives here rather than in a test helper because only engine code is
+ * guaranteed to call the SDL the engine runs on, whether SDL is linked
+ * statically or dynamically.
+ *
+ * SDL must be running, which means some app must be alive. When the last app is
+ * destroyed SDL shuts down and takes every virtual pad with it; a pad attached
+ * before that is then stale, and every call below except detach and free
+ * reports it rather than touching SDL.
+ */
+typedef struct rgame_virtual_gamepad rgame_virtual_gamepad;
+
+/* Plugs in a new virtual pad. Returns NULL when no app is alive or SDL refuses;
+ * rgame_virtual_gamepad_error says why. */
+rgame_virtual_gamepad *rgame_virtual_gamepad_attach(void);
+
+/* Whether SDL has shut down since this pad was attached. */
+int rgame_virtual_gamepad_stale(const rgame_virtual_gamepad *pad);
+
+/*
+ * Sets an SDL controller button (SDL_CONTROLLER_BUTTON_*) up or down, or an
+ * axis (SDL_CONTROLLER_AXIS_*) to a value in -32768..32767. Returns 0 on
+ * success and -1 when SDL refuses. Each runs SDL's joystick update, but SDL
+ * may still defer the change: outside an app's frame loop a press read back
+ * only after one rgame_virtual_gamepad_pump.
+ */
+int rgame_virtual_gamepad_set_button(rgame_virtual_gamepad *pad, int button, int down);
+int rgame_virtual_gamepad_set_axis(rgame_virtual_gamepad *pad, int axis, int value);
+
+/*
+ * The raw joystick button as SDL last applied it — before any controller
+ * mapping. Differs from what an app reads only if the mapping is wrong.
+ */
+int rgame_virtual_gamepad_button_down(const rgame_virtual_gamepad *pad, int button);
+
+/* Whether SDL treats the pad as a game controller, i.e. has a mapping for it.
+ * An app seats only pads for which this is 1. */
+int rgame_virtual_gamepad_is_game_controller(const rgame_virtual_gamepad *pad);
+
+/* Whether the pad is still a live, attached device. */
+int rgame_virtual_gamepad_attached(const rgame_virtual_gamepad *pad);
+
+/* Runs SDL's event pump and applies pending joystick state — for waiting on a
+ * change SDL has accepted and not yet applied. */
+void rgame_virtual_gamepad_pump(void);
+
+/* Unplugs the pad, as far as SDL and every app are concerned. Safe to call
+ * twice, and on a stale pad, where it does nothing. */
+void rgame_virtual_gamepad_detach(rgame_virtual_gamepad *pad);
+
+/* Frees the handle without touching SDL. A pad freed while still attached stays
+ * plugged in until SDL shuts down. NULL-safe. */
+void rgame_virtual_gamepad_free(rgame_virtual_gamepad *pad);
+
+/* Why the last attach failed, or SDL's own last error. Never NULL. */
+const char *rgame_virtual_gamepad_error(void);
+
 /* Monotonic milliseconds since startup. For time-based animation phase, etc. */
 unsigned int rgame_app_ticks_ms(const rgame_app *app);
 

data/ext/rgame_core/input/virtual_gamepad.c

@@ -0,0 +1,151 @@
+/*
+ * virtual_gamepad.c — a synthetic SDL game controller, for tests.
+ *
+ * Layer 3, and thin: every function is one or two SDL calls. What earns it a
+ * file in the engine rather than in a spec helper is *which* SDL it calls. A
+ * helper reaching SDL from outside the extension has to find it by name or by
+ * exported symbol, and neither works on every platform once SDL is linked into
+ * core_ext statically: on Windows the extension exports no SDL symbol, and a
+ * library name resolves to some other copy of SDL. Code compiled into the
+ * engine can only call the SDL the engine runs on.
+ *
+ * Covered end to end by the gamepad and input specs in spec_core/, which drive
+ * an app's real hot-plug and button path through it.
+ */
+
+#include "rgame/core.h"
+#include "app/sdl_session.h"
+
+#include <SDL2/SDL.h>
+#include <stdlib.h>
+
+struct rgame_virtual_gamepad {
+    SDL_Joystick *joystick;
+    unsigned session;
+    int detached;
+};
+
+static const char *attach_error = NULL;
+
+static int usable(const rgame_virtual_gamepad *pad) {
+    return !pad->detached && pad->session == rgame_sdl_session();
+}
+
+/*
+ * The pad's device index now. SDL renumbers device indices whenever any other
+ * device arrives or leaves, so the index attach returned is not kept: the
+ * instance id is the stable identity, and the index is looked up from it.
+ */
+static int device_index(const rgame_virtual_gamepad *pad) {
+    SDL_JoystickID id = SDL_JoystickInstanceID(pad->joystick);
+    int count = SDL_NumJoysticks();
+    for (int index = 0; index < count; index++) {
+        if (SDL_JoystickGetDeviceInstanceID(index) == id) {
+            return index;
+        }
+    }
+    return -1;
+}
+
+rgame_virtual_gamepad *rgame_virtual_gamepad_attach(void) {
+    attach_error = NULL;
+
+    unsigned session = rgame_sdl_session();
+    if (session == 0) {
+        attach_error = "no app is open, so SDL is not running";
+        return NULL;
+    }
+
+    int index = SDL_JoystickAttachVirtual(SDL_JOYSTICK_TYPE_GAMECONTROLLER, SDL_CONTROLLER_AXIS_MAX,
+                                          SDL_CONTROLLER_BUTTON_MAX, 0);
+    if (index < 0) {
+        return NULL;
+    }
+
+    SDL_Joystick *joystick = SDL_JoystickOpen(index);
+    if (!joystick) {
+        SDL_JoystickDetachVirtual(index);
+        return NULL;
+    }
+
+    rgame_virtual_gamepad *pad = calloc(1, sizeof *pad);
+    if (!pad) {
+        SDL_JoystickClose(joystick);
+        SDL_JoystickDetachVirtual(index);
+        attach_error = "out of memory";
+        return NULL;
+    }
+    pad->joystick = joystick;
+    pad->session = session;
+    return pad;
+}
+
+int rgame_virtual_gamepad_stale(const rgame_virtual_gamepad *pad) {
+    return pad->session != rgame_sdl_session();
+}
+
+int rgame_virtual_gamepad_set_button(rgame_virtual_gamepad *pad, int button, int down) {
+    if (!usable(pad)) {
+        return -1;
+    }
+    int result = SDL_JoystickSetVirtualButton(pad->joystick, button, down ? SDL_PRESSED : SDL_RELEASED);
+    /* Setting virtual state only queues it. An update applies it where SDL can;
+     * where it cannot yet, rgame_virtual_gamepad_pump is the retry. */
+    SDL_JoystickUpdate();
+    return result;
+}
+
+int rgame_virtual_gamepad_set_axis(rgame_virtual_gamepad *pad, int axis, int value) {
+    if (!usable(pad)) {
+        return -1;
+    }
+    int result = SDL_JoystickSetVirtualAxis(pad->joystick, axis, (Sint16)value);
+    SDL_JoystickUpdate();
+    return result;
+}
+
+int rgame_virtual_gamepad_button_down(const rgame_virtual_gamepad *pad, int button) {
+    return usable(pad) && SDL_JoystickGetButton(pad->joystick, button) == SDL_PRESSED;
+}
+
+int rgame_virtual_gamepad_is_game_controller(const rgame_virtual_gamepad *pad) {
+    if (!usable(pad)) {
+        return 0;
+    }
+    int index = device_index(pad);
+    return index >= 0 && SDL_IsGameController(index) == SDL_TRUE;
+}
+
+int rgame_virtual_gamepad_attached(const rgame_virtual_gamepad *pad) {
+    return usable(pad) && SDL_JoystickGetAttached(pad->joystick) == SDL_TRUE;
+}
+
+void rgame_virtual_gamepad_pump(void) {
+    if (rgame_sdl_session() == 0) {
+        return;
+    }
+    SDL_PumpEvents();
+    SDL_JoystickUpdate();
+}
+
+void rgame_virtual_gamepad_detach(rgame_virtual_gamepad *pad) {
+    if (!usable(pad)) {
+        pad->detached = 1;
+        return;
+    }
+    int index = device_index(pad);
+    SDL_JoystickClose(pad->joystick);
+    if (index >= 0) {
+        SDL_JoystickDetachVirtual(index);
+    }
+    pad->joystick = NULL;
+    pad->detached = 1;
+}
+
+void rgame_virtual_gamepad_free(rgame_virtual_gamepad *pad) {
+    free(pad);
+}
+
+const char *rgame_virtual_gamepad_error(void) {
+    return attach_error ? attach_error : SDL_GetError();
+}

data/ext/rgame_core/ruby/core_ext.c

@@ -549,4 +549,5 @@ void Init_core_ext(void) {
     rgame_init_font(mCore);
     rgame_init_audio(mCore);
     rgame_init_locale(mCore);
+    rgame_init_virtual_gamepad(mCore);
 }

data/ext/rgame_core/ruby/core_ext.h

@@ -28,6 +28,9 @@ void rgame_init_locale(VALUE mCore);
  * share a file when everything else here does not. */
 void rgame_init_audio(VALUE mCore);
 
+/* A synthetic game controller for the Core specs; see virtual_gamepad_ext.c. */
+void rgame_init_virtual_gamepad(VALUE mCore);
+
 /*
  * Wraps a baked recording in a Ruby object. Only Renderer#record calls this:
  * `images` is the Array of Images drawn while recording, which the new object

data/ext/rgame_core/ruby/virtual_gamepad_ext.c

@@ -0,0 +1,162 @@
+/*
+ * virtual_gamepad_ext.c — the Ruby binding for RGame::Core::VirtualGamepad.
+ *
+ *   pad = RGame::Core::VirtualGamepad.new   # needs an open App
+ *   pad.set_button(0, true)                  # SDL_CONTROLLER_BUTTON_A down
+ *   pad.button_down?(0)                      # => true
+ *   pad.detach
+ *
+ * Test-only, and named so, like Audio.debug_live_sounds. The engine side is
+ * input/virtual_gamepad.c, which says why this belongs in the extension. This
+ * file checks arguments and turns the engine's "stale" and "refused" answers
+ * into exceptions; how long to wait for a press to land, and whether presses
+ * land at all on a given machine, is the spec harness's business
+ * (spec_core/support/virtual_gamepad.rb).
+ */
+
+#include "ruby/core_ext.h"
+
+#include "rgame/core.h"
+
+typedef struct {
+    rgame_virtual_gamepad *pad;
+} rgame_virtual_gamepad_ref;
+
+/* Frees the handle only. Detaching from inside the collector would raise a
+ * device-removed event at whatever moment GC happened to run, and after the
+ * last App has gone SDL would be touched after SDL_Quit. */
+static void virtual_gamepad_ref_free(void *ptr) {
+    rgame_virtual_gamepad_ref *ref = ptr;
+    rgame_virtual_gamepad_free(ref->pad);
+    xfree(ref);
+}
+
+static size_t virtual_gamepad_ref_size(const void *ptr) {
+    (void)ptr;
+    return sizeof(rgame_virtual_gamepad_ref);
+}
+
+static const rb_data_type_t virtual_gamepad_data_type = {
+    .wrap_struct_name = "rgame_virtual_gamepad",
+    .function = {
+        .dfree = virtual_gamepad_ref_free,
+        .dsize = virtual_gamepad_ref_size,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+/* The pad behind `self`, raising when it can no longer be used: never
+ * initialized, or attached during a run of SDL that has since ended. */
+static rgame_virtual_gamepad *virtual_gamepad_live(VALUE self) {
+    rgame_virtual_gamepad_ref *ref;
+    TypedData_Get_Struct(self, rgame_virtual_gamepad_ref, &virtual_gamepad_data_type, ref);
+    if (!ref->pad) {
+        rb_raise(rb_eRuntimeError, "virtual gamepad is not initialized");
+    }
+    if (rgame_virtual_gamepad_stale(ref->pad)) {
+        rb_raise(rb_eRuntimeError,
+                 "virtual gamepad outlived SDL: every App was destroyed after it was attached");
+    }
+    return ref->pad;
+}
+
+static VALUE virtual_gamepad_alloc(VALUE klass) {
+    rgame_virtual_gamepad_ref *ref;
+    VALUE object = TypedData_Make_Struct(klass, rgame_virtual_gamepad_ref,
+                                         &virtual_gamepad_data_type, ref);
+    ref->pad = NULL;
+    return object;
+}
+
+/* VirtualGamepad.new — plugs in a pad. Raises when no App is open. */
+static VALUE virtual_gamepad_initialize(VALUE self) {
+    rgame_virtual_gamepad_ref *ref;
+    TypedData_Get_Struct(self, rgame_virtual_gamepad_ref, &virtual_gamepad_data_type, ref);
+    if (ref->pad) {
+        rb_raise(rb_eRuntimeError, "virtual gamepad is already attached");
+    }
+
+    rgame_virtual_gamepad *pad = rgame_virtual_gamepad_attach();
+    if (!pad) {
+        rb_raise(rb_eRuntimeError, "cannot attach a virtual gamepad: %s",
+                 rgame_virtual_gamepad_error());
+    }
+    ref->pad = pad;
+    return self;
+}
+
+/*
+ * #set_button(button, down) — `button` is SDL's controller button number, the
+ * same number RGame::Util::Controls' PAD_ ids add to the gamepad range. True
+ * when SDL accepted the change, which SDL may apply only on a later pump.
+ */
+static VALUE virtual_gamepad_set_button(VALUE self, VALUE button, VALUE down) {
+    rgame_virtual_gamepad *pad = virtual_gamepad_live(self);
+    int result = rgame_virtual_gamepad_set_button(pad, NUM2INT(button), RTEST(down));
+    return result == 0 ? Qtrue : Qfalse;
+}
+
+/* #set_axis(axis, value) — `value` in -32768..32767, SDL's own axis range. */
+static VALUE virtual_gamepad_set_axis(VALUE self, VALUE axis, VALUE value) {
+    rgame_virtual_gamepad *pad = virtual_gamepad_live(self);
+    int raw = NUM2INT(value);
+    if (raw < -32768 || raw > 32767) {
+        rb_raise(rb_eRangeError, "axis value %d is outside -32768..32767", raw);
+    }
+    return rgame_virtual_gamepad_set_axis(pad, NUM2INT(axis), raw) == 0 ? Qtrue : Qfalse;
+}
+
+/* #button_down?(button) — the raw joystick button, before controller mapping. */
+static VALUE virtual_gamepad_button_down_p(VALUE self, VALUE button) {
+    rgame_virtual_gamepad *pad = virtual_gamepad_live(self);
+    return rgame_virtual_gamepad_button_down(pad, NUM2INT(button)) ? Qtrue : Qfalse;
+}
+
+/* #game_controller? — whether SDL has a mapping for the pad, which an App needs
+ * before it seats one. */
+static VALUE virtual_gamepad_game_controller_p(VALUE self) {
+    return rgame_virtual_gamepad_is_game_controller(virtual_gamepad_live(self)) ? Qtrue : Qfalse;
+}
+
+static VALUE virtual_gamepad_attached_p(VALUE self) {
+    return rgame_virtual_gamepad_attached(virtual_gamepad_live(self)) ? Qtrue : Qfalse;
+}
+
+/* #detach — unplugs the pad. Does nothing the second time, or once SDL has shut
+ * down, since the pad went with it. */
+static VALUE virtual_gamepad_detach(VALUE self) {
+    rgame_virtual_gamepad_ref *ref;
+    TypedData_Get_Struct(self, rgame_virtual_gamepad_ref, &virtual_gamepad_data_type, ref);
+    if (ref->pad) {
+        rgame_virtual_gamepad_detach(ref->pad);
+    }
+    return Qnil;
+}
+
+/* VirtualGamepad.pump — runs SDL's event pump and applies pending pad state. */
+static VALUE virtual_gamepad_s_pump(VALUE klass) {
+    (void)klass;
+    rgame_virtual_gamepad_pump();
+    return Qnil;
+}
+
+/* VirtualGamepad.sdl_error — what SDL last said when it refused something. */
+static VALUE virtual_gamepad_s_sdl_error(VALUE klass) {
+    (void)klass;
+    return rb_utf8_str_new_cstr(rgame_virtual_gamepad_error());
+}
+
+void rgame_init_virtual_gamepad(VALUE mCore) {
+    VALUE cVirtualGamepad = rb_define_class_under(mCore, "VirtualGamepad", rb_cObject);
+
+    rb_define_alloc_func(cVirtualGamepad, virtual_gamepad_alloc);
+    rb_define_method(cVirtualGamepad, "initialize", virtual_gamepad_initialize, 0);
+    rb_define_method(cVirtualGamepad, "set_button", virtual_gamepad_set_button, 2);
+    rb_define_method(cVirtualGamepad, "set_axis", virtual_gamepad_set_axis, 2);
+    rb_define_method(cVirtualGamepad, "button_down?", virtual_gamepad_button_down_p, 1);
+    rb_define_method(cVirtualGamepad, "game_controller?", virtual_gamepad_game_controller_p, 0);
+    rb_define_method(cVirtualGamepad, "attached?", virtual_gamepad_attached_p, 0);
+    rb_define_method(cVirtualGamepad, "detach", virtual_gamepad_detach, 0);
+    rb_define_singleton_method(cVirtualGamepad, "pump", virtual_gamepad_s_pump, 0);
+    rb_define_singleton_method(cVirtualGamepad, "sdl_error", virtual_gamepad_s_sdl_error, 0);
+}

data/ext/rgame_util/extconf.rb

@@ -6,4 +6,9 @@ $CFLAGS << ' -std=gnu17 -Wall -Wextra'
 
 $CFLAGS << ' -ffp-contract=off'
 
+unless enable_config('libruby-link', true) || RbConfig::CONFIG['host_os'].match?(/mingw|mswin|cygwin/)
+  $LIBRUBYARG = ''
+  $DEFLIBPATH.delete('$(libdir)')
+end
+
 create_makefile('rgame/util_ext')

data/lib/rgame/cli/templates/Gemfile.tt

@@ -8,10 +8,10 @@ source 'https://rubygems.org'
 # replace this line with something like `ruby '~> <%= ruby_version.split('.').first(2).join('.') %>'`.
 ruby file: '.ruby-version'
 
-# The engine. It has no runtime dependencies of its own — SDL2 and OpenGL are
-# system libraries rather than gems — but installing it compiles two C
-# extensions, so a C compiler, `make`, `pkg-config` and the SDL2/OpenGL
-# development headers have to be present. See the rgame README.
+# The engine. Its one gem dependency is rexml, which Bundler installs with it.
+# SDL2 and OpenGL are system libraries rather than gems, and installing rgame
+# compiles two C extensions, so a C compiler, `make`, `pkg-config` and the
+# SDL2/OpenGL development headers have to be present. See the rgame README.
 gem 'rgame', '<%= rgame_requirement %>'
 
 group :development, :test do

data/lib/rgame/core/virtual_gamepad.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+
+module RGame
+  module Core
+    # A synthetic game controller, for tests that need the real gamepad path
+    # with no hardware. It is C (`ext/rgame_core/input/virtual_gamepad.c`, bound
+    # in `ruby/virtual_gamepad_ext.c`), and it serves tests, not gameplay.
+    #
+    #   pad = RGame::Core::VirtualGamepad.new   # an App must be open
+    #   pad.set_button(0, true)                  # SDL_CONTROLLER_BUTTON_A
+    #   pad.set_axis(0, -32_768)                 # left stick fully left
+    #   pad.detach                               # the App sees it unplugged
+    #
+    # SDL fabricates the device in-process, so the App seats it and raises its
+    # `gamepad_connected` and `gamepad_disconnected` callbacks as it would for a
+    # real pad. Buttons and axes take SDL's own numbers.
+    #
+    # It is part of the extension rather than a spec helper because only the
+    # extension is guaranteed to reach the SDL the App runs on, whether SDL is
+    # linked statically or dynamically.
+    class VirtualGamepad
+    end
+  end
+end

data/lib/rgame/core.rb

@@ -5,6 +5,7 @@ require_relative 'core/app'
 require_relative 'core/locale'
 require_relative 'core/input'
 require_relative 'core/gamepad'
+require_relative 'core/virtual_gamepad'
 require_relative 'core/image'
 require_relative 'core/renderer'
 require_relative 'core/recording'

data/lib/rgame/engine/tile_map.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'rexml/document'
-require 'base64'
 require 'zlib'
 
 require_relative '../util'
@@ -52,7 +51,7 @@ module RGame
         layers = []
         above = []
         root.each_element('layer') do |layer_el|
-          raw = Base64.decode64(layer_el.elements['data'].text.strip)
+          raw = layer_el.elements['data'].text.strip.unpack1('m')
           gids = Zlib::Inflate.inflate(raw).unpack('V*')
           gids.map! { |g| g & FLIP_MASK }
           layers << gids

data/lib/rgame/version.rb

@@ -8,5 +8,5 @@
 # module here is enough; the extensions define `RGame` too, and doing so twice
 # is harmless.
 module RGame
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: rgame
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Paul Süßenbach
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
 description: |
   RGame is a small 2D game engine for Ruby, written in Ruby and C. It's build
   on top of SDL2, OpenGL and miniaudio. It's built with testability and
@@ -125,6 +139,7 @@ files:
 - ext/rgame_core/app/frame_loop.h
 - ext/rgame_core/app/locale.c
 - ext/rgame_core/app/locale.h
+- ext/rgame_core/app/sdl_session.h
 - ext/rgame_core/audio/audio.c
 - ext/rgame_core/audio/audio_internal.h
 - ext/rgame_core/audio/vorbis_decoder.c
@@ -158,6 +173,7 @@ files:
 - ext/rgame_core/input/gamepad.h
 - ext/rgame_core/input/input.c
 - ext/rgame_core/input/input.h
+- ext/rgame_core/input/virtual_gamepad.c
 - ext/rgame_core/ruby/audio_ext.c
 - ext/rgame_core/ruby/core_ext.c
 - ext/rgame_core/ruby/core_ext.h
@@ -166,6 +182,7 @@ files:
 - ext/rgame_core/ruby/locale_ext.c
 - ext/rgame_core/ruby/recording_ext.c
 - ext/rgame_core/ruby/renderer_ext.c
+- ext/rgame_core/ruby/virtual_gamepad_ext.c
 - ext/rgame_core/text/atlas.c
 - ext/rgame_core/text/atlas.h
 - ext/rgame_core/text/font.c
@@ -232,6 +249,7 @@ files:
 - lib/rgame/core/sprite_sheet.rb
 - lib/rgame/core/tile_map_renderer.rb
 - lib/rgame/core/ui_atlas.rb
+- lib/rgame/core/virtual_gamepad.rb
 - lib/rgame/engine.rb
 - lib/rgame/engine/actor_blockers.rb
 - lib/rgame/engine/animation_set.rb