glowstone 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in glowstone.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Tom Heinan
+
+MIT License
+
+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,57 @@
+# Glowstone
+
+This tiny gem implements the [GameSpy query protocol](http://int64.org/docs/gamestat-protocols/gamespy2.html) to access pertinent real-time information hidden away inside your Minecraft server. You give Glowstone your server info, and Glowstone gives you:
+- which players are currently online
+- the base map name and default gamemode
+- what plugins you're running
+- even more stuff you probably don't care about!
+
+All credit goes to [Dinnerbone](http://dinnerbone.com/) for his [excellent post](http://dinnerbone.com/blog/2011/10/14/minecraft-19-has-rcon-and-query/) on the inner workings of the protocol.  Check out his Python implementation [here](https://github.com/Dinnerbone/mcstatus).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'glowstone'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install glowstone
+
+## Usage
+
+Glowstone's interface is super simple.  Just instantiate yourself a new server object, like so:
+
+```ruby
+my_server = Glowstone::Server.new "minecraft.tomheinan.com"
+```
+
+... and Glowstone will whip you up a server object full of all that delicious realtime data you've been craving:
+
+```ruby
+=> #<Glowstone::Server:0x007ffe250099b8 @host="minecraft.tomheinan.com", @port=25565, @timeout=3, @socket=#<UDPSocket:fd 8>, @motd="Welcome to Arkenfall!", @gamemode="SMP", @version="1.2.5", @plugins=["CraftBukkit on Bukkit 1.2.5-R4.1-MCPC-SNAPSHOT: mod_MinecraftForge ForgeMod", "AdminCmd 6.0.1 (BUILD 01.06.2012 @ 10:41:06)", "WorldEdit 5.3", "ExtraBiomes XL ForgeMod", "WorldGuard 5.5.3", "PermissionsBukkit 1.6"], @map_name="arkenfall", @num_players=1, @max_players=16, @players=["tomheinan"]>
+```
+
+And that's all there is to it!  No fancy bukkit plugins or server-side scripts required.  If your server object is particularly long-lived and you find yourself wanting to refresh its data, just do `my_server.refresh` and it'll pull down the latest information for you.
+
+## Troubleshooting
+
+**Help! I'm not receiving any data!**
+
+The first thing to do is make sure your server is set up to send it.  Check your `server.properties` file and make sure the `enable-query` flag is set to `true`. Then, make sure your server's firewall allows connections on UDP port `25565`.  If you've changed that value via the `query.port` flag, then you'll also need to specify it when instantiating Glowstone, like so:
+
+```ruby
+my_server = Glowstone::Server.new("myminecraftserver.com", 12345)
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/glowstone.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/glowstone/version', __FILE__)
+
+Gem::Specification.new do |gem|
+	gem.name          = "glowstone"
+	gem.authors       = ["Tom Heinan"]
+	gem.email         = ["me@tomheinan.com"]
+	gem.description   = "Glowstone helps shed light on your Minecraft server!"
+	gem.summary       = "This tiny gem implements the Gamespy query protocol to access pertinent real-time information hidden away inside your Minecraft server."
+	gem.homepage      = "http://tomheinan.com"
+
+	gem.files         = `git ls-files`.split($\)
+	gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+	gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+	gem.require_paths = ["lib"]
+	gem.version       = Glowstone::VERSION
+
+	gem.add_dependency "bindata", "~> 1.4.5"
+end

data/lib/glowstone.rb

@@ -0,0 +1,12 @@
+require "glowstone/version"
+require "glowstone/server"
+require "glowstone/packets"
+
+module Glowstone
+
+	MAGIC_BYTES    = [0xFE, 0xFD]
+	REQUEST_BYTE   = {:challenge => [0x09], :query => [0x00]}
+	CLIENT_ID      = [0x67, 0x6C, 0x6F, 0x77]
+	SOCKET_TIMEOUT = 3 # seconds
+
+end

data/lib/glowstone/packets.rb

@@ -0,0 +1,35 @@
+require 'bindata'
+
+class StatusPacket < BinData::Record
+	endian :big
+
+	int8 :request_type
+	string :client_id, :length => 4
+
+	skip :length => 9 # "splitnum\0"
+	uint8 :world_height # maybe?
+	skip :length => 10 # "\0hostname\0"
+	stringz :motd
+	skip :length => 9 # "gametype\0"
+	stringz :gametype
+	skip :length => 26 # "game_id\0MINECRAFT\0version\0"
+	stringz :version
+	skip :length => 8 # "plugins\0"
+	stringz :plugins
+	skip :length => 4 # "map\0"
+	stringz :map_name
+	skip :length => 11 # "numplayers\0"
+	stringz :num_players
+	skip :length => 11 # "maxplayers\0"
+	stringz :max_players
+	skip :length => 9 # "hostport\0"
+	stringz :port
+	stringz :host_label
+	stringz :host
+	int8 :na1
+	int8 :na2
+	stringz :na3
+	skip :length => 1
+	array :players, :type => :stringz, :initial_length => lambda { num_players.to_i }
+
+end

data/lib/glowstone/server.rb

@@ -0,0 +1,57 @@
+require 'socket'
+
+module Glowstone
+
+	class Server
+
+		attr_reader :host, :port
+		attr_accessor :timeout
+
+		def initialize(host="localhost", port=25565)
+			@host = host
+			@port = port
+			@timeout = SOCKET_TIMEOUT
+
+			@socket = UDPSocket.new
+			@socket.connect(@host, @port)
+			refresh
+		end
+
+		def refresh
+			response = perform_request(MAGIC_BYTES + REQUEST_BYTE[:query] + CLIENT_ID + get_session_id + CLIENT_ID)
+			status = StatusPacket.read response
+
+			@motd = status.motd
+			@gamemode = status.gametype
+			@version = status.version
+			@plugins = status.plugins.split(/;\s*/)
+			@map_name = status.map_name
+			@num_players = status.num_players.to_i
+			@max_players = status.max_players.to_i
+			@players = status.players
+
+			self
+		end
+
+		protected ##################### helper methods and other such shenanigans #
+
+		def get_session_id
+			response = perform_request(MAGIC_BYTES + REQUEST_BYTE[:challenge] + CLIENT_ID)
+			
+			# the challenge token comes back as a series of bytes that represent the
+			# integer we want, so we have to convert it to the actual 32bit int
+			[response.slice(5..-2).to_i].pack("l>").bytes.to_a
+		end
+
+		def perform_request(request)
+			@socket.send(request.pack("c*"), 0)
+			packet = if select([@socket], nil, nil, @timeout)
+				@socket.recvfrom(2048)
+			end
+			raise SocketError if packet == nil
+			packet.first
+		end
+
+	end
+
+end

data/lib/glowstone/version.rb

@@ -0,0 +1,3 @@
+module Glowstone
+	VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: glowstone
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Tom Heinan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bindata
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.4.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.4.5
+description: Glowstone helps shed light on your Minecraft server!
+email:
+- me@tomheinan.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- glowstone.gemspec
+- lib/glowstone.rb
+- lib/glowstone/packets.rb
+- lib/glowstone/server.rb
+- lib/glowstone/version.rb
+homepage: http://tomheinan.com
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: This tiny gem implements the Gamespy query protocol to access pertinent real-time
+  information hidden away inside your Minecraft server.
+test_files: []