ruby-sfml 3.0.0.1 → 3.0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f6e44279278680f06163024e2dd2f1eecbc8e8624960d589ec74e591849c9b3
-  data.tar.gz: 23fc48fc06aa0f7e6807b681c2601784de0159d9429055617e87d1e7977d20fa
+  metadata.gz: 8136e14f0f8d0f777f7649e15a61e6017e386f7e80e023d5a2b8000191db9213
+  data.tar.gz: f6fed33adc435dcbe67777499d0aae14e58ae670a7a04fc94cb58b23805e8fc8
 SHA512:
-  metadata.gz: d351b03bb583fb5bb7ddd469da17838d876d7f5c99cbdae5387c94dfbf933f7299362d70bc8360c71b1b5737c49622bb55795869f2bd49d1784aab910f16d32d
-  data.tar.gz: d5b91cdb38ee758ca2fc76daf52f2aba4c6172b7d6798d51783caa677a10684d394881dca6e01e704e8db9d1be372ef38035de43e4f49b3bab26a9066d5728f5
+  metadata.gz: 62d6d8965915bfe6e95161ae8580a3b2d84eca6334a33387238073de069839dae4f08829f82f42042f43850899ed24329e3d49610ac6ec95092b53685ed49d2e
+  data.tar.gz: a4f6805ba848b00c623ae4f1b0029b97423f154058e472e3208c48873c9f2be229707aed0ac2934483256c03f048fc06bf3f6c9c8001712ab7e764d8aa23bba4

data/CHANGELOG.md

@@ -8,6 +8,85 @@ ruby-sfml's own patch level.
 
 ## [Unreleased]
 
+## [3.0.0.2] — 2026-05-09
+
+### Added
+- **`SFML::App`** — subclass-friendly main loop. Removes the
+  boilerplate of window creation, event pumping, dt management,
+  and clear/display so a small app fits in a few methods.
+- Class-level configuration DSL for `SFML::App`. Defaults that
+  used to be passed to `.new` can now be declared in the class
+  body and inherited:
+  ```ruby
+  class MyApp < SFML::App
+    width        800
+    height       600
+    title        "Smooth"
+    framerate    120
+    antialiasing 4
+    background   SFML::Color["#1a1a1a"]
+  end
+  ```
+  Per-instance kwargs to `.new` still override on a case-by-case
+  basis. Available macros: `width`, `height`, `title`, `framerate`,
+  `vsync`, `background`, `style`, `fullscreen`, `antialiasing`,
+  `context`.
+- **`SFML::ContextSettings`** — configures the OpenGL context the
+  window backs onto: anti-aliasing level, depth/stencil bits, GL
+  version. The fifth argument to `sfRenderWindow_create` is no
+  longer `NULL` by default; pass `antialiasing: 4` (or
+  `context: SFML::ContextSettings.new(...)`) to
+  `RenderWindow.new` / `SFML::App.new` to turn on MSAA. Read back
+  what the driver actually gave you with
+  `window.context_settings`. Wraps `sfContextSettings` and
+  `sfRenderWindow_getSettings`.
+- **`on_key`** — class-level keybinding DSL. Bind a key to an
+  instance method, a Proc, or a block; bindings inherit through
+  subclasses with later definitions shadowing earlier ones:
+  ```ruby
+  class MyApp < SFML::App
+    on_key :escape, :quit
+    on_key :f11,    :toggle_fullscreen
+    on_key :p       do |app| app.toggle_pause end
+  end
+  ```
+  Bindings live as the class's `key_handlers` Hash; the same DSL
+  is also available on `SFML::Scene`, where scene-level bindings
+  shadow app-level ones for the active scene.
+- **`pause` / `resume` / `toggle_pause` / `paused?`** on
+  `SFML::App` — while paused, `update(dt)` is skipped but `draw`
+  continues, so a pause overlay can be drawn on top of a frozen
+  scene.
+- **`on_resize(width, height)`** hook on `SFML::App` and
+  `SFML::Scene` — replaces the `case event in {type: :resized,
+  size: {x:, y:}}` boilerplate that used to live inside
+  `on_event`. Default forwards to the active scene.
+- **`SFML::Scene`** — base class for stateful screens (menu,
+  gameplay, results screen, settings overlay, etc.). Lifecycle
+  hooks (`setup` / `update` / `draw` / `on_event` / `on_resize` /
+  `teardown`), its own `on_key` DSL, and a `switch_to(other)`
+  shortcut that delegates to the host app. The host app picks a
+  starting scene with the `initial_scene SomeScene` class macro;
+  `App.switch_to` tears down the previous scene before calling
+  `setup` on the new one.
+- New example
+  [24_scenes](examples/24_scenes/scenes.rb) — title → play scene
+  pair built on `SFML::Scene` + `initial_scene`.
+- New example
+  [04_app_class](examples/04_app_class/app_class.rb) — bouncing
+  ball on top of `SFML::App` with class-level config and
+  `on_key` bindings (replaces the old `04_game_class` example).
+
+### Changed
+- `SFML::App._dispatch` no longer auto-quits on Esc. Apps that
+  want it bind it explicitly with `on_key :escape, :quit`. The
+  window-close button (`:closed`) still always quits.
+- Audio specs (anything under `spec/sfml/audio/`) are now
+  auto-tagged `:audio` and skipped by default on macOS, where
+  CoreAudio + the CSFML OpenAL backend occasionally hang the
+  test group. Opt-in with `bundle exec rspec --tag audio`.
+  Linux runs the full suite as before.
+
 ## [3.0.0.1] — 2026-05-07
 
 ### Added
