= Rubygame README Rubygame is a game-development extension and library for the ruby language, with similarities to pygame. The purpose of rubygame is make the creation of games in the ruby language simple, easy, and fun, without limiting flexibility. Rubygame provides two things: 1. an interface to Simple DirectMedia Layer (SDL); 2. a library containing 'helper' classes and modules. Rubygame was born out of a need (specifically, MY need) for a clean, convenient Ruby-to-SDL binding (for more information, see the FAQ on the webpage: http://rubygame.seul.org/faq.html). If rubygame isn't your cup of tea, you might try two other Ruby-to-SDL bindings, Ruby/SDL and RUDL. Many of the tutorials and examples for pygame will work with rubygame (after some minor modification) so I encourage you to consult those as well. Pygame's 'chimp' tutorial example has been translated to rubygame, with differences noted in the comments. See 'chimp.rb' in the samples directory packaged with rubygame. Rubygame is being programmed to be modular, meaning you can pick and choose which parts to use. For example, if you don't need TrueType font support, SDL_ttf is not required to compile rubygame. Additionally, it is possible for a game to detect at run-time which features are present, and behave differently (for example, disabling optional features). Further, rubygame is (or will be) multi-tiered, meaning that you can access rubygame's functionality on a number of levels, each level being built on the level below it. At the lowest level, rubygame is essentially a Ruby interface to SDL. At higher levels, rubygame provides sprite classes, event queues, etc. At still higher levels, rubygame might (in the future) provide features like a simple physics model or animation classes. Each higher level is closer to a complete game, but is also less flexible. Rubygame is considered to be in beta (as of January 2006). The API may change, but backward-incompatible changes will be marked by a major version number increment (e.g. from 1.0 to 2.0). New features additions which are backward-compatible will be marked by a minor version number increment (e.g. from 1.0 to 1.1). Bug fixes or other changes which do not affect the API will be marked by a patch version number increment (e.g. 1.0 to 1.0.1). If you would like to help make rubygame better, please send me comments via email (address at bottom of file)! === Links 1. Pygame: http://www.pygame.org 2. SDL: http://www.libsdl.org 3. Ruby/SDL: http://www.kmc.gr.jp/~ohai/rubysdl.en.html 4. RUDL: http://rudl.sourceforge.net == Requirements Rubygame has been tested (and was developed) on the following, although older or newer versions may work: * ruby >= 1.8 * SDL >= 1.2.7 * SDL_gfx >= 2.0.10 (for Draw/Transform modules) * SDL_image >= 1.2.3 (for Image.load() method) * SDL_ttf >= 2.0.6 (for TTF class) If you are compiling source, you will obviously need a C compiler as well. These versions of gcc worked fine for me: * gcc >= 3.3.2 (other compilers might work too) If you are compiling source on a binary-based ditribution (i.e. not Gentoo or LFS) you will also need the "dev" packages of ruby, SDL, SDL_gfx, SDL_image, and SDL_ttf. At this time, rubygame is only known to work on GNU/Linux. MacOSX and (eventually) Windows ports are likely. If you want to use rubygame on either of those platforms, please send me an email (address at bottom of file) and tell me, so I can guage interest! == Install === Basic Install Decompress archive and enter its top directory. Then run ($ indicates as user, # as root): $ rake config $ rake build # rake install or just: # rake install The 'config' and 'build' steps will happen automatically. You can also build HTML documentation into the 'html' directory: # rake rdoc === Advanced Install The 'Basic Install' instructions are easy, but don't allow for tweaking to fit your system. You can do that by manually invoking the setup.rb file in the toplevel rubygame directory, and passing arguments to it. setup.rb has several steps that correspond to the rake steps above: $ ruby setup.rb config $ ruby setup.rb setup ## corresponds to 'rake build' # ruby setup.rb install or just: # ruby setup.rb all You can install files into a different directory by giving some options. See "ruby setup.rb --help". During the 'config' phase, you can pass any of these additional arguments like so: "ruby setup.rb config -- --arg val --arg val" --cflags:: (string, default: "-Wall") Specify flags to pass to the C compiler when compiling the source. If you use --no-sdl-config, you will probably have to use this flag. --enable-opengl:: (bool, default: yes) Compile the GL module to allow rubygame to work alongside OpenGL to provide hardware-accelerated three-dimensional graphics. Please note that rubygame does not provide any OpenGL functionality, it merely allows the Screen to work as OpenGL's framebuffer. --include-path:: (path) A colon-separated list of directory paths to check for C headers, supplementing the directory given by `sdl-config --cflags`. Use this to help the compiler find headers installed in unusual places. --library-path:: (path) A colon-separated list of directory paths to check for libraries, supplementing the directory given by `sdl-config --libs`. Use this to help the compiler find libraries installed in unusual places. --libs:: (string) Specify flags to pass to the C linker when linking compiled source. If you use --no-sdl-config, you will probably have to use this flag. --no-sdl-config:: (bool, default: no) Skip invoking `sdl-config` to get compiler flags or include/library paths. Only use this if you know what you're doing! --sdl-config:: (string, default: "sdl-config") Specify an alternate command to use when trying to find compiler and linker flags. --with-gfx:: (bool, default: yes) Compile Rubygame with SDL_gfx support? This is required for 'Draw' and 'Transform' modules to work (with the exception of the Transform.flip method, which does not require it.) --with-image:: (bool, default: yes) Compile Rubygame with SDL_image support? This is required for the Image.load() method to work. --with-ttf:: (bool, default: yes) Compile Rubygame with SDL_ttf support? This is required for the TTF class to work. == Usage To use Rubygame in an application, do: require 'rubygame' You will probably also want a display window and event queue: screen = Rubygame::Screen.set_mode( [640,480] ) queue = Rubygame::Queue.instance() For more information, see the documentation (online at http://rubygame.seul.org). == License Rubygame is distributed under the terms of the GNU Lesser GPL. See LICENSE for more details. Some sample files may be distributed under different licenses than the GNU Lesser GPL. See 'samples/README' and 'samples/GPL' for more details. John 'jacius' Croisant (rubygame at seul dot org)