What is this?

ggez is a Rust library to create a Good Game Easily.

More specifically, ggez is a lightweight game framework for making 2D games with minimum friction. It aims to implement an API quite similar to (a Rustified version of) the Love2D game engine. This means it will contain basic and portable 2D drawing, sound, resource loading and event handling.

ggez is not meant to be everything to everyone, but rather a good base upon which to build. Thus it takes a fairly batteries-included approach without needing a million options and plugins for everything imaginable, but also does not dictate higher-level functionality such as physics engine or ECS. Instead the goal is to allow you to use whichever libraries you want to provide these functions, or build your own libraries atop ggez such as the ggez-goodies crate.

Features

• Filesystem abstraction that lets you load resources from folders or zip files
• Hardware-accelerated rendering of bitmaps
• Playing and loading sounds through SDL2_mixer
• TTF font rendering with rusttype, as well as bitmap fonts.
• Interface for handling keyboard and mouse events easily through callbacks
• Config file for defining engine and game settings
• Easy timing and FPS measurement functions.

Usage

ggez is built on the latest stable Rust compiler and distributed on crates.io. To include it in your project, just add the dependency line to your Cargo.toml file:

text ggez = "0.2.0"

However you also need to have the SDL2, SDL2mixer and SDL2image libraries installed on your system. The best way to do this is documented by the SDL2 crate.

ggez consists of three main parts: A Context object which contains all the state requierd to interface with the computer's hardware, a GameState trait that the user implements to register callbacks for events, and various sub-modules such as graphics and audio that provide the functionality to actually get stuff done.

Examples

See the examples/ directory in the source. hello_world is exactly what it says. imageview is a simple program that shows off a number of features such as sound and drawing. astroblasto is a small Asteroids-like game.

To run the examples, you have to copy or symlink the resources directory to a place the running game can find it. Cargo does not have an easy way of doing this itself at the moment, so the procedure is (on Linux):

text cargo build --example astroblasto cp -R resources target/debug/ cargo run --example astroblasto

Either way, if it can't find the resources it will give you an error along the lines of ResourceNotFound("'resources' directory not found! Should be in "/home/foo/src/ggez/target/debug/resources"). Just copy or symlink the resources/ directory to where the error says it's looking.

Implementation details

ggez is a fairly thin wrapper around SDL2 and a few other libraries, which does influence some of the API and impose some restrictions. For example, thread safety.

SDL2 is generally speaking NOT thread-safe. It uses lots of globals internally, and just isn't designed with thread safety in mind. This isn't generally a huge restriction in C code, but in Rust the practical result is that none of the types derived from SDL2 are Send or Sync, such as the ggez::graphics::Image type. It's inconvenient and we want to work around it eventually, but for now, them's the breaks.

Extant things to do

0.2.x

Enhancements that don't actually change the API or compatibility

• Crate-level docs (so you get an intro instead of just a list of modules on the root page)
• Document SDL's thread constraints! It's mentioned in Context struct docs but maybe should be in other places. The Game trait would be a good place to do it perhaps? Or just a mention in the docs for each resource type?
• Submit an update to the zip crate to make it possible to check whether a directory exists.

0.3.0

API-breaking or altering changes

• Get rid of the Option in the event callback function signatures... why does SDL2 even have that there anyway?
• Better timing for update and draw in the mainloop would be nice so you don't have to delay manually
• Replace try!() with ? everywhere (so we stop working on older versions of rustc)
• Make it always possible to load resources from raw data instead of files. (which might make testing easier)
• Clean up and consistentify GameError a bit, rename it to GgezError perhaps? I think there might be an unused case or two in there.
• Start integrating ncollide?
• Remove unused example assets

Future work

• Make subsystems modular, so we don't have to initialize sound if we don't need to and it's not a hard error if we can't use it. See https://www.idolagames.com/piston-sdl-window-with-sound/ perhaps.
• Possibly related, see if it's possible to make the GameState trait optional; provide tools with which to roll your own game loop.
• Interpolation for the mainloop timing stuff? Or at least be able to support the user doing it.
• Include vector math?
• Play with GFX more
• Play with audio more: the ears crate looks rather good, rust-portaudio might be an option???, perhaps alto. Love2D apparently directly wraps OpenAL. Or tomaka has a library, rodio. Or rsoundio?
• Need to add more tests, somehow

It would be nice to have a full OpenGL-y backend like Love2D does, with things like shaders, render targets, etc. gfx might be the best option there, maaaaaaybe. Right now the API is mostly limited to Love2D 0.7 or so. Using OpenAL (through the ears crate perhaps?) for sound would get us positional audio too.

Useful goodies

• ggez-goodies for things that are useful but not fundamental and generally don't depend on each other
• specs for entity-component system (alternatives: ecs or recs crates)
• cgmath or vecmath for math operations? nalgebra does great too.
• physics/collision??? ncollide and nphysics; there's ports/wrappers of box2d and chipmunk physics engines but they're young.

Credits

• http://opengameart.org/content/flappy-dragon-sprite-sheets
• http://opengameart.org/content/cozy-endless-game-background