SGE Fundamentals

The Stellar Game Engine (abbreviated “SGE”, pronounced as “Sage”) is a free 2-D game engine. The purpose of the SGE is to make game development easier, which allows more rapid development by experienced game developers and also helps less experienced game developers learn how to develop games.

Official implementations of the SGE are free/libre software, and the SGE documentation is free/libre as well.

Even if it isn’t required, you are encouraged to release your games’ code under a free/libre software license, such as the GNU General Public License, the Expat License, or the Apache License. Doing so is easy, does not negatively affect you, and is highly appreciated as a contribution to a free society.

SGE Concepts

Naming Conventions

There are many cases where you will want to derive a class from a SGE class. Since there can be multiple implementations of the SGE, it can be easy when doing so to overwrite a special variable used by some implementations internally, which can be disastrous. To avoid such occasions, implementations are expected to never introduce any attribute names which are not explicitly mentioned in the documentation for a class unless the new attribute names are preceded by an underscore, as in the hypothetical attribute name _foo. This naming convention will protect users of the SGE from unexpected errors provided that they do not use such names themselves.

A suggested convention for users of the SGE to use for “private” attributes in place of the usual leading underscore is to precede these attributes with v_ or p_.

Events

The SGE uses an event-based system. When an event occurs, a certain event method (with a name that begins with event_) is called. To define actions triggered by events, simply override the appropriate event method.

At a lower level, it is possible to read “input events” from sge.game.input_events and handle them manually. See the documentation for sge.input for more information. This is not recommended, however, unless you are running your own loop for some reason (in which case it is necessary to do this in order to get input from the user).

Colors

The SGE accepts a few different formats for defining colors.

The sixteen basic HTML colors, provided as strings, are accepted. These are case-insensitive, so "red" is interpreted the same as "Red" or "rEd". The colors are:

  • "white"
  • "silver"
  • "gray"
  • "black"
  • "red"
  • "maroon"
  • "yellow"
  • "olive"
  • "lime"
  • "green"
  • "aqua"
  • "teal"
  • "blue"
  • "navy"
  • "fuchsia"
  • "purple"

Tuples containing three or four integers are accepted. Each index represents a component of a color: first red, then green, then blue, with the values being integers from 0 to 255. For example, (255, 128, 0) indicates a color with full red intensity, 50% green intensity, and no blue intensity, which is a shade of orange. Note that the components are colors of light, not colors of pigment.

The fourth value of the tuple, if specified, indicates the alpha transparency of the color, with the possible values again being integers from 0 to 255. 255 is fully opaque, 0 is fully transparent, and any value in between indicates the amount of opacity; for example, 128 is 50% transparent. If the fourth value is unspecified, it is assumed that the color is fully opaque.

RGBA tuples are the only way to specify alpha transparency of colors in SGE. All other methods for indicating color assume full opacity.

HTML hex strings and integers are accepted. HTML hex strings are in the format "#RRGGBB", where RR, GG, and BB are replaced with the red, green, and blue components of the color, respectively, in hexadecimal form. FF (equivalent to 255 in decimal form) is full intensity of the respective color, and 00 (equivalent to 0 in decimal form) is no intensity of the respective color. For example, "#FF8000" is the same as (255, 128, 0), or orange.

Integers, treated as hexadecimals, are accepted in the same form as HTML hex strings, but integral. For example, 0xFF8000 is the same as "#FF8000".

Position

In all cases of positioning for the SGE, it is based on a two-dimensional graph with each unit being a pixel. This graph is not quite like regular graphs. The horizontal direction, normally called x, is the same as the x-axis on a regular graph; 0 is the origin, positive numbers are to the right of the origin, and negative numbers are to the left of the origin. However, in the vertical direction, normally called y, 0 is the origin, positive numbers are below the origin, and negative numbers are above the origin. While slightly jarring if you are used to normal graphs, this is in fact common in 2-D game development and is so how pixels in most image formats are indexed.

