Rubygame tutorial #1: getting started

I while ago I posted on Ruby/SDL, which allows you to program SDL applications in Ruby. It works, but I think many Ruby programmers would like to have a higher-level API, something similar to pygame.

Enter rubygame. The first rubygame site states that:

Rubygame is a cross-platform multimedia library for ruby, the most beautiful programming language in the world. It embraces the ruby spirit to provide developers with a library that is clean and easy to use so you can get things done painlessly, and yet powerful and flexible so you can get them done right

I have written a few pygame tutorials to date, but since I happen to also love Ruby I thought that I would try to put together some similar tutorials for Ruby programmers as well. So, let’s get started.

Getting Rubygame

Before you can start developing using rubygame, you obviously need to get it installed. It doesn’t exist in the Debian repositories (at least not yet), but I downloaded it by hand, and it wasn’t difficult at all to install. Just make sure you have all the dependencies installed. Then just follow the instructions in the README.

What you need to know already

I assume that you have some familiarity with Ruby, but you don’t have to be an expert at all (it would be difficult for me to demand that out of you since I am by no means one myself!).

Displaying a window

Let’s get started with a simple program that displays a small window. Type this in as you see it and save it as something like window.rb. You should have some familiarity with how to use a computer and how to type commands in a terminal window.

1 #! /usr/bin/ruby -w
2
3 require ‘rubygame‘
4
5 Rubygame.init
6 screen = Rubygame::Screen.new [640, 400]
7 loop {}
8

You can run it directly by typing ruby window.rb (assuming that’s what you called it) or you can chmod +x window.rb in which case you can run it with ./window.rb.

You should see an empty, black window. The window is 640 pixels wide and 400 pixels high. You will also notice that clicking on the window’s close button doesn’t do a thing. In order to close the window you will have to activate your terminal window and press CTRL+C.

In order to use rubygame you first have to require it. Then you should call Rubygame.init to allow rubygame to initialize itself. Create a Rubygame::Screen, passing in the window’s width and height as an Array. The next line just jumps the program into an indefite loop, which is why we have to press CTRL+C to stop the program.

Exercises

1. Modify the program to use other values than 640 and 400 for the width and the height of the window. Run the program to confirm that the window size changes. For instance, create a window that is 320×200.

2. Modify the program to accept the width and the height of the window as command-line arguments.

3. Create a program that upon start up prompts the user for the width and the height and then creates a window of those dimensions.

4. Create two instances of Rubygame::Screen. You can call them screen1 and screen2 if you wish. What do you think should happen? Run the program. What actually happens? Can you explain why?

Adding an event loop

It would probably be a good idea to create a program that behaves properly, at the very least when the user tries to close the window. The following does just that:

 1 #! /usr/bin/ruby -w
 2
 3 require ‘rubygame‘
 4
 5 Rubygame.init
 6 screen = Rubygame::Screen.new [640, 400]
 7 events = Rubygame::EventQueue.new
 8
 9 loop do
10   events.each { |event|
11      if event.class == Rubygame::QuitEvent
12        Rubygame.quit
13        exit
14      end
15   }
16 end

The first new thing is that we create and EventQueue. Events are things that happen to the window, like the mouse moving over it, a key on the keyboard being pressed while the window is active and so on. Another event is the Quit event, which is triggered when the close window button is clicked.

In order to be able to respond to events that happen during the life time of the application, we need an event loop. This is basically just a loop that checks if there are any new events in the event queue. If there are we can deal with them. In this case all we do is check if the event is the QuitEvent, and if so, close down Rubygame and quit the application.

Exercises

1. Rewrite all the exercises you wrote in the previous section to include an event loop.

2. See if you can re-write the application to break out of the outer loop when the application receives the Quit event. There are several ways to do this.

Adding some color

So far so good. But let’s change the background color. Try this:

 1 #! /usr/bin/ruby -w
 2
 3 require ‘rubygame‘
 4
 5 Rubygame.init
 6 screen = Rubygame::Screen.new [640, 400]
 7 events = Rubygame::EventQueue.new
 8 screen.fill [255, 255, 0]
 9 screen.update
10
11 loop do
12   events.each { |event|
13      if event.class == Rubygame::QuitEvent
14        Rubygame.quit
15        exit
16      end
17   }
18 end

What is new is that we fill the screen with a color. The color comes in a triplet consisting of red, green and blue (RGB). Each can be a value between 0 and 255.

Exercises

1. Create a window with a white background color.

2. Create a window with a red background color.

3. Experiment with setting different background colors. If you are not familiar with RGB values then spend a little extra time to figure out how to get colors like yellow, brown, cyan etc.

4. Create a program that asks the user to specify the values for red, green and blue. Check that the values are in the valid range (0-255) and then use these for the background color.

5. Create a program that upon start-up checks the time of the day and sets the brightness of the background color accordingly. Use a blue scale. If it is midnight, the screen should be black. If it is midday, the screen should be bright blue. Any other time the background should be something in between corresponding to the brightness outside.

But wait

I was having so much fun that I almost forgot: Ruby is an object-oriented programming language. Below is a modified version of the previous program that sticks everything into a class and adds a few LOC at the same time.

 1 #! /usr/bin/ruby -w
 2
 3 require ‘rubygame‘
 4
 5 class Simple
 6   include Rubygame
 7
 8   def initialize
 9     @screen = Screen.new [640, 400]
10     @events = EventQueue.new
11     @screen.fill [255, 240, 0]
12     @screen.update
13   end
14
15   def event_loop
16     loop do
17       @events.each { |event|
18         case event
19         when QuitEvent
20           return
21         end
22       }
23     end
24   end
25 end
26
27 Rubygame.init
28 Simple.new.event_loop
29 Rubygame.quit
30

This example can be seen as a form of template for the next few programs that we will be writing.

Exercises

1. Modify the last version of the program so that it has the attributes width and height. The constructor should take a width and height as well. If you like, you can let the constructor have default values for these two.

Conclusion

Well, with that, the first Rubygame tutorial is at an end. In the next tutorial we will start drawing some things on the screen and looking at a few more events that our program can deal with. Until then, practice, practice, practice. And, remember to always have fun when you program in Ruby.

---

Possibly related posts: (automatically generated)

• Rubygame tutorial #2: pixels
• Pygame tutorial #1: getting started
• Pygame tutorial #4: more on events
• How to make a simple window in SDL