
Classes
*******


Contents
^^^^^^^^

* Classes

  * sge.Game

    * sge.Game Methods

    * sge.Game Event Methods

  * sge.Sprite

    * sge.Sprite Methods

  * sge.BackgroundLayer

    * sge.BackgroundLayer Methods

  * sge.Background

    * sge.Background Methods

  * sge.Sound

    * sge.Sound Methods

  * sge.Music

    * sge.Music Methods

  * sge.Color

  * sge.Font

    * sge.Font Methods

  * sge.Object

    * sge.Object Methods

    * sge.Object Event Methods

  * sge.Room

    * sge.Room Methods

    * sge.Room Event Methods

  * sge.View

    * sge.View Methods


sge.Game
========

class class sge.Game(width=640, height=480, fullscreen=False, scale=None, scale_proportional=True, scale_smooth=False, fps=60, delta=False, delta_min=15, delta_max=None, grab_input=False, window_text=None, window_icon=None, collision_events_enabled=True)

   This class handles most parts of the game which operate on a global
   scale, such as global game events.  Before anything else is done
   with the SGE, an object either of this class or of a class derived
   from it must be created.

   When an object of this class is created, it is automatically
   assigned to "sge.game".

   Note: Do not create multiple "sge.Game" objects.  Doing so is
     unsupported and may cause errors.

   width

      The width of the game's display.

   height

      The height of the game's display.

   fullscreen

      Whether or not the game should be in fullscreen.

   scale

      A number indicating a fixed scale factor (e.g. "1" for no
      scaling, "2" for doubled size).  If set to "None" or "0",
      scaling is automatic (causes the game to fit the window or
      screen).

   scale_proportional

      If set to "True", scaling is always proportional.  If set to
      "False", the image will be distorted to completely fill the game
      window or screen.  This has no effect unless "scale" is "None"
      or "0".

   scale_smooth

      Whether or not a smooth scaling algorithm (as opposed to a
      simple scaling algorithm such as nearest-neighbor) should be
      used.

   fps

      The rate the game should run in frames per second.

      Note: This is only the maximum; if the computer is not fast
        enough, the game may run more slowly.

   delta

      Whether or not delta timing should be used.  Delta timing
      affects object speeds, animation rates, and alarms.

   delta_min

      Delta timing can cause the game to be choppy.  This attribute
      limits this by pretending that the frame rate is never lower
      than this amount, resulting in the game slowing down like normal
      if it is.

   delta_max

      Indicates a higher frame rate cap than "fps" to allow the game
      to reach by using delta timing to slow object speeds, animation
      rates, and alarms down.  If set to "None", this feature is
      disabled and the game will not be permitted to run faster than
      "fps".

      This attribute has no effect unless "delta" is "True".

   grab_input

      Whether or not all input should be forcibly grabbed by the game.
      If this is "True" and "sge.mouse.visible" is "False", the mouse
      will be in relative mode.  Otherwise, the mouse will be in
      absolute mode.

   window_text

      The text for the OS to display as the window title, e.g. in the
      frame of the window.  If set to "None", the SGE chooses the
      text.

   window_icon

      The path to the image file to use as the window icon.  If set to
      "None", the SGE chooses the icon.  If the file specified does
      not exist, "IOError" is raised.

   collision_events_enabled

      Whether or not collision events should be executed.  Setting
      this to "False" will improve performence if collision events are
      not needed.

   alarms

      A dictionary containing the global alarms of the game.  Each
      value decreases by 1 each frame (adjusted for delta timing if it
      is enabled).  When a value is at or below 0,
      "sge.Game.event_alarm()" is executed with "alarm_id" set to the
      respective key, and the item is deleted from this dictionary.

   input_events

      A list containing all input event objects which have not yet
      been handled, in the order in which they occurred.

      Note: If you handle input events manually, be sure to delete
        them from this list, preferably by getting them with
        "list.pop()". Otherwise, the event will be handled more than
        once, which is usually not what you want.

   start_room

      The room which becomes active when the game first starts and
      when it restarts.  Must be set exactly once, before the game
      first starts, and should not be set again afterwards.

   current_room

      The room which is currently active.  (Read-only)

   mouse

      A "sge.Object" object which represents the mouse cursor.  Its
      bounding box is a one-pixel square.  It is automatically added
      to every room's default list of objects.

      Some of this object's attributes control properties of the
      mouse. See the documentation for "sge.mouse" for more
      information.

      (Read-only)


sge.Game Methods
----------------

Game.__init__(width=640, height=480, fullscreen=False, scale=None, scale_proportional=True, scale_smooth=False, fps=60, delta=False, delta_min=15, delta_max=None, grab_input=False, window_text=None, window_icon=None, collision_events_enabled=True)

   Arguments set the respective initial attributes of the game. See
   the documentation for "sge.Game" for more information.

   The created "sge.Game" object is automatically assigned to
   "sge.game".

Game.start()

   Start the game.  Should only be called once; the effect of any
   further calls is undefined.

Game.end()

   Properly end the game.

Game.pause(sprite=None)

   Pause the game.

   Arguments:

   * "sprite" -- The sprite to show in the center of the screen
     while the game is paused.  If set to "None", the SGE chooses the
     image.

   Normal events are not executed while the game is paused. Instead,
   events with the same name, but prefixed with "event_paused_"
   instead of "event_" are executed.  Note that not all events have
   these alternative "paused" events associated with them.

Game.unpause()

   Unpause the game.

Game.pump_input()

   Cause the SGE to recieve input from the OS.

   This method needs to be called periodically for the SGE to recieve
   events from the OS, such as key presses and mouse movement, as well
   as to assure the OS that the program is not locked up.

   Upon calling this, each event is translated into the appropriate
   class in "sge.input" and the resulting object is appended to
   "input_events".

   You normally don't need to use this function directly.  It is
   called automatically in each frame of the SGE's main loop.  You
   only need to use this function directly if you take control away
   from the SGE's main loop, e.g. to create your own loop.

Game.regulate_speed(fps=None)

   Regulate the SGE's running speed and return the time passed.

   Arguments:

   * "fps" -- The target frame rate in frames per second.  Set to
     "None" to target the current value of "fps".

   When this method is called, the program will sleep long enough so
   that the game runs at "fps" frames per second, then return the
   number of milliseconds that passed between the previous call and
   the current call of this method.

   You normally don't need to use this function directly.  It is
   called automatically in each frame of the SGE's main loop.  You
   only need to use this function directly if you want to create your
   own loop.

Game.refresh()

   Refresh the screen.

   This method needs to be called for changes to the screen to be seen
   by the user.  It should be called every frame.

   You normally don't need to use this function directly.  It is
   called automatically in each frame of the SGE's main loop.  You
   only need to use this function directly if you take control away
   from the SGE's main loop, e.g. to create your own loop.

Game.project_dot(x, y, color, z=0)

   Project a single-pixel dot onto the game window.

   Arguments:

   * "x" -- The horizontal location relative to the window to
     project the dot.

   * "y" -- The vertical location relative to the window to project
     the dot.

   * "z" -- The Z-axis position of the projection in relation to
     other window projections.

   Window projections are projections made directly onto the game
   window, independent of the room or any views.

   Note: The Z-axis position of a window projection does not
     correlate with the Z-axis position of anything positioned within
     the room, such as room projections and "sge.Object" objects.
     Window projections are always positioned in front of such things.

   See the documentation for "sge.Sprite.draw_dot()" for more
   information.

Game.project_line(x1, y1, x2, y2, color, z=0, thickness=1, anti_alias=False)

   Project a line segment onto the game window.

   Arguments:

   * "x1" -- The horizontal location relative to the window of the
     first endpoint of the projected line segment.

   * "y1" -- The vertical location relative to the window of the
     first endpoint of the projected line segment.

   * "x2" -- The horizontal location relative to the window of the
     second endpoint of the projected line segment.

   * "y2" -- The vertical location relative to the window of the
     second endpoint of the projected line segment.

   * "z" -- The Z-axis position of the projection in relation to
     other window projections.

   See the documentation for "sge.Sprite.draw_line()" and
   "sge.Game.project_dot()" for more information.

Game.project_rectangle(x, y, width, height, z=0, fill=None, outline=None, outline_thickness=1)

   Project a rectangle onto the game window.

   Arguments:

   * "x" -- The horizontal location relative to the window to
     project the rectangle.

   * "y" -- The vertical location relative to the window to project
     the rectangle.

   * "z" -- The Z-axis position of the projection in relation to
     other window projections.

   See the documentation for "sge.Sprite.draw_rectangle()" and
   "sge.Game.project_dot()" for more information.

Game.project_ellipse(x, y, width, height, z=0, fill=None, outline=None, outline_thickness=1, anti_alias=False)

   Project an ellipse onto the game window.

   Arguments:

   * "x" -- The horizontal location relative to the window to
     position the imaginary rectangle containing the ellipse.

   * "y" -- The vertical location relative to the window to position
     the imaginary rectangle containing the ellipse.

   * "z" -- The Z-axis position of the projection in relation to
     other window projections.

   * "width" -- The width of the ellipse.

   * "height" -- The height of the ellipse.

   * "outline_thickness" -- The thickness of the outline of the
     ellipse.

   * "anti_alias" -- Whether or not anti-aliasing should be used.

   See the documentation for "sge.Sprite.draw_ellipse()" and
   "sge.Game.project_dot()" for more information.

