rubygame 2.5.3 → 2.6.0

data/doc/getting_started.rdoc

@@ -1,47 +1,76 @@
 = Getting Started with Rubygame
 
+This guide is also available on the Rubygame wiki:
+
+* http://rubygame.org/wiki/Getting_started
+
 == About Rubygame
 
-Rubygame is a combination extension and library for the Ruby language,
-designed for creating computer games (and having fun doing it!).
-As an extension, it provides an interface to the Simple DirectMedia Library
-(SDL) and its companion libraries SDL_gfx, SDL_image, SDL_ttf, and SDL_mixer.
-As a Ruby library, it provides classes/modules which implement some useful
-concepts such as Sprites, Event Queues, and rasterized fonts (SFont).
+Rubygame is a cross-platform game-development library for Ruby,
+inspired by Pygame. Rubygame strives to empower game developers by
+providing them with powerful and flexible mid-to-high level tools.
+Instead of worrying about low-level technical details, you can focus
+your energy on more interesting things (like making a fun game).
+
+== Installing Rubygame
+
+Installation guides for Mac and Windows are available in the 'doc'
+directory:
+
+Mac::     {doc/macosx_install.rdoc}[link:doc/macosx_install.rdoc]
+Windows:: {doc/windows_install.rdoc}[link:doc/windows_install.rdoc]
+
+You can also find installation instructions for many operating systems
+online at the Rubygame wiki:
+
+* http://rubygame.org/wiki/Installation_Instructions
+
+== Guides and tutorials
 
-== Suggested Order
+The Rubygame wiki has a list of guides and tutorials to help you get
+started using Rubygame:
+
+* http://rubygame.org/wiki/Guides_and_tutorials
+
+== Suggested order of reading
 
 To get acquainted with Rubygame, we recommend exploring the available classes
 and modules in this order.
 
 First, take a look at the most fundamental classes: 
-- Rubygame::Screen (the display window, what the user sees)
-- Rubygame::Surface (stores image data which can be copied to the Screen)
-- Rubygame::Rect (stores a rectangular area, like part of the Screen)
-
-As a next step, read about the event Queue and the hardware events, which
-allow you to take keyboard and mouse input, among other things.
-- Rubygame::EventQueue (stores events for processing)
-- Rubygame::KeyDownEvent (keyboard button is pressed)
-- Rubygame::KeyUpEvent (keyboard button is released)
-- Rubygame::MouseDownEvent (mouse button is clicked)
-- Rubygame::MouseUpEvent (mouse button is released)
-- Rubygame::MouseMotionEvent (mouse cursor is moved)
-- Rubygame::QuitEvent (user tries to close the window)
-- Rubygame::JoyDownEvent (joystick button is pressed)
-- Rubygame::JoyUpEvent (joystick button is released)
-- Rubygame::JoyAxisEvent (joystick axis is moved)
-- Rubygame::JoyBallEvent (joystick trackball is moved)
-- Rubygame::JoyHatEvent (joystick 8-directional hat switch is moved)
-- Rubygame::ActiveEvent (the Screen gets keyboard and/or mouse focus)
-- Rubygame::ResizeEvent (the Screen is resized)
-- Rubygame::ExposeEvent (the Screen is redrawn, mostly for OpenGL)
-
-Finally, familiarize yourself with:
-- Rubygame::Clock for monitoring and controlling framerate to save resources
-- Rubygame::Sprites for an easy-to-use yet flexible on-screen object framework
-- Rubygame::TTF and Rubygame::SFont for rendering text
-- Rubygame::GL for hardware-accelerated 3D graphics with OpenGL
-
-There are several sample applications in the rubygame/samples/ directory
+
+Rubygame::Surface:: An image canvas that you can load from an image
+                    file, draw shapes on and "blit" (copy) to other
+                    Surfaces (or the Screen).
+Rubygame::Screen::  A special Surface that is displayed to the user.
+                    Everything drawn on the Screen appears in the
+                    application window on the user's desktop.
+Rubygame::Rect::    A rectangular area, used for choosing what parts
+                    of a Surface to copy from or to, among other uses.
+
+As a next step, read about the EventQueue, EventHandler, and the user
+input event classes. These allow you to handle keyboard, mouse, and
+joystick input from the user, among other things. By creating your own
+event classes, these systems can also be used to represent things
+occuring within your game, such as the player losing a life or the
+level being completed.
+
+Rubygame::EventQueue::   A special Array that caches events to be
+                         handled later.
+Rubygame::EventHandler:: A flexible hook-based system for performing
+                         actions when certain types of events occur.
+Rubygame::Events::       A module containing all the built-in event
+                         classes in Rubygame.
+
+Finally, you may be interested in these features:
+
+Rubygame::Sprites:: A simple and flexible game object framework.
+Rubygame::Sound::   Play sound effects to make your game more lively.
+Rubygame::Music::   Play music to enhance your game's mood.
+Rubygame::Clock::   Monitor and control framerate to lower CPU use.
+Rubygame::TTF::     Render text with TrueType fonts.
+Rubygame::SFont::   Render text with bitmap-based fonts.
+Rubygame::GL::      Enable OpenGL 2D & 3D graphics.
+
+There are several sample applications in the 'samples' directory
 packaged with Rubygame which can also help you get started.

