Crate quicksilver

Source
Expand description

§quicksilver

Quicksilver Logo

Crates.io Docs Status dependency status

A simple 2D game framework written in pure Rust, for both the Web and Desktop

§Maintenance Status

I’ve posted an update on my website about Quicksilver. To keep a long story short: Quicksilver is no longer actively developed. For now I will continue to triage bugs and pull requests and (maybe) fix small bugs.

§Alpha Notice

This version of Quicksilver is currently working its way through alpha! There is still work to do on the API and on bugfixes, as well as waiting on an upstream library for audio support. Please feel free to use this version and provide feedback! If you run into bugs or want to give feedback on API decisions, please open an issue.

§A quick example

Create a rust project and add this line to your Cargo.toml file under [dependencies]:

    quicksilver = "0.4.0-alpha5"

Then replace src/main.rs with the following (the contents of quicksilver’s examples/01_square.rs):

// Example 1: The Square
// Open a window, and draw a colored square in it
use quicksilver::{
    geom::{Rectangle, Vector},
    graphics::{Color, Graphics},
    Input, Window, Result, Settings, run,
};

fn main() {
    run(
        Settings {
            title: "Square Example",
            ..Settings::default()
        },
        app,
    );
}

async fn app(window: Window, mut gfx: Graphics, mut input: Input) -> Result<()> {
    // Clear the screen to a blank, white color
    gfx.clear(Color::WHITE);
    // Paint a blue square with a red outline in the center of our screen
    // It should have a top-left of (350, 100) and a size of (150, 100)
    let rect = Rectangle::new(Vector::new(350.0, 100.0), Vector::new(100.0, 100.0));
    gfx.fill_rect(&rect, Color::BLUE);
    gfx.stroke_rect(&rect, Color::RED);
    // Send the data to be drawn
    gfx.present(&window)?;
    loop {
        while let Some(_) = input.next_event().await {}
    }
}

Run this with cargo run or, if you have the wasm32 toolchain installed, you can build for the web (instructions below).

§Learning Quicksilver

A good way to get started with Quicksilver is to read and run the examples which also serve as tutorials. If you have any questions, feel free to open an issue or ask for help in the Rust Community Discord from other Quicksilver users and developers.

§Building and Deploying a Quicksilver application

Quicksilver should always compile and run on the latest stable version of Rust, for both web and desktop.

Make sure to put all your assets in a top-level folder of your crate called static/. All Quicksilver file loading-APIs will expect paths that originate in the static folder, so static/image.png should be referenced as image.png.

§Linux dependencies

On Windows and Mac, all you’ll need to build Quicksilver is a recent stable version of rustc and cargo. A few of Quicksilver’s dependencies require Linux packages to build, namely libudev, zlib, and alsa. To install these on Ubuntu or Debian, run the command sudo apt install libudev-dev zlib1g-dev alsa libasound2-dev.

§Deploying for desktop

If you’re deploying for desktop platforms, build in release mode (cargo build --release) and copy the executable file produced (found at “target/release/”) and any assets you used (image files, etc.) and create an archive (on Windows a zip file, on Unix a tar file). You should be able to distribute this archive with no problems; if there are any, please open an issue.

§Deploying for the web

If you’re deploying for the web, first make sure you’ve installed the cargo web tool. Then use cargo web deploy to build your application for distribution (located at target/deploy).

If you want to test your application locally, use cargo web start --features quicksilver/stdweb and open your favorite browser to the port it provides.

§wasm-bindgen support

Quicksilver has recently gained experimental support for wasm-bindgen, under the web-sys feature. The workflow is not currently documented here, but it should be the same as using any other library with wasm-bindgen.

§Optional Features

Quicksilver by default tries to provide all features a 2D application may need, but not all applications need these features.

The optional features available are:

Each are enabled by default, but you can specify which features you actually want to use.

§Supported Platforms

The engine is supported on Windows, macOS, Linux, and the web via WebAssembly.

Mobile support would be a future possibility, but likely only through external contributions.

Re-exports§

Modules§

  • geom
    A 2D geometry module
  • graphics
    Draw 2D graphics to the screen
  • input
    Read events / input state
  • saving
    A module to manage cross-platform save data via the gestalt library

Structs§

  • Settings
    Initial window and behavior options
  • Timer
    A timer that you can use to fix the time between actions, for example updates or draw calls.
  • Window
    The window on the user’s desktop or in the browser tab

Enums§

Functions§

Type Aliases§