raylib-rs

raylib-rs is a safe, idiomatic Rust binding for raylib 6.0.

• MSRV: Rust 1.85 (edition 2024, pinned in rust-toolchain.toml).
• Repository: https://github.com/raylib-rs/raylib-rs
• Crates: raylib (safe wrapper), raylib-sys (raw FFI).
• Docs: rustdoc on docs.rs/raylib; narrative book and live examples gallery below.

Versions normally match raylib's own, with the minor number incremented for any binding-side patches (e.g. 6.0.1 for raylib v6.0). On occasion, if enough breaking changes land between raylib releases, we'll cut a 6.1 that is a raylib 6.0 binding plus binding-side breaking changes.

What's new in 6.0

The 6.0 release is a near-complete rework of the binding. Highlights:

• raylib 6.0 parity. C source bumped; bindings regenerated. The SUPPORT_* feature set matches raylib 6.0's config.h (notably SUPPORT_STANDARD_FILEIO is gone — it's unconditional in 6.0; SUPPORT_FILEFORMAT_PNM and SUPPORT_GPU_SKINNING were added).
• Zero math dependencies by default. Vector2/3/4, Matrix, and Quaternion are native #[repr(C)] Rust structs with methods+operators powered by a C shim over raylib's own raymath. glam, mint, and serde are strictly opt-in features.
• Safe rlgl immediate-mode module. rl_begin / rl_draw / rl_push_matrix return RAII guards (RlImmediate, RlMatrix); &Texture2D / &Shader bind helpers; render-state toggles.
• raygui rework at 6.0 parity (57/57 functions). The module was split into grouped sub-traits (RaylibGuiState, RaylibGuiContainers, RaylibGuiControls, RaylibGuiAdvanced, RaylibGuiIcons); control labels now take impl AsRef<str> (no CStr plumbing).
• Skeletal-animation RAII redesign. Loading returns a single ModelAnimations collection that owns the heap array and frees all frames on drop. The singular UnloadModelAnimation is gone in 6.0, so the previous per-item-owning API was unsound.
• Headless software renderer. New software_renderer feature wires raylib's rlsw Memory platform — no GPU, no window, no display server. A new raylib::test_harness module (with_headless, render_frame, pixel_at, assert_pixel) drives the WS4b pixel-probe test tier and runs in CI on all three desktop OSes.
• New safe wrappers for areas that previously required unsafe:
  • raylib::core::pixel — get_pixel_color / set_pixel_color / bytes_per_pixel over raylib's pixel-format helpers; typed PixelColorError.
  • raylib::core::hashes — safe compute_crc32 / compute_md5 / compute_sha1 / compute_sha256 (the last three pin to RaylibThread because raylib returns a shared static buffer).
  • Mixed audio bus — closure-driven attach_audio_mixed_processor returning a MixedAudioProcessorCallback RAII guard.
  • raylib::core::audio::set_audio_stream_callback — sound replacement via a closure on AudioStream.
