Pebble

A modular ECS framework for building render engines in Rust. Pebble provides the application loop, plugin system, resource management, and a GPU asset pipeline — but makes no rendering decisions for you. Batching, depth, post-processing, shaders, and draw calls are all yours to own.

[!WARNING] Pebble is built primarily for my own projects. It is shared publicly and you are free to use it, but expect breaking changes without notice. My own use cases drive priorities over external feature requests.

Design philosophy

Most graphics frameworks force you into their renderer. Pebble does the opposite: it gives you the plumbing and gets out of the way.

• Bring your own graphics API. Implement the Backend + FrameOperations traits for wgpu, Metal, Vulkan, or anything else.
• Bring your own windowing. Implement WindowProvider + WindowRunner for winit, SDL2, or a headless context.
• Bring your own assets. Implement Asset<B> to describe how a CPU-side value becomes a GPU-side value. Pebble handles the dirty queue, retry logic, and dependency ordering automatically.
• Compose with plugins. Everything — windowing, the backend, asset types, game logic — is a Plugin. Your engine is just a list of plugins wired to an App.

Core concepts

App and plugins

App::new()
    .add_plugin(MyWindowPlugin)
    .add_plugin(MyBackendPlugin)
    .add_plugin(MyGamePlugin)
    .build()
    .run();

build() runs all plugin registrations and validates that every declared resource dependency has a provider. There's no dedicated "run once at startup" stage or step — see .once() below for that. run() hands the app to the runner installed by your window plugin.

Systems and stages

Systems are plain Rust functions. Parameters are declared in the function signature and fetched automatically:

fn my_system(
    time:   Res<Time>,           // immutable resource borrow
    mut rb: ResMut<RigidBodies>, // mutable resource borrow
    mut q:  Query<&mut Transform>, // ECS query
    mut cmd: Commands,           // deferred world mutations
) { … }

Systems are registered at a SystemStage that determines when they run each tick:

AssetSync and AssetSyncDeps are prioritized: they're run to convergence (repeated until a full pass inserts no new resources) at the very front of every tick and again after every other stage, so newly queued asset/resource work is drained immediately rather than waiting for the next tick's front pass.

Systems that declare a hard requirement — a bare Res<T>/ResMut<T> parameter — are checked before their stage runs. What happens when the resource isn't there yet depends on whether anything has registered it as eventually arriving:

• If some plugin called app.provides::<T>() (GraphicsPlugin does this for the GPU backend; LazyResourcePlugin does it for the type it constructs), the system just waits quietly and is retried next tick.
• Otherwise, App panics immediately, naming both the resource and the offending system, and suggesting app.provides::<T>() as the fix if the timing really is expected. This catches the common case — forgetting app.add_resource(...) — without also catching every legitimate "this arrives asynchronously" resource.

Wrapping a system in .run_if::<ResourceExists<T>>() (or any other condition — see Run conditions) fully exempts it from this check — the condition is trusted to gate correctly.

Run once

There's no separate "Startup" stage — instead, .once() turns "have I already done this" into the system's own return value, on whichever stage you register it:

fn spawn_scene(mut commands: Commands, pbr: Option<Res<PBR>>) -> Option<()> {
    let pbr = pbr?; // not ready yet — try again next tick
    if pbr.cubemap_material_inst == RawAssetHandle::default() {
        return None; // PBR exists but this field isn't populated yet — keep waiting
    }
    commands.spawn(/* ... */);
    Some(()) // done — never runs again
}

app.add_system(SystemStage::PreUpdate, spawn_scene.once());

Return None to mean "not ready, call me again next tick"; return Some(()) to mean "done" — the system is retired permanently and never invoked again, no matter how many ticks that took. This is what replaces manually tracking a Local<bool> "already ran" flag, and it composes with the same hard-requirement checking as any other system: a bare Res<T> param is still checked (wait if provided, panic if not) before the function is even called.

Queries

Queries

Query<Q> wraps an hecs query. Iterate it directly with &mut query, or use the lookup helpers when you don't need the whole result set:

fn move_system(mut q: Query<(&mut Position, &Velocity)>) {
    for (pos, vel) in &mut q {
        pos.x += vel.x;
        pos.y += vel.y;
    }
}

• query.get(entity, |item| ...) — fetch components for one known Entity without scanning the rest of the query.
• query.single() / query.get_single() — expect exactly one match (the player, the active camera). single panics if that's not true; get_single returns None instead.

Include Entity in Q (e.g. Query<(Entity, &Health)>) if you need the entity id back out alongside its components.

Run conditions

.run_if::<C>() gates a system (or a whole tuple passed to add_systems) behind a RunCondition, so its SystemParams are only fetched — and its body only runs — when the condition holds. It's re-checked every tick:

app.add_systems(
    SystemStage::Update,
    report_expensive_setup.run_if::<ResourceExists<ExpensiveSetup>>(),
);

Built-in conditions: ResourceExists<T>, plus And<A, B> / Or<A, B> for combining conditions. Implement RunCondition yourself for anything else.

Resources

Resources are singleton values stored in the ECS world. Any hecs::Component type can be a resource:

