ruby-sfml 3.0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8688630fa5286e1b5c28ed9c5cda8aa635a197fe74dc422859253f45f11f111a
+  data.tar.gz: bcb83c0e0667fcae607fa3d3b0ca32527d25dec96fd8726ae697b1b5340c68f9
+SHA512:
+  metadata.gz: d2a0d250ee6f2a7ca62d7da0305f3345bed8170be02f7700074ae1dbb76a24379687c13e64488ab6cbea5eed78821aa9554ecac6501a76ca16eb3febcbe8ca47
+  data.tar.gz: f9b7399e3e2b6168e217292573ef54a15a6217c4675f21f3718a4786787590fda2900d6795b68cd422ca1a5859962aa75d51371305f3ca1584914d5d4e0d13e2

data/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes are documented here. The format roughly follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the gem
+versioning is [described in the README](README.md#versioning) — first
+three segments mirror the targeted CSFML release, fourth segment is
+ruby-sfml's own patch level.
+
+## [Unreleased]
+
+## [3.0.0.0] — initial release
+
+First public cut. Targets **CSFML 3.0.0** (released March 2025) and
+**Ruby ≥ 3.2**. API surface complete for the SFML 3.0 spec; some
+engineering polish still pending (`gem build` end-to-end verification,
+RBS signatures, hosted RDoc).
+
+### System
+- `Vector2`, `Vector3` — operator-friendly value classes with `coerce`
+  (`2 * vec`), pattern-match `deconstruct`, `length`, `normalize`,
+  `dot`/`cross`, conversion helpers
+- `Rect` — single class for float / int rectangles with `contains?`,
+  `intersects?`, deconstruction
+- `Time`, `Clock` — monotonic timer, immutable Time arithmetic
+
+### Window
+- `RenderWindow` — main 2D drawing surface
+- `Window` — bare GL-only window for raw-OpenGL apps
+- `Event` — pattern-matchable hash-like value (`case event in {type: :key_pressed, code: :escape}`)
+- `Keyboard`, `Mouse`, `Joystick` — polling APIs with symbol-named keys / buttons / axes
+- `Cursor` — 21 system cursor types + `from_pixels` for custom shapes
+- `Clipboard` — UTF-8 in / UTF-8 out via the unicode-string CSFML path
+- `VideoMode`
+
+### Graphics
+- `Color`, `Image`, `Texture`, `RenderTexture`
+- `Sprite`, `CircleShape`, `RectangleShape`, `ConvexShape` — share a
+  `Transformable` mixin (position, rotation, scale, origin, move)
+- `Vertex`, `VertexArray` — batched geometry; six primitive types
+- `Font`, `Text` — UTF-8 strings, `local_bounds` / `global_bounds`,
+  Font.find searches common system paths plus a bundled DejaVu Sans
+- `View` — 2D camera, including `from_rect` and viewport for split-screen / minimap
+- `RenderStates`, `BlendMode` — full blend mode catalogue, kwargs
+  shortcut on `window.draw(thing, blend_mode: SFML::BlendMode::ADD)`
+- `Shader` — load from file or memory, uniform setter that dispatches by
+  Ruby type (`shader[:time] = 1.5`, `shader[:tex] = my_texture`,
+  `shader[:tint] = SFML::Color.red`)
+- `Transform` — standalone 4×3 matrix value class, chainable
+- `RenderTarget#draw` accepts `texture:`, `blend_mode:`, `shader:`,
+  `coordinate_type:`, `render_states:` kwargs
+- `RenderTarget#draw_primitives(vertices, type)` — one-shot batch
+  rendering without a `VertexArray` object
+
+### Audio
+- `SoundBuffer`, `Sound`, `Music`
+- 3D positional audio on Sound and Music (`#position=`, `#attenuation=`,
+  `#min_distance=`, `#relative_to_listener=`)
+- `Listener` — global "ear" with `position`, `direction`, `up_vector`,
+  `global_volume`
+- `SoundBufferRecorder` + `SoundRecorder` static helpers — record audio
+  from the system mic into a SoundBuffer
+
+### Network
+- `Network::IpAddress` — value class with `from_string`, `from_bytes`,
+  `LOCALHOST` / `ANY` / `BROADCAST` constants, `local`, `public`
+- `Network::TcpSocket`, `Network::TcpListener` — TCP client + server,
+  blocking and non-blocking modes
+- `Network::UdpSocket` — connectionless datagrams
+- `SocketStatus` returned as symbols (`:done`, `:not_ready`,
+  `:disconnected`, `:error`, `:partial`)
+- Intentionally not wrapped: `Http`, `Ftp` (use Ruby stdlib's
+  `Net::HTTP` / `Net::FTP` — they're nicer)
+
+### Helpers
+- `Game` — subclass-friendly main loop with `setup` / `update(dt)` /
+  `draw` / `on_event` hooks. Auto-quit on Esc + close button.
+- `Assets` — cached, search-path-driven loader.
+  `SFML::Assets.font("DejaVuSans")`, `.texture(name)`, `.sound(name)`,
+  `.music(name)`. Default search root is `<dir of $0>/assets/`.
+- Bundled DejaVu Sans (Bitstream Vera license) — `SFML::Font.default`
+  works without a system font install
+
+### Engineering
+- Two-tier API: `SFML::C::*` thin FFI bindings, `SFML::*` idiomatic
+  Ruby on top. Most user-facing classes are ~50–150 LOC each
+- `RenderTarget` mixin — `RenderWindow` and `RenderTexture` share
+  every drawing method through CSFML_PREFIX dispatch
+- 287 RSpec examples, all hitting real CSFML
+- 20 self-contained example folders under [examples/](examples/)
+- CI matrix: Ubuntu + macOS × Ruby 3.2 / 3.3 / 3.4
+- Linux CI builds CSFML 3 from source (cached) and runs specs under
+  `xvfb-run`
+- `extconf.rb` checks every required `libcsfml-*` plus probes
+  `sfClock_isRunning` (CSFML 3.0+ only) — `gem install` aborts with a
+  helpful message on CSFML 2.x
+- Same probe re-runs at `require "sfml"` time as a runtime sanity
+  check
+- `at_exit` hook stops live `Sound`/`Music` and bypasses Ruby's
+  finalizer pass via `exit!` — eliminates a class of GL/OpenAL-teardown
+  segfaults that plagued every non-trivial example
+- RDoc 7 (Aliki theme) generated via `rake rdoc`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ruby-sfml contributors
+
+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.

data/README.md

@@ -0,0 +1,245 @@
+# ruby-sfml
+
+Modern, idiomatic Ruby bindings for [SFML 3.x](https://www.sfml-dev.org/) via [CSFML](https://github.com/SFML/CSFML) and [Ruby FFI](https://github.com/ffi/ffi).
+
+> **Status:** the API surface is complete for SFML 3.0 — system, window, graphics, audio, network, plus the higher-level `Game` and `Assets` helpers. 287 RSpec examples, 20 runnable example folders. Some details (gem-build verification, RBS signatures, hosted docs) are still pending.
+
+## Why
+
+The original [rbSFML](https://github.com/Groogy/rbSFML) is unmaintained and only works against SFML 2 and Ruby 2.2. `ruby-sfml` targets the current SFML 3.x line, modern Ruby (3.2+), and a Ruby-first API — blocks instead of polling loops, symbols instead of enums, operators on vectors, automatic resource cleanup via GC.
+
+## Requirements
+
+- Ruby `>= 3.2`
+- CSFML **3.0** or compatible 3.x at the system level
+
+### Install CSFML
+
+| OS                       | Command                                  | Notes |
+| ------------------------ | ---------------------------------------- | ----- |
+| Ubuntu 25.04+ / Debian   | `sudo apt install libcsfml-dev`          | Ships CSFML 3 |
+| Ubuntu 22.04 / 24.04     | repo too old (CSFML 2.5)                 | Build from [3.0.0 release](https://github.com/SFML/CSFML/releases/tag/3.0.0) |
+| macOS (brew)             | `brew install csfml`                     | Currently 3.x |
+| Arch Linux               | `sudo pacman -S csfml`                   | Currently 3.x |
+| Windows                  | https://www.sfml-dev.org/download/csfml/ | Pick the 3.0 tarball |
+
+ruby-sfml verifies the linked CSFML twice:
+
+- **At `gem install`** — `extconf.rb` checks for the five `libcsfml-*` libraries plus a CSFML 3.0+ symbol (`sfClock_isRunning`). Aborts with a clear message if the system has CSFML 2.x.
+- **At `require "sfml"`** — same probe runs as a runtime sanity check, in case libraries were swapped between install and use.
+
+You'll see a useful error either way; nothing falls through to a cryptic CSFML segfault.
+
+## A 12-line game
+
+```ruby
+require "sfml"
+
+class Hello < SFML::Game
+  def setup
+    @ball = SFML::CircleShape.new(radius: 30, fill_color: SFML::Color.white,
+                                  position: [200, 200])
+  end
+
+  def update(dt)  = @ball.move(60 * dt.as_seconds * SFML::Vector2[1, 0])
+  def draw        = window.draw(@ball)
+end
+
+Hello.new(title: "Hello", background: SFML::Color.cornflower_blue).run
+```
+
+`SFML::Game` handles window creation, the main loop, event pumping, dt, and the Esc/close-button quit. Override `setup` / `update` / `draw` / `on_event`. Drop into the manual loop style any time you want full control.
+
+## A 5-line manual loop
+
+```ruby
+require "sfml"
+
+window = SFML::RenderWindow.new(800, 600, "Hello", framerate: 60)
+
+while window.open?
+  window.each_event do |event|
+    case event
+    in {type: :closed}                     then window.close
+    in {type: :key_pressed, code: :escape} then window.close
+    else # always include `else` — case/in raises on unmatched events.
+    end
+  end
+
+  window.clear(SFML::Color.cornflower_blue)
+  window.display
+end
+```
+
+## Available modules
+
+| Area     | Classes                                                      |
+| -------- | ------------------------------------------------------------ |
+| System   | `Vector2`, `Vector3`, `Rect`, `Time`, `Clock`                |
+| Window   | `RenderWindow`, `Window` (bare, GL-only), `VideoMode`, `Event`, `Keyboard`, `Mouse`, `Joystick`, `Cursor`, `Clipboard` |
+| Graphics | `Color`, `Image`, `Texture`, `RenderTexture`, `Sprite`, `CircleShape`, `RectangleShape`, `ConvexShape`, `Vertex`, `VertexArray`, `Font`, `Text`, `View`, `BlendMode`, `RenderStates`, `Shader`, `Transform` |
+| Audio    | `SoundBuffer`, `Sound`, `Music`, `Listener`, `SoundRecorder`, `SoundBufferRecorder` (3D positional audio supported on Sound and Music) |
+| Helpers  | `Assets` (search-path + cache), `Game` (lifecycle main loop) |
+
+**Network**: `IpAddress`, `TcpSocket`, `TcpListener`, `UdpSocket` for stream / datagram networking.
+
+## What's intentionally *not* wrapped
+
+CSFML 3 has a few corners we deliberately don't expose. Each is either
+(a) niche enough not to justify the surface area, (b) better served by
+a Ruby standard library, or (c) requires patterns that don't translate
+cleanly to FFI.
+
+**Use Ruby stdlib instead**
+- `sf::Http` — `Net::HTTP` is a better Ruby fit
+- `sf::Ftp` — `Net::FTP` likewise
+- `sf::SocketSelector` — `IO.select` or [Async](https://github.com/socketry/async)
+
+**Callback-based APIs that fight FFI / the GVL**
+- Raw `sf::SoundRecorder` (per-buffer callbacks on the audio thread) —
+  use `SFML::SoundBufferRecorder` for "record into memory, save on stop"
+- `sf::SoundStream` (custom audio source via inheritance) — niche; if
+  you need it, generate samples to a file and play via `Music`
+
+**Mobile / niche inputs** (SFML 3 itself treats these as experimental)
+- `sf::Touch`, `sf::Sensor` (accelerometer, gyro, etc.)
+
+**Advanced graphics features**
+- `sf::VertexBuffer` (static GPU vertex buffer) — `VertexArray` covers
+  the common case; if you need static-mesh perf, open an issue
+- Geometry shaders — only vertex and fragment stages on `SFML::Shader`
+- `sf::Shader#setUniformArray` (bulk uniforms) — set elements one by one
+- Stencil buffer ops (`clearStencil`, custom `StencilMode`) — accept
+  CSFML defaults
+- `sf::Image#saveToMemory` — only `Image#save(path)` is wrapped
+
+**Advanced audio features**
+- Sound / Music cones, velocity, Doppler factor, custom DSP via
+  `setEffectProcessor` — basic 3D positional + attenuation is in;
+  the rest is rarely used in 2D gamedev
+- `sf::Listener` cone — same reasoning
+
+**Embedding / integration corners**
+- `RenderWindow.createFromHandle` (embed in another framework's window)
+- Custom `sf::InputStream` for loading assets from non-file sources
+- Window icon, min/max size, native handle accessors on `SFML::Window`
+
+**Other Ruby bindings worth knowing about**
+- SFML 2.x is *not* covered. The previous-generation gem
+  [rbSFML](https://github.com/Groogy/rbSFML) targets SFML 2; it's
+  unmaintained and only works with Ruby ≤ 2.2.
+
+If anything in the list above is blocking you, **open an issue** —
+"niche" is just a default, not a closed door.
+
+## Examples
+
+Each example is a self-contained folder under [examples/](examples/),
+numbered roughly in learning order. Assets each example needs sit next
+to its script. Run from the gem root:
+
+```sh
+bundle exec ruby examples/<NN_name>/<name>.rb
+```
+
+| #   | Example                                                                        | What it shows                                                       |
+| --- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| 01  | [hello_window](examples/01_hello_window/hello_window.rb)                       | Empty window, manual event loop                                     |
+| 02  | [events_demo](examples/02_events_demo/events_demo.rb)                          | Pattern matching on input events                                    |
+| 03  | [bouncing_ball](examples/03_bouncing_ball/bouncing_ball.rb)                    | dt-based physics, `CircleShape` + `RectangleShape`                  |
+| 04  | [game_class](examples/04_game_class/game_class.rb)                             | Same idea on top of `SFML::Game`                                    |
+| 05  | [mouse_demo](examples/05_mouse_demo/mouse_demo.rb)                             | Polling vs. events; paint with the mouse                            |
+| 06  | [pong](examples/06_pong/pong.rb)                                               | Two-player Pong with in-window score (`Text`) and bounce `Sound`    |
+| 07  | [scrolling_world](examples/07_scrolling_world/scrolling_world.rb)              | `View` as a 2D camera: drag-pan, wheel-zoom around cursor, FPS HUD  |
+| 08  | [joystick_demo](examples/08_joystick_demo/joystick_demo.rb)                    | Live gamepad inspector (axes, buttons, connect/disconnect)          |
+| 09  | [image_viewer](examples/09_image_viewer/image_viewer.rb)                       | Load a PNG, mutate the `Image`, re-upload to `Texture` on a key     |
+| 10  | [pixel_paint](examples/10_pixel_paint/pixel_paint.rb)                          | Paint into a CPU `Image`, blit to GPU `Texture` each dirty frame    |
+| 11  | [particles](examples/11_particles/particles.rb)                                | Thousands of points in one draw call via `VertexArray` + `ConvexShape` ground |
+| 12  | [render_texture](examples/12_render_texture/render_texture.rb)                 | Off-screen `RenderTexture` for trail / motion-blur effects        |
+| 13  | [tilemap](examples/13_tilemap/tilemap.rb)                                      | Textured `VertexArray` tilemap + additive `BlendMode` torch       |
+| 14  | [shader_wave](examples/14_shader_wave/shader_wave.rb)                          | Pure GLSL fragment `Shader` — procedural ripple + plasma          |
+| 15  | [cursors_clipboard](examples/15_cursors_clipboard/cursors_clipboard.rb)        | All 21 system `Cursor` shapes + `Clipboard` copy/paste            |
+| 16  | [spatial_audio](examples/16_spatial_audio/spatial_audio.rb)                    | 3D positional `Sound` + `Listener` — three drones around the cursor |
+| 17  | [voice_memo](examples/17_voice_memo/voice_memo.rb)                             | Record from microphone via `SoundBufferRecorder`, save + play back |
+| 18  | [draw_primitives](examples/18_draw_primitives/draw_primitives.rb)              | Raw `draw_primitives` — line burst rebuilt every frame             |
+| 19  | [udp_loopback](examples/19_udp_loopback/udp_loopback.rb)                       | UDP send/receive on localhost via `Network::UdpSocket`             |
+| 20  | [bare_window](examples/20_bare_window/bare_window.rb)                          | `SFML::Window` (no 2D batcher) — events for raw-OpenGL apps        |
+
+## Idioms baked in
+
+- **Symbols, not enums:** `Keyboard.key_pressed?(:escape)`, not `Keyboard::Key::Escape`.
+- **Pattern matching for events:**
+  ```ruby
+  case event
+  in {type: :key_pressed, code: :escape}
+  in {type: :resized, size: {x:, y:}}
+  in {type: :mouse_button_pressed, button: :left, position: {x:, y:}}
+  end
+  ```
+- **Vectors with operators:** `pos + velocity * dt`, `2 * vec`, `vec.length`, deconstruction in `case/in`.
+- **Kwargs constructors:** `Sprite.new(texture, position: [0, 0], color: SFML::Color.red)`, `CircleShape.new(radius: 10, fill_color: ...)` — no setter chains.
+- **Asset manager with cache:** `SFML::Assets.font("DejaVuSans")`, `SFML::Assets.sound("blip")` — load each thing once, refer by name.
+- **GC-managed resources:** every CSFML pointer goes through `FFI::AutoPointer`, so `sfXxx_destroy` is called automatically.
+
+## Versioning
+
+The gem version is `MAJOR.MINOR.PATCH.GEM_PATCH` — the first three segments mirror the CSFML release the gem was built against; the fourth is our own patch level for fixes / additions on top of the same upstream:
+
+| gem version | targets CSFML | meaning                                         |
+| ----------- | ------------- | ----------------------------------------------- |
+| `3.0.0.0`   | 3.0.0         | First cut against CSFML 3.0.0                   |
+| `3.0.0.1`   | 3.0.0         | Bug fix on top of CSFML 3.0.0                   |
+| `3.0.1.0`   | 3.0.1         | CSFML 3.0.1 ships, we re-cut                    |
+| `3.1.0.0`   | 3.1.0         | New CSFML minor — added bindings for new APIs   |
+
+`SFML::CSFML_VERSION` exposes the upstream string at runtime.
+
+Bundler-pinning patterns:
+
+```ruby
+gem "ruby-sfml", "~> 3.0"      # any 3.x.x.x — typical
+gem "ruby-sfml", "~> 3.0.0"    # only 3.0.0.x — hold across a CSFML minor
+gem "ruby-sfml", "~> 3.0.0.0"  # only our patches on CSFML 3.0.0 — paranoid pin
+```
+
+## Process exit
+
+ruby-sfml installs a single `at_exit` hook that:
+
+1. Stops every live `SFML::Sound` / `SFML::Music` so the audio thread quiets before anything is freed.
+2. Calls `Kernel#exit!` with the appropriate status, bypassing Ruby's natural finalizer pass.
+
+This is intentional. CSFML's GL context, font glyph atlases, and OpenAL state are reclaimed by the OS on process exit; running each `FFI::AutoPointer` finalizer in a non-deterministic order tends to crash inside libGL/libopenal. The OS doesn't care, and now neither do we.
+
+The trade-off: any user `at_exit` hook registered **before** `require "sfml"` will be skipped. Hooks registered after the require run first (Ruby's at_exit is LIFO) and are unaffected. Put your `require` at the top of the file (the normal place for it) and there's nothing to think about.
+
+## Architecture
+
+Two layers. Users only touch the top one.
+
+```
+SFML::C    # thin FFI wrapper around CSFML, 1:1 with the C API
+SFML       # idiomatic Ruby on top
+```
+
+Each render target (RenderWindow + RenderTexture) includes a `Graphics::RenderTarget` mixin that dispatches `clear`, `display`, `draw`, `view=`, `map_pixel_to_coords` etc. through the includer's `CSFML_PREFIX`. Adding a new target (say a future `RenderImage`) is ~30 lines.
+
+When SFML 3.1 / CSFML 3.1 ships, only the bottom layer typically needs to move.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec        # 287 examples
+bundle exec rake rdoc    # generate HTML docs in doc/ (Aliki theme via RDoc 7)
+```
+
+The spec suite hits real CSFML for everything that isn't pure Ruby — `Clock` reads the real monotonic clock, `Text#local_bounds` measures real glyphs, audio loads a WAV — so a green run also confirms the FFI bindings line up. `spec/fixtures/` holds the only assets the suite touches (a font and a tiny WAV) so tests are independent of `examples/`.
+
+CI runs the full suite on Ubuntu and macOS × Ruby 3.2 / 3.3 / 3.4. Linux builds CSFML 3 from source (cached), then runs specs under `xvfb-run` so the headless runner has an X server for `RenderWindow`.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).
+
+The gem also bundles [DejaVu Sans](https://dejavu-fonts.github.io/) under its [permissive license](lib/sfml/assets/fonts/DejaVuSans.LICENSE.txt) — used as the default font when you don't supply your own.

data/ext/ruby-sfml/extconf.rb

@@ -0,0 +1,69 @@
+require "mkmf"
+
+# This is not a real native extension. We use the extconf.rb hook only as a
+# pre-flight check: if CSFML 3.x is not on the system, fail `gem install` here
+# with a clear message instead of letting the user discover the problem at
+# runtime.
+
+REQUIRED_LIBS = %w[csfml-system csfml-window csfml-graphics csfml-audio csfml-network]
+
+missing = REQUIRED_LIBS.reject { |lib| have_library(lib) }
+
+unless missing.empty?
+  abort <<~MSG
+
+    ============================================================================
+    ruby-sfml requires CSFML 3.x to be installed on your system.
+
+    Missing libraries: #{missing.join(', ')}
+
+    Install CSFML, then re-run `gem install ruby-sfml`:
+
+        Ubuntu / Debian:  sudo apt install libcsfml-dev
+        macOS (brew):     brew install csfml
+        Arch Linux:       sudo pacman -S csfml
+        Windows:          https://www.sfml-dev.org/download/csfml/
+
+    See https://github.com/m1kh41l/ruby-sfml#requirements for full instructions.
+    ============================================================================
+
+  MSG
+end
+
+# All libcsfml-* are present, but they might be 2.x (Ubuntu 22.04 / 24.04
+# ship 2.5 in their repos). Probe a CSFML 3.0+ symbol — sfClock_isRunning
+# is part of the SFML 3 sf::Clock rewrite and isn't in any 2.x release.
+unless have_func("sfClock_isRunning")
+  abort <<~MSG
+
+    ============================================================================
+    ruby-sfml requires CSFML 3.0 or newer.
+
+    The libcsfml on your system is older than 3.0 — sfClock_isRunning,
+    introduced in the SFML 3.0 / CSFML 3.0 release (March 2025), is not
+    exported by the linked library.
+
+    Upgrade options:
+
+        Ubuntu 25.04+ / Debian:  sudo apt install libcsfml-dev
+        Ubuntu 22.04 / 24.04:    repo is too old; build from source:
+                                   https://github.com/SFML/CSFML/releases/tag/3.0.0
+        macOS (brew):            brew upgrade csfml
+        Arch Linux:              sudo pacman -S csfml
+
+    Or grab a prebuilt 3.x release from
+    https://github.com/SFML/CSFML/releases.
+    ============================================================================
+
+  MSG
+end
+
+# Emit a no-op Makefile so RubyGems considers the extension "built".
+File.write("Makefile", <<~MAKE)
+  all:
+  \t@true
+  install:
+  \t@true
+  clean:
+  \t@true
+MAKE

data/lib/sfml/assets/fonts/DejaVuSans.LICENSE.txt

@@ -0,0 +1,78 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: DejaVu fonts
+Upstream-Author: Stepan Roh <src@users.sourceforge.net> (original author),
+                  see /usr/share/doc/fonts-dejavu-core/AUTHORS for full list
+Source: https://dejavu-fonts.github.io/
+
+Files: *
+Copyright: Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. 
+ Bitstream Vera is a trademark of Bitstream, Inc.
+ DejaVu changes are in public domain.
+License: bitstream-vera
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of the fonts accompanying this license ("Fonts") and associated
+ documentation files (the "Font Software"), to reproduce and distribute the
+ Font Software, including without limitation the rights to use, copy, merge,
+ publish, distribute, and/or sell copies of the Font Software, and to permit
+ persons to whom the Font Software is furnished to do so, subject to the
+ following conditions:
+ .
+ The above copyright and trademark notices and this permission notice shall
+ be included in all copies of one or more of the Font Software typefaces.
+ .
+ The Font Software may be modified, altered, or added to, and in particular
+ the designs of glyphs or characters in the Fonts may be modified and
+ additional glyphs or characters may be added to the Fonts, only if the fonts
+ are renamed to names not containing either the words "Bitstream" or the word
+ "Vera".
+ .
+ This License becomes null and void to the extent applicable to Fonts or Font
+ Software that has been modified and is distributed under the "Bitstream
+ Vera" names.
+ .
+ The Font Software may be sold as part of a larger software package but no
+ copy of one or more of the Font Software typefaces may be sold by itself.
+ .
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+ TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+ FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
+ ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+ THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
+ FONT SOFTWARE.
+ .
+ Except as contained in this notice, the names of Gnome, the Gnome
+ Foundation, and Bitstream Inc., shall not be used in advertising or
+ otherwise to promote the sale, use or other dealings in this Font Software
+ without prior written authorization from the Gnome Foundation or Bitstream
+ Inc., respectively. For further information, contact: fonts at gnome dot
+ org.
+
+Files: debian/*
+Copyright: (C) 2005-2006 Peter Cernak <pce@users.sourceforge.net> 
+           (C) 2006-2011 Davide Viti <zinosat@tiscali.it>
+           (C) 2011-2013 Christian Perrier <bubulle@debian.org>
+           (C) 2013 Fabian Greffrath <fabian+debian@greffrath.com>
+License: GPL-2+
+ This program is free software; you can redistribute it
+ and/or modify it under the terms of the GNU General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later
+ version.
+ .
+ This program is distributed in the hope that it will be
+ useful, but WITHOUT ANY WARRANTY; without even the implied
+ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ PURPOSE.  See the GNU General Public License for more
+ details.
+ .
+ You should have received a copy of the GNU General Public
+ License along with this package; if not, write to the Free
+ Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ Boston, MA  02110-1301 USA
+ .
+ On Debian systems, the full text of the GNU General Public
+ License version 2 can be found in the file
+ /usr/share/common-licenses/GPL-2'.

data/lib/sfml/assets.rb

@@ -0,0 +1,121 @@
+module SFML
+  # Cached, search-path-driven asset loader. Use it to avoid repeating file
+  # paths and to load each asset exactly once.
+  #
+  #   font  = SFML::Assets.font("DejaVuSans")
+  #   tex   = SFML::Assets.texture("hero")           # finds hero.png/.jpg/.bmp
+  #   blip  = SFML::Assets.sound("blip")             # finds blip.wav/.ogg/...
+  #   music = SFML::Assets.music("track")            # NOT cached (stateful)
+  #
+  # By default the search root is `<dir of $0>/assets/`. Override:
+  #
+  #   SFML::Assets.root = File.expand_path("data", __dir__)
+  #   SFML::Assets.add_search_path("/usr/local/share/mygame")
+  #
+  # Cache survives until you call .clear or the process exits.
+  module Assets
+    TEXTURE_EXTS = %w[.png .jpg .jpeg .bmp .gif .tga].freeze
+    SOUND_EXTS   = %w[.wav .ogg .flac .mp3].freeze
+    MUSIC_EXTS   = SOUND_EXTS
+    FONT_EXTS    = %w[.ttf .otf].freeze
+
+    class NotFound < SFML::Error; end
+
+    class << self
+      def search_paths
+        @search_paths ||= [default_root]
+      end
+
+      def search_paths=(paths)
+        @search_paths = Array(paths).map { |p| File.expand_path(p) }
+        @cache&.clear
+      end
+
+      def root=(path)
+        self.search_paths = [path]
+      end
+
+      def add_search_path(path)
+        search_paths << File.expand_path(path) unless search_paths.include?(File.expand_path(path))
+      end
+
+      # Drop everything from the in-memory cache. New loads will re-read
+      # from disk and recreate textures, fonts, sound buffers.
+      def clear
+        @cache&.clear
+        self
+      end
+
+      def font(name)
+        cache[[:font, name]] ||= load_font(name)
+      end
+
+      def texture(name)
+        cache[[:texture, name]] ||= load_texture(name)
+      end
+
+      def sound(name)
+        cache[[:sound, name]] ||= load_sound_buffer(name)
+      end
+
+      # Music is intentionally NOT cached — it owns a streaming position and
+      # play state, so each caller wants its own instance.
+      def music(name)
+        path = locate(name, MUSIC_EXTS) or raise NotFound,
+          "Music #{name.inspect} not found. Searched: #{search_paths.inspect}"
+        Music.load(path)
+      end
+
+      private
+
+      def cache
+        @cache ||= {}
+      end
+
+      def default_root
+        File.expand_path("assets", File.dirname($PROGRAM_NAME || "."))
+      end
+
+      def load_font(name)
+        path = locate(name, FONT_EXTS)
+        return Font.load(path) if path
+        # Fall back to a system-font search — fonts are large and rarely
+        # shipped with games, so this often does the right thing.
+        Font.find(name) or raise NotFound,
+          "Font #{name.inspect} not found in #{search_paths.inspect} or system fonts"
+      end
+
+      def load_texture(name)
+        path = locate(name, TEXTURE_EXTS) or raise NotFound,
+          "Texture #{name.inspect} not found. Searched: #{search_paths.inspect}"
+        Texture.load(path)
+      end
+
+      def load_sound_buffer(name)
+        path = locate(name, SOUND_EXTS) or raise NotFound,
+          "Sound #{name.inspect} not found. Searched: #{search_paths.inspect}"
+        SoundBuffer.load(path)
+      end
+
+      # Finds an asset on disk. If `name` already has a matching extension,
+      # uses it as-is; otherwise tries each extension in order.
+      def locate(name, extensions)
+        name_str = name.to_s
+        candidates =
+          if extensions.any? { |ext| name_str.end_with?(ext) }
+            [name_str]
+          else
+            extensions.map { |ext| "#{name_str}#{ext}" }
+          end
+
+        search_paths.each do |dir|
+          candidates.each do |cand|
+            full = File.join(dir, cand)
+            return full if File.file?(full)
+          end
+        end
+        nil
+      end
+    end
+  end
+end