• mdBook narrative documentation at book/ — 28 chapters: introduction, quickstart, 4 platform install guides, 5 Core Concepts, 14 Modules, 2 Ecosystem chapters, plus a Showcase appendix.
• Showcase gallery. A new showcase/ workspace crate ports 229 raylib + raygui examples to idiomatic raylib-rs under a visual-parity rule, with an in-canvas F1 source-viewer overlay (C-vs-Rust tabs) and per-example "Source on GitHub" deep-links. Deployed as a Pages site.
• Layered CI / quality gates. Workflows: check (fmt + clippy -Dwarnings + deny(missing_docs) + cargo-deny + doctests/doc-links), test (unit + doctests on the three desktop OSes), web (wasm32-emscripten build verification), sanitizers (ASAN/UBSAN informational), book, pages, showcase. The release plumbing is release-sys.yml + release-safe.yml (workflow_dispatch, dry-run-gated).
• Tests. Tier-1 unit tests for window-independent functions (collision, color, easing, raymath, file, text); Tier-2 headless render tests under software_renderer (render_shapes, render_text, render_gui, render_rlgl, integration smoke). All run in CI under cargo nextest for per-test process isolation (raylib's single-init is per-process).

See CHANGELOG.md for the full breaking-change list and the complete add list.

Installation

Supported platforms

¹ raygui and rlgl ship in the Pages showcase build (wasm32-unknown-emscripten). Per-target completeness tracked in docs/superpowers/notes/. ² software_renderer on the web target is tracked-deferred; see the WS6b notes.

Three desktop OSes (ubuntu-latest, macos-latest, windows-latest) are covered by the check, test, and sanitizers workflows. The web workflow build-verifies wasm32-unknown-emscripten. Android is not supported.

Build dependencies

cmake, glfw development headers, and curl (for the build script). Per-platform notes:

• Windows: install CMake; the build pulls in MSVC build tools as needed.
• Linux (Debian/Ubuntu): cmake libasound2-dev libudev-dev libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libgl1-mesa-dev. For Wayland add libglfw3-dev wayland-devel libxkbcommon-devel wayland-protocols wayland-protocols-devel libecm-dev and enable the wayland feature.
• macOS: brew install cmake.
• NixOS: a shell.nix is provided at the repo root — nix-shell ./shell.nix. Add the wayland feature: cargo add raylib -F wayland.

Per-OS install guides live in the book — Windows, macOS, Linux, and Web each have a dedicated chapter.

Quick start

1. Add the dependency to Cargo.toml:

[dependencies]
raylib = "6.0.0-rc.2"

2. Open a window and draw:

use raylib::prelude::*;

fn main() {
    let (mut rl, thread) = raylib::init()
        .size(640, 480)
        .title("Hello, World")
        .build();

    while !rl.window_should_close() {
        let mut d = rl.begin_drawing(&thread);

        d.clear_background(Color::WHITE);
        d.draw_text("Hello, world!", 12, 12, 20, Color::BLACK);
    }
}

See book/src/getting-started/quickstart.md for a longer walkthrough.

Cross-compiling

cross can simplify cross-builds — see the wiki.

Features

Default features mirror raylib 6.0's defaults. default-features = false is supported (but be aware that several SUPPORT_* flags are effectively mandatory — disabling them will break parts of raylib that assume they're on).

Headline features:

Each SUPPORT_* capability from raylib's config.h is exposed as a Cargo feature of the same name (e.g. SUPPORT_FILEFORMAT_PNG, SUPPORT_IMAGE_GENERATION). They are all on under default / full. See raylib/Cargo.toml for the complete list.

Mutual exclusion: select one of opengl_33 / opengl_21 / opengl_es_20 / software_renderer. The build script does not currently diagnose multiple selections — last #[cfg] wins, which is a footgun.

Documentation

API reference

• rustdoc on docs.rs — published on each crate release: https://docs.rs/raylib.
• Build locally with cargo doc --no-deps -p raylib --features full --open.

The book

Narrative documentation lives in book/ and is published by the book workflow. 28 chapters organized as:

• Getting Started — quickstart, Windows / macOS / Linux / Web install guides, deferred targets.
• Core Concepts — RaylibHandle/RaylibThread, RAII and resources, strings and allocations, safety, features and platforms.
• Modules — window and drawing, input, shapes, textures and images, text and fonts, 3D models, audio, raymath, collision, raygui, rlgl, software renderer, callbacks and logging, error handling.
• Ecosystem — glam / mint / serde interop, what comes next.
• Appendix — Showcase examples index (links each module chapter to its runnable examples).

Build locally: mdbook serve book (after cargo install mdbook).

Showcase & live gallery

showcase/ ports the raylib C example set to idiomatic raylib-rs under a visual-parity rule (the Rust port should look the same as the C original when run side-by-side). The crate currently ships:

• 229 examples across 9 categories — audio (11), core (49), models (30), others (3), raygui (12), shaders (35), shapes (41), text (16), textures (32).
• An in-canvas F1 source-viewer overlay with C-vs-Rust tabs and a "Source on GitHub" deep-link footer (URLs derived at build time from .gitmodules + submodule SHAs, so links resolve to the exact upstream commit).
• A Pages gallery with thumbnail tiles, per-tile C/Rust GitHub links, a name filter, and per-example emscripten output wrapped in gallery chrome via a shared example_shell.html.

Live site: https://raylib-rs.github.io/raylib-rs/.

Run an example locally:

cargo run -p raylib-showcase --example core_basic_window

Authoring guidance for new ports lives in the raylib-showcase-port-flow skill and in docs/superpowers/notes/ws9-showcase-complete.md. The CI gate is WS9_STRICT_PAIRING=1 — a .c example without a matching Rust port breaks the build.

The legacy samples/ directory was removed in 6.0; the canonical home for example code is now showcase/.

Safe-binding characteristics

