solargraph-dragonruby

A Solargraph plugin that gives LSP editors autocomplete, hover docs and go-to-definition for the DragonRuby Game Toolkit API: args.outputs, args.inputs, args.state, $gtk/DR, Grid, Geometry, Layout, Easing, and more.

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:

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:

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, with extra coverage added here (see What's covered).

• 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)

Install the gem into the same Ruby that runs solargraph:

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:

include:
  - "mygame/app/**/*.rb"
plugins:
  - solargraph-dragonruby

Restart your editor's language server.

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.

• 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.

Install the Solargraph extension.

Install the Solargraph LSP with Mason, or point your LSP client at solargraph stdio.

Install the LSP package, then add Solargraph under Settings > Package Settings > LSP > Settings:

{
  "clients": {
    "solargraph": {
      "enabled": true,
      "command": ["solargraph", "stdio"],
      "selector": "source.ruby",
      "initializationOptions": { "diagnostics": true }
    }
  }
}

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.

Add changes to the ## [Unreleased] section of CHANGELOG.md as you go. To release:

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, 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).

The gem is available under the MIT License. The vendored stubs in stubs/upstream come from owenbutler/dragonruby-yard-doc and are by Owen Butler and contributors, also MIT licensed (see stubs/upstream/LICENSE.txt).