data/doc/keyboard_symbols.rdoc

@@ -0,0 +1,243 @@
+This is a list of every possible key that a keyboard event can have in
+Rubygame. You can view this list in a nicer form at
+http://rubygame.org/wiki/Keyboard_Symbols .
+
+The names on the left represent constants in the Rubygame module, e.g.
+Rubygame::K_BACKSPACE. These were used in the legacy (before Rubygame
+2.4) event classes: Rubygame::KeyDownEvent and Rubygame::KeyUpEvent.
+
+The legacy event classes are deprecated and will be removed in
+Rubygame 3.0, so you should not use them.
+
+The symbols on the right are used in the new event classes:
+Rubygame::Events::KeyPressed and Rubygame::Events::KeyReleased.
+
+  K_BACKSPACE     :backspace
+  K_TAB           :tab
+  K_CLEAR         :clear
+  K_RETURN        :return
+  K_PAUSE         :pause
+  K_ESCAPE        :escape
+  K_SPACE         :space
+  K_EXCLAIM       :exclamation_mark
+  K_QUOTEDBL      :double_quote
+  K_HASH          :hash
+  K_DOLLAR        :dollar
+  K_AMPERSAND     :ampersand
+  K_QUOTE         :quote
+  K_LEFTPAREN     :left_parenthesis
+  K_RIGHTPAREN    :right_parenthesis
+  K_ASTERISK      :asterisk
+  K_PLUS          :plus
+  K_COMMA         :comma
+  K_MINUS         :minus
+  K_PERIOD        :period
+  K_SLASH         :slash
+  K_0             :number_0
+  K_1             :number_1
+  K_2             :number_2
+  K_3             :number_3
+  K_4             :number_4
+  K_5             :number_5
+  K_6             :number_6
+  K_7             :number_7
+  K_8             :number_8
+  K_9             :number_9
+  K_COLON         :":"                  (will become :colon in Rubygame 3.0)
+  K_SEMICOLON     :semicolon
+  K_LESS          :less_than
+  K_EQUALS        :equals
+  K_GREATER       :greater_than
+  K_QUESTION      :question_mark
+  K_AT            :at
+  K_LEFTBRACKET   :left_bracket
+  K_BACKSLASH     :backslash
+  K_RIGHTBRACKET  :right_bracket
+  K_CARET         :caret
+  K_UNDERSCORE    :underscore
+  K_BACKQUOTE     :backquote
+  K_A             :a
+  K_B             :b
+  K_C             :c
+  K_D             :d
+  K_E             :e
+  K_F             :f
+  K_G             :g
+  K_H             :h
+  K_I             :i
+  K_J             :j
+  K_K             :k
+  K_L             :l
+  K_M             :m
+  K_N             :n
+  K_O             :o
+  K_P             :p
+  K_Q             :q
+  K_R             :r
+  K_S             :s
+  K_T             :t
+  K_U             :u
+  K_V             :v
+  K_W             :w
+  K_X             :x
+  K_Y             :y
+  K_Z             :z
+  K_DELETE        :delete
+  K_WORLD_0       :world_0
+  K_WORLD_1       :world_1
+  K_WORLD_2       :world_2
+  K_WORLD_3       :world_3
+  K_WORLD_4       :world_4
+  K_WORLD_5       :world_5
+  K_WORLD_6       :world_6
+  K_WORLD_7       :world_7
+  K_WORLD_8       :world_8
+  K_WORLD_9       :world_9
+  K_WORLD_10      :world_10
+  K_WORLD_11      :world_11
+  K_WORLD_12      :world_12
+  K_WORLD_13      :world_13
+  K_WORLD_14      :world_14
+  K_WORLD_15      :world_15
+  K_WORLD_16      :world_16
+  K_WORLD_17      :world_17
+  K_WORLD_18      :world_18
+  K_WORLD_19      :world_19
+  K_WORLD_20      :world_20
+  K_WORLD_21      :world_21
+  K_WORLD_22      :world_22
+  K_WORLD_23      :world_23
+  K_WORLD_24      :world_24
+  K_WORLD_25      :world_25
+  K_WORLD_26      :world_26
+  K_WORLD_27      :world_27
+  K_WORLD_28      :world_28
+  K_WORLD_29      :world_29
+  K_WORLD_30      :world_30
+  K_WORLD_31      :world_31
+  K_WORLD_32      :world_32
+  K_WORLD_33      :world_33
+  K_WORLD_34      :world_34
+  K_WORLD_35      :world_35
+  K_WORLD_36      :world_36
+  K_WORLD_37      :world_37
+  K_WORLD_38      :world_38
+  K_WORLD_39      :world_39
+  K_WORLD_40      :world_40
+  K_WORLD_41      :world_41
+  K_WORLD_42      :world_42
+  K_WORLD_43      :world_43
+  K_WORLD_44      :world_44
+  K_WORLD_45      :world_45
+  K_WORLD_46      :world_46
+  K_WORLD_47      :world_47
+  K_WORLD_48      :world_48
+  K_WORLD_49      :world_49
+  K_WORLD_50      :world_50
+  K_WORLD_51      :world_51
+  K_WORLD_52      :world_52
+  K_WORLD_53      :world_53
+  K_WORLD_54      :world_54
+  K_WORLD_55      :world_55
+  K_WORLD_56      :world_56
+  K_WORLD_57      :world_57
+  K_WORLD_58      :world_58
+  K_WORLD_59      :world_59
+  K_WORLD_60      :world_60
+  K_WORLD_61      :world_61
+  K_WORLD_62      :world_62
+  K_WORLD_63      :world_63
+  K_WORLD_64      :world_64
+  K_WORLD_65      :world_65
+  K_WORLD_66      :world_66
+  K_WORLD_67      :world_67
+  K_WORLD_68      :world_68
+  K_WORLD_69      :world_69
+  K_WORLD_70      :world_70
+  K_WORLD_71      :world_71
+  K_WORLD_72      :world_72
+  K_WORLD_73      :world_73
+  K_WORLD_74      :world_74
+  K_WORLD_75      :world_75
+  K_WORLD_76      :world_76
+  K_WORLD_77      :world_77
+  K_WORLD_78      :world_78
+  K_WORLD_79      :world_79
+  K_WORLD_80      :world_80
+  K_WORLD_81      :world_81
+  K_WORLD_82      :world_82
+  K_WORLD_83      :world_83
+  K_WORLD_84      :world_84
+  K_WORLD_85      :world_85
+  K_WORLD_86      :world_86
+  K_WORLD_87      :world_87
+  K_WORLD_88      :world_88
+  K_WORLD_89      :world_89
+  K_WORLD_90      :world_90
+  K_WORLD_91      :world_91
+  K_WORLD_92      :world_92
+  K_WORLD_93      :world_93
+  K_WORLD_94      :world_94
+  K_WORLD_95      :world_95
+  K_KP0           :keypad_0
+  K_KP1           :keypad_1
+  K_KP2           :keypad_2
+  K_KP3           :keypad_3
+  K_KP4           :keypad_4
+  K_KP5           :keypad_5
+  K_KP6           :keypad_6
+  K_KP7           :keypad_7
+  K_KP8           :keypad_8
+  K_KP9           :keypad_9
+  K_KP_PERIOD     :keypad_period
+  K_KP_DIVIDE     :keypad_divide
+  K_KP_MULTIPLY   :keypad_multiply
+  K_KP_MINUS      :keypad_minus
+  K_KP_PLUS       :keypad_plus
+  K_KP_ENTER      :keypad_enter
+  K_KP_EQUALS     :keypad_equals
+  K_UP            :up
+  K_DOWN          :down
+  K_RIGHT         :right
+  K_LEFT          :left
+  K_INSERT        :insert
+  K_HOME          :home
+  K_END           :end
+  K_PAGEUP        :page_up
+  K_PAGEDOWN      :page_down
+  K_F1            :f1
+  K_F2            :f2
+  K_F3            :f3
+  K_F4            :f4
+  K_F5            :f5
+  K_F6            :f6
+  K_F7            :f7
+  K_F8            :f8
+  K_F9            :f9
+  K_F10           :f10
+  K_F11           :f11
+  K_F12           :f12
+  K_F13           :f13
+  K_F14           :f14
+  K_F15           :f15
+  K_NUMLOCK       :numlock
+  K_CAPSLOCK      :caps_lock
+  K_SCROLLOCK     :scroll_lock
+  K_RSHIFT        :right_shift
+  K_LSHIFT        :left_shift
+  K_RCTRL         :right_ctrl
+  K_LCTRL         :left_ctrl
+  K_RALT          :right_alt
+  K_LALT          :left_alt
+  K_RMETA         :right_meta
+  K_LMETA         :left_meta
+  K_LSUPER        :left_super
+  K_RSUPER        :right_super
+  K_MODE          :alt_gr
+  K_HELP          :help
+  K_PRINT         :print_screen
+  K_SYSREQ        :sys_req
+  K_BREAK         :break
+  K_MENU          :menu
+  K_POWER         :power
+  K_EURO          :euro

