A small native application core with a universal message bus — and optional sandboxed WASM extensions, in any language.
How to use it · Release archives · Examples · Documentation · Changelog
The core owns windows, the tray icon, input (SDL), logging, and a message bus. Everything else is composed onto that bus: native modules in Rust — rendering, UI, audio, web panels, your own — and, when you turn them on, WASM extensions.
Every part talks to every other over that one bus, and none can tell whether the other is native or WASM. Extensions are optional. When used, they never touch the OS and never render directly: they publish draw commands, widget specs, or web-panel JSON, and the engine presents. That boundary is what makes an extension hot-reloadable, sandboxed, and language-agnostic.
flowchart LR
subgraph guests["WASM extensions — optional, any language"]
game["your game"]
tool["your tool"]
gui["your GUI"]
end
bus(("message bus"))
subgraph core["bones engine — native"]
present["renderer · egui · wry panels"]
io["input · audio · persistence"]
mine["your native modules"]
end
game & tool & gui <--> bus
bus <--> present & io & mine
The kernel infrastructure, renderer, egui UI, audio, game-core, optional web panels, hot reload, orderly shutdown, extension flow-control budgets, and custom native-module injection all work today.
Web panels let an extension build its interface in HTML, CSS, and JavaScript instead of native widgets. The engine shows the page inside its own window, using the operating system's web view through wry (WebView2 on Windows, WebKitGTK on Linux), and passes JSON messages between the page and the extension. docs/examples/web-app.md builds one.
Three ways in, from least to most code of your own. The first needs no Rust at all; the other two are for applications that own their binary, with or without extensions.
You ship the engine binary unchanged and write your product — a game, a tool, a GUI — as one or more WASM extensions.
- Download the engine for your platform from the latest release; Release archives says which one.
- Create an extension project. In Rust it is a
cdylibcrate depending onbones-wasm-sdk; in any other language, bindings generated from the ABI shipped in the archive. - Build it for
wasm32-wasip2and drop the.wasminto the archive'sextensions/folder. Runbones, and it loads on start — and reloads when you rebuild.
examples/README.md walks through the project setup and picks the example closest to what you are building: a game, an egui tool, a web-panel app, persistent state. Start with the hello-demo tutorial.
Your application owns main and builds the engine with the Kernel builder — choosing the window and the modules in code rather than in bones.toml. Product logic can live in native modules, in extensions, or both. This is how commits and the other projects below use bones.
[dependencies]
# Drop "wasm" for a purely native application: no extensions, and no WASM runtime in the build.
bones-kernel = { git = "https://github.com/an-dr/bones", tag = "v3.0.0", features = ["wasm"] }Distributed by git tag, not crates.io; docs/architecture/structure.md says what a tag promises. Opt-in modules cover what a desktop application needs around the engine: single instance, self-update, desktop registration, OS access.
When you need a capability the sandbox cannot reach — a device, a native library, an OS service — or code your application calls on a hot path, write a native module in Rust and inject it with .module(...). It joins the same bus and can define its own message vocabulary, which extensions then reach like any other. docs/design/extensions.md says when to choose a module over an extension. custom-engine is the worked example.
Every release carries six archives, each with a .sha256 beside it. They differ by platform and by whether they include web panels — HTML interfaces for extensions — which need the operating system's web view at runtime. Each contains the engine, an empty extensions/ folder, the ABI (wit/), a sample bones.toml with every default spelled out, the licence, and third-party notices.
| Archive | Web panels | Your machine needs |
|---|---|---|
bones-<version>-windows-x64-web.zip |
✅ | Windows 10 or 11 — WebView2 is part of the OS |
bones-<version>-windows-arm64-web.zip |
✅ | Windows 10 or 11 on ARM |
bones-<version>-linux-x64.zip |
— | An X11 or Wayland desktop with ALSA — standard on desktop distributions |
bones-<version>-linux-x64-web.zip |
✅ | The same, plus libwebkit2gtk-4.1 and GTK 3 |
bones-<version>-linux-arm64.zip |
— | As linux-x64, on ARM64 |
bones-<version>-linux-arm64-web.zip |
✅ | As linux-x64-web, on ARM64 |
Which Linux archive? Take -web if your extensions open web panels and you can install webkit2gtk (sudo apt install libwebkit2gtk-4.1-0 on Debian and Ubuntu). A -web build will not start at all where that library is missing; the plain build has no such dependency, and refuses web = true in bones.toml with an error instead.
Every push to main also uploads the same six as CI artifacts, for trying a change before it is released. To build one yourself: cargo xtask dist, adding --features web for the web variant.
Deliberately independent (ADR-029). An extension outlives the engine build that loaded it and may not be written in Rust, so one number cannot promise both audiences.
| Line | What it covers | Moves when |
|---|---|---|
engine — bones, bones-kernel |
the Rust API an embedder links | the library surface changes |
ABI — bones:extension, bones-messages, bones-wasm-sdk |
the contract a .wasm extension is built against |
the guest contract changes |
An extension author in Rust pins the ABI line, not the engine line:
[dependencies]
bones-wasm-sdk = { git = "https://github.com/an-dr/bones", tag = "abi-v1.2.0" }See CHANGELOG.md for what has moved.
| Platform | Status |
|---|---|
| Windows x64 and ARM64 | Supported. Tested in CI on every push and pull request, web panels included; released as archives |
| Linux x64 and ARM64 | Supported. Tested in CI on every push and pull request; released with and without web panels |
| Android | Planned — see docs/roadmap.md |
| macOS | Not built or tested. The engine is written to be portable and the SDL and wry backends are cross-platform; reports are welcome |
git clone --recurse-submodules https://github.com/an-dr/bones
cargo xtask doctor # what is missing, and where to get it
cargo xtask test # fixtures, gates, and every test
cargo run -p bones # run the engine you just builtIt needs a Rust toolchain and a C compiler with CMake, since the kernel infrastructure builds SDL3 from source — plus, on Linux, the development packages cargo xtask linux-packages lists. Nothing is installed for you. docs/contributing/building.md has every command; docs/contributing/testing.md what the suite gates.
| Project | What it is |
|---|---|
| commits | A desktop Git client. Embeds bones and runs its Git Graph view in a wry web panel |
| artificial-will-game-v2 | A game about a robot named Will. Embeds bones and ships its gameplay as extensions |
| copper | A manifest-first automation host for AI-generated extensions. Embeds bones for its settings UI and tray |
Built something on bones? Add the badge to your README, and open a pull request to list it here:
[](https://github.com/an-dr/bones)Start at docs/index.md — the architecture, detailed designs, decisions (ADRs), and worked examples. The short version:
- docs/architecture/ — the system: parts, structure, messaging, upgrading.
- docs/architecture/structure.md — what lives where and what may depend on what.
- docs/adr/ — why the design is the way it is.
- docs/roadmap.md — what comes next.
See CONTRIBUTING.md for how to build, test, and land a change, and docs/contributing/releasing.md for cutting a release — pushing a v* tag is the whole of it.
This project is developed openly with AI agents, at AI Level 3. The base agent policy — flows, roles, and skills — lives in an-dr/agents; AGENTS.md holds the rules specific to this repository.
Commits are authored by the person who reviewed and committed them. CI rejects any commit that credits an AI tool as a co-author: the tool is no more an author than the editor or the compiler.
MIT — see LICENSE.