Game.project_circle(x, y, radius, z=0, fill=None, outline=None, outline_thickness=1, anti_alias=False)

   Project a circle onto the game window.

   Arguments:

   * "x" -- The horizontal location relative to the window to
     position the center of the circle.

   * "y" -- The vertical location relative to the window to position
     the center of the circle.

   * "z" -- The Z-axis position of the projection in relation to
     other window projections.

   See the documentation for "sge.Sprite.draw_circle()" and
   "sge.Game.project_dot()" for more information.

Game.project_polygon(points, z=0, fill=None, outline=None, outline_thickness=1, anti_alias=False)

   Draw a polygon on the sprite.

   Arguments:

   * "points" -- A list of points relative to the room to position
     each of the polygon's angles.  Each point should be a tuple in
     the form "(x, y)", where x is the horizontal location and y is
     the vertical location.

   * "z" -- The Z-axis position of the projection in relation to
     other window projections.

   See the documentation for "sge.Sprite.draw_polygon()" and
   "sge.Game.project_dot()" for more information.

Game.project_sprite(sprite, image, x, y, z=0, blend_mode=None)

   Project a sprite onto the game window.

   Arguments:

   * "x" -- The horizontal location relative to the window to
     project "sprite".

   * "y" -- The vertical location relative to the window to project
     "sprite".

   * "z" -- The Z-axis position of the projection in relation to
     other window projections.

   See the documentation for "sge.Sprite.draw_sprite()" and
   "sge.Game.project_dot()" for more information.

Game.project_text(font, text, x, y, z=0, width=None, height=None, color=sge.Color("black"), halign='left', valign='top', anti_alias=True)

   Project text onto the game window.

   Arguments:

   * "x" -- The horizontal location relative to the window to
     project the text.

   * "y" -- The vertical location relative to the window to project
     the text.

   * "z" -- The Z-axis position of the projection in relation to
     other window projections.

   See the documentation for "sge.Sprite.draw_text()" and
   "sge.Game.project_dot()" for more information.


sge.Game Event Methods
----------------------

Game.event_step(time_passed, delta_mult)

   Called once each frame.

   Arguments:

   * "time_passed" -- The number of milliseconds that have passed
     during the last frame.

   * "delta_mult" -- What speed and movement should be multiplied by
     this frame due to delta timing.  If "delta" is "False", this is
     always "1".

Game.event_alarm(alarm_id)

   Called when the value of an alarm reaches 0.

   See the documentation for "sge.Game.alarms" for more information.

Game.event_key_press(key, char)

   See the documentation for "sge.input.KeyPress" for more
   information.

Game.event_key_release(key)

   See the documentation for "sge.input.KeyRelease" for more
   information.

Game.event_mouse_move(x, y)

   See the documentation for "sge.input.MouseMove" for more
   information.

Game.event_mouse_button_press(button)

   See the documentation for "sge.input.MouseButtonPress" for more
   information.

Game.event_mouse_button_release(button)

   See the documentation for "sge.input.MouseButtonRelease" for more
   information.

Game.event_joystick_axis_move(js_name, js_id, axis, value)

   See the documentation for "sge.input.JoystickAxisMove" for more
   information.

Game.event_joystick_hat_move(js_name, js_id, hat, x, y)

   See the documentation for "sge.input.JoystickHatMove" for more
   information.

Game.event_joystick_trackball_move(js_name, js_id, ball, x, y)

   See the documentation for "sge.input.JoystickTrackballMove" for
   more information.