• RAII everywhere. Resource types (Image, Texture2D, RenderTexture2D, Font, Mesh, Shader, Material, Model, ModelAnimations, …) clean up on drop. Unload* functions are intentionally not exposed.
• Audio lifetimes. Wave, Sound, Music, and AudioStream are lifetime-bound to AudioHandle.
• RaylibHandle + RaylibThread token. Most of the API hangs off RaylibHandle to enforce single-init and proper window teardown. RaylibThread is !Send — never put it in a Mutex / Arc or hand it across threads.
• Strings. Functions take &str and return owned String. Per-frame gui draw fns took &CStr historically; in 6.0 they accept impl AsRef<str> via a thread-local scratch buffer.
• Allocations. Functions that return raylib-allocated buffers wrap them as ManuallyDrop<Box<[T]>> or DataBuf<[T]> and free via the matching Unload* / MemFree, never libc::free — this stays correct under custom allocators.
• No samples/ migration shim. Code that imported from samples/ should move to showcase/.

For the full safety contract — including the unsafe-discipline rules new code must follow — see CONTRIBUTE.md.

Testing

Two-tier test surface; both run in CI on Windows, Linux, and macOS:

• Tier-1 unit tests (window-independent): exercise raymath, collision, color, easing, file, text.

  cargo nextest run -p raylib --features full
  cargo test --doc -p raylib --features full
  

• Tier-2 headless render tests (no GPU, no window) under the software_renderer feature:

  cargo nextest run -p raylib \
    --no-default-features \
    --features software_renderer,SUPPORT_MODULE_RTEXTURES,SUPPORT_MODULE_RSHAPES,SUPPORT_MODULE_RTEXT,SUPPORT_MODULE_RMODELS,SUPPORT_MODULE_RAUDIO,SUPPORT_IMAGE_GENERATION,raygui
  

raylib's single-init constraint is per-process, not per-thread, so cargo nextest run (per-test process isolation) is the recommended runner. cargo test --doc is still used for doctests; nextest does not run them. Contributors without cargo-nextest can fall back to cargo test ... -- --test-threads=1 for files with at most one with_headless test per binary.

CI workflows live in .github/workflows/: check, test, web, sanitizers, book, pages, showcase, release-sys, release-safe.

Contributing

Contributions are welcome. Please:

1. Read CONTRIBUTE.md and the relevant book chapter (Core Concepts / Modules).
2. Make sure cargo nextest run -p raylib --features full and cargo test --doc -p raylib --features full pass locally (Windows or Linux).
3. If you touch the safe raylib crate, also run the software-renderer leg above so the headless tests stay green.
4. If you change feature lists, keep raylib/Cargo.toml and raylib-sys/Cargo.toml in sync.
5. Bump versions consistently across Cargo.toml files and add a CHANGELOG.md entry.
6. Tag hot/small fns with #[inline], #[must_use], and const where applicable.

Updating raygui

The raygui.h file has to have this ifdef modified to point to where raylib.h lives:

#if !defined(RAYGUI_STANDALONE)
#include "../raylib/src/raylib.h"
#endif

Tech notes

• Resource types use RAII / move semantics.
• LoadFontData returns a pointer to a heap-allocated CharInfo array in C; the binding copies into an owned Vec<CharInfo> and frees the original.
• LoadDroppedFiles returns a raylib-owned string array; the binding copies into Vec<String> and returns to the caller.
• Linking is automatic on Windows 10/11, Ubuntu, and macOS 15. Other platforms may need extra tweaks.
• Image::gen_image_* is #[cfg]-gated on SUPPORT_IMAGE_GENERATION (avoids an MSVC link error).
• DRM/tty rendering: enable ["drm", "opengl_es_20"]. Wayland: enable ["wayland"].

Background — the 6.0 upgrade

The 6.0 release was developed across nine workstreams plus a pre-WS9 quality queue and a final-release wrap-up. The full design+decision record lives under docs/superpowers/:

• Roadmap and cross-cutting decisions: docs/superpowers/specs/2026-05-25-raylib-rs-6.0-roadmap-design.md
• Per-workstream plans: docs/superpowers/plans/
• Workstream completion notes (one per workstream): docs/superpowers/notes/
• Backlog triage (every open PR/issue at the start of the effort): docs/superpowers/inventory.md

For the day-to-day working-rules summary read by every session, see CLAUDE.md.

Support

• Chat: raylib Discord — https://discord.gg/VkzNHUE.
• Issues / discussion: https://github.com/raylib-rs/raylib-rs/issues.
• Wiki: https://github.com/raylib-rs/raylib-rs/wiki.