Classes

sge.Game

class sge.Game(width=640, height=480, fullscreen=False, scale=None, scale_proportional=True, scale_smooth=False, fps=60, delta=False, delta_min=15, 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.

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

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.

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

Game.project_line(x1, y1, x2, y2, color, 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.

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

Game.project_rectangle(x, y, width, height, 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.

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

Game.project_ellipse(x, y, width, height, 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.
  • 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.

Game.project_circle(x, y, radius, 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.

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

Game.project_polygon(points, 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.

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

Game.project_sprite(sprite, image, x, y, 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.

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

Game.project_text(font, text, x, y, 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.

See the documentation for sge.Sprite.draw_text() 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)

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

Game.event_mouse_collision_left(other)

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

Game.event_mouse_collision_right(other)

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

Game.event_mouse_collision_top(other)

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

Game.event_mouse_collision_bottom(other)

Proxy for sge.game.mouse.event_collision_bottom(). See the documentation for sge.Object.event_collision_bottom() 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 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.

speed

The suggested rate to animate the image at as a factor of sge.game.fps.

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 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 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 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 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 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 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 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, 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 and events which have names starting with event_inactive_ will be executed instead of the corresponding normal events.

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.

Note

Making an object inactive will not likely have a significant effect on performance. For performance enhancement, it is far more effective to exclude objects from collision detection. Object deactivation is meant to be used to easily maintain control over objects that are currently being excluded from collision detection (e.g. to prevent a gravity effect that would otherwise occur, or to prevent the object from moving through walls).

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.

yvelocity

The velocity of the object toward the bottom.

speed

The total (directional) speed of the object.

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.

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. If set to None, the value recommended by the sprite is used.

image_speed

The animation rate as a factor of sge.game.fps. 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, 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.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:
  • 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 after the respective room start event.
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:

self.x += self.xvelocity * delta_mult
self.y += self.yvelocity * delta_mult

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

Object.event_collision(other)

Called when another object collides with this object and none of the directional collision events are appropriate. In particular, this is called if the collision was already happening in the previous frame. This is also the event method called by the directional collision event methods by default.

Arguments:

  • other – The other object which was collided with.
Object.event_collision_left(other)

Called when another object collides with this object’s left side.

Arguments:

  • other – The other object which was collided with.

By default, this method simply calls sge.Object.event_collision().

Object.event_collision_right(other)

Called when another object collides with this object’s right side.

Arguments:

  • other – The other object which was collided with.

By default, this method simply calls sge.Object.event_collision().

Object.event_collision_top(other)

Called when another object collides with this object’s top side.

Arguments:

  • other – The other object which was collided with.

By default, this method simply calls sge.Object.event_collision().

Object.event_collision_bottom(other)

Called when another object collides with this object’s bottom side.

Arguments:

  • other – The other object which was collided with.

By default, this method simply calls sge.Object.event_collision().

Object.event_inactive_step(time_passed, delta_mult)

See the documentation for sge.Object.event_step() for more information. The object is considered to be inactive when active is False.

Object.event_inactive_key_press(key, char)

The object is considered to be inactive when active is False.

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

Object.event_inactive_key_release(key)

The object is considered to be inactive when active is False.

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

Object.event_inactive_mouse_move(x, y)

The object is considered to be inactive when active is False.

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

Object.event_inactive_mouse_button_press(button)

The object is considered to be inactive when active is False.

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

Object.event_inactive_mouse_button_release(button)

The object is considered to be inactive when active is False.

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

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

The object is considered to be inactive when active is False.

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

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

The object is considered to be inactive when active is False.

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

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

The object is considered to be inactive when active is False.

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

Object.event_inactive_joystick_button_press(js_name, js_id, button)

The object is considered to be inactive when active is False.

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

Object.event_inactive_joystick_button_release(js_name, js_id, button)

The object is considered to be inactive when active is False.

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

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 sge.Room(objects=(), width=None, height=None, views=None, background=None, background_x=0, background_y=0)

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.

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)

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)

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:

Room.remove(obj)

Remove an object from the room.

Arguments:

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

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.

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 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.