@@ -202,8 +281,8 @@ RBS signatures, hosted RDoc).
   `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.
+- `App` — subclass-friendly main loop with `setup` / `update(dt)` /
+  `draw` / `on_event` hooks.
 - `Assets` — cached, search-path-driven loader.
   `SFML::Assets.font("DejaVuSans")`, `.texture(name)`, `.sound(name)`,
   `.music(name)`. Default search root is `<dir of $0>/assets/`.

data/README.md

@@ -1,54 +1,89 @@
-# ruby-sfml
+<h1>
+  <img src="ruby-sfml.png" alt="" height="48" align="absmiddle">
+  ruby-sfml
+</h1>
 
 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 (incl. stencil buffer + VBOs), audio (incl. 3D positional + custom DSP + procedural streams), network (incl. HTTP / FTP / socket selector), input (keyboard, mouse, joystick, touch, sensors), plus the higher-level `Game` and `Assets` helpers. 387 RSpec examples, 23 runnable example folders. RBS signatures are the main remaining engineering item.
+[![gem version](https://img.shields.io/gem/v/ruby-sfml.svg)](https://rubygems.org/gems/ruby-sfml)
+[![docs](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://www.rubydoc.info/gems/ruby-sfml)
+
+> **Status:** API surface complete for SFML 3.0 — system, window, graphics (incl. stencil buffer + VBOs), audio (incl. 3D positional + custom DSP + procedural streams), network (incl. HTTP / FTP / socket selector), input (keyboard, mouse, joystick, touch, sensors), plus the higher-level `App` / `Scene` / `Assets` helpers. 410 RSpec examples, 24 runnable example folders.
 
 ## 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
+## Installation
 
-- Ruby `>= 3.2`
-- CSFML **3.0** or compatible 3.x at the system level
+ruby-sfml needs **Ruby ≥ 3.2** and **CSFML 3.0** (or compatible 3.x) on
+the system. Install in two steps:
 
-### Install CSFML
+### 1. Install dependencies (CSFML)
 
-| OS                       | Command                                  | Notes |
-| ------------------------ | ---------------------------------------- | ----- |
-| Ubuntu 25.04+ / Debian   | `sudo apt install libcsfml-dev`          | Ships CSFML 3 |
+| 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 |
+| 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                                                     |
+
+### 2. Install the gem
+
+In a Bundler-managed project, add to your `Gemfile`:
+
+```ruby
+gem "ruby-sfml", "~> 3.0"
+```
+
+then `bundle install`.
+
+Or drop it in directly:
+
+```sh
+gem install ruby-sfml
+```
 
-ruby-sfml verifies the linked CSFML twice:
+Hosted on [rubygems.org](https://rubygems.org/gems/ruby-sfml); HTML
+docs auto-generate at
+[rubydoc.info/gems/ruby-sfml](https://www.rubydoc.info/gems/ruby-sfml).
 
-- **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.
+### How the CSFML check happens
 
-You'll see a useful error either way; nothing falls through to a cryptic CSFML segfault.
+ruby-sfml verifies the linked CSFML in two places so a missing or
+out-of-date library never falls through to a cryptic segfault:
 
-## A 12-line game
+- **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"`** — the same probe runs as a runtime sanity
+  check, in case libraries were swapped between install and use.
+
+## A 13-line app
 
 ```ruby
 require "sfml"
 
-class Hello < SFML::Game
+class Hello < SFML::App
+  title        "Hello"
+  background   SFML::Color.cornflower_blue
+  antialiasing 4
+
   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)
+  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
+Hello.new.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.
+`SFML::App` handles window creation, the main loop, event pumping, dt, and the Esc/close-button quit. Override `setup` / `update` / `draw` / `on_event`. Class-level macros (`title`, `framerate`, `antialiasing`, `background`, ...) set per-class defaults; per-instance kwargs to `.new` still override on a case-by-case basis. Drop into the manual loop style any time you want full control.
 
 ## A 5-line manual loop
 
@@ -79,44 +114,36 @@ end
 | Window   | `RenderWindow`, `Window` (bare, GL-only), `VideoMode`, `Event`, `Keyboard`, `Mouse`, `Joystick`, `Touch`, `Sensor`, `Cursor`, `Clipboard` |
 | Graphics | `Color`, `Image`, `Texture`, `RenderTexture`, `Sprite`, `CircleShape`, `RectangleShape`, `ConvexShape`, `Vertex`, `VertexArray`, `VertexBuffer`, `Font`, `Text`, `View`, `BlendMode`, `StencilMode`, `RenderStates`, `Shader`, `Transform` |
 | Audio    | `SoundBuffer`, `Sound`, `Music`, `Listener`, `SoundCone`, `SoundStream`, `SoundRecorder`, `SoundBufferRecorder` (3D positional + cones + Doppler + custom DSP via `effect_processor=`) |
-| Helpers  | `Assets` (search-path + cache), `Game` (lifecycle main loop) |
+| Helpers  | `Assets` (search-path + cache), `App` (lifecycle main loop with class-level config + `on_key` DSL + `pause` / `on_resize`), `Scene` (stateful screens + `switch_to` between them), `ContextSettings` (MSAA / GL version) |
 
 **Network**: `IpAddress`, `TcpSocket`, `TcpListener`, `UdpSocket`, `SocketSelector` for stream / datagram networking, plus the niche `Http` and `Ftp` clients (use Ruby's `Net::HTTP` / `Net::FTP` if you have the choice — these exist for parity with CSFML).
 
 ## What's intentionally *not* wrapped
 
-A handful of CSFML 3 corners deliberately stay out:
+Three corners of CSFML 3 deliberately stay out:
 
-- **Geometry shaders** — CSFML doesn't expose them at all (only vertex
-  and fragment stages); nothing for us to wrap.
+- **Geometry shaders** — CSFML doesn't expose them at all (only
+  vertex and fragment stages); there's nothing on the C side to
+  wrap.
 - **Raw `sf::SoundRecorder`** (per-buffer callbacks on the audio
-  thread) — use `SFML::SoundBufferRecorder` for the common "record
-  into memory, save on stop" path. The raw callback variant fights
-  the GVL hard.
+  thread) — fights the GVL too hard for what it gives. Use
+  `SFML::SoundBufferRecorder` for the common "record into memory,
+  save on stop" path.
 - **Custom `sf::InputStream`** for loading assets from non-file
-  sources — Ruby has `IO`, just read into memory and use the
-  byte-string constructors.
-
-**An aside on `Http` / `Ftp` / `SocketSelector`** — these *are*
-wrapped (matches CSFML for parity), but for any non-trivial use
-Ruby's stdlib `Net::HTTP` / `Net::FTP` and `IO.select` are better
-tools.
+  sources — Ruby's `IO` covers this. Read the bytes yourself and
+  feed them into the byte-string constructors.
 
-**An aside on `SoundStream` and `effect_processor=`** — both *are*
-wrapped, but their callbacks run on the SFML audio thread and
-must reacquire the GVL each invocation. Fine for trivial DSP;
-expect glitches for anything heavier.
+If anything else is missing or blocking you, **open an issue**.
 
-**Other Ruby bindings worth knowing about**
+## 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.
-- **RubySFML3** (Andy P., 2026) — a thin FFI wrapper that exposes
-  the CSFML C API directly. If you want raw bindings (no idiomatic
-  Ruby layer, no auto-cleanup), check that project instead.
-
-If anything missing here is blocking you, **open an issue**.
+- [RubySFML3](https://github.com/gAndy50/RubySFML3) — a thin FFI
+  wrapper that exposes the CSFML C API directly. If you want raw
+  bindings (no idiomatic Ruby layer, no auto-cleanup), check that
+  project instead.
 
 ## Examples
 
@@ -133,7 +160,7 @@ bundle exec ruby examples/<NN_name>/<name>.rb
 | 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`                                    |
