solargraph-dragonruby 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 69f9b6b80173020c3d7aec40a6f782716dfd0b42da4894216b0d380e7115bf27
+  data.tar.gz: 885052b696f737c49425ee95b57114c9e40ff211f5c358050e8bc56cb8a02830
+SHA512:
+  metadata.gz: 43ecc336e05490e0e9edaa820964a514a2f449cb60b363703afbbbe76a0b3609f4d39af11d21a66015e55243d3b6383d1b160d0f10c868dcce940652b6db6f6e
+  data.tar.gz: a5beca5b99d1f3e00427364b187d83c9f19b71a86e7e5e4927dd1b60e6deaa3f6343032e306b438279f4b79538503e57fe9f97ed34624967edbb38bb1a96525c

data/CHANGELOG.md

@@ -0,0 +1,56 @@
+## [Unreleased]
+
+## [0.2.0] - 2026-10-08
+
+- Adds `module Main` support: the `boot`/`start`/`tick`/`reset`/`did_reset`/`shutdown` hooks type `args` as
+  `GTK::Args` when they take it, and `args`, `inputs`, `outputs`, `state` (a `Hash`), `events` and `audio`
+  complete as bare calls inside `Main`.
+- Adds the `attr_dr`/`attr_gtk`, `attr_sprite`, `attr_rect`, `attr_label` and `attr_line` class macros: a call in a
+  class body (or instance method) is treated as including `AttrDR`, `AttrSprite`, `AttrRect`, `AttrLabel` or `AttrLine`,
+  so their methods complete on `self` and on instances.
+- Adds documented APIs that were missing:
+  - Inputs: mouse `key_down`/`key_held`/`key_up`, `rect`/`point` (with `offset:`), the combined keyboard or controller
+    `args.inputs.key_down`/`key_held`/`key_up`, `left_right_dpad`/`left_right_perc_dpad`/`up_down_arrow` and the other
+    top-level aliases, `Keyboard#directional_vector`/`directional_angle`, and `args.inputs.touch` values (`FingerTouch`)
+  - Keyboard keys: `f1`–`f12`, the numpad, `home`/`end`/`page_up`/`page_down`/`insert`, `caps_lock`, and more symbols
+  - `Easing.spline`, `Numeric.compose_blendmode` and the `BLENDFACTOR_*`/`BLENDOPERATION_*` constants,
+    `Numeric#mid?`/`between?`/`min`/`max` and `Numeric.mid`, `args.audio.volume`, and `Zlib`
+- Fixes the signatures of `Easing.smooth_start`/`smooth_stop`/`smooth_step` (keyword arguments) and `Numeric#mid`.
+- Adds undocumented APIs that the runtime and sample apps use:
+  - Numeric: `randomize`, `rand_sign`, `half`, `to_vector`, `towards`, `from_right`/`from_left`/`from_bottom`,
+    `sin`/`cos`/`tan` (and `_d`/`_r`), `ease`/`ease_spline`, `to_sf(decimal_places:, include_sign:)`, ...
+  - `Grid.x`/`y`/`center`/`w_half`/`h_half`, `origin_center?`, `letterbox?`, `hd?` and more pixel-category properties
+  - `Layout.rect_group`, `rects`, `point`, `rect_center`, `font_size_*`, `safe_rect`, ...
+  - `Geometry.line_slope`, `line_length`, `line_rect`, `rect_to_line`, `cubic_bezier`, `circle?`, ...
+  - Inputs: `directional_vector`/`directional_angle` (on inputs, keyboard key states and controllers), more mouse
+    properties (`position`, `held`, `left`, `click_at`, `key_down?`, ...), `finger_one`/`finger_two`, `pinch_zoom`
+  - `String#wrapped_lines`, `String.line_anchors`, `trim`, ..., and the global `log_info`/`log_warn`/`log_once`/... functions
+  - `DR.pause!`, `serialize_state`/`deserialize_state`, `set_rng`, `notify`, `http_head`/`http_put`, `platform`, ...,
+    `outputs.render_target_state`, `outputs.a11y`, `watch_fps`, and `File.append`
+- Fixes the `Layout.rect` signature (keyword arguments).
+- Types the Hashes DragonRuby returns, so their fields complete (`Geometry.vec2_add(a, b).x`,
+  `Layout.rect(...).center.x`, `DR.http_get(url).response_data`, ...): adds phantom `Typing::PointHash`, `RectHash`,
+  `RectPropsHash`, `LineHash`, `CircleHash`, `ColorHash`, `SizeHash`, and record types for `Numeric#frame`, http
+  responses, `DR.stat_file`, `keyboard.keys` and render target state. Shape parameters are documented as
+  `[Typing::Rect, Object]` (and `Point`, `Line`, `Circle`), which still accepts any value.
+- Types `MouseButton#click`/`down`/`held`/`up` as `MousePoint`, `Easing.ease` definitions as `Array<Symbol, Proc>`, and
+  makes `Layout.rect_group`/`point` and `Numeric#to_layout_*` take keyword arguments.
+- Fixes upstream Geometry docs: `line_intersect`/`ray_intersect` return types, mismatched parameter names, and the
+  signatures of `inside_rect?`, `point_inside_circle?`, `rotate_point`, `rect_navigate`, `zoom_rect`, `line_to_points`, ...
+
+## [0.1.0] - 2026-10-07
+
+- Initial release: Solargraph plugin (`plugins: [solargraph-dragonruby]`) that adds DragonRuby API pins.
+- Vendors the YARD stubs from owenbutler/dragonruby-yard-doc @ 06cc3d1 (`rake stubs:sync` to update).
+- Adds coverage for `args.state`/entities, `Grid`, `DR`, events, pixel arrays, keyboard/controller/mouse
+  details, `vec2_*` and other Geometry functions, the Geometry mixin on Hash/Array, and Numeric/Array/Layout helpers.
+- Adds Indie/Pro APIs: `outputs.shader`, `DR.get_dlopen_path`, `DR.start_text_input`/`stop_text_input`,
+  `args.inputs.http_requests` (with `HTTPRequest#respond`/`reject`), and `Layout.allscreen_rect`.
+- Notes the required license tier in the docs of Indie/Pro APIs, including upstream's `dlopen` and HD functions
+  and `Grid`'s all-screen, pixel-category and scale properties.
+- Types `buffered_click`/`buffered_held` as `MousePoint` (DragonRuby 7.22), adds them on `Mouse` along with
+  `MousePoint#x`/`#y`, and types `args.inputs.text` as `Array<String>`.
+- Requires Solargraph 0.61.x.
+
+[Unreleased]: https://github.com/asimmons91/solargraph-dragonruby/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/asimmons91/solargraph-dragonruby/compare/v0.1.0...v0.2.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"solargraph-dragonruby" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["austin_simmons@fastmail.com"](mailto:"austin_simmons@fastmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Austin Simmons
+
+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/NOTICE

