Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A Ruby library for games — supporting audio spatialization and 2D (and even 3D!) graphics
C Ruby Objective-C C++
Branch: master
Failed to load latest commit information.
ext Cleaning up mo.c's lists and hashes
lib Removed require of iconv in 1.9, (even if that is wrong since String#…
samples Changed PI to Math::PI due to changes in the constant lookup rules
test Allowed Ray to bind an image to more than a single texture unit
.gemtest Initial commit
.gitignore Added a gemspec
.yardopts Initial commit
LICENSE Added a zlib license (see #53) Made Ray::Image respect the OpenGL convention for texture coordinates…
ray.gemspec Version bumped to 0.2.1
yard_ext.rb Made documentation for images more consistent

What is Ray?

Ray is a library than can create windows, play music, and draw 2D graphics (or not too complex 3D by doing just a bit more work, thanks to OpenGL). It is meant to be easy and fun to use (à la Shoes), and still flexible and powerful.

Tutorial & Installation

See on this page. Also notice there's an IRC channel on freenode: #ray.



require 'ray' "Hello" do
  register { add_hook :quit, method(:exit!) }

  scene :hello do
    @text = text "Hello world!", :size => 30, :angle => 30, :at => [50, 50]
    render { |win| win.draw @text }

  scenes << :hello

Flexible for more complex games

require 'ray'

class TitleScene < Ray::Scene
  scene_name :title

  def setup
    # setup resources

  def register
    # register for events

  def render(win)
    # draw!

  def clean_up
    # perform cleanup

class GameScene < Ray::Scene
  scene_name :game

  # same stuff

# ...

class Game < Ray::Game
  def initialize
    super "Awesome Game"

    # ...

    scenes << :title

Drawable API

Ray has a drawable class that specifies a common interface to all the drawable objects – how to perform transformations to them and how to draw them.

 obj =

 window.draw obj

 obj.pos    = [0, 2]   # set position
 obj.angle  = 40       # rotation
 obj.origin = [20, 20] # just sets the origin of transformations
 # ...

 # You can even have a completely custom transformation matrix:
 obj.matrix = Ray::Matrix.translation [2, 3, 4]

Off-screen rendering

When rendering to a window is not enough, you can render on an image just fine: some_image do |target|
  target.draw[50, 50], 10,

OpenGL integration

Ray uses OpenGL, and provides some classes and methods to allow using it from Ray. In fact, Ray::Drawable can simply be used for OpenGL rendering:

# Ray has a more advanced sprite class, of course!
class CustomSprite < Ray::Drawable
  def initialize(image)
    super() # very important: creating the actual drawable

    # Ray allocates a VBO to store your vertices.
    # You could just use your own OpenGL binding to call glBegin and glEnd
    # if you don't want to use it.
    self.vertex_count = 4

    # Tells Ray to enable texturing for this drawable
    self.textured = true

    @image = image

  # return an array of vertices
  def fill_vertices
    rect = @img.tex_rect [0, 0, @img.w, @img.h]

    [[0,      0],      Ray::Color.white, rect.top_left),[@img.w, 0],      Ray::Color.white, rect.top_right),[0,      @img.h], Ray::Color.white, rect.bottom_left),[@img.w, @img.h], Ray::Color.white, rect.bottom_right),

  # The index parameter is there in case you'd want to use
  # draw_elements. You can fill indices by defining a fill_indices method
  # and setting index_count.
  def render(first, index)

    # Some low level OpenGL calls are available
    Ray::GL.draw_arrays :triangle_strip, first, 4

You can also create and use shaders from Ruby:

shader = :vertex => "vertex_shader.glsl",
                         :frag   => "frag_shader.glsl"
drawable.shader = shader

# You can't assign an image to a render target, but you can recompile it:
window.shader.compile :vertex => "vertex.glsl", :frag => "frag.glsl"

3D rendering

3D rendering is a very cool thing! Even if Ray's graphics module only uses 2D, a 3D API can be created with it. You can just use Ray::Drawable again, but you will ned to specify the layout of your vertices and to write your own shaders (the default shaders are only designed for 2D). You will probably need a custom projection matrix too.

class Cube < Ray::Drawable
  include Ray::GL

  Vertex = Ray::GL::Vertex.make [
    [:pos, "in_Position", :vector3],
    [:col, "in_Color",    :color]

  def initialize
    super Vertex
    # ...

  # ...

# ...

# Tell the shader what vertex layout to use.
window.shader.apply_vertex Cube::Vertex
window.shader.compile :vertex => "vertex.glsl", :frag => "frag.glsl"

# Ray::Matrix can create 3D transformation and projection matrices!
window.view = Ray::Matrix.perspective(90, 1, 1, 100)

Audio playback

Ray can play short sounds right away and stream longer ones — it uses OpenAL for this. 3D audio effects can be added as well.

@sound = sound "test.wav"
@music = music "test.ogg"



@music.volume = 80
@music.pitch  = 0.9
@music.pos    = [10, 20, 30]


Ray's events can be faked so that you can simulate user input in your tests:

require 'awesome_scene'

describe AwesomeScene do
  before :each do
    @game =
    @scene = @game.registered_scene(:awesome_scene)


  it "has a cursor at (0, 0)" do
    @scene.cursor.pos.should == [0, 0]

  it "moves its cursor after the mouse moved" do
    @game.raise_event :mouse_motion, Ray::Vector2[100, 100]

    @scene.cursor.pos.should == [100, 100]

  it "draws its cursor" do
    @scene.window.should_receive(:draw, @scene.cursor)
    @scene.render @scene.window

  after :each do


You can animate the fact the state of an object is changing (its position, etc.) using Ray's animation objects:

animations << translation(:from => [0, 0], :to => [100, 100],
                          :duration => 4).start(@some_drawable)

(They can really be used to animate any change, not just those that are visible, and not just those applied to a drawable.)

Something went wrong with that request. Please try again.