data/doc/macosx_install.rdoc

@@ -1,70 +1,84 @@
-= How to install Rubygame on Mac OS X
+Note: You can view the latest version of this guide online at the
+Rubygame wiki: http://rubygame.org/wiki/Mac_Installation_Guide
 
-This is an outline of the steps to compile and use Rubygame on Mac OS X!
+== Installing Xcode
 
-== Installing dependencies...
+Rubygame does not need to be compiled anymore (since version 2.6),
+but you will need to install the Xcode development tools in order
+to install the dependencies with Fink or Darwinports, as well as
+to compile rsdl.
+
+You can find Xcode on your Mac OS X installation disc. Or, you can
+download Xcode online. You must register for a (free) Mac developer
+account for this.
 
-You have two options for installing the software libraries that Rubygame
-depends on: Darwinports or Fink. Which option you choose is just a matter of
-preference.
+* Mac OS X 10.5 (Leopard) and 10.6 (Snow Leopard):
+  {Xcode 3.1}[https://connect.apple.com/cgi-bin/WebObjects/MemberSite.woa/wa/getSoftware?bundleID=20414]
 
-=== ...with Darwinports[http://darwinports.opendarwin.org/]
+* Mac OS X 10.3 (Panther) and 10.4 (Tiger):
+  {Xcode 2.5}[http://connect.apple.com/cgi-bin/WebObjects/MemberSite.woa/wa/getSoftware?bundleID=19907]
+
+== Installing dependencies...
 
+You have two options for installing the software libraries that
+Rubygame depends on: Fink or Darwinports. Which option you choose is
+just a matter of preference.
 
-1. {Install darwinports}[http://darwinports.opendarwin.org/getdp/]
+=== ...with {Fink}[http://www.finkproject.org/]
+
+1. {Install Fink}[http://www.finkproject.org/download/index.php?phpLang=en]
+   and update to the latest version.
 2. Open a new terminal (can be found in /Applications/Utilities).
-3. Install SDL: 
+3. Install SDL:
 
-    sudo port install libsdl
+     sudo apt-get install sdl
 
-4. (Optional, but *highly* recommended:) Install the SDL companion 
-   libraries: 
+4. (Optional, but *highly* recommended:) Install the SDL companion
+   libraries:
 
-    sudo port install libsdl_gfx libsdl_image libsdl_mixer libsdl_ttf
+     sudo apt-get install sdl-gfx13 sdl-image sdl-mixer sdl-ttf
 
-=== ...with Fink[http://www.finkproject.org/]
+Thanks to Matt Crinklaw for these instructions.
 
-1. {Install Fink}[http://www.finkproject.org/download/index.php?phpLang=en]
-   and update to the latest version.
+=== ...with {Darwinports}[http://darwinports.com/]
+
+1. {Install Darwinports}[http://darwinports.com/download/] (you must
+   register first).
 2. Open a new terminal (can be found in /Applications/Utilities).
 3. Install SDL:
 
-    sudo apt-get install sdl
+     sudo port install libsdl
 
 4. (Optional, but *highly* recommended:) Install the SDL companion
    libraries:
 
-    sudo apt-get install sdl-gfx13 sdl-image sdl-mixer sdl-ttf
+     sudo port install libsdl_gfx libsdl_image libsdl_mixer libsdl_ttf
+
+Thanks to Raffael Mancini (sepisultrum) for these instructions.
 
 == Installing rsdl
 
-In order to use Rubygame applications on Mac OS X, you must use a special wrapper for the ruby interpreter, called rsdl.
+In order to use Rubygame applications on Mac OS X, you must use a special wrapper for the Ruby interpreter, called rsdl.
 
-1. {Download and unpack rsdl}[http://www.kumaryu.net/?c=plugin;plugin=attach_download;p=%28Ruby%29+Ruby%2FSDL%CD%D1ruby;file_name=rsdl.tar.gz].
+1. {Get rsdl}[http://github.com/knu/rsdl].
 2. From within the rsdl directory:
 
-    make
-    sudo cp rsdl /usr/local/bin/
-    
+     ruby ./configure.rb
+     make
+     sudo cp rsdl /usr/local/bin/
 
 == Installing Rubygame
-1. {Download and unpack Rubygame}[http://rubyforge.org/frs/?group_id=5089].
-2. From within the rubygame directory:
 
-    sudo rake install
+The simplest way to install Rubygame is: <code>gem install rubygame</code>
 
-3. Please refer to the README file for options that you can pass to setup.rb
-   or rake (depending on your version of Rubygame)
+Or you can {download the source
+from Github}[http://github.com/jacius/rubygame/] and follow the installation instructions in README.
 
 == Running an application
 
 If all went well, you can now run Rubygame applications like so: 
-<code>rsdl a_rubygame_app.rb</code>
 
-If something bad happened along the way, you can {email rubygame-users}[https://sourceforge.net/mail/?group_id=172781]
-and we'll try to help! Be sure to include plenty of details and paste any error
-messages that occur (plus a good bit of the text right before the error
-messages).
+    rsdl a_rubygame_app.rb
 
-(Many thanks to Raffael Mancini (sepisultrum) and Matt Crinklaw for
-instructions to install dependencies with darwinports and fink, respectively.)
+If you have any trouble installing Rubygame, please post in the
+{forums}[http://rubygame.org/forums/].