app.add_resource(MyConfig { … });

// In a system:
fn my_system(config: Res<MyConfig>) { … }

Option<Res<T>> is used when a resource may not exist yet — the system receives None and can skip its work gracefully. This is the standard way to wait for things like the GPU backend, which arrives asynchronously after startup.

The asset pipeline

The Asset<B> trait describes how a CPU-side source type is converted to a processed type using backend B:

impl Asset<WGPUBackend> for GPUMesh {
    type Source = Mesh;       // stored in Assets<Mesh>
    type Deps<'a> = ();       // no extra dependencies

    fn upload<'a>(source: &Mesh, backend: &WGPUBackend, _deps: &()) -> Option<Self> {
        // create GPU buffers from source data
        Some(GPUMesh { … })
    }
}

B is generic — it need not be a GPU backend. Use B = () for CPU-to-CPU transforms (decompression, format conversion), or any other service type for audio, networking, etc.

Registering AssetPlugin::<B, T>::new() wires up the full pipeline automatically:

• Assets<T::Source> — stores raw CPU data, tracks a dirty queue.
• ProcessedAssets<T> — stores the converted results, indexed by the same handles.
• A sync system on AssetSync that drains the dirty queue each tick, calling T::upload for each pending entry.

If upload returns None the handle is re-queued for the next tick. If a Deps resource is missing the whole sync system waits until it appears. No manual ordering or callbacks needed.

Lazy resources

LazyResource<B> complements Asset<B> for resources that have exactly one instance in the whole app and need a device to be constructed, but don't come from authored data and don't need a Handle or a pool entry.

impl LazyResource<WGPUBackend> for DepthTexture {
    type Deps<'a> = ();

    fn construct<'a>(backend: &WGPUBackend, _deps: &()) -> Option<Self> {
        let texture = backend.device.create_texture(/* Depth16Unorm … */);
        let view    = texture.create_view(&Default::default());
        Some(DepthTexture { texture, view })
    }
}

Register with LazyResourcePlugin. The plugin adds a system to AssetSyncDeps that waits for B and all Deps to be present as resources, calls construct once, inserts the result via Res<T>, and never runs again. If construct returns None it retries next tick.

.add_plugin(LazyResourcePlugin::<WGPUBackend, DepthTexture>::new())

Good candidates: depth textures, camera uniform buffers, shared bind group layouts — anything that is one-of-a-kind and needs a backend before it can exist. If you need more than one instance of something, use Asset<B> + Handle instead.

Quick start

Add to Cargo.toml:

[dependencies]

pebble-engine = "0.2"

The minimal application — clear the screen to a colour:

use pebble::prelude::*;

fn main() {
    App::new()
        .add_plugin(WindowPlugin::<MyWindow>::new(WindowConfig {
            title: "Hello Pebble",
            width: 800,
            height: 600,
        }))
        .add_plugin(GraphicsPlugin::<MyBackend, MyWindow>::new())
        .add_plugin(RenderPlugin::<MyBackend>::new())
        .add_system(SystemStage::Render, render)
        .build()
        .run();
}

fn render(mut frame: ResMut<CurrentFrame<MyBackend>>) {
    if let Some(mut active) = frame.active() {
        let mut _pass = active.render_context([0.1, 0.1, 0.1, 1.0]);
        // draw calls go here
    }
}

MyWindow implements WindowProvider + WindowRunner. MyBackend implements Backend + FrameOperations. See the examples below for complete, runnable implementations using wgpu and winit.

Examples

The examples are standalone crates that share a examples/common crate providing a wgpu + winit backend implementation, except ecs_basics, which needs no window or graphics backend at all. They are ordered by complexity and each has a step-by-step README, except ecs_basics, which is documented inline.

Run any example from its directory:

cd examples/hello_triangle

cargo run

Compiled shaders (SPIR-V) are pre-built in examples/assets/shaders/compiled/. If you modify the GLSL sources, recompile them with python3 examples/compile_shaders.py.

Implementing a backend

To use Pebble with your own graphics API, implement two traits:

FrameOperations — represents one acquired frame:

impl FrameOperations for MyFrame {
    type Context<'a> = MyRenderPass<'a>;  // what you draw with
    type Attachment      = MyTextureView;
    type DepthAttachment = MyTextureView;

    fn begin(&mut self, pass: Pass<'_, Self>) -> Self::Context<'_> { … }
}

Backend — manages the swapchain and device:

impl Backend for MyBackend {
    type Frame = MyFrame;

    fn init(handle: impl GPUSurfaceHandle, width: u32, height: u32, sender: InitSender<Self>) {
        // create device/swapchain synchronously or on a thread, then:
        sender.send(MyBackend { … });
    }

    fn acquire(&mut self) -> Result<Self::Frame, AcquireError> { … }
    fn present(&mut self, frame: Self::Frame) { … }
}

init always delivers the backend through an InitSender, whether you do it synchronously (call sender.send before returning) or asynchronously (spawn a thread/task and call sender.send when ready). The framework polls the channel each PreRender tick until the backend arrives.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.