Except where otherwise specified, the origin is always located at the top-leftmost position of an object.

In addition to integers, position variables are allowed by the SGE to be floating-point numbers.

Z-Axis

The SGE uses a Z-axis to determine where objects are placed in the third dimension. Objects with a higher Z value are considered to be closer to the viewer and thus will be placed over objects which have a lower Z value. Note that the Z-axis does not allow 3-D gameplay or effects; it is only used to tell the SGE what to do with objects that overlap. For example, if an object called spam has a Z value of 5 while an object called eggs has a Z value of 2, spam will obscure part or all of eggs when the two objects overlap.

If two objects with the same Z-axis value overlap, the SGE arbitrarily chooses which one is considered to be closer to the viewer. The SGE is allowed to change this decision, but only while the objects in question are not overlapping, since changing the decision while the two objects are overlapping would cause an undesirable flicker effect.

The Game Loop

There can occasionally be times where you want to run your own loop, independent of the SGE’s main loop. This is not recommended in general, but if you must (to freeze the game, for example), you should know the general game loop structure:

while True:
    # Input events
    sge.game.pump_input()
    while sge.game.input_events:
        event = sge.game.input_events.pop(0)

        # Handle event

    # Regulate speed
    time_passed = sge.game.regulate_speed()

    # Logic (e.g. collision detection and step events)

    # Refresh
    sge.game.refresh()

sge.Game.pump_input() should be called every frame regardless of whether or not user input is needed. Failing to call it will cause the queue to build up, but more importantly, the OS may decide that the program has locked up if it doesn’t get a response for a long time.

sge.Game.regulate_speed() limits the frame rate of the game and tells you how much time has passed since the last frame. It is not technically necessary, but using it is highly recommended; otherwise, the CPU will be working harder than it needs to and if things are moving, their speed will be irregular.

sge.Game.refresh() is necessary for any changes to the screen to be seen by the user. This includes new objects, removed objects, new projections, discontinued projections, etc.

Global Variables and Constants

sge.IMPLEMENTATION

A string indicating the name of the SGE implementation.

sge.ALIGN_LEFT

Flag indicating horizontal alignment to the left.

sge.ALIGN_CENTER

Flag indicating horizontal alignment to the center.

sge.ALIGN_RIGHT

Flag indicating horizontal alignment to the right.

sge.ALIGN_TOP

Flag indicating vertical alignment to the top

sge.ALIGN_MIDDLE

Flag indicating vertical alignment to the middle.

sge.ALIGN_BOTTOM

Flag indicating vertical alignment to the bottom.

sge.BLEND_NORMAL

Flag indicating normal blending.

sge.BLEND_RGBA_ADD

Flag indicating RGBA Addition blending: the red, green, blue, and alpha color values of the source are added to the respective color values of the destination, to a maximum of 255.

sge.BLEND_RGBA_SUBTRACT

Flag indicating RGBA Subtract blending: the red, green, blue, and alpha color values of the source are subtracted from the respective color values of the destination, to a minimum of 0.

sge.BLEND_RGBA_MULTIPLY

Flag indicating RGBA Multiply blending: the red, green, blue, and alpha color values of the source and destination are converted to values between 0 and 1 (divided by 255), the resulting destination color values are multiplied by the respective resulting source color values, and these results are converted back into values between 0 and 255 (multiplied by 255).

sge.BLEND_RGBA_SCREEN

Flag indicating RGBA Screen blending: the red, green, blue, and alpha color values of the source and destination are inverted (subtracted from 255) and converted to values between 0 and 1 (divided by 255), the resulting destination color values are multiplied by the respective resulting source color values, and these results are converted back into values between 0 and 255 (multiplied by 255) and inverted again (subtracted from 255).

sge.BLEND_RGBA_MINIMUM

Flag indicating RGBA Minimum (Darken Only) blending: the smallest respective red, green, blue, and alpha color values out of the source and destination are used.

sge.BLEND_RGBA_MAXIMUM

