GameDig for Ruby

Query game servers from Ruby powered by node-gamedig.

This is a Ruby wrapper gem for node-gamedig, providing support to use the node cli or running a node process with nodo for faster responses.

Contents

• Installation
• Usage examples
• Documentation
• Contributing

Installation

Prerequisites

For using the CLI variant, install the gamedig package with your favourite package manager globally, e.g. here with npm or yarn:

yarn

    yarn global add gamedig

npm

    npm install -g gamedig

For the nodo variant, NodeJS >= 22.x is installed and available via commandline (in PATH).

Gem

Add this line to your application's Gemfile:

gem 'game_dig'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install game_dig

Usage examples

You can use the basic cli wrapper or the nodo instance.

CLI wrapper

This will just run the gamedig cli and return its result.

    require 'game_dig'
    data = GameDig.query(type: 'minecraft', host: 'my-server.example.com')
    p data

Nodo wrapper

This will start a node process in the background and communicate with it using the nodo gem.

As this prevents starting a new node process for each query, this is much faster for multiple queries.

    require 'game_dig/nodo'
    data = GameDig.query(type: 'minecraft', host: 'my-server.example.com')
    p data

Query parameters

You can pass all parameters supported by node-gamedig, checkout the rubydoc for more details.

Here an example with all parameters, the camelCase parameters are converted to snake_case in ruby:

    require 'game_dig'
    data = GameDig.query(
      # mandatory parameters
      type: 'minecraft',
      host: 'my-server.example.com',
      # optional parameters
      address: '119.212.123.34', # overrides host and skips DNS lookup
      port: 25565, # optional, default depends on game type
      max_retries: 1, # number of retry attempts
      socket_timeout: 2000, 
      attempt_timeout: 10000,
      given_port_only: false,
      ip_family: 0,
      debug: false,
      request_rules: false,
      request_players: true,
      request_rules_required: false,
      request_players_required: false,
      strip_colors: true,
      port_cache: true,
      no_breadth_order: false,
      check_old_ids: false
    )
    # => GameDig::QueryResult
    
    # Accessing data
    puts data.max_players
    # => 16
    
    # Accessing data as hash
    puts data.to_h["max_players"]
    # => 16

Query response

The default response object is of type GameDig::QueryResult. It contains the data returned by gamedig and provides accessors for all common keys. But the method of queryPort is in snake_case query_port instead of camelCase. And the methods numplayers and maxplayers are num_players and max_players respectively.

The response can be converted to a ruby hash by #to_h with the same structure as the original node-gamedig response.

The objects of raw and bots are untouched, as they may depend on the game type and are not modified by gamedig itself.

For example:

data.to_h
# =>
{
  "name" => "My Minecraft Server",
  "map" => "world",
  "password" => false,
  "num_players" => 5,
  "max_players" => 20,
  "players" => [
    { "name" => "Player1", "raw" => {} },
    { "name" => "Player2", "raw" => {} },
  # ...
  ],
  "bots" => [
    { "name" => "Bot1", "raw" => {} },
    { "name" => "Bot2", "raw" => {} },
  # ...
  ],
  "connect" => "my-server.example.com:25565",
  "ping" => 45,
  "query_port" => 25565,
  "version" => "1.16.4",
  "raw" => {
    # ...
  }
}    

Documentation

Check out the doc at RubyDoc:
https://www.rubydoc.info/gems/game_dig

As this library is only a wrapper, checkout the original node-gamedig documentation:
https://github.com/gamedig/node-gamedig

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/magynhard/ruby-game_dig.

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.