= 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)