Crate ggez [] [src]

What is this?

Build Status Docs Status license Crates.io Crates.io

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 based on (a Rustified version of) the LÖVE game framework. 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 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.

Features

  • Filesystem abstraction that lets you load resources from folders or zip files
  • Hardware-accelerated rendering engine built on the gfx-rs graphics engine
  • Loading and playing .ogg, .wav and .flac files via the rodio crate
  • 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:

ggez = "0.3.0"

However you also need to have the SDL2 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 required to interface with the computer's hardware, an EventHandler 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. The general pattern is to create a struct holding your game's data which implements the EventHandler trait. Create a Conf object with the default values you want in it, Create a new Context from it, and then call event::run() with the Context and an instance of your EventHandler.

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 but complete Asteroids-like game.

To run the examples, you have to tell your program where to find the resources directory included in the git repository. The easy way is to enable cargo-resource-root feature flag to tell ggez to look for a resources directory next to your Cargo.toml, or copy or symlink the resources directory to a place the running game can find it (such as next to the game executable).

cargo run --example astroblasto --features=cargo-resource-root

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 built upon SDL2 for windowing and events, rodio for sound, and a 2D drawing engine implemented in gfx using the OpenGL backend (which currently defaults to use OpenGL 3.2). It should be entirely thread-safe outside of the basic event-handling loop, and portable to Windows, Linux and Mac.

The goal is to eventually have ggez be pure Rust, but we're not there yet.

Reexports

pub use error::*;

Modules

audio

Provides an interface to output sound to the user's speakers.

conf

The conf module contains functions for loading and saving game configurations.

error

Error types and conversion functions.

event

The event module contains traits and structs to actually run your game mainloop and handle top-level state, as well as handle input events such as keyboard and mouse.

filesystem

Provides a portable interface to the filesystem.

graphics

The graphics module performs the actual drawing of images, text, and other objects with the Drawable trait. It also handles basic loading of images and text.

input
timer

Timing and measurement functions.

Structs

Context

A Context is an object that holds on to global resources. It basically tracks hardware state such as the screen, audio system, timers, and so on. Generally this type is not thread- safe and only one Context can exist at a time. Trying to create another one will fail.