Introduction

I apologize for how limited this documentation is, but as this extension is primarily a simple wrapper around SFML's C++ classes, I will rely on SFML's documentation to explain more detail about the classes and methods. This documentation is simply meant to explain which classes and methods are available in Ruby, as well as what changes have been made during the translation from C++ to Ruby.

As Ruby doesn't support native threading and has its own networking classes, I only exposed certain classes in the system, window, graphics, and audio libraries. For most exposed classes, the only changes I made were to make the methods start with a lower-case letter. For classes with simple Get/Set methods, I often drop the Get and Set to allow you to use sprite.left and sprite.left=. I also added a few to_i, to_f, and to_s methods where it seemed appropriate. Last but not least, I added an each iterator to VideoMode.

In addition to the C++ classes I exposed, I also added two helper classes in RubySFML.rb, one for rendering tiled sprites, and the other for dealing with sprites that use 2D velocity/accelerate calculations (TSprite and VSprite respectively).

Tips for Windows Users

For the Windows users out there, I apologize for not being compatible with the one-click installer, but it's being built with Visual Studio 6.0, which is ridiculously old and not compatible with any of the SFML libraries. There's a free version of Visual Studio 2005 available, and the Ruby source compiles very smoothly with it, so I can't think of a good excuse for the one-click installer to still be using 6.0.

On the bright side, you can distribute your game in a self-sufficient package by zipping it up with the bin and lib folders that come with the Windows binary version of this extension. Add a simple installer that creates a program group icon that runs "%install_path%\bin\ruby.exe %install_path%\my_game.rb", and you're all set. Oh yeah, OpenAL needs to be installed on any machine running this. Fortunately it is a very small/simple install, and it should be easy for you to either bundle it with your distribution or provide a link for your users to download it. All of this keeps your users from having to download/run the one-click installer, install all the necessary extensions, worry about compatibility issues, etc. It is likely that very few Windows users will ever play your game if you don't provide them everything they need to run it, so it's probably better this way.

Note: This custom build of Ruby does have gems and zlib (which is required by gems), but no other extensions are installed. Feel free to install any other gems/extensions you need (native mswin32 gems compiled with Visual Studio 6.0 may not work). Keep in mind that many gems often have large doc, examples, and test folders. Deleting these unnecessary folders, along with the gem cache folder, can significantly shrink the size of the file you're distributing.

RubySFML Sample Code

# Include the RubySFML extension
require "RubySFML"
include SFML

# Create the main window
mode = VideoMode.new 800, 600, 32
window = RenderWindow.new mode, "RubySFML Test", false

# Load a sprite to display
image = Image.new "cute_image.jpg"
sprite = Sprite.new image
 
# Create a graphical string to display
text = Text.new "Hello SFML", "arial.ttf", 50
 
# Load a music and start playing it
music = Music.new "nice_music.ogg"
music.play
 
# Start the game loop
running = true
while running
	while event = window.getEvent
		running = false if event.type == Event::Close
	end
 
	# Draw the sprite, then the text, and update the window
	window.draw sprite
	window.draw text
	window.display
end

RubySFML Modules

RubySFML Classes

RubySFML Methods (by module/class)

SFML

SFML::Clock

SFML::Color

SFML::Drawable

SFML::Event

For all event types
For the Event::TextEntered event type
For Event::KeyPressed and Event::KeyReleased event types
For mouse and joystick event types
For the Event::Resize event type

SFML::FloatRect

SFML::Image

SFML::Input

SFML::IntRect

SFML::Music

SFML::PostFX

SFML::RenderWindow

SFML::Sound

SFML::SoundBuffer

SFML::SoundBufferRecorder

SFML::Sprite

SFML::Text

SFML::VideoMode

SFML::View

SFML::Window