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.
- 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.
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
ggez = "0.2.0"
However you also need to have the SDL2, SDL2_mixer and SDL2_image 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
provide the functionality to actually get stuff done.
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
To run the examples, you have to copy or symlink the
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):
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
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
Sync, such as the
type. It's inconvenient and we want to work around it eventually,
but for now, them's the breaks.
Extant things to do
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.
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
?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
- 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,
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.
- 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.