@@ -0,0 +1,8 @@
+solargraph-dragonruby
+Copyright (c) 2026 Austin Simmons. MIT License, see LICENSE.txt.
+
+This project includes third-party files:
+
+stubs/upstream/
+  Vendored from https://github.com/owenbutler/dragonruby-yard-doc
+  Copyright (c) 2024 Owen Butler. MIT License, see stubs/upstream/LICENSE.txt.

data/README.md

@@ -0,0 +1,185 @@
+# solargraph-dragonruby
+
+A [Solargraph](https://solargraph.org) plugin that gives LSP editors autocomplete,
+hover docs and go-to-definition for the [DragonRuby Game Toolkit](https://dragonruby.org) API:
+`args.outputs`, `args.inputs`, `args.state`, `$gtk`/`DR`, `Grid`, `Geometry`, `Layout`, `Easing`, and more.
+
+```ruby
+def tick args                         # args is typed as GTK::Args automatically
+  args.outputs.sprites << { ... }     # completes outputs, inputs, state, grid, events, ...
+  if args.inputs.keyboard.key_down.space
+    DR.notify! "jump"
+  end
+end
+```
+
+The `module Main` entry point works too:
+
+```ruby
+module Main
+  def start                           # boot, start, tick, reset, ... with or without args
+    state.score = 0                   # state is a Hash in Main
+  end
+
+  def tick
+    outputs.labels << { ... }         # args, inputs, outputs, state, events and audio complete bare
+  end
+end
+```
+
+So do DragonRuby's class macros:
+
+```ruby
+class Ship
+  attr_sprite                         # x, y, w, h, path, angle, ... plus top, right, intersect_rect?, ...
+end
+
+class Game
+  attr_dr                             # or attr_gtk: args, state, inputs, outputs, grid, ... on self
+end
+```
+
+The API definitions are YARD stubs. Most of them come from
+[owenbutler/dragonruby-yard-doc](https://github.com/owenbutler/dragonruby-yard-doc),
+with extra coverage added here (see [What's covered](#whats-covered)).
+
+## Requirements
+
+- A CRuby install. DragonRuby doesn't need one, but Solargraph does.
+- Solargraph 0.61.x: `gem install solargraph -v '~> 0.61.0'`
+- An editor configured to use the Solargraph language server (see [Editor setup](#editor-setup))
+
+## Installation
+
+Install the gem into the same Ruby that runs `solargraph`:
+
+```sh
+gem install solargraph-dragonruby
+```
+
+Then create a `.solargraph.yml` in your game's root directory (`solargraph config` generates
+a default one) and add the plugin:
+
+```yml
+include:
+  - "mygame/app/**/*.rb"
+plugins:
+  - solargraph-dragonruby
+```
+
+Restart your editor's language server.
+
+### Migrating from a dragonruby-yard-doc checkout
+
+If your `.solargraph.yml` includes a cloned copy of the stubs (for example
+`../dragonruby-yard-doc/*.rb`), remove that line. Otherwise every definition is
+indexed twice.
+
+## What's covered
+
+- **From dragonruby-yard-doc** (`stubs/upstream`): `GTK::Args`, `GTK::Runtime` (`$gtk`, `$dr`),
+  outputs, inputs (keyboard, mouse, controllers), `Geometry`, `Easing`, `Layout`, `Numeric`
+  extensions, `Kernel.tick_count`, and the `tick`/`boot`/`reset` hooks.
+- **Added here** (`stubs/extensions`), checked against the DragonRuby 7.22 docs, sample apps and open-source runtime:
+  - `module Main`: the `boot`/`start`/`tick`/`reset`/`did_reset`/`shutdown` hooks (with or without `args`) and bare
+    `args`/`inputs`/`outputs`/`state`/`events`/`audio`, with `state` typed as `Hash`
+  - `args.state` (entities, `new_entity`, `new_entity_strict`), `args.grid`, `args.events`, `args.pixel_array(s)`
+  - The `DR` and `Grid` constants, plus the `$grid` and `$state` globals
+  - `Grid` orientation/origin, all-screen and pixel-category properties
+  - More `DR` functions: save data, env vars, window size/position, `on_tick_count`, `benchmark`, `reset_and_replay`, ...
+  - Keyboard key states (`key_down.space`, `key_held.truthy_keys`, `key_down?(:enter)`), WASD/arrow helpers
+  - Controller dpad and directional vectors, `accept`/`cancel`, and face button aliases (`south`, `east`, ...)
+  - `args.inputs.mouse.buttons.left.buffered_click` and the other mouse button properties, `mouse.key_down.left`,
+    `mouse.rect(offset:)`, and touch points (`args.inputs.touch`)
+  - The shared keyboard-or-controller `args.inputs.key_down.left` and the other key-state directions
+  - Function, numpad and navigation keys (`key_down.f1`, `kp_enter`, `page_down`, ...)
+  - `vec2_*` and other `Geometry` functions, and the Geometry mixin on `Hash`/`Array` (`rect.intersect_rect?(other)`)
+  - `Numeric#frame_index`, `elapsed_time`, `to_sf`, `mid?`, ..., plus `Array#map_2d`, `include_any?`, and `Layout.row_count`, ...
+  - `Easing.spline` and keyword `smooth_start`/`smooth_stop`/`smooth_step`, `Numeric.compose_blendmode` with the
+    `BLENDFACTOR_*`/`BLENDOPERATION_*` constants, `args.audio.volume`, and `Zlib`
+  - Undocumented APIs used by the sample apps: `10.randomize(:ratio, :sign)`, `Grid.center`, `Layout.rect_group`,
+    `Geometry.line_slope`, `String#wrapped_lines`, `log_info`, `DR.serialize_state`, `outputs.render_target_state`, ...
+  - `outputs.watch`/`outputs.debug.watch`, `outputs.sounds`, `did_reset`/`shutdown`, `Kernel.global_tick_count`
+  - The `attr_dr`/`attr_gtk`, `attr_sprite`, `attr_rect`, `attr_label` and `attr_line` class macros: calling one in a
+    class (or in one of its instance methods) completes the methods it adds
+- **Indie and Pro APIs** are included. Their hover docs say which license tier they need:
+  - Shaders: `outputs.shader = { path:, uniforms:, textures: }` (Indie/Pro)
+  - C Extensions: `DR.dlopen`, `DR.get_dlopen_path` (Indie/Pro)
+  - HD and All Screen: `DR.set_hd_max_scale`, `set_hd_letterbox`, `toggle_hd_letterbox`, `Layout.allscreen_rect`,
+    and `Grid`'s all-screen, pixel-category and scale properties (Pro)
+  - `DR.start_text_input`/`stop_text_input`, `args.inputs.http_requests` (Pro)
+
+  Completions don't depend on your license, so check the hover note before relying on one of these.
+
+Hashes that DragonRuby returns are typed by their shape, so their keys complete like methods:
+`Geometry.vec2_add(a, b).x`, `Layout.rect(row: 0, col: 0).center.y`, `DR.http_get(url).response_data`. These
+`Typing::*Hash` types are phantom types: they exist only in the stubs.
+
+## Editor setup
+
+### VS Code
+
+Install the [Solargraph extension](https://marketplace.visualstudio.com/items?itemName=castwide.solargraph).
+
+### Vim/Neovim
+
+Install the Solargraph LSP with [Mason](https://github.com/williamboman/mason.nvim), or point
+your LSP client at `solargraph stdio`.
+
+### Sublime Text
+
+Install the [LSP](https://lsp.sublimetext.io/) package, then add Solargraph under
+`Settings > Package Settings > LSP > Settings`:
+
+```json
+{
+  "clients": {
+    "solargraph": {
+      "enabled": true,
+      "command": ["solargraph", "stdio"],
+      "selector": "source.ruby",
+      "initializationOptions": { "diagnostics": true }
+    }
+  }
+}
+```
+
+## Development
+
+```sh
+bin/setup              # install dependencies
+bundle exec rake       # tests + standardrb
+bundle exec rake stubs:sync        # re-vendor upstream stubs from main
+bundle exec rake stubs:sync[<ref>] # ...or from a specific branch/tag
+```
+
+- `stubs/upstream/` is vendored verbatim; `UPSTREAM` records the source commit. Don't edit it by hand.
+- `stubs/extensions/` holds our additions. When an extension re-declares an upstream
+  method (for example to add a return type), the upstream definition is dropped.
+- The Solargraph dependency is pinned to `~> 0.61.0`, because its plugin internals
+  change between minor releases. Re-run the tests before widening it.
+
+### Releasing
+
+Add changes to the `## [Unreleased]` section of `CHANGELOG.md` as you go. To release:
+
+```sh
+bundle exec rake release:prepare[minor]   # or major, patch, or an explicit version like 1.2.3
+git push origin main v0.2.0               # the command it prints
+```
+
+`release:prepare` runs the tests, bumps `version.rb` and `Gemfile.lock`, moves the Unreleased notes under a
+dated heading, and commits and tags the release. Pushing the tag runs `.github/workflows/release.yml`, which checks
+that the tag, version and changelog agree, publishes the gem to RubyGems.org with
+[Trusted Publishing](https://guides.rubygems.org/trusted-publishing/), and creates the GitHub release from that
+version's changelog notes.
+
+One-time setup: on RubyGems.org, add a trusted publisher for this repository with the workflow `release.yml` and
+the environment `release` (use a "pending" trusted publisher if the gem has never been pushed).
+
+## Credits and license
+
+The gem is available under the [MIT License](LICENSE.txt). The vendored stubs in
+`stubs/upstream` come from [owenbutler/dragonruby-yard-doc](https://github.com/owenbutler/dragonruby-yard-doc)
+and are by Owen Butler and contributors, also MIT licensed (see
+[stubs/upstream/LICENSE.txt](stubs/upstream/LICENSE.txt)).

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create do |t|
+  # Solargraph and its dependencies emit many -w warnings on Ruby 4.0.
+  t.warning = false
+end
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/solargraph/dragonruby/convention.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Dragonruby
+    # Adds pins parsed from the bundled DragonRuby YARD stubs to every ApiMap.
+    class Convention < Solargraph::Convention::Base
+      STUBS_DIR = File.expand_path("../../../stubs", __dir__)
+
+      # Parsed once per process. ApiMap#catalog asks for global pins on every
+      # re-map, and returning the same pin objects keeps the store from
+      # reindexing them.
+      #
+      # @return [Array<Solargraph::Pin::Base>]
+      def self.pins
+        @pins ||= begin
+          upstream = load_pins("upstream")
+          extensions = load_pins("extensions")
+          # Solargraph prefers the first method pin for a path, so an extension
+          # that re-declares an upstream method (e.g. to add a return type)
+          # only takes effect if the upstream pin is dropped.
+          overridden = extensions.grep(Solargraph::Pin::Method).to_set(&:path)
+          upstream.reject { |pin| pin.is_a?(Solargraph::Pin::Method) && overridden.include?(pin.path) }
+            .concat(extensions)
+            .freeze
+        end
+      end
+
+      # @param dir [String]
+      # @return [Array<Solargraph::Pin::Base>]
+      def self.load_pins(dir)
+        Dir[File.join(STUBS_DIR, dir, "*.rb")].sort
+          .flat_map { |path| Solargraph::SourceMap.load(path).all_pins }
+      end
+      private_class_method :load_pins
+
+      # @param _object [Object, nil] unused; Solargraph 0.61 passes nil
+      # @return [Solargraph::Environ]
+      def global(_object)
+        Solargraph::Environ.new(pins: self.class.pins.dup)
+      end
+    end
+  end
+end

data/lib/solargraph/dragonruby/macro_node.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Dragonruby
+    # Maps DragonRuby's class macros (`attr_dr`, `attr_sprite`, ...) to the
+    # module each one includes (see stubs/extensions/attr.rb), so Solargraph
+    # treats `attr_sprite` like `include AttrSprite`.
+    #
+    # This is a node processor rather than a Convention#local because
+    # Solargraph 0.61 doesn't notice when a file's convention pins change, so
+    # adding or removing a macro wouldn't take effect until a restart.
+    class MacroNode < Solargraph::Parser::NodeProcessor::Base
+      MACROS = {
+        attr_dr: "AttrDR",
+        attr_gtk: "AttrDR",
+        attr_sprite: "AttrSprite",
+        attr_rect: "AttrRect",
+        attr_label: "AttrLabel",
+        attr_line: "AttrLine"
+      }.freeze
+
+      # Runs after Solargraph's own SendNode, which has already processed the
+      # children, so this only adds the include.
+      #
+      # @return [Boolean] true, so later :send processors still run
+      def process
+        receiver, name, *arguments = node.children
+        return true unless receiver.nil? && arguments.empty? && MACROS.key?(name) && region.scope != :class
+
+        # Called in an instance method, the macro includes into `self.class`.
+        closure = region.closure.is_a?(Solargraph::Pin::Method) ? region.closure.closure : region.closure
+        return true unless closure.is_a?(Solargraph::Pin::Namespace) && !closure.path.empty?
+
+        pins.push Solargraph::Pin::Reference::Include.new(
+          location: location,
+          closure: closure,
+          name: MACROS[name],
+          source: :dragonruby
+        )
+        true
+      end
+    end
+  end
+end

data/lib/solargraph/dragonruby/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Solargraph
+  module Dragonruby
+    VERSION = "0.2.0"
+  end
+end

data/lib/solargraph/dragonruby.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "solargraph"
+require_relative "dragonruby/version"
+require_relative "dragonruby/convention"
+require_relative "dragonruby/macro_node"
+
+module Solargraph
+  # Solargraph plugin providing DragonRuby Game Toolkit API pins.
+  module Dragonruby
+  end
+end
+
+Solargraph::Convention.register Solargraph::Dragonruby::Convention
+Solargraph::Parser::NodeProcessor.register :send, Solargraph::Dragonruby::MacroNode

data/lib/solargraph-dragonruby.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Entry point for `.solargraph.yml` `plugins: [solargraph-dragonruby]`,
+# which Solargraph loads with `require "solargraph-dragonruby"`.
+require_relative "solargraph/dragonruby"

data/sig/solargraph/dragonruby.rbs

@@ -0,0 +1,19 @@
+module Solargraph
+  module Dragonruby
+    VERSION: String
+
+    class Convention < Solargraph::Convention::Base
+      STUBS_DIR: String
+
+      def self.pins: () -> Array[Solargraph::Pin::Base]
+
+      def global: (untyped _object) -> Solargraph::Environ
+    end
+
+    class MacroNode < Solargraph::Parser::NodeProcessor::Base
+      MACROS: Hash[Symbol, String]
+
+      def process: () -> bool
+    end
+  end
+end

data/stubs/extensions/README.md

@@ -0,0 +1,20 @@
+# Extensions
+
+YARD stubs for DragonRuby APIs that the vendored upstream stubs
+(`../upstream`, synced from owenbutler/dragonruby-yard-doc) do not cover yet.
+
+- Written against the DragonRuby 7.22 Pro SDK: the docs (`docs/api/*.md`),
+  the sample apps, and the open-source runtime (`docs/oss/dragon/*.rb`).
+  When they disagree, the runtime source and samples win. For example, the
+  docs still describe `outputs.shader_path`/`shader_tex1`, which no longer exist.
+- Indie/Pro-only APIs say so in their doc comment ("Indie or Pro license." /
+  "Pro license.").
+- These files reopen upstream classes. If one re-declares a method that
+  upstream already defines, the upstream pin is dropped (see
+  `Solargraph::Dragonruby::Convention.pins`), so the definition here wins.
+- `rake stubs:sync` never touches this directory.
+- Hashes with a known shape use the phantom types in `typing.rb`: return
+  `Typing::PointHash`, `Typing::RectHash`, ... (they subclass Hash), and type
+  shape parameters as `[Typing::Point, Object]`, `[Typing::Rect, Object]`, ...
+  Keep `Object` in parameter types: with only the phantom type,
+  `solargraph typecheck --level strict` rejects plain Hashes.

data/stubs/extensions/args.rb

@@ -0,0 +1,91 @@
+module GTK
+  class Args
+    # Property bag for your game's state. Values are retained across `tick`
+    # invocations and cleared by `DR.reset`. Arbitrarily nested properties
+    # are allowed, and a backing entity is created on your behalf.
+    #
+    # Recommended initialization (in `boot`): `args.state = {}`
+    #
+    # @return [GTK::OpenEntity]
+    attr_accessor :state
+
+    # Screen and canvas information. Also available globally as `Grid`
+    # (preferred) and `$grid`.
+    #
+    # @return [GTK::Grid]
+    attr_reader :grid
+
+    # Raw and window resize events.
+    #
+    # @return [GTK::Events]
+    attr_reader :events
+
+    # All pixel arrays created via #pixel_array, keyed by name.
+    #
+    # @return [Hash{Symbol => GTK::PixelArray}]
+    attr_reader :pixel_arrays
+
+    # Returns the pixel array named `name`, creating it if needed. Render it
+    # with `args.outputs.sprites << { ..., path: name }`.
+    #
+    # @param name [Symbol]
+    # @return [GTK::PixelArray]
+    def pixel_array name; end
+
+    # The runtime. Prefer the `DR` constant.
+    #
+    # @return [GTK::Runtime]
+    attr_reader :gtk
+
+    # Current tick of the game. Prefer `Kernel.tick_count`.
+    #
+    # @return [Integer]
+    attr_reader :tick_count
+
+    # Audio sources that are playing, keyed by name. Assign a Hash to play
+    # one (`args.audio[:music] = { input: "sounds/music.ogg", looping: true }`);
+    # a `:length` key (seconds) is added on the following tick.
+    #
+    # @return [AudioHash]
+    attr_reader :audio
+  end
+
+  class Events
+    # @return [Boolean] true if the window was resized or the orientation of the game changed.
+    attr_reader :resize_occurred
+
+    # @return [Boolean] true if the orientation of the game changed (only possible when
+    #   `orientation` in `game_metadata.txt` is `landscape,portrait` or `portrait,landscape`).
+    attr_reader :orientation_changed
+
+    # Raw events. These are already reflected in the rest of the API, so this is
+    # mostly useful for debugging.
+    #
+    # @return [Array<Hash>]
+    attr_reader :raw
+  end
+
+  class PixelArray
+    # @return [Integer]
+    attr_accessor :w, :h
+
+    # Hexadecimal color values in ABGR format, starting at the top-left
+    # pixel. `nil` entries render as a checkerboard.
+    #
+    # @return [Array<Integer>]
+    attr_accessor :pixels
+  end
+end
+
+# The type of `args.audio`: a Hash of audio sources plus a global volume.
+class AudioHash < Hash
+  # Global volume for all audio, from `0.0` to `1.0` (defaults to `1.0`, or
+  # `0.4` on iOS). Web builds in production return `0.0` while the game
+  # doesn't have focus.
+  #
+  # @return [Float]
+  attr_reader :volume
+
+  # @param value [Float] clamped to `0.0..1.0`
+  attr_writer :volume
+end

data/stubs/extensions/array.rb

@@ -0,0 +1,25 @@
+class ::Array
+  # For an array of arrays, yields each element with its row and column index.
+  #
+  # @yieldparam row [Integer]
+  # @yieldparam col [Integer]
+  # @yieldparam value [Object]
+  # @return [Array<Array>]
+  def map_2d &block; end
+
+  # @param items [Array<Object>]
+  # @return [Boolean] true if any of `items` is in self
+  def include_any? *items; end
+
+  # @param other [Typing::Rect, Object] a rect
+  # @param tolerance [Float]
+  # @return [Boolean] true if any element intersects `other`
+  def any_intersect_rect? other, tolerance = 0.1; end
+
+  # Alias of `compact`.
+  # @return [Array]
+  def reject_nil; end
+
+  # @return [Array] self without `nil` or `false` items
+  def reject_false; end
+end