+| 04  | [app_class](examples/04_app_class/app_class.rb)                                 | Same idea on top of `SFML::App`                                     |
 | 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  |
@@ -219,7 +246,7 @@ When SFML 3.1 / CSFML 3.1 ships, only the bottom layer typically needs to move.
 
 ```sh
 bundle install
-bundle exec rspec        # 287 examples
+bundle exec rspec        # 410 examples (all subsystems on Linux)
 bundle exec rake rdoc    # generate HTML docs in doc/ (Aliki theme via RDoc 7)
 ```
 
@@ -227,6 +254,17 @@ The spec suite hits real CSFML for everything that isn't pure Ruby — `Clock` r
 
 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`.
 
+### Audio specs on macOS
+
+CoreAudio + the CSFML OpenAL backend occasionally hang an audio test group on macOS. To keep a darwin run reliable, every spec under `spec/sfml/audio/` is auto-tagged `:audio` and **excluded by default on darwin**. Force them in when you do want to run them:
+
+```sh
+bundle exec rspec --tag audio                  # only audio specs
+bundle exec rspec spec/sfml/audio/sound_spec.rb --tag audio   # one file
+```
+
+On Linux the `:audio` filter doesn't fire — the whole suite runs by default.
+
 ## License
 
 MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/sfml/app.rb

@@ -0,0 +1,257 @@
+module SFML
+  # Subclass-friendly main loop. Removes the boilerplate of window
+  # creation, event pumping, clock management, and clear/display so
+  # a small app fits in a few methods.
+  #
+  #   class MyApp < SFML::App
+  #     antialiasing 4               # class-level config — applies to every instance
+  #     framerate    120
+  #     background   SFML::Color.new(18, 20, 28)
+  #
+  #     def setup
+  #       @ball = SFML::CircleShape.new(radius: 30, position: [200, 200],
+  #                                     fill_color: SFML::Color.white)
+  #     end
+  #
+  #     def update(dt)
+  #       @ball.move([60 * dt.as_seconds, 30 * dt.as_seconds])
+  #     end
+  #
+  #     def draw
+  #       window.draw(@ball)
+  #     end
+  #   end
+  #
+  #   MyApp.new(title: "Hello").run
+  #
+  # The loop auto-handles :closed and :key_pressed/:escape by calling
+  # #quit; everything else is forwarded to #on_event. Override that
+  # to handle keys, mouse, etc.
+  #
+  # ## Configuration
+  #
+  # Every constructor kwarg is also a class-level macro: declare
+  # defaults with `antialiasing 4` etc. inside the class body, and
+  # `MyApp.new` picks them up. Per-instance kwargs still win on a
+  # case-by-case basis. Subclasses inherit their parent's settings
+  # — set one in a base class, override in a subclass.
+  class App
+    CONFIG_KEYS = %i[
+      width height title
+      framerate vsync background
+      style fullscreen
+      antialiasing context
+    ].freeze
+
+    class << self
+      CONFIG_KEYS.each do |key|
+        # Each macro doubles as a reader (no args) and a writer
+        # (one arg). When reading, walks up the inheritance chain so
+        # a subclass picks up the parent's value if it hasn't
+        # overridden it.
+        define_method(key) do |*args|
+          ivar = "@#{key}"
+          if args.empty?
+            return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+            return superclass.send(key) if superclass.respond_to?(key)
+
+            nil
+          else
+            instance_variable_set(ivar, args.first)
+          end
+        end
+      end
+
+      include Keybindings   # provides `on_key` + `key_handlers`
+
+      # Set the scene class the app should switch into automatically
+      # at `setup` time. Inheritable: a subclass that doesn't set
+      # one inherits the parent's choice.
+      def initial_scene(klass = nil)
+        @initial_scene = klass if klass
+        return @initial_scene if instance_variable_defined?(:@initial_scene)
+        superclass.respond_to?(:initial_scene) ? superclass.initial_scene : nil
+      end
+    end
+
+    attr_reader   :window
+    attr_accessor :background_color
+
+    # Per-instance kwargs override anything set at the class level.
+    # Anything not given here OR at the class level falls back to
+    # the hard-coded defaults below.
+    def initialize(**opts)
+      cfg = self.class
+
+      width        = opts[:width]        || cfg.width        || 800
+      height       = opts[:height]       || cfg.height       || 600
+      title        = opts[:title]        || cfg.title        || cfg.name
+      framerate    = opts[:framerate]    || cfg.framerate    || 60
+      vsync        = opts.fetch(:vsync,        cfg.vsync)
+      background   = opts[:background]   || cfg.background   || Color::BLACK
+      style        = opts.fetch(:style,        cfg.style)
+      fullscreen   = opts.fetch(:fullscreen,   cfg.fullscreen)
+      fullscreen   = false if fullscreen.nil?
+      antialiasing = opts.fetch(:antialiasing, cfg.antialiasing)
+      context      = opts.fetch(:context,      cfg.context)
+
+      window_opts = { framerate: framerate, fullscreen: fullscreen }
+      window_opts[:vsync]        = vsync         unless vsync.nil?
+      window_opts[:style]        = style         unless style.nil?
+      window_opts[:antialiasing] = antialiasing  unless antialiasing.nil?
+      window_opts[:context]      = context       unless context.nil?
+
+      @window           = RenderWindow.new(width, height, title, **window_opts)
+      @background_color = background
+    end
+
+    # Width and height shortcuts that always reflect the current
+    # window size — matters once the user is allowed to resize.
+    def width  = @window.size.x
+    def height = @window.size.y
+
+    # Close the window. The main loop exits at the start of the
+    # next frame.
+    def quit
+      @window.close
+      self
+    end
+
+    # ---- Scenes ----
+    #
+    # `current_scene` is whatever the app last activated via
+    # `switch_to`. When non-nil, App's default `update` / `draw` /
+    # `on_event` / `on_resize` forward to it; key bindings on the
+    # scene class shadow ones on the app class while the scene is
+    # active.
+
+    attr_reader :current_scene
+
+    # Activate `scene_or_class`. Tears down the previous scene
+    # before calling `setup` on the new one. Accepts either:
+    #   * a Scene subclass — instantiated with `self` as host
+    #   * an existing Scene instance — used as-is
+    def switch_to(scene_or_class)
+      new_scene =
+        case scene_or_class
+        when Class then scene_or_class.new(self)
+        else            scene_or_class
+        end
+      @current_scene&.teardown
+      @current_scene = new_scene
+      @current_scene&.setup
+      @current_scene
+    end
+
+    # ---- Pause / resume ----
+    #
+    # While paused, `update(dt)` is *not* called — the world stops
+    # advancing. `draw` keeps running so the window still updates
+    # (handy for pause overlays that need to be drawn over a
+    # frozen scene).
+
+    def pause   = (@paused = true)
+    def resume  = (@paused = false)
+    def toggle_pause = (@paused = !paused?)
+    def paused? = @paused == true
+
+    # The main entry point. Calls #setup once, then runs the
+    # per-frame loop until the window closes.
+    def run
+      setup
+      clock = Clock.new
+      while @window.open?
+        dt = clock.restart
+        @window.each_event { |event| _dispatch(event) }
+        update(dt) unless paused?
+        @window.clear(@background_color)
+        draw
+        @window.display
+      end
+      teardown
+      self
+    end
+
+    # ---- Override these in subclasses --------------------------------------
+    #
+    # Defaults forward to the current scene when one is active. The
+    # `initial_scene` class macro auto-instantiates a scene at
+    # `setup` time so subclasses with `initial_scene Foo` don't
+    # have to define `setup` themselves.
+
+    def setup
+      if (klass = self.class.initial_scene)
+        switch_to(klass)
+      end
+    end
+
+    def update(dt)
+      @current_scene&.update(dt)
+    end
+
+    def draw
+      @current_scene&.draw
+    end
+
+    # The framework consumes:
+    #   * `:closed` — closes the window (always)
+    #   * `:resized` — forwarded to `on_resize`
+    #   * `:key_pressed` whose code matches a scene- or app-level
+    #     `on_key` binding
+    # Everything else lands here. Override to handle game-specific
+    # input. By default forwards to the current scene's `on_event`.
+    def on_event(event)
+      @current_scene&.on_event(event)
+    end
+
+    # Default: forward to the current scene. Override to additionally
+    # do app-wide layout fixups; call `super` to keep the scene in
+    # the loop.
+    def on_resize(width, height)
+      @current_scene&.on_resize(width, height)
+    end
+
+    # Called once after the main loop exits. Tears down the active
+    # scene by default.
+    def teardown
+      @current_scene&.teardown
+    end
+
+    private
+
+    def _dispatch(event)
+      case event
+      in {type: :closed}
+        quit
+      in {type: :resized, size: {x:, y:}}
+        on_resize(x, y)
+      in {type: :key_pressed, code:}
+        # Scene-level bindings win over app-level (CSS-style cascade:
+        # the more-specific layer overrides the more-general one).
+        if @current_scene && (h = @current_scene.class.key_handlers[code])
+          _invoke_scene_key(h)
+        elsif (h = self.class.key_handlers[code])
+          _invoke_key_handler(h)
+        else
+          on_event(event)
+        end
+      else
+        on_event(event)
+      end
+    end
+
+    def _invoke_key_handler(handler)
+      case handler
+      when Symbol then send(handler)
+      when Proc   then handler.call(self)
+      end
+    end
+
+    def _invoke_scene_key(handler)
+      case handler
+      when Symbol then @current_scene.send(handler)
+      when Proc   then handler.call(@current_scene)
+      end
+    end
+  end
+end

data/lib/sfml/c/graphics.rb

@@ -79,12 +79,15 @@ module SFML
 
       typedef :pointer, :render_window_t
 
-      # See CSFML/Graphics/RenderWindow.h. We pass NULL for sfContextSettings
-      # in the high-level wrapper; that matches SFML defaults.
+      # See CSFML/Graphics/RenderWindow.h. The fifth param is a
+      # `const sfContextSettings*` — pass `nil` for SFML defaults
+      # or the pointer to a populated ContextSettings struct for
+      # MSAA / depth-buffer / GL-version tuning.
       attach_function :sfRenderWindow_create,
                       [Window::VideoMode.by_value, :string, :uint32, :int, :pointer],
                       :render_window_t
 
+      attach_function :sfRenderWindow_getSettings, [:render_window_t], Window::ContextSettings.by_value
       attach_function :sfRenderWindow_destroy,                [:render_window_t], :void
       attach_function :sfRenderWindow_close,                  [:render_window_t], :void
       attach_function :sfRenderWindow_isOpen,                 [:render_window_t], :bool

data/lib/sfml/c/window.rb

@@ -10,6 +10,36 @@ module SFML
                :bits_per_pixel, :uint32
       end
 
+      # sfContextSettings — passed to sfWindow_create / sfRenderWindow_create
+      # to configure the underlying OpenGL context. Field order and types
+      # match CSFML/Window/Window.h exactly:
+      #
+      #   typedef struct {
+      #     unsigned int depthBits;
+      #     unsigned int stencilBits;
+      #     unsigned int antiAliasingLevel;
+      #     unsigned int majorVersion;
+      #     unsigned int minorVersion;
+      #     uint32_t     attributeFlags;
+      #     bool         sRgbCapable;
+      #   } sfContextSettings;
+      class ContextSettings < FFI::Struct
+        layout :depth_bits,         :uint32,
+               :stencil_bits,       :uint32,
+               :anti_aliasing_level,:uint32,
+               :major_version,      :uint32,
+               :minor_version,      :uint32,
+               :attribute_flags,    :uint32,
+               :s_rgb_capable,      :bool
+      end
+
+      # Context attribute bitmask values — match SFML's enum.
+      module ContextAttribute
+        DEFAULT = 0
+        CORE    = 1 << 0
+        DEBUG   = 1 << 2
+      end
+
       # sfStyle is a bitmask. sfWindowState is a plain enum.
       module Style
         NONE     = 0

data/lib/sfml/graphics/render_window.rb

@@ -24,31 +24,51 @@ module SFML
     # The second form takes (video_mode, title, **opts) for full control.
     #
     # Options:
-    #   style:      bitmask of SFML::C::Window::Style constants
-    #   fullscreen: true to use sfFullscreen state instead of sfWindowed
-    #   framerate:  cap to N FPS via sfRenderWindow_setFramerateLimit
-    #   vsync:      enable vertical sync
+    #   style:        bitmask of SFML::C::Window::Style constants
+    #   fullscreen:   true to use sfFullscreen state instead of sfWindowed
+    #   framerate:    cap to N FPS via sfRenderWindow_setFramerateLimit
+    #   vsync:        enable vertical sync
+    #   antialiasing: shorthand — MSAA level (2 / 4 / 8). Same as
+    #                 passing `context: ContextSettings.new(antialiasing: N)`
+    #   context:      a SFML::ContextSettings for full GL-context control
     def initialize(*args, **opts)
       mode, title = parse_args(args)
       style = opts.fetch(:style, DEFAULT_STYLE)
       state = opts[:fullscreen] ? :fullscreen : :windowed
 
+      settings = _resolve_context_settings(opts)
+      # Hold a reference for the duration of the C call so the
+      # struct's memory survives until CSFML has copied it.
+      @ctx_struct = settings ? settings.to_native : nil
+      ctx_ptr     = @ctx_struct ? @ctx_struct.to_ptr : nil
+
       ptr = C::Graphics.sfRenderWindow_create(
         mode.to_native,
         title.to_s,
         style,
         C::Window::State[state],
-        nil,
+        ctx_ptr,
       )
       raise Error, "sfRenderWindow_create returned NULL" if ptr.null?
 
       @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfRenderWindow_destroy))
       @event_buffer = C::Window::Event.new
+      @requested_context = settings
 
       self.framerate_limit = opts[:framerate] if opts[:framerate]
       self.vsync = opts[:vsync]               unless opts[:vsync].nil?
     end
 
+    # The actual ContextSettings the driver gave us. May differ
+    # from what we requested — the driver picks the closest level
+    # of MSAA / GL version it supports.
+    def context_settings
+      ContextSettings.from_native(C::Graphics.sfRenderWindow_getSettings(@handle))
+    end
+
+    # What we asked for at creation time, if anything (otherwise nil).
+    attr_reader :requested_context
+
     def open?
       C::Graphics.sfRenderWindow_isOpen(@handle)
     end
@@ -182,6 +202,17 @@ module SFML
 
     private
 
+    def _resolve_context_settings(opts)
+      if opts[:context]
+        unless opts[:context].is_a?(ContextSettings)
+          raise ArgumentError, "context: must be a SFML::ContextSettings"
+        end
+        opts[:context]
+      elsif opts[:antialiasing]
+        ContextSettings.new(antialiasing: opts[:antialiasing])
+      end
+    end
+
     def _vec2u_or_nil(value)
       return nil if value.nil?
 

data/lib/sfml/keybindings.rb

@@ -0,0 +1,28 @@
+module SFML
+  # Class-level `on_key` DSL — shared by `SFML::App` and `SFML::Scene`.
+  # Each class that extends this module gets:
+  #
+  #   * `on_key(code, :method_name)` — bind a key to an instance method
+  #   * `on_key(code, ->(receiver) { ... })` — bind to a Proc
+  #   * `on_key(code) { |receiver| ... }` — bind to a block
+  #
+  # Inheritance: a subclass's bindings layer on top of the parent's,
+  # so `class Sub < Parent; on_key :x, :foo; end` keeps the parent's
+  # other bindings while overriding (or adding) `:x`.
+  module Keybindings
+    def on_key(code, target = nil, &block)
+      @key_handlers ||= {}
+      handler = block || target
+      raise ArgumentError, "on_key needs a target Symbol/Proc or a block" unless handler
+      @key_handlers[code.to_sym] = handler
+    end
+
+    # `Hash{key_code => handler}` — own bindings layered over the
+    # parent's (own keys win).
+    def key_handlers
+      own    = (@key_handlers ||= {})
+      parent = superclass.respond_to?(:key_handlers) ? superclass.key_handlers : {}
+      parent.merge(own)
+    end
+  end
+end

data/lib/sfml/scene.rb

@@ -0,0 +1,82 @@
+module SFML
+  # A chunk of game state with its own lifecycle — menu, gameplay,
+  # game-over, settings overlay, etc. The host `SFML::App` keeps a
+  # `current_scene` and forwards `update` / `draw` / `on_event` /
+  # `on_resize` to it. Switch between scenes with `app.switch_to`
+  # (or `switch_to` from inside a scene, which delegates).
+  #
+  #   class TitleScene < SFML::Scene
+  #     on_key :enter, :start_game
+  #
+  #     def setup
+  #       @gui = SFML::GUI::App.new(window: window, stylesheet: SHEET)
+  #       # ... build UI ...
+  #     end
+  #
+  #     def update(dt) = @gui.update(dt)
+  #     def draw       = @gui.draw
+  #
+  #     def start_game
+  #       switch_to PlayScene
+  #     end
+  #   end
+  #
+  #   class PlayScene < SFML::Scene
+  #     # …
+  #   end
+  #
+  #   class MyApp < SFML::App
+  #     initial_scene TitleScene   # auto-switches to it on app setup
+  #   end
+  #
+  # `SFML::Scene` carries its own `on_key` DSL — scene-level
+  # bindings shadow app-level bindings while the scene is active.
+  class Scene
+    class << self
+      include Keybindings
+    end
+
+    attr_reader :app
+
+    def initialize(app)
+      @app = app
+    end
+
+    # Convenience accessors that match `SFML::App`'s.
+    def window = @app.window
+    def width  = @app.width
+    def height = @app.height
+
+    # Switch the host app to a new scene from inside this one.
+    # Accepts a Scene class (instantiated with `app`) or an already-
+    # constructed Scene instance.
+    def switch_to(scene_or_class)
+      @app.switch_to(scene_or_class)
+    end
+
+    # ---- Override these in subclasses --------------------------------------
+
+    # Called once when the host app activates this scene (replacing
+    # whatever scene was active before). Build per-scene state here.
+    def setup; end
+
+    # Called every frame the scene is active and the app isn't paused.
+    def update(_dt); end
+
+    # Called every frame after #update.
+    def draw; end
+
+    # Called for every event the framework didn't auto-handle (closed,
+    # resized, and on_key bindings). Override to handle game-specific
+    # input patterns.
+    def on_event(_event); end
+
+    # Window resize. Default: no-op.
+    def on_resize(_width, _height); end
+
+    # Called once when the host app switches away (or when the app
+    # loop exits while this scene is active). Free per-scene
+    # resources here.
+    def teardown; end
+  end
+end

data/lib/sfml/version.rb

@@ -15,5 +15,5 @@ module SFML
   #   "3.0.1.0"  — CSFML 3.0.1 ships, we re-cut from upstream
   #   "3.0.1.1"  — our patch on top of CSFML 3.0.1
   #   "3.1.0.0"  — CSFML 3.1.0 ships, we add new bindings
-  VERSION = "3.0.0.1"
+  VERSION = "3.0.0.2"
 end

data/lib/sfml/window/context_settings.rb

@@ -0,0 +1,121 @@
+module SFML
+  # Configuration for the underlying OpenGL context that backs a
+  # `Window` / `RenderWindow`. Passed at window-creation time to
+  # request anti-aliasing, depth/stencil buffers, or a specific
+  # OpenGL version.
+  #
+  #   settings = SFML::ContextSettings.new(antialiasing: 4)
+  #   window   = SFML::RenderWindow.new(800, 600, "Smooth", context: settings)
+  #
+  # Or use the `RenderWindow.new` shortcut directly:
+  #
+  #   window = SFML::RenderWindow.new(800, 600, "Smooth", antialiasing: 4)
+  #
+  # Anti-aliasing is the most common knob — typical values are 0
+  # (off), 2, 4, or 8. The driver picks the closest level it
+  # actually supports; query `window.context_settings` after
+  # creation to see what you got.
+  class ContextSettings
+    DEFAULT_DEPTH_BITS    = 0
+    DEFAULT_STENCIL_BITS  = 0
+    DEFAULT_AA_LEVEL      = 0
+    DEFAULT_MAJOR_VERSION = 1
+    DEFAULT_MINOR_VERSION = 1
+
+    ATTRIBUTE_FLAGS = {
+      default: C::Window::ContextAttribute::DEFAULT,
+      core:    C::Window::ContextAttribute::CORE,
+      debug:   C::Window::ContextAttribute::DEBUG,
+    }.freeze
+
+    attr_reader :depth_bits, :stencil_bits, :antialiasing,
+                :major_version, :minor_version, :attribute_flags,
+                :srgb_capable
+
+    def initialize(depth_bits: DEFAULT_DEPTH_BITS,
+                   stencil_bits: DEFAULT_STENCIL_BITS,
+                   antialiasing: DEFAULT_AA_LEVEL,
+                   major_version: DEFAULT_MAJOR_VERSION,
+                   minor_version: DEFAULT_MINOR_VERSION,
+                   attributes: :default,
+                   srgb_capable: false)
+      @depth_bits      = Integer(depth_bits)
+      @stencil_bits    = Integer(stencil_bits)
+      @antialiasing    = Integer(antialiasing)
+      @major_version   = Integer(major_version)
+      @minor_version   = Integer(minor_version)
+      @attribute_flags = _attribute_mask(attributes)
+      @srgb_capable    = !!srgb_capable
+      freeze
+    end
+
+    # Build the matching CSFML struct on the heap. Returned struct
+    # is owned by the caller (FFI::AutoPointer is *not* set — pass
+    # by reference into a window-creation call and let it copy).
+    def to_native
+      s = C::Window::ContextSettings.new
+      s[:depth_bits]          = @depth_bits
+      s[:stencil_bits]        = @stencil_bits
+      s[:anti_aliasing_level] = @antialiasing
+      s[:major_version]       = @major_version
+      s[:minor_version]       = @minor_version
+      s[:attribute_flags]     = @attribute_flags
+      s[:s_rgb_capable]       = @srgb_capable
+      s
+    end
+
+    def self.from_native(struct)
+      attrs = ATTRIBUTE_FLAGS.find { |_, v| v == struct[:attribute_flags] }&.first || :default
+      new(
+        depth_bits:      struct[:depth_bits],
+        stencil_bits:    struct[:stencil_bits],
+        antialiasing:    struct[:anti_aliasing_level],
+        major_version:   struct[:major_version],
+        minor_version:   struct[:minor_version],
+        attributes:      attrs,
+        srgb_capable:    struct[:s_rgb_capable],
+      )
+    end
+
+    def ==(other)
+      other.is_a?(ContextSettings) &&
+        depth_bits == other.depth_bits &&
+        stencil_bits == other.stencil_bits &&
+        antialiasing == other.antialiasing &&
+        major_version == other.major_version &&
+        minor_version == other.minor_version &&
+        attribute_flags == other.attribute_flags &&
+        srgb_capable == other.srgb_capable
+    end
+    alias eql? ==
+
+    def hash = [@depth_bits, @stencil_bits, @antialiasing,
+                @major_version, @minor_version, @attribute_flags,
+                @srgb_capable].hash
+
+    def to_s
+      "ContextSettings(aa=#{@antialiasing}, depth=#{@depth_bits}, " \
+        "stencil=#{@stencil_bits}, gl=#{@major_version}.#{@minor_version})"
+    end
+    alias inspect to_s
+
+    private
+
+    def _attribute_mask(attrs)
+      case attrs
+      when Integer       then attrs
+      when Symbol        then ATTRIBUTE_FLAGS.fetch(attrs) do
+        raise ArgumentError, "unknown attribute :#{attrs}; one of #{ATTRIBUTE_FLAGS.keys}"
+      end
+      when Array
+        attrs.reduce(0) do |mask, name|
+          mask | ATTRIBUTE_FLAGS.fetch(name) do
+            raise ArgumentError, "unknown attribute :#{name}; one of #{ATTRIBUTE_FLAGS.keys}"
+          end
+        end
+      else
+        raise ArgumentError, "expected Symbol/Array/Integer, got #{attrs.class}"
+      end
+    end
+  end
+end

data/lib/sfml.rb

@@ -80,6 +80,7 @@ require "sfml/window/cursor"
 require "sfml/window/clipboard"
 require "sfml/window/video_mode"
 require "sfml/window/event"
+require "sfml/window/context_settings"
 require "sfml/window/window"
 require "sfml/graphics/color"
 require "sfml/graphics/transformable"
@@ -120,4 +121,6 @@ require "sfml/network/socket_selector"
 require "sfml/network/http"
 require "sfml/network/ftp"
 require "sfml/assets"
-require "sfml/game"
+require "sfml/keybindings"
+require "sfml/scene"
+require "sfml/app"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-sfml
 version: !ruby/object:Gem::Version
-  version: 3.0.0.1
+  version: 3.0.0.2
 platform: ruby
 authors:
 - Mykhailo Melnyk
@@ -79,6 +79,7 @@ files:
 - README.md
 - ext/ruby-sfml/extconf.rb
 - lib/sfml.rb
+- lib/sfml/app.rb
 - lib/sfml/assets.rb
 - lib/sfml/assets/fonts/DejaVuSans.LICENSE.txt
 - lib/sfml/assets/fonts/DejaVuSans.ttf
@@ -97,7 +98,6 @@ files:
 - lib/sfml/c/network.rb
 - lib/sfml/c/system.rb
 - lib/sfml/c/window.rb
-- lib/sfml/game.rb
 - lib/sfml/graphics/blend_mode.rb
 - lib/sfml/graphics/circle_shape.rb
 - lib/sfml/graphics/color.rb
@@ -120,6 +120,7 @@ files:
 - lib/sfml/graphics/vertex_array.rb
 - lib/sfml/graphics/vertex_buffer.rb
 - lib/sfml/graphics/view.rb
+- lib/sfml/keybindings.rb
 - lib/sfml/network/ftp.rb
 - lib/sfml/network/http.rb
 - lib/sfml/network/ip_address.rb
@@ -127,6 +128,7 @@ files:
 - lib/sfml/network/tcp_listener.rb
 - lib/sfml/network/tcp_socket.rb
 - lib/sfml/network/udp_socket.rb
+- lib/sfml/scene.rb
 - lib/sfml/system/clock.rb
 - lib/sfml/system/rect.rb
 - lib/sfml/system/time.rb
@@ -134,6 +136,7 @@ files:
 - lib/sfml/system/vector3.rb
 - lib/sfml/version.rb
 - lib/sfml/window/clipboard.rb
+- lib/sfml/window/context_settings.rb
 - lib/sfml/window/cursor.rb
 - lib/sfml/window/event.rb
 - lib/sfml/window/joystick.rb

data/lib/sfml/game.rb

@@ -1,101 +0,0 @@
-module SFML
-  # Subclass-friendly main loop. Removes the boilerplate of window creation,
-  # event pumping, clock management, and clear/display so a small game fits
-  # in a few methods.
-  #
-  #   class MyGame < SFML::Game
-  #     def setup
-  #       @ball = SFML::CircleShape.new(radius: 30, position: [200, 200],
-  #                                     fill_color: SFML::Color.white)
-  #     end
-  #
-  #     def update(dt)
-  #       @ball.move([60 * dt.as_seconds, 30 * dt.as_seconds])
-  #     end
-  #
-  #     def draw
-  #       window.draw(@ball)
-  #     end
-  #   end
-  #
-  #   MyGame.new(title: "Hello").run
-  #
-  # The loop auto-handles :closed and :key_pressed/:escape by calling #quit;
-  # everything else is forwarded to #on_event. Override that to handle keys,
-  # mouse, etc.
-  class Game
-    attr_reader   :window
-    attr_accessor :background_color
-
-    def initialize(
-      width: 800, height: 600, title: nil,
-      framerate: 60, vsync: nil,
-      background: Color::BLACK,
-      style: nil, fullscreen: false
-    )
-      window_opts = { framerate: framerate, fullscreen: fullscreen }
-      window_opts[:vsync] = vsync   unless vsync.nil?
-      window_opts[:style] = style   unless style.nil?
-
-      @window           = RenderWindow.new(width, height, title || self.class.name, **window_opts)
-      @background_color = background
-    end
-
-    # Width and height shortcuts that always reflect the current window size,
-    # which matters once the user is allowed to resize.
-    def width  = @window.size.x
-    def height = @window.size.y
-
-    # Close the window. The main loop exits at the start of the next frame.
-    def quit
-      @window.close
-      self
-    end
-
-    # The main entry point. Calls #setup once, then runs the per-frame loop
-    # until the window closes.
-    def run
-      setup
-      clock = Clock.new
-      while @window.open?
-        dt = clock.restart
-        @window.each_event { |event| _dispatch(event) }
-        update(dt)
-        @window.clear(@background_color)
-        draw
-        @window.display
-      end
-      teardown
-      self
-    end
-
-    # ---- Override these in subclasses --------------------------------------
-
-    # Called once, just before the first frame. Build initial state here.
-    def setup; end
-
-    # Called every frame. `dt` is a SFML::Time covering the previous frame.
-    def update(dt); end
-
-    # Called every frame after #update. Use window.draw(...) for any drawables.
-    def draw; end
-
-    # Called for events the framework didn't auto-handle (everything except
-    # :closed and the Esc key). Call #quit from here to exit on a custom key.
-    def on_event(event); end
-
-    # Called once after the window closes. Useful for saving state. Default
-    # is a no-op.
-    def teardown; end
-
-    private
-
-    def _dispatch(event)
-      case event
-      in {type: :closed}                     then quit
-      in {type: :key_pressed, code: :escape} then quit
-      else                                        on_event(event)
-      end
-    end
-  end
-end