Game.event_joystick_button_press(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonPress" for more
   information.

Game.event_joystick_button_release(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonRelease" for
   more information.

Game.event_gain_keyboard_focus()

   See the documentation for "sge.input.KeyboardFocusGain" for more
   information.

Game.event_lose_keyboard_focus()

   See the documentation for "sge.input.KeyboardFocusLose" for more
   information.

Game.event_gain_mouse_focus()

   See the documentation for "sge.input.MouseFocusGain" for more
   information.

Game.event_lose_mouse_focus()

   See the documentation for "sge.input.MouseFocusLose" for more
   information.

Game.event_close()

   See the documentation for "sge.input.QuitRequest" for more
   information.

   This is always called after any "sge.Room.event_close()" occurring
   at the same time.

Game.event_mouse_collision(other, xdirection, ydirection)

   Proxy for "sge.game.mouse.event_collision()".  See the
   documentation for "sge.Object.event_collision()" for more
   information.

Game.event_paused_step(time_passed, delta_mult)

   See the documentation for "sge.Game.event_step()" for more
   information.

Game.event_paused_key_press(key, char)

   See the documentation for "sge.input.KeyPress" for more
   information.

Game.event_paused_key_release(key)

   See the documentation for "sge.input.KeyRelease" for more
   information.

Game.event_paused_mouse_move(x, y)

   See the documentation for "sge.input.MouseMove" for more
   information.

Game.event_paused_mouse_button_press(button)

   See the documentation for "sge.input.MouseButtonPress" for more
   information.

Game.event_paused_mouse_button_release(button)

   See the documentation for "sge.input.MouseButtonRelease" for more
   information.

Game.event_paused_joystick_axis_move(js_name, js_id, axis, value)

   See the documentation for "sge.input.JoystickAxisMove" for more
   information.

Game.event_paused_joystick_hat_move(js_name, js_id, hat, x, y)

   See the documentation for "sge.input.JoystickHatMove" for more
   information.

Game.event_paused_joystick_trackball_move(js_name, js_id, ball, x, y)

   See the documentation for "sge.input.JoystickTrackballMove" for
   more information.

Game.event_paused_joystick_button_press(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonPress" for more
   information.

Game.event_paused_joystick_button_release(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonRelease" for
   more information.

Game.event_paused_gain_keyboard_focus()

   See the documentation for "sge.input.KeyboardFocusGain" for more
   information.

Game.event_paused_lose_keyboard_focus()

   See the documentation for "sge.input.KeyboardFocusLose" for more
   information.

Game.event_paused_gain_mouse_focus()

   See the documentation for "sge.input.MouseFocusGain" for more
   information.

Game.event_paused_lose_mouse_focus()

   See the documentation for "sge.input.MouseFocusLose" for more
   information.

Game.event_paused_close()

   See the documentation for "sge.Game.event_close()" for more
   information.


sge.Sprite
==========

class class sge.Sprite(name=None, directory='', width=None, height=None, transparent=True, origin_x=0, origin_y=0, fps=60, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None)

   This class stores images and information about how the SGE is to
   use those images.

   What image formats are supported depends on the implementation of
   the SGE, but image formats that are generally a good choice are PNG
   and JPEG.  See the implementation-specific information for a full
   list of supported formats.

   width

      The width of the sprite.

      Note: Changing this attribute will cause the sprite to be
        scaled horizontally.  This is a destructive transformation: it
        can result in loss of pixel information, especially if it is
        done repeatedly.  Because of this, it is advised that you do
        not adjust this value for routine scaling.  Use the
        "image_xscale" attribute of a "sge.Object" object instead.

   height

      The height of the sprite.

      Note: Changing this attribute will cause the sprite to be
        scaled vertically.  This is a destructive transformation: it
        can result in loss of pixel information, especially if it is
        done repeatedly.  Because of this, it is advised that you do
        not adjust this value for routine scaling.  Use the
        "image_yscale" attribute of a "sge.Object" object instead.

   transparent

      Whether or not the image should be partially transparent.  If an
      image does not have an alpha channel, a colorkey will be used,
      with the transparent color being the color of the top-rightmost
      pixel.

   origin_x

      The suggested horizontal location of the origin relative to the
      left edge of the images.

   origin_y

      The suggested vertical location of the origin relative to the
      top edge of the images.

   fps

      The suggested rate in frames per second to animate the image at.
      Can be negative, in which case animation will be reversed.

   speed

      The suggested rate to animate the image at as a factor of
      "sge.game.fps".  Can be negative, in which case animation will
      be reversed.

   bbox_x

      The horizontal location relative to the sprite of the suggested
      bounding box to use with it.  If set to "None", it will become
      equal to "-origin_x" (which is always the left edge of the
      image).

   bbox_y

      The vertical location relative to the sprite of the suggested
      bounding box to use with it.  If set to "None", it will become
      equal to "-origin_y" (which is always the top edge of the
      image).

   bbox_width

      The width of the suggested bounding box.

   bbox_height

      The height of the suggested bounding box.

   name

      The name of the sprite given when it was created.  (Read-only)

   frames

      The number of animation frames in the sprite.  (Read-only)

   rd

      Reserved dictionary for internal use by the SGE.  (Read-only)


sge.Sprite Methods
------------------

Sprite.__init__(name=None, directory='', width=None, height=None, transparent=True, origin_x=0, origin_y=0, fps=60, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None)

   Arguments:

   * "name" -- The base name of the image files, used to find all
     individual image files that make up the sprite's animation`. One
     of the following rules will be used to find the images:

     * The base name plus a valid image extension.  If this rule is
       used, the image will be loaded as a single-frame sprite.

     * The base name and an integer separated by either a hyphen
       ("-") or an underscore ("_") and followed by a valid image
       extension. If this rule is used, all images with names like
       this are loaded and treated as an animation, with the lower-
       numbered images being earlier frames.

     * The base name and an integer separated by either "-strip" or
       "_strip" and followed by a valid image extension.  If this rule
       is used, the image will be treated as an animation read as a
       horizontal reel from left to right, split into the number of
       frames indicated by the integer.

     * If the base name is "None", the sprite will be a fully
       transparent rectangle at the specified size (with both "width"
       and "height" defaulting to 32 if they are set to "None").  The
       SGE decides what to assign to the sprite's "name" attribute in
       this case, but it will always be a string.

     If none of the above rules can be used, "IOError" is raised.

   * "directory" -- The directory to search for image files in.

   All other arguments set the respective initial attributes of the
   sprite.  See the documentation for "Sprite" for more information.

Sprite.append_frame()

   Append a new blank frame to the end of the sprite.

Sprite.insert_frame(frame)

   Insert a new blank frame into the sprite.

   Arguments:

   * "frame" -- The frame of the sprite to insert the new frame in
     front of, where "0" is the first frame.

Sprite.delete_frame(frame)

   Delete a frame from the sprite.

   Arguments:

   * "frame" -- The frame of the sprite to delete, where "0" is the
     first frame.

Sprite.draw_dot(x, y, color, frame=None)

   Draw a single-pixel dot on the sprite.

   Arguments:

   * "x" -- The horizontal location relative to the sprite to draw
     the dot.

   * "y" -- The vertical location relative to the sprite to draw the
     dot.

   * "color" -- A "sge.Color" object representing the color of the
     dot.

   * "frame" -- The frame of the sprite to draw on, where "0" is the
     first frame; set to "None" to draw on all frames.

Sprite.draw_line(x1, y1, x2, y2, color, thickness=1, anti_alias=False, frame=None)

   Draw a line segment on the sprite.

   Arguments:

   * "x1" -- The horizontal location relative to the sprite of the
     first end point of the line segment.

   * "y1" -- The vertical location relative to the sprite of the
     first end point of the line segment.

   * "x2" -- The horizontal location relative to the sprite of the
     second end point of the line segment.

   * "y2" -- The vertical location relative to the sprite of the
     second end point of the line segment.

   * "color" -- A "sge.Color" object representing the color of the
     line segment.

   * "thickness" -- The thickness of the line segment.

   * "anti_alias" -- Whether or not anti-aliasing should be used.

   * "frame" -- The frame of the sprite to draw on, where "0" is the
     first frame; set to "None" to draw on all frames.

Sprite.draw_rectangle(x, y, width, height, fill=None, outline=None, outline_thickness=1, frame=None)

   Draw a rectangle on the sprite.

   Arguments:

   * "x" -- The horizontal location relative to the sprite to draw
     the rectangle.

   * "y" -- The vertical location relative to the sprite to draw the
     rectangle.

   * "width" -- The width of the rectangle.

   * "height" -- The height of the rectangle.

   * "fill" -- A "sge.Color" object representing the color of the
     fill of the rectangle.

   * "outline" -- A "sge.Color" object representing the color of the
     outline of the rectangle.

   * "outline_thickness" -- The thickness of the outline of the
     rectangle.

   * "frame" -- The frame of the sprite to draw on, where "0" is the
     first frame; set to "None" to draw on all frames.

Sprite.draw_ellipse(x, y, width, height, fill=None, outline=None, outline_thickness=1, anti_alias=False, frame=None)

   Draw an ellipse on the sprite.

   Arguments:

   * "x" -- The horizontal location relative to the sprite to
     position the imaginary rectangle containing the ellipse.

   * "y" -- The vertical location relative to the sprite to position
     the imaginary rectangle containing the ellipse.

   * "width" -- The width of the ellipse.

   * "height" -- The height of the ellipse.

   * "fill" -- A "sge.Color" object representing the color of the
     fill of the ellipse.

   * "outline" -- A "sge.Color" object representing the color of the
     outline of the ellipse.

   * "outline_thickness" -- The thickness of the outline of the
     ellipse.

   * "anti_alias" -- Whether or not anti-aliasing should be used.

   * "frame" -- The frame of the sprite to draw on, where "0" is the
     first frame; set to "None" to draw on all frames.

Sprite.draw_circle(x, y, radius, fill=None, outline=None, outline_thickness=1, anti_alias=False, frame=None)

   Draw a circle on the sprite.

   Arguments:

   * "x" -- The horizontal location relative to the sprite to
     position the center of the circle.

   * "y" -- The vertical location relative to the sprite to position
     the center of the circle.

   * "radius" -- The radius of the circle.

   * "fill" -- A "sge.Color" object representing the color of the
     fill of the circle.

   * "outline" -- A "sge.Color" object representing the color of the
     outline of the circle.

   * "outline_thickness" -- The thickness of the outline of the
     circle.

   * "anti_alias" -- Whether or not anti-aliasing should be used.

   * "frame" -- The frame of the sprite to draw on, where "0" is the
     first frame; set to "None" to draw on all frames.

Sprite.draw_polygon(points, fill=None, outline=None, outline_thickness=1, anti_alias=False, frame=None)

   Draw a polygon on the sprite.

   Arguments:

   * "points" -- A list of points relative to the sprite to position
     each of the polygon's angles.  Each point should be a tuple in
     the form "(x, y)", where x is the horizontal location and y is
     the vertical location.

   * "fill" -- A "sge.Color" object representing the color of the
     fill of the polygon.

   * "outline" -- A "sge.Color" object representing the color of the
     outline of the polygon.

   * "outline_thickness" -- The thickness of the outline of the
     polygon.

   * "anti_alias" -- Whether or not anti-aliasing should be used.

   * "frame" -- The frame of the sprite to draw on, where "0" is the
     first frame; set to "None" to draw on all frames.

Sprite.draw_sprite(sprite, image, x, y, frame=None, blend_mode=None)

   Draw another sprite on the sprite.

   Arguments:

   * "sprite" -- The sprite to draw with.

   * "image" -- The frame of "sprite" to draw with, where "0" is the
     first frame.

   * "x" -- The horizontal location relative to "self" to position
     the origin of "sprite".

   * "y" -- The vertical location relative to "self" to position the
     origin of "sprite".

   * "frame" -- The frame of the sprite to draw on, where "0" is the
     first frame; set to "None" to draw on all frames.

   * "blend_mode" -- The blend mode to use.  Possible blend modes
     are:

     * "sge.BLEND_NORMAL"

     * "sge.BLEND_RGBA_ADD"

     * "sge.BLEND_RGBA_SUBTRACT"

     * "sge.BLEND_RGBA_MULTIPLY"

     * "sge.BLEND_RGBA_SCREEN"

     * "sge.BLEND_RGBA_MINIMUM"

     * "sge.BLEND_RGBA_MAXIMUM"

     * "sge.BLEND_RGB_ADD"

     * "sge.BLEND_RGB_SUBTRACT"

     * "sge.BLEND_RGB_MULTIPLY"

     * "sge.BLEND_RGB_SCREEN"

     * "sge.BLEND_RGB_MINIMUM"

     * "sge.BLEND_RGB_MAXIMUM"

     "None" is treated as "sge.BLEND_NORMAL".

Sprite.draw_text(font, text, x, y, width=None, height=None, color=sge.Color("black"), halign='left', valign='top', anti_alias=True, frame=None)

   Draw text on the sprite.

   Arguments:

   * "font" -- The font to use to draw the text.

   * "text" -- The text (as a string) to draw.

   * "x" -- The horizontal location relative to the sprite to draw
     the text.

   * "y" -- The vertical location relative to the sprite to draw the
     text.

   * "width" -- The width of the imaginary rectangle the text is
     drawn in; set to "None" to make the rectangle as wide as needed
     to contain the text without additional line breaks. If set to
     something other than "None", a line which does not fit will be
     automatically split into multiple lines that do fit.

   * "height" -- The height of the imaginary rectangle the text is
     drawn in; set to "None" to make the rectangle as tall as needed
     to contain the text.

   * "color" -- A "sge.Color" object representing the color of the
     text.

   * "halign" -- The horizontal alignment of the text and the
     horizontal location of the origin of the imaginary rectangle the
     text is drawn in.  Can be set to one of the following:

     * ""left"" -- Align the text to the left of the imaginary
       rectangle the text is drawn in.  Set the origin of the
       imaginary rectangle to its left edge.

     * ""center"" -- Align the text to the center of the imaginary
       rectangle the text is drawn in.  Set the origin of the
       imaginary rectangle to its center.

     * ""right"" -- Align the text to the right of the imaginary
       rectangle the text is drawn in.  Set the origin of the
       imaginary rectangle to its right edge.

   * "valign" -- The vertical alignment of the text and the vertical
     location of the origin of the imaginary rectangle the text is
     drawn in.  Can be set to one of the following:

     * ""top"" -- Align the text to the top of the imaginary
       rectangle the text is drawn in.  Set the origin of the
       imaginary rectangle to its top edge.  If the imaginary
       rectangle is not tall enough to contain all of the text, cut
       text off from the bottom.

     * ""middle"" -- Align the the text to the middle of the
       imaginary rectangle the text is drawn in.  Set the origin of
       the imaginary rectangle to its middle.  If the imaginary
       rectangle is not tall enough to contain all of the text, cut
       text off equally from the top and bottom.

     * ""bottom"" -- Align the text  to the bottom of the imaginary
       rectangle the text is drawn in.  Set the origin of the
       imaginary rectangle to its top edge.  If the imaginary
       rectangle is not tall enough to contain all of the text, cut
       text off from the top.

   * "anti_alias" -- Whether or not anti-aliasing should be used.

   * "frame" -- The frame of the sprite to draw on, where "0" is the
     first frame; set to "None" to draw on all frames.

Sprite.draw_erase(x, y, width, height, frame=None)

   Erase part of the sprite.

   Arguments:

   * "x" -- The horizontal location relative to the sprite of the
     area to erase.

   * "y" -- The vertical location relative to the sprite of the area
     to erase.

   * "width" -- The width of the area to erase.

   * "height" -- The height of the area to erase.

   * "frame" -- The frame of the sprite to erase from, where "0" is
     the first frame; set to "None" to erase from all frames.

Sprite.draw_clear(frame=None)

   Erase everything from the sprite.

   Arguments:

   * "frame" -- The frame of the sprite to clear, where "0" is the
     first frame; set to "None" to clear all frames.

Sprite.draw_lock()

   Lock the sprite for continuous drawing.

   Use this method to "lock" the sprite for being drawn on several
   times in a row.  What exactly this does depends on the
   implementation and it may even do nothing at all, but calling this
   method before doing several draw actions on the sprite in a row
   gives the SGE a chance to make the drawing more efficient.

   After you are done with continuous drawing, call
   "sge.Sprite.draw_unlock()" to let the SGE know that you are done
   drawing.

   Warning: Do not cause a sprite to be used while it's locked.  For
     example, don't leave it locked for the duration of a frame, and
     don't draw it or project it on anything.  The effect of using a
     locked sprite could be as minor as graphical errors and as severe
     as crashing the program, depending on the SGE implementation.
     Always call "sge.Sprite.draw_unlock()" immediately after you're
     done drawing for a while.

Sprite.draw_unlock()

   Unlock the sprite.

   Use this method to "unlock" the sprite after it has been "locked"
   for continuous drawing by "sge.Sprite.draw_lock()".

Sprite.mirror()

   Mirror the sprite horizontally.

Sprite.flip()

   Flip the sprite vertically.

Sprite.rotate(x, adaptive_resize=True)

   Rotate the sprite about the center.

   Arguments:

   * "x" -- The rotation amount in degrees, with rotation in a
     positive direction being counter-clockwise.

   * "adaptive_resize" -- Whether or not the sprite should be
     resized to accomodate rotation.  If this is "True", rotation
     amounts other than multiples of 180 will result in the size of
     the sprite being adapted to fit the whole rotated image.  The
     origin will also be adjusted so that the rotation is about the
     center.

   Note: This is a destructive transformation: it can result in loss
     of pixel information, especially if it is done repeatedly.
     Because of this, it is advised that you do not adjust this value
     for routine rotation.  Use the "image_rotation" attribute of a
     "sge.Object" object instead.

Sprite.copy()

   Return a copy of the sprite.

Sprite.save(fname)

   Save the sprite to an image file.

   Arguments:

   * "fname" -- The path of the file to save the sprite to.  If it
     is not a path that can be saved to, "IOError" is raised.

   If the sprite has multiple frames, the image file saved will be a
   horizontal reel of each of the frames from left to right with no
   space in between the frames.

classmethod Sprite.from_text(font, text, width=None, height=None, color=sge.Color("black"), halign='left', valign='top', anti_alias=True)

   Create a sprite, draw the given text on it, and return the sprite.
   See the documentation for "sge.Sprite.draw_text()" for more
   information.

   The sprite's origin is set based on "halign" and "valign".

classmethod Sprite.from_tileset(fname, x=0, y=0, columns=1, rows=1, xsep=0, ysep=0, width=1, height=1, origin_x=0, origin_y=0, transparent=True, fps=0, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None)

   Return a sprite based on the tiles in a tileset.

   Arguments:

   * "fname" -- The path to the image file containing the tileset.

   * "x" -- The horizontal location relative to the image of the
     top- leftmost tile in the tileset.

   * "y" -- The vertical location relative to the image of the top-
     leftmost tile in the tileset.

   * "columns" -- The number of columns in the tileset.

   * "rows" -- The number of rows in the tileset.

   * "xsep" -- The spacing between columns in the tileset.

   * "ysep" -- The spacing between rows in the tileset.

   * "width" -- The width of the tiles.

   * "height" -- The height of the tiles.

   For all other arguments, see the documentation for
   "Sprite.__init__()".

   Each tile in the tileset becomes a subimage of the returned sprite,
   ordered first from left to right and then from top to bottom.

classmethod Sprite.from_screenshot(x=0, y=0, width=None, height=None)

   Return the current display on the screen as a sprite.

   Arguments:

   * "x" -- The horizontal location of the rectangular area to take
     a screenshot of.

   * "y" -- The vertical location of the rectangular area to take a
     screenshot of.

   * "width" -- The width of the area to take a screenshot of; set
     to None for all of the area to the right of "x" to be included.

   * "height" -- The height of the area to take a screenshot of; set
     to "None" for all of the area below "y" to be included.

   If you only wish to save a screenshot (of the entire screen) to a
   file, the easiest way to do that is:

      sge.Sprite.from_screenshot().save("foo.png")


sge.BackgroundLayer
===================

class class sge.BackgroundLayer(sprite, x, y, z=0, xscroll_rate=1, yscroll_rate=1, repeat_left=False, repeat_right=False, repeat_up=False, repeat_down=False)

   This class stores a sprite and certain information for a layer of a
   background.  In particular, it stores the location of the layer,
   whether the layer tiles horizontally, vertically, or both, and the
   rate at which it scrolls.

   sprite

      The sprite used for this layer.  It will be animated normally if
      it contains multiple frames.

   x

      The horizontal location of the layer relative to the background.

   y

      The vertical location of the layer relative to the background.

   z

      The Z-axis position of the layer in the room.

   xscroll_rate

      The horizontal rate that the layer scrolls as a factor of the
      additive inverse of the horizontal movement of the view.

   yscroll_rate

      The vertical rate that the layer scrolls as a factor of the
      additive inverse of the vertical movement of the view.

   repeat_left

      Whether or not the layer should be repeated (tiled) to the left.

   repeat_right

      Whether or not the layer should be repeated (tiled) to the
      right.

   repeat_up

      Whether or not the layer should be repeated (tiled) upwards.

   repeat_down

      Whether or not the layer should be repeated (tiled) downwards.

   rd

      Reserved dictionary for internal use by the SGE.  (Read-only)


sge.BackgroundLayer Methods
---------------------------

BackgroundLayer.__init__(sprite, x, y, z=0, xscroll_rate=1, yscroll_rate=1, repeat_left=False, repeat_right=False, repeat_up=False, repeat_down=False)

   Arguments set the respective initial attributes of the layer. See
   the documentation for "sge.BackgroundLayer" for more information.


sge.Background
==============

class class sge.Background(layers, color)

   This class stores the layers that make up the background (which
   contain the information about what images to use and where) as well
   as the color to use where no image is shown.

   layers

      A list containing all "sge.BackgroundLayer" objects used in this
      background.  (Read-only)

   color

      A "sge.Color" object representing the color used in parts of the
      background where no layer is shown.

   rd

      Reserved dictionary for internal use by the SGE.  (Read-only)


sge.Background Methods
----------------------

Background.__init__(layers, color)

   Arguments set the respective initial attributes of the background.
   See the documentation for "sge.Background" for more information.


sge.Sound
=========

class class sge.Sound(fname, volume=100, max_play=1)

   This class stores and plays sound effects.  Note that this is
   inefficient for large music files; for those, use "sge.Music"
   instead.

   What sound formats are supported depends on the implementation of
   the SGE, but sound formats that are generally a good choice are Ogg
   Vorbis and uncompressed WAV.  See the implementation-specific
   information for a full list of supported formats.

   volume

      The volume of the sound in percent from "0" to "100" ("0" for no
      sound, "100" for max sound).

   max_play

      The maximum number of instances of this sound playing permitted.
      If a sound is played while this number of the instances of the
      same sound are already playing, one of the already playing
      sounds will be stopped before playing the new instance.  Set to
      "None" for no limit.

   fname

      The file name of the sound given when it was created. (Read-
      only)

   length

      The length of the sound in milliseconds.  (Read-only)

   playing

      The number of instances of this sound playing.  (Read-only)

   rd

      Reserved dictionary for internal use by the SGE.  (Read-only)


sge.Sound Methods
-----------------

Sound.__init__(fname, volume=100, max_play=1)

   Arguments:

   * "fname" -- The path to the sound file.  If set to "None", this
     object will not actually play any sound. If this is neither a
     valid sound file nor "None", "IOError" is raised.

   All other arguments set the respective initial attributes of the
   sound.  See the documentation for "sge.Sound" for more information.

Sound.play(loops=1, volume=100, balance=0, maxtime=None, fade_time=None)

   Play the sound.

   Arguments:

   * "loops" -- The number of times to play the sound; set to "None"
     or "0" to loop indefinitely.

   * "volume" -- The volume to play the sound at as a percentage of
     "self.volume" from "0" to "100" ("0" for no sound, "100" for
     "self.volume").

   * "balance" -- The balance of the sound effect on stereo speakers
     as a float from "-1" to "1", where "0" is centered (full volume
     in both speakers), "1" is entirely in the right speaker, and "-1"
     is entirely in the left speaker.

   * "maxtime" -- The maximum amount of time to play the sound in
     milliseconds; set to "None" for no limit.

   * "fade_time" -- The time in milliseconds over which to fade the
     sound in; set to "None" or "0" to immediately play the sound at
     full volume.

Sound.stop(fade_time=None)

   Stop the sound.

   Arguments:

   * "fade_time" -- The time in milliseconds over which to fade the
     sound out before stopping; set to "None" or "0" to immediately
     stop the sound.

Sound.pause()

   Pause playback of the sound.

Sound.unpause()

   Resume playback of the sound if paused.

static Sound.stop_all()

   Stop playback of all sounds.


sge.Music
=========

class class sge.Music(fname, volume=100)

   This class stores and plays music.  Music is very similar to sound
   effects, but only one music file can be played at a time, and it is
   more efficient for larger files than "sge.Sound".

   What music formats are supported depends on the implementation of
   the SGE, but Ogg Vorbis is generally a good choice.  See the
   implementation-specific information for a full list of supported
   formats.

   Note: You should avoid the temptation to use MP3 files; MP3 is a
     patent-encumbered format, so many systems do not support it and
     royalties to the patent holders may be required for commercial
     use.  There are many programs which can convert your MP3 files to
     the free Ogg Vorbis format.

   volume

      The volume of the music in percent from "0" to "100" ("0" for no
      sound, "100" for maximum volume).

   fname

      The file name of the music given when it was created. (Read-
      only)

   length

      The length of the music in milliseconds.  (Read-only)

   playing

      Whether or not the music is playing.  (Read-only)

   position

      The current position (time) playback of the music is at in
      milliseconds.  (Read-only)

   rd

      Reserved dictionary for internal use by the SGE.  (Read-only)


sge.Music Methods
-----------------

Music.__init__(fname, volume=100)

   Arguments:

   * "fname" -- The path to the sound file.  If set to "None", this
     object will not actually play any music. If this is neither a
     valid sound file nor "None", "IOError" is raised.

   All other arguments set the respective initial attributes of the
   music.  See the documentation for "sge.Music" for more information.

Music.play(start=0, loops=1, maxtime=None, fade_time=None)

   Play the music.

   Arguments:

   * "start" -- The number of milliseconds from the beginning to
     start playing at.

   See the documentation for "sge.Sound.play()" for more information.

Music.queue(start=0, loops=1, maxtime=None, fade_time=None)

   Queue the music for playback.

   This will cause the music to be added to a list of music to play in
   order, after the previous music has finished playing.

   See the documentation for "sge.Music.play()" for more information.

static Music.stop(fade_time=None)

   Stop the currently playing music.

   See the documentation for "sge.Sound.stop()" for more information.

static Music.pause()

   Pause playback of the currently playing music.

static Music.unpause()

   Resume playback of the currently playing music if paused.

static Music.clear_queue()

   Clear the music queue.


sge.Color
=========

class class sge.Color(value)

   This class stores color information.

   Objects of this class can be converted to iterables indicating the
   object's "red", "green", "blue", and "alpha" values, respectively;
   to integers which can be interpreted as a hexadecimal
   representation of the color, excluding alpha transparency; and to
   strings which indicate the English name of the color (in all
   lowercase) if possible, and "hex_string" otherwise.

   red

      The red component of the color as an integer, where "0"
      indicates no red intensity and "255" indicates full red
      intensity.

   green

      The green component of the color as an integer, where "0"
      indicates no green intensity and "255" indicates full green
      intensity.

   blue

      The blue component of the color as an integer, where "0"
      indicates no blue intensity and "255" indicates full blue
      intensity.

   alpha

      The alpha transparency of the color as an integer, where "0"
      indicates full transparency and "255" indicates full opacity.

   hex_string

      An HTML hex string representation of the color.  (Read-only)


sge.Font
========

class class sge.Font(name=None, size=12, underline=False, bold=False, italic=False)

   This class stores a font for use by text drawing methods.

   Note that bold and italic rendering could be ugly.  It is better to
   choose a bold or italic font rather than enabling bold or italic
   rendering, if possible.

   size

      The height of the font in pixels.

   underline

      Whether or not underlined rendering is enabled.

   bold

      Whether or not bold rendering is enabled.

      Note: Using this option can be ugly.  It is better to choose a
        bold font rather than enabling bold rendering, if possible.

   italic

      Whether or not italic rendering is enabled.

      Note: Using this option can be ugly.  It is better to choose
        an italic font rather than enabling italic rendering, if
        possible.

   name

      The name of the font as specified when it was created. (Read-
      only)

   rd

      Reserved dictionary for internal use by the SGE.  (Read-only)


sge.Font Methods
----------------

Font.__init__(name=None, size=12, underline=False, bold=False, italic=False)

   Arguments:

   * "name" -- The name of the font.  Can be one of the following:

     * A string indicating the path to the font file.

     * A string indicating the case-insensitive name of a system
       font, e.g. ""Liberation Serif"".

     * A list or tuple of strings indicating either a font file or a
       system font to choose from in order of preference.

     If none of the above methods return a valid font, the SGE will
     choose the font.

   All other arguments set the respective initial attributes of the
   font.  See the documentation for "sge.Font" for more information.

   Note: It is generally not a good practice to rely on system
     fonts. There are no standard fonts; a font which you have on your
     system is probably not on everyone's system.  Rather than relying
     on system fonts, choose a font which is under a libre license
     (such as the GNU General Public License or the SIL Open Font
     License) and distribute it with your game; this will ensure that
     everyone sees text rendered the same way you do.

Font.get_width(text, width=None, height=None)

   Return the width of a certain string of text when rendered.

   See the documentation for "sge.Sprite.draw_text()" for more
   information.

Font.get_height(text, width=None, height=None)

   Return the height of a certain string of text when rendered.

   See the documentation for "sge.Sprite.draw_text()" for more
   information.

classmethod Font.from_sprite(sprite, chars, hsep=0, vsep=0, size=12, underline=False, bold=False, italic=False)

   Return a font derived from a sprite.

   Arguments:

   * "sprite" -- The "sge.Sprite" object to derive the font from.

   * "chars" -- A list of characters to set the sprite's frames to.
     For example, "['A', 'B', 'C']" would assign the first frame to
     the letter "A", the second frame to the letter "B", and the third
     frame to the letter "C".  Any character not listed here will be
     rendered as its differently-cased counterpart if possible (e.g.
     "A" as "a") or as a blank space otherwise.

   * "hsep" -- The amount of horizontal space to place between
     characters when text is rendered.

   * "vsep" -- The amount of vertical space to place between lines
     when text is rendered.

   All other arguments set the respective initial attributes of the
   font.  See the documentation for "sge.Font" for more information.

   The font's "name" attribute will be set to the name of the sprite
   the font is derived from.

   The font's "size" attribute will indicate the height of the
   characters in pixels.  The width of the characters will be adjusted
   proportionally.


sge.Object
==========

class class sge.Object(x, y, z=0, sprite=None, visible=True, active=True, checks_collisions=True, tangible=True, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None, regulate_origin=False, collision_ellipse=False, collision_precise=False, xvelocity=0, yvelocity=0, xacceleration=0, yacceleration=0, xdeceleration=0, ydeceleration=0, image_index=0, image_origin_x=None, image_origin_y=None, image_fps=None, image_xscale=1, image_yscale=1, image_rotation=0, image_alpha=255, image_blend=None)

   This class is used for game objects, such as the player, enemies,
   bullets, and the HUD.  Generally, each type of object has its own
   subclass of "sge.Object".

   x

      The horizontal position of the object in the room.

   y

      The vertical position of the object in the room.

   z

      The Z-axis position of the object in the room.

   sprite

      The sprite currently in use by this object.  Set to "None" for
      no sprite.

   visible

      Whether or not the object's sprite should be projected onto the
      screen.

   active

      Indicates whether the object is active ("True") or inactive
      ("False").  While the object is active, it will exhibit normal
      behavior; events will be executed normally as will any other
      automatic functionality, such as adding "xvelocity" and
      "yvelocity" to "x" and "y".  If "active" is "False", automatic
      functionality and normal events will be disabled.

      Note: Inactive "sge.Object" objects are still visible by
        default and continue to be involved in collisions.  In
        addition, collision events and destroy events still occur even
        if the object is inactive.  If you wish for the object to not
        be visible, set "visible" to "False".  If you wish for the
        object to not perform collision events, set
        "checks_collisions" to "False".

   checks_collisions

      Whether or not the object should check for collisions
      automatically and cause collision events.  If an object is not
      using collision events, setting this to "False" will give a
      boost in performance.

      Note: This will not prevent automatic collision detection by
        other objects from detecting this object, and it will also not
        prevent this object's collision events from being executed. If
        you wish to disable collision detection entirely, set
        "tangible" to "False".

   tangible

      Whether or not collisions involving the object can be detected.
      Setting this to "False" can improve performance if the object
      doesn't need to be involved in collisions.

      Depending on the game, a useful strategy to boost performance
      can be to exclude an object from collision detection while it is
      outside the view.  If you do this, you likely want to set
      "active" to "False" as well so that the object doesn't move in
      undesireable ways (e.g. through walls).

      Note: If this is "False", "checks_collisions" is implied to be
        "False" as well regardless of its actual value.  This is
        because checking for collisions which can't be detected is
        meaningless.

   bbox_x

      The horizontal location of the bounding box relative to the
      object's position.  If set to "None", the value recommended by
      the sprite is used.

   bbox_y

      The vertical location of the bounding box relative to the
      object's position.  If set to "None", the value recommended by
      the sprite is used.

   bbox_width

      The width of the bounding box in pixels.  If set to "None", the
      value recommended by the sprite is used.

   bbox_height

      The height of the bounding box in pixels.  If set to "None", the
      value recommended by the sprite is used.

   regulate_origin

      If set to "True", the origin is automatically adjusted to be the
      location of the pixel recommended by the sprite after
      transformation.  This will cause rotation to be about the origin
      rather than being about the center of the image.

      Note: The value of this attribute has no effect on the
        bounding box. If you wish for the bounding box to be adjusted
        as well, you must do so manually.  As an alternative, you may
        want to consider using precise collision detection instead.

   collision_ellipse

      Whether or not an ellipse (rather than a rectangle) should be
      used for collision detection.

   collision_precise

      Whether or not precise (pixel-perfect) collision detection
      should be used.  Note that this can be inefficient and does not
      work well with animated sprites.

   bbox_left

      The position of the left side of the bounding box in the room
      (same as "x" + "bbox_x").

   bbox_right

      The position of the right side of the bounding box in the room
      (same as "bbox_left" + "bbox_width").

   bbox_top

      The position of the top side of the bounding box in the room
      (same as "y" + "bbox_y").

   bbox_bottom

      The position of the bottom side of the bounding box in the room
      (same as "bbox_top" + "bbox_height").

   xvelocity

      The velocity of the object toward the right in pixels per frame.

   yvelocity

      The velocity of the object toward the bottom in pixels per
      frame.

   speed

      The total (directional) speed of the object in pixels per frame.

   move_direction

      The direction of the object's movement in degrees, with "0"
      being directly to the right and rotation in a positive direction
      being counter-clockwise.

   xacceleration

      The acceleration of the object to the right in pixels per frame.
      If non-zero, movement as a result of "xvelocity" will be
      adjusted based on the kinematic equation, "v[f]^2 = v[i]^2 +
      2*a*d".

   yacceleration

      The acceleration of the object downward in pixels per frame.  If
      non-zero, movement as a result of "yvelocity" will be adjusted
      based on the kinematic equation, "v[f]^2 = v[i]^2 + 2*a*d".

   xdeceleration

      Like "xacceleration", but its sign is ignored and it always
      causes the absolute value of "xvelocity" to decrease.

   ydeceleration

      Like "yacceleration", but its sign is ignored and it always
      causes the absolute value of "yvelocity" to decrease.

   image_index

      The animation frame currently being displayed, with "0" being
      the first one.

   image_origin_x

      The horizontal location of the origin relative to the left edge
      of the images.  If set to "None", the value recommended by the
      sprite is used.

   image_origin_y

      The vertical location of the origin relative to the top edge of
      the images.  If set to "None", the value recommended by the
      sprite is used.

   image_fps

      The animation rate in frames per second.  Can be negative, in
      which case animation will be reversed.  If set to "None", the
      value recommended by the sprite is used.

   image_speed

      The animation rate as a factor of "sge.game.fps".  Can be
      negative, in which case animation will be reversed.  If set to
      "None", the value recommended by the sprite is used.

   image_xscale

      The horizontal scale factor for the sprite.

   image_yscale

      The vertical scale factor for the sprite.

   image_rotation

      The rotation of the sprite in degrees, with rotation in a
      positive direction being counter-clockwise.

      If "regulate_origin" is "True", the image is rotated about the
      origin.  Otherwise, the image is rotated about its center.

   image_alpha

      The alpha value applied to the entire image, where "255" is the
      original image, "128" is half the opacity of the original image,
      "0" is fully transparent, etc.

   image_blend

      A "sge.Color" object representing the color to blend with the
      sprite.  Set to "None" for no color blending.

   alarms

      A dictionary containing the alarms of the object.  Each value
      decreases by 1 each frame (adjusted for delta timing if it is
      enabled).  When a value is at or below 0,
      "sge.Object.event_alarm()" is executed with "alarm_id" set to
      the respective key, and the item is deleted from this
      dictionary.

   mask

      The current mask used for non-rectangular collision detection.
      See the documentation for "sge.collision.masks_collide()" for
      more information.  (Read-only)

   xstart

      The initial value of "x" when the object was created. (Read-
      only)

   ystart

      The initial value of "y" when the object was created. (Read-
      only)

   xprevious

      The value of "x" at the end of the previous frame. (Read-only)

   yprevious

      The value of "y" at the end of the previous frame. (Read-only)

   mask_x

      The horizontal location of the mask in the room.  (Read-only)

   mask_y

      The vertical location of the mask in the room.  (Read-only)

   rd

      Reserved dictionary for internal use by the SGE.  (Read-only)


sge.Object Methods
------------------

Object.__init__(x, y, z=0, sprite=None, visible=True, active=True, checks_collisions=True, tangible=True, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None, regulate_origin=False, collision_ellipse=False, collision_precise=False, xvelocity=0, yvelocity=0, xacceleration=0, yacceleration=0, xdeceleration=0, ydeceleration=0, image_index=0, image_origin_x=None, image_origin_y=None, image_fps=None, image_xscale=1, image_yscale=1, image_rotation=0, image_alpha=255, image_blend=None)

   Arugments set the respective initial attributes of the object. See
   the documentation for "sge.Object" for more information.

Object.move_x(move)

   Move the object horizontally.  This method can be overridden to
   conveniently define a particular way movement should be handled.
   Currently, it is used in the default implementation of
   "event_update_position()".

   Arguments:

   * "move" -- The amount to add to "x".

   The default behavior of this method is the following code:

      self.x += move

Object.move_y(move)

   Move the object vertically.  This method can be overridden to
   conveniently define a particular way movement should be handled.
   Currently, it is used in the default implementation of
   "event_update_position()".

   Arguments:

   * "move" -- The amount to add to "y".

   The default behavior of this method is the following code:

      self.y += move

Object.collision(other=None, x=None, y=None)

   Return a list of objects colliding with this object.

   Arguments:

   * "other" -- What to check for collisions with.  Can be one of
     the following:

     * A "sge.Object" object.

     * A list of "sge.Object" objects.

     * A class derived from "sge.Object".

     * "None": Check for collisions with all objects.

   * "x" -- The horizontal position to pretend this object is at for
     the purpose of the collision detection.  If set to "None", "x"
     will be used.

   * "y" -- The vertical position to pretend this object is at for
     the purpose of the collision detection.  If set to "None", "y"
     will be used.

Object.destroy()

   Remove the object from the current room.  "foo.destroy()" is
   identical to "sge.game.current_room.remove(foo)".

classmethod Object.create(*args, **kwargs)

   Create an object of this class and add it to the current room.

   "args" and "kwargs" are passed to the constructor method of "cls"
   as arguments.  Calling "obj = cls.create(*args, **kwargs)" is the
   same as:

      obj = cls(*args, **kwargs)
      sge.game.current_room.add(obj)


sge.Object Event Methods
------------------------

Object.event_create()

   Called in the following cases:

   * Right after the object is added to the current room.

   * Right after a room starts for the first time after the object
     was added to it, if and only if the object was added to the room
     while it was not the current room.  In this case, this event is
     called for each appropriate object after the respective room
     start event or room resume event, in the same order that the
     objects were added to the room.

Object.event_destroy()

   Called right after the object is removed from the current room.

   Note: If the object is removed from a room while it is not the
     current room, this method will not be called.

Object.event_step(time_passed, delta_mult)

   Called each frame after automatic updates to objects (such as the
   effects of the speed variables), but before collision events.

   See the documentation for "sge.Game.event_step()" for more
   information.

Object.event_alarm(alarm_id)

   See the documentation for "sge.Object.alarms" for more information.

Object.event_animation_end()

   Called when an animation cycle ends.

Object.event_key_press(key, char)

   See the documentation for "sge.input.KeyPress" for more
   information.

Object.event_key_release(key)

   See the documentation for "sge.input.KeyRelease" for more
   information.

Object.event_mouse_move(x, y)

   See the documentation for "sge.input.MouseMove" for more
   information.

Object.event_mouse_button_press(button)

   See the documentation for "sge.input.MouseButtonPress" for more
   information.

Object.event_mouse_button_release(button)

   See the documentation for "sge.input.MouseButtonRelease" for more
   information.

Object.event_joystick_axis_move(js_name, js_id, axis, value)

   See the documentation for "sge.input.JoystickAxisMove" for more
   information.

Object.event_joystick_hat_move(js_name, js_id, hat, x, y)

   See the documentation for "sge.input.JoystickHatMove" for more
   information.

Object.event_joystick_trackball_move(js_name, js_id, ball, x, y)

   See the documentation for "sge.input.JoystickTrackballMove" for
   more information.

Object.event_joystick_button_press(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonPress" for more
   information.

Object.event_joystick_button_release(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonRelease" for
   more information.

Object.event_update_position(delta_mult)

   Called when it's time to update the position of the object. This
   method handles this functionality, so defining this will override
   the default behavior and allow you to handle the speed variables in
   a special way.

   The default behavior of this method is the following code:

      if delta_mult:
          vi = self.xvelocity
          vf = vi + self.xacceleration * delta_mult
          dc = abs(self.xdeceleration) * delta_mult
          if abs(vf) > dc:
              vf -= math.copysign(dc, vf)
          else:
              vf = 0
          self.xvelocity = vf
          self.move_x(((vi + vf) / 2) * delta_mult)

          vi = self.yvelocity
          vf = vi + self.yacceleration * delta_mult
          dc = abs(self.ydeceleration) * delta_mult
          if abs(vf) > dc:
              vf -= math.copysign(dc, vf)
          else:
              vf = 0
          self.yvelocity = vf
          self.move_y(((vi + vf) / 2) * delta_mult)

   See the documentation for "sge.Game.event_step()" for more
   information.

Object.event_collision(other, xdirection, ydirection)

   Called when this object collides with another object.

   Arguments:

   * "other" -- The other object which was collided with.

   * "xdirection" -- The horizontal direction of the collision from
     the perspective of this object.  Can be "-1" (left), "1" (right),
     or "0" (no horizontal direction).

   * "ydirection" -- The vertical direction of the collision from
     the perspective of this object.  Can be "-1" (up), "1" (down), or
     "0" (no vertical direction).

   Directionless "collisions" (ones with both an xdirection and
   ydirection of "0") are possible.  These are typically collisions
   which were already occurring in the previous frame (continuous
   collisions).

Object.event_paused_step(time_passed, delta_mult)

   See the documentation for "sge.Game.event_step()" for more
   information.

Object.event_paused_key_press(key, char)

   See the documentation for "sge.input.KeyPress" for more
   information.

Object.event_paused_key_release(key)

   See the documentation for "sge.input.KeyRelease" for more
   information.

Object.event_paused_mouse_move(x, y)

   See the documentation for "sge.input.MouseMove" for more
   information.

Object.event_paused_mouse_button_press(button)

   See the documentation for "sge.input.MouseButtonPress" for more
   information.

Object.event_paused_mouse_button_release(button)

   See the documentation for "sge.input.MouseButtonRelease" for more
   information.

Object.event_paused_joystick_axis_move(js_name, js_id, axis, value)

   See the documentation for "sge.input.JoystickAxisMove" for more
   information.

Object.event_paused_joystick_hat_move(js_name, js_id, hat, x, y)

   See the documentation for "sge.input.JoystickHatMove" for more
   information.

Object.event_paused_joystick_trackball_move(js_name, js_id, ball, x, y)

   See the documentation for "sge.input.JoystickTrackballMove" for
   more information.

Object.event_paused_joystick_button_press(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonPress" for more
   information.

Object.event_paused_joystick_button_release(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonRelease" for
   more information.


sge.Room
========

class class sge.Room(objects=(), width=None, height=None, views=None, background=None, background_x=0, background_y=0, object_area_width=None, object_area_height=None)

   This class stores the settings and objects found in a room.  Rooms
   are used to create separate parts of the game, such as levels and
   menu screens.

   width

      The width of the room in pixels.  If set to "None",
      "sge.game.width" is used.

   height

      The height of the room in pixels.  If set to "None",
      "sge.game.height" is used.

   views

      A list containing all "sge.View" objects in the room.

   background

      The "sge.Background" object used.

   background_x

      The horizontal position of the background in the room.

   background_y

      The vertical position of the background in the room.

   object_area_width

      The width of this room's object areas in pixels.  If set to
      "None", "sge.game.width" is used.  For optimum performance, this
      should generally be about the average width of objects in the
      room which check for collisions.

   object_area_height

      The height of this room's object areas in pixels.  If set to
      "None", "sge.game.height" is used.  For optimum performance,
      this should generally be about the average height of objects in
      the room which check for collisions.

   alarms

      A dictionary containing the alarms of the room.  Each value
      decreases by 1 each frame (adjusted for delta timing if it is
      enabled).  When a value is at or below 0,
      "sge.Room.event_alarm()" is executed with "alarm_id" set to the
      respective key, and the item is deleted from this dictionary.

   objects

      A list containing all "sge.Object" objects in the room.  (Read-
      only)

   object_areas

      A 2-dimensional list of object areas, indexed in the following
      way:

         object_areas[x][y]

      Where "x" is the horizontal location of the left edge of the
      area in the room divided by "object_area_width", and "y" is the
      vertical location of the top edge of the area in the room
      divided by "object_area_height".

      For example, if "object_area_width" is "32" and
      "object_area_height" is "48", then "object_areas[2][4]"
      indicates the object area with an x location of 64 and a y
      location of 192.

      Each object area is a set containing "sge.Object" objects whose
      sprites or bounding boxes reside within the object area.

      Object areas are only created within the room, i.e. the
      horizontal location of an object area will always be less than
      "width", and the vertical location of an object area will always
      be less than "height".  Depending on the size of collision areas
      and the size of the room, however, the last row and/or the last
      column of collision areas may partially reside outside of the
      room.

      Note: It is generally easier to use
        "sge.Room.get_objects_at()" than to access this list directly.

   object_area_void

      A set containing "sge.Object" objects whose sprites or bounding
      boxes reside within any area not covered by the room's object
      area.

      Note: Depending on the size of object areas and the size of
        the room, the "void" area may not include the entirety of the
        outside of the room.  There may be some space to the right of
        and/or below the room which is covered by collision areas.

   rd

      Reserved dictionary for internal use by the SGE.  (Read-only)


sge.Room Methods
----------------

Room.__init__(objects=(), width=None, height=None, views=None, background=None, background_x=0, background_y=0, object_area_width=None, object_area_height=None)

   Arguments:

   * "views" -- A list containing all "sge.View" objects in the
     room. If set to "None", a new view will be created with "x=0",
     "y=0", and all other arguments unspecified, which will become the
     first view of the room.

   * "background" -- The "sge.Background" object used.  If set to
     "None", a new background will be created with no layers and the
     color set to black.

   All other arguments set the respective initial attributes of the
   room.  See the documentation for "sge.Room" for more information.

Room.add(obj)

   Add an object to the room.

   Arguments:

   * "obj" -- The "sge.Object" object to add.

Room.remove(obj)

   Remove an object from the room.

   Arguments:

   * "obj" -- The "sge.Object" object to remove.

Room.start(transition=None, transition_time=1500, transition_arg=None)

   Start the room.

   Arguments:

   * "transition" -- The type of transition to use.  Should be one
     of the following:

     * "None" (no transition)

     * ""fade"" (fade to black)

     * ""dissolve""

     * ""pixelate""

     * ""wipe_left"" (wipe right to left)

     * ""wipe_right"" (wipe left to right)

     * ""wipe_up"" (wipe bottom to top)

     * ""wipe_down"" (wipe top to bottom)

     * ""wipe_upleft"" (wipe bottom-right to top-left)

     * ""wipe_upright"" (wipe bottom-left to top-right)

     * ""wipe_downleft"" (wipe top-right to bottom-left)

     * ""wipe_downright"" (wipe top-left to bottom-right)

     * ""wipe_matrix""

     * ""iris_in""

     * ""iris_out""

     If an unsupported value is given, default to "None".

   * "transition_time" -- The time the transition should take in
     milliseconds.  Has no effect if "transition" is "None".

   * "transition_arg" -- An arbitrary argument that can be used by
     the following transitions:

     * ""wipe_matrix"" -- The size of each square in the matrix
       transition as a tuple in the form "(w, h)", where "w" is the
       width and "h" is the height.  Default is "(4, 4)".

     * ""iris_in"" and ""iris_out"" -- The position of the center of
       the iris as a tuple in the form "(x, y)", where "x" is the
       horizontal location relative to the window and "y" is the
       vertical location relative to the window. Default is the center
       of the window.

Room.get_objects_at(x, y, width, height)

   Return a set of objects near a particular area.

   Arguments:

   * "x" -- The horizontal location relative to the room of the left
     edge of the area.

   * "y" -- The vertical location relative to the room of the top
     edge of the area.

   * "width" -- The width of the area in pixels.

   * "height" -- The height of the area in pixels.

   Note: This function does not ensure that objects returned are
     actually *within* the given area.  It simply combines all object
     areas that need to be checked into a single set.  To ensure that
     an object is actually within the area, you must check the object
     manually, or use "sge.collision.rectangle()" instead.

Room.project_dot(x, y, z, color)

   Project a single-pixel dot onto the room.

   Arguments:

   * "x" -- The horizontal location relative to the room to project
     the dot.

   * "y" -- The vertical location relative to the room to project
     the dot.

   * "z" -- The Z-axis position of the projection in the room.

   See the documentation for "sge.Sprite.draw_dot()" for more
   information.

Room.project_line(x1, y1, x2, y2, z, color, thickness=1, anti_alias=False)

   Project a line segment onto the room.

   Arguments:

   * "x1" -- The horizontal location relative to the room of the
     first endpoint of the projected line segment.

   * "y1" -- The vertical location relative to the room of the first
     endpoint of the projected line segment.

   * "x2" -- The horizontal location relative to the room of the
     second endpoint of the projected line segment.

   * "y2" -- The vertical location relative to the room of the
     second endpoint of the projected line segment.

   * "z" -- The Z-axis position of the projection in the room.

   See the documentation for "sge.Sprite.draw_line()" for more
   information.

Room.project_rectangle(x, y, z, width, height, fill=None, outline=None, outline_thickness=1)

   Project a rectangle onto the room.

   Arguments:

   * "x" -- The horizontal location relative to the room to project
     the rectangle.

   * "y" -- The vertical location relative to the room to project
     the rectangle.

   * "z" -- The Z-axis position of the projection in the room.

   See the documentation for "sge.Sprite.draw_rectangle()" for more
   information.

Room.project_ellipse(x, y, z, width, height, fill=None, outline=None, outline_thickness=1, anti_alias=False)

   Project an ellipse onto the room.

   Arguments:

   * "x" -- The horizontal location relative to the room to position
     the imaginary rectangle containing the ellipse.

   * "y" -- The vertical location relative to the room to position
     the imaginary rectangle containing the ellipse.

   * "z" -- The Z-axis position of the projection in the room.

   * "width" -- The width of the ellipse.

   * "height" -- The height of the ellipse.

   * "outline_thickness" -- The thickness of the outline of the
     ellipse.

   * "anti_alias" -- Whether or not anti-aliasing should be used.

   See the documentation for "sge.Sprite.draw_ellipse()" for more
   information.

Room.project_circle(x, y, z, radius, fill=None, outline=None, outline_thickness=1, anti_alias=False)

   Project a circle onto the room.

   Arguments:

   * "x" -- The horizontal location relative to the room to position
     the center of the circle.

   * "y" -- The vertical location relative to the room to position
     the center of the circle.

   * "z" -- The Z-axis position of the projection in the room.

   See the documentation for "sge.Sprite.draw_circle()" for more
   information.

Room.project_polygon(points, z, fill=None, outline=None, outline_thickness=1, anti_alias=False)

   Draw a polygon on the sprite.

   Arguments:

   * "points" -- A list of points relative to the room to position
     each of the polygon's angles.  Each point should be a tuple in
     the form "(x, y)", where x is the horizontal location and y is
     the vertical location.

   * "z" -- The Z-axis position of the projection in the room.

   See the documentation for "sge.Sprite.draw_polygon()" for more
   information.

Room.project_sprite(sprite, image, x, y, z, blend_mode=None)

   Project a sprite onto the room.

   Arguments:

   * "x" -- The horizontal location relative to the room to project
     "sprite".

   * "y" -- The vertical location relative to the room to project
     "sprite".

   * "z" -- The Z-axis position of the projection in the room.

   See the documentation for "sge.Sprite.draw_sprite()" for more
   information.

Room.project_text(font, text, x, y, z, width=None, height=None, color=sge.Color("black"), halign='left', valign='top', anti_alias=True)

   Project text onto the room.

   Arguments:

   * "x" -- The horizontal location relative to the room to project
     the text.

   * "y" -- The vertical location relative to the room to project
     the text.

   * "z" -- The Z-axis position of the projection in the room.

   See the documentation for "sge.Sprite.draw_text()" for more
   information.


sge.Room Event Methods
----------------------

Room.event_room_start()

   Called when the room is started for the first time.  It is always
   called after any "sge.Game.event_game_start()" and before any
   "sge.Object.event_create" occurring at the same time.

Room.event_room_resume()

   Called when the room is started after it has already previously
   been started.  It is always called before any
   "sge.Object.event_create()" occurring at the same time.

Room.event_room_end()

   Called when another room is started or the game ends while this
   room is the current room.  It is always called before any
   "sge.Game.event_game_end()" occurring at the same time.

Room.event_step(time_passed, delta_mult)

   See the documentation for "sge.Game.event_step()" for more
   information.

Room.event_alarm(alarm_id)

   See the documentation for "sge.Room.alarms" for more information.

Room.event_key_press(key, char)

   See the documentation for "sge.input.KeyPress" for more
   information.

Room.event_key_release(key)

   See the documentation for "sge.input.KeyRelease" for more
   information.

Room.event_mouse_move(x, y)

   See the documentation for "sge.input.MouseMove" for more
   information.

Room.event_mouse_button_press(button)

   Mouse button press event.

   See the documentation for "sge.input.MouseButtonPress" for more
   information.

Room.event_mouse_button_release(button)

   See the documentation for "sge.input.MouseButtonRelease" for more
   information.

Room.event_joystick_axis_move(js_name, js_id, axis, value)

   See the documentation for "sge.input.JoystickAxisMove" for more
   information.

Room.event_joystick_hat_move(js_name, js_id, hat, x, y)

   See the documentation for "sge.input.JoystickHatMove" for more
   information.

Room.event_joystick_trackball_move(js_name, js_id, ball, x, y)

   See the documentation for "sge.input.JoystickTrackballMove" for
   more information.

Room.event_joystick_button_press(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonPress" for more
   information.

Room.event_joystick_button_release(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonRelease" for
   more information.

Room.event_gain_keyboard_focus()

   See the documentation for "sge.input.KeyboardFocusGain" for more
   information.

Room.event_lose_keyboard_focus()

   See the documentation for "sge.input.KeyboardFocusLose" for more
   information.

Room.event_gain_mouse_focus()

   See the documentation for "sge.input.MouseFocusGain" for more
   information.

Room.event_lose_mouse_focus()

   See the documentation for "sge.input.MouseFocusLose" for more
   information.

Room.event_close()

   This is always called before any "sge.Game.event_close()" occurring
   at the same time.

   See the documentation for "sge.input.QuitRequest" for more
   information.

Room.event_paused_step(time_passed, delta_mult)

   See the documentation for "sge.Game.event_step()" for more
   information.

Room.event_paused_key_press(key, char)

   See the documentation for "sge.input.KeyPress" for more
   information.

Room.event_paused_key_release(key)

   See the documentation for "sge.input.KeyRelease" for more
   information.

Room.event_paused_mouse_move(x, y)

   See the documentation for "sge.input.MouseMove" for more
   information.

Room.event_paused_mouse_button_press(button)

   See the documentation for "sge.input.MouseButtonPress" for more
   information.

Room.event_paused_mouse_button_release(button)

   See the documentation for "sge.input.MouseButtonRelease" for more
   information.

Room.event_paused_joystick_axis_move(js_name, js_id, axis, value)

   See the documentation for "sge.input.JoystickAxisMove" for more
   information.

Room.event_paused_joystick_hat_move(js_name, js_id, hat, x, y)

   See the documentation for "sge.input.JoystickHatMove" for more
   information.

Room.event_paused_joystick_trackball_move(js_name, js_id, ball, x, y)

   See the documentation for "sge.input.JoystickTrackballMove" for
   more information.

Room.event_paused_joystick_button_press(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonPress" for more
   information.

Room.event_paused_joystick_button_release(js_name, js_id, button)

   See the documentation for "sge.input.JoystickButtonRelease" for
   more information.

Room.event_paused_gain_keyboard_focus()

   See the documentation for "sge.input.KeyboardFocusGain" for more
   information.

Room.event_paused_lose_keyboard_focus()

   See the documentation for "sge.input.KeyboardFocusLose" for more
   information.

Room.event_paused_gain_mouse_focus()

   See the documentation for "sge.input.MouseFocusGain" for more
   information.

Room.event_paused_lose_mouse_focus()

   See the documentation for "sge.input.MouseFocusLose" for more
   information.

Room.event_paused_close()

   See the documentation for "sge.Room.event_close()" for more
   information.


sge.View
========

class class sge.View(x, y, xport=0, yport=0, width=None, height=None, wport=None, hport=None)

   This class controls what the player sees in a room at any given
   time.  Multiple views can exist in a room, and this can be used to
   create a split-screen effect.

   x

      The horizontal position of the view in the room.  When set, if
      it brings the view outside of the room it is in, it will be re-
      adjusted so that the view is completely inside the room.

   y

      The vertical position of the view in the room.  When set, if it
      brings the view outside of the room it is in, it will be re-
      adjusted so that the view is completely inside the room.

   xport

      The horizontal position of the view port on the window.

   yport

      The vertical position of the view port on the window.

   width

      The width of the view.  When set, if it results in the view
      being outside of the room it is in, "x" will be adjusted so that
      the view is completely inside the room.

   height

      The height of the view.  When set, if it results in the view
      being outside the room it is in, "y" will be adjusted so that
      the view is completely inside the room.

   wport

      The width of the view port.  Set to "None" to make it the same
      as "width".  If this value differs from "width", the image will
      be horizontally scaled so that it fills the port.

   hport

      The height of the view port.  Set to "None" to make it the same
      as "height".  If this value differs from "height", the image
      will be vertically scaled so that it fills the port.

   rd

      Reserved dictionary for internal use by the SGE.  (Read-only)


sge.View Methods
----------------

View.__init__(x, y, xport=0, yport=0, width=None, height=None, wport=None, hport=None)

   Arguments:

   * "width" -- The width of the view.  If set to "None", it will
     become "sge.game.width - xport".

   * "height" -- The height of the view.  If set to "None", it will
     become "sge.game.height - yport".

   All other arugments set the respective initial attributes of the
   view.  See the documentation for "sge.View" for more information.
