Introduction to Rubygame 2.3

Rubygame 2.3.0 has been released! This article will introduce you to the new features, and help developers get the most out of the new version!

New Features

Sound and Music classes

Rubygame 2.3.0 adds two new classes, Sound and Music, which offer numerous advantages over the older Mixer::Sample and Mixer::Music classes. Both classes offer a consistent and natural API (e.g., sound.volume = 0.5, sound.stop), and will automatically initialize the audio device and allocate audio channels as needed.

Please note that with the addition of these new classes, the older Mixer::Sample and Mixer::Music are deprecated. See the section on deprecations, below.

NamedResource mixin module

In addition to the new classes, Rubygame 2.3.0 adds a new utility mixin module, NamedResource. NamedResource extends classes with a per-class Hash table for storing resources (e.g. images, sounds) by name for future access. Even more excitingly, NamedResource allows resources to be autoloaded on demand, when they are first needed.

NamedResource is included in the new Sound and Music classes, as well as in Surface. To use the autoloading feature in your games, simply add directory paths to the class's autoload_dirs array (e.g.: Surface.autoload_dirs << "images"). Resources will then be autoloaded from those directories the first time you access them (e.g.: Surface["imagename.bmp"]).

NamedResource is also available to use in your own classes. This can be useful for loading and storing resources like maps, characters, weapon definitions, etc. Please see the documentation for NamedResources for an example of using it in a class.



The Mixer module (including the Mixer::Sample and Mixer::Music classes) is deprecated and will be removed in the future (version 3.0). New games should not use the Mixer module, and existing games are strongly encouraged to migrate to the newer classes.

Important module methods from the Mixer, most notably open_audio and close_audio, are now available directly in the Rubygame module. Please note that you only need to use these methods if you don't want to use the default audio settings. Sound and Music will both automatically open the audio device as needed, and it will be closed when Rubygame.quit is called. Also note that Rubygame.open_audio takes arguments as a Hash, whereas Rubygame::Mixer.open_audio has taken a series of optional arguments.


The Surface.load method should now be used in favor of Surface.load_image. This is simply a new name, for consistency with the new Sound and Music classes. It functions identically with Surface.load_image. Surface.load_image is deprecated and will be removed in the future.

Enabling deprecation warnings

In order to test whether your game is using deprecated features, run ruby with the "-w" flag, or set "$_v = true" inside your application. This will cause Rubygame to emit a warning (with file and line number) whenever a deprecated method or class is used, like so:

chimp.rb:205: warning: Rubygame::Mixer is DEPRECATED and will be removed in Rubygame 3.0! Please see the docs for more information.

You should use this as a guide to help you ensure that your game will be compatible with Rubygame 3.0, when it is released.

Versions between now and then (e.g. 2.4, 2.5) will contain more deprecated modules and methods, so you should be sure to check for deprecation warnings with each new version. Of course, the release notes for those versions will describe what has become deprecated, as well.


Have something interesting to say about this post? Email your thoughtful comments to