Flag indicating RGBA Maximum (Lighten Only) blending: the largest respective red, green, blue, and alpha color values out of the source and destination are used.

sge.BLEND_RGB_ADD

Flag indicating RGB Addition blending: the same thing as RGBA Addition blending (see sge.BLEND_RGBA_ADD) except the destination’s alpha values are not changed.

sge.BLEND_RGB_SUBTRACT

Flag indicating RGB Subtract blending: the same thing as RGBA Subtract blending (see sge.BLEND_RGBA_SUBTRACT) except the destination’s alpha values are not changed.

sge.BLEND_RGB_MULTIPLY

Flag indicating RGB Multiply blending: the same thing as RGBA Multiply blending (see sge.BLEND_RGBA_MULTIPLY) except the destination’s alpha values are not changed.

sge.BLEND_RGB_SCREEN

Flag indicating RGB Screen blending: the same thing as RGBA Screen blending (see sge.BLEND_RGBA_SCREEN) except the destination’s alpha values are not changed.

sge.BLEND_RGB_MINIMUM

Flag indicating RGB Minimum (Darken Only) blending: the same thing as RGBA Minimum blending (see sge.BLEND_RGBA_MINIMUM) except the destination’s alpha values are not changed.

sge.BLEND_RGB_MAXIMUM

Flag indicating RGB Maximum (Lighten Only) blending: the same thing as RGBA Maximum blending (see sge.BLEND_RGBA_MAXIMUM) except the destination’s alpha values are not changed.

sge.game

Stores the current sge.Game object. If there is no sge.Game object currently, this variable is set to None.

sge.image_directories

A list of directories where images can be found. Default is ./data/images, ./data/sprites, or ./data/backgrounds, where . is the program directory.

sge.font_directories

A list of directories where font files can be found. Default is ./data/fonts, where . is the program directory.

sge.sound_directories

A list of directories where sounds can be found. Default is ./data/sounds, where . is the program directory.

sge.music_directories

A list of directories where music files can be found. Default is ./data/music, where . is the program directory.

Information specific to the Pygame SGE

License

The Pygame SGE is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The Pygame SGE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with the Pygame SGE. If not, see <http://www.gnu.org/licenses/>.

Dependencies

Formats Support

sge.Sprite supports the following image formats:

  • PNG
  • JPEG
  • Non-animated GIF
  • BMP
  • PCX
  • Uncompressed Truevision TGA
  • TIFF
  • ILBM
  • Netpbm
  • X Pixmap

sge.Sound supports the following audio formats:

  • Uncompressed WAV
  • Ogg Vorbis

sge.Music supports the following audio formats:

  • Ogg Vorbis
  • MP3 (support limited; use not recommended)
  • MOD
  • XM
  • MIDI

For starting position in MOD files, the pattern order number is used instead of the number of milliseconds.

If Pygame is built without full image support, sge.Sprite will only be able to load uncompressed BMP images.

The pygame.mixer module, which is used for all audio playback, is optional and depends on SDL_mixer; if pygame.mixer is unavailable, sounds and music will not play.

On some systems, sge.Music attempting to load an unsupported format can crash the game. Since MP3 support is limited, it is best to avoid using it; consider using Ogg Vorbis instead.

Missing Features

sge.Sprite.draw_line(), sge.Room.project_line(), and sge.Game.project_line() support anti-aliasing for lines with a thickness of 1 only. sge.Sprite.draw_text(), sge.Room.project_text(), and sge.Game.project_text() support anti-aliasing in all cases. No other drawing or projecting methods support anti-aliasing.

sge.BLEND_RGBA_SCREEN and sge.BLEND_RGB_SCREEN are unsupported. If one of these blend modes is attempted, normal blending will be used instead.

Speed Improvements

The Pygame SGE supports hardware rendering, which can improve performance in some cases. It is not enabled by default. To enable it, set sge.hardware_rendering to True. The benefit of hardware acceleration is usually negligible, which is why it is disabled by default.