What is this?
ggez is a Rust library to create a Good Game Easily.
More specifically, ggez is a lightweight cross-platform game framework for making 2D games with minimum friction. It aims to implement an API based on (a Rustified version of) the LÖVE game framework. This means it contains basic and portable 2D drawing, sound, resource loading and event handling, but finer details and performance characteristics may be different than LÖVE.
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 additions and plugins for everything imaginable, but also does not dictate higher-level functionality such as physics engine or entity component system. Instead the goal is to allow you to use whichever libraries you want to provide these functions, or build your own libraries atop ggez.
- Filesystem abstraction that lets you load resources from folders or zip files
- Hardware-accelerated 2D rendering built on the
- Loading and playing .ogg, .wav and .flac files via the
- TTF font rendering with
- Interface for handling keyboard and mouse events easily through callbacks
- Config file for defining engine and game settings
- Easy timing and FPS measurement functions.
- Math library integration with
- Some more advanced graphics options: shaders, sprite batches and render targets
Non-Features (i.e. things to add from elsewhere if needed)
- Animation (check out keyframe; it works pretty well with ggez (source))
- Assets manager
- Fully supported: Windows, Linux
- Not officially supported but might work anyway: Mac
For details, see docs/BuildingForEveryPlatform.md
If you want to run ggez on Android, iOS or the web using WebAssembly take a look at good-web-game.
Who's using ggez?
Check out the projects list!
ggez requires rustc >= 1.42 and is distributed on
crates.io. To include it in your project, just add the dependency
line to your
ggez = "0.6.1"
ggez consists of three main parts: A
Context object which
contains all the state required to interface with the computer's
EventHandler trait that the user implements to
register callbacks for events, and various sub-modules such as
audio that provide the functionality to actually
get stuff done. The general pattern is to create a struct holding
your game's data which implements the
Create a new
Context object with default objects from a
Conf object, and then call
Context and an instance of your
EventHandler to run your game's
See the API docs for full documentation, or the examples directory for a number of commented examples of varying complexity. Most examples show off
a single feature of ggez, while
snake are small but complete games.
For a quick tutorial on ggez, see the Hello ggez guide in the
examples/ directory in the source. Most examples show off
a single feature of ggez, while
astroblasto is a small but
complete Asteroids-like game.
To run the examples, just check out the source and execute
cargo run --example
in the root directory:
git clone https://github.com/ggez/ggez.git cd ggez cargo run --example 05_astroblasto
If this doesn't work, see the FAQ for solutions to common problems.
Basic Project Template
use ; use ; use ;
ggez is built upon
winit for windowing and events,
sound, and a 2D drawing engine implemented in
gfx using the OpenGL
backend (which currently defaults to use OpenGL 3.2). It is entirely
thread-safe (though platform constraints mean the event-handling loop
and drawing must be done in the main thread), and portable to Windows
ggez is pure Rust™.
Sources of information:
- The FAQ has answers to common questions and problems.
- The API docs, a lot of design stuff is explained there.
- Check out the examples.
If you still have problems or questions, feel free to ask! Easiest ways are:
- Open an issue on the Github issue tracker
- Say hi on the unofficial Rust Discord server or the Rust Gamedev server