Yggdrasil

Provides access to Mojang's authentication system. This functionality can be used to authenticate with custom game launchers.

Installation

Add this line to your application's Gemfile:

gem 'lapis-yggdrasil'

Or to your gemspec:

spec.add_dependency 'lapis-yggdrasil'

And then execute:

$ bundle

Or install it yourself as:

$ gem install lapis-yggdrasil

Usage

Script usage

Include the gem by adding this to your scripts:

require 'lapis/yggdrasil'

Authenticating with Yggdrasil

This gem tracks authentication by using sessions. To create a session, you must perform an initial authentication.

client  = Lapis::Yggdrasil::AuthenticationClient.official
session = client.authenticate(username, password)

session will contain a tracking information for the authentication. The session can be reused later without prompting the user for a username and password again. An AuthenticationError will be raised if the credentials are wrong.

NOTE: The username will be the user's email address for "Mojang accounts."

Reusing a session

To reuse the session at a later time:

session.refresh

And to check if the current session is still valid:

unless session.valid?
  # Session has expired and needs to be refreshed.
  session.refresh
end
# Proceed with valid session.

Ending a session

To end the session:

session.invalidate

NOTE: Due to the way Yggdrasil works, a session may become invalid at any time. The exact details aren't known, but authenticating elsewhere and timeouts seem to cause previous sessions to become invalid.

Using a session

The information needed for a Minecraft client is contained in the session information. The following information is available after authenticating:

session.info.client_token # Token representing the Minecraft client.
session.info.access_token # Token provided by Yggdrasil used with the client token to prove authentication.
session.info.profile      # Current profile the user has selected.
session.info.profile.name # Displayed name in the game.
session.info.profile.id   # UUID of the player.

client_token, access_token, and id are all UUIDs. Lapis has its own UUID class. Use #to_s to generate a more recognizable format. Passing false to #to_s will remove dashes.

Command-line usage

TODO

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake test to run the tests. It's recommended that you run bundle exec rake inspect to run inspections. You can also run bin/console for an interactive prompt that will allow you to experiment. bundle exec rake doc will generate documentation.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release. This will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub.