classicvalues / riddle-2

Rust native game/media development library

About Riddle

Riddle is a Rust media library in the vein of SDL, building as far as possible on the most active/standard rust libraries (winit, wgpu, image, etc). Riddle is NOT an engine, or a framework. It is a library devoted to exposing media related features in a unified way while avoiding prescribing program structure [note 1].

The rough feature set is listed here, along with the crates the features are primarily built upen. Riddle is only possible due to the massive efforts of the greater rust community.

• Windowing and System Event Loops (Docs), exposed through riddle::platform. Uses winit.
• Input State Management (Docs), exposed through riddle::input. Gamepad, mouse and keyboard support. Built on winit and gilrs
• Image Loading and Basic Graphics Operations (Docs), exposed through riddle::image. Uses image.
• Font Loading and Rendering (Docs), exposed through riddle::font. Uses rusttype.
• Math (Docs), exposed through riddle::math. Uses mint, and glam.
• Audio Loading and Playing. (Docs), Uses rodio.
• Basic 2D Renderer (Docs), exposed through riddle::renderer. Uses wgpu.
• Timers and Framerate Tracking (Docs), exposed throug riddle::time.

This crate depends on an array of crates, each of which implements a specific feature. All sub-crates can be used independently of the top level riddle crate, but are best used by adding a dependency on riddle with appropriate feature flags configured.

Each crate fully wraps the underlying libraries to allow for a consistent API to be preserved between releases. They also contain extension traits, to provide direct access to the underlying types. The few exceptions to this, where types from other crates are exposed through Riddle's public API are where those crates have become defacto standards for cross crate integration, such as mint, and raw-window-handle.

Documentation

Since the crate isn't on crates.io docs are hosted on Github Pages:

• master: Link
• 0.2.0: Link
• 0.1.0: Link

Cargo Features

• riddle-renderer - The riddle-renderer-wgpu renderer will be enabled. default
• riddle-audio- The riddle-audio subsystem will be enabled. default
• riddle-font - The riddle-font crate will be included, and reexported through riddle::font. default
• riddle-mp3 - Enable mp3 support in riddle-audio.

Getting started

Add a git dependency in your cargo.toml to the most recent release [note 2]:

[dependencies.riddle]
version = "0.2"
git = "https://github.com/riddle-rs/riddle/"
tag = "0.2.0"

If you want to use the bleeding edge insert the following in to your cargo.toml:

[dependencies.riddle]
version = "0.3.0-dev"
git = "https://github.com/riddle-rs/riddle/"
branch = "master"

Place the following in main.rs:

use riddle::{*, platform::*, renderer::*, common::Color};

fn main() -> Result<(), RiddleError> {
    // Initialize the library
    let rdl = RiddleLib::new()?;

    // Create a window and renderer
    let window = WindowBuilder::new().build(rdl.context())?;
    let renderer = Renderer::new_from_window(&window)?;

    // Start the main event loop
    rdl.run(move |rdl| {
        match rdl.event() {
            Event::Platform(PlatformEvent::WindowClose(_)) => rdl.quit(),
            Event::ProcessFrame => {
                // Clear the window with black every frame
                renderer.render(|render_ctx| {
                    render_ctx.clear(Color::BLACK);
                }).unwrap();
            }
            _ => (),
         }
    })
}

Examples

The rustdocs for most public APIs contain example code to illustrate how the various riddle systems work, and how they should be used.

More complete examples live in riddle/examples.

The current set of examples is:

• pong - A simple pong game, using input, basic fill-rect rendering, and audio.
• wgpu-renderer-overlay - A demo showing how to use riddle to create a window, in which a custom WGPU 3d renderer co-exists with a Riddle 2d renderer.
• sandbox - This is a scratchpad example which tries to use as much functionality as possible to provide quick manual verification of changes to the library. It is not a learning resource.

Linux build dependencies

To build on Linux the following packages are required (on Ubuntu at least): libasound2-dev libudev-dev. These are required for rodio(audio library), and gilrs(controller support library) respectively.

They can be installed by running:

sudo apt install libasound2-dev libudev-dev

Notes

1. A necesary exception is the top level RiddleLib::run function which must be used if riddle::platform is to be used.