Shell

What the Shell is

The Shell is the heart of Roves — the actual compiled engine binary. Everything else on this wiki (Packmaster, the GitHub Action) doesn't replace it — both just build or download this exact same Shell on your behalf and hand you the result already put together.

As the name suggests, the Shell is a container: an empty, pre-built native application that knows how to load and run a dist — your game's already-built web output, whatever your own bundler (Vite, webpack, or anything else that produces a browser-runnable index.html) produces — as a real, double-click desktop app. No browser chrome, no toolbar, no address bar — one window that opens your game and nothing else. It's the same role a Tauri or Electron shell plays, just for a different underlying engine; see Why Roves? for that comparison.

The Shell is already built for you

You don't need to compile anything to get a working Shell. Every tagged engine version publishes a ready-to-run Shell — with no game content in it yet — on the Releases page, starting at v0.1.0. Each platform is published twice: a plain build and a _steam-suffixed one compiled with the Steam bridge built in.

These are optimized (--release) builds with the real GStreamer media stack (bundled automatically on Windows/macOS). Pick the version your game targets, download the zip for your platform, and extract it anywhere — that's the whole install step.

Inserting your dist into the Shell

This is the part that actually matters: turning that empty container plus your built game into something playable. Every path below — Packmaster included — ends up doing the exact same thing under the hood, so pick whichever fits how you work.

Nothing here requires Rust, Python, or mach — just a downloaded Shell and your already-built game.

1. Build your game with your own bundler, however you already do it. This produces a folder — commonly named dist/ — containing an index.html plus whatever assets it references.

2. Download and extract the matching Shell zip from the table above.

3. Copy your build output next to the Shell binary (play.exe / play.app / play), keeping it named dist so it lines up with the Shell's own default expectations.

4. Tell the Shell where to find it. Two ways, depending on whether you want a double-click-runnable copy or you're just testing:

   • A launch.json next to the binary (recommended — this is exactly what mach bundle/Packmaster generate for you):

     {
       "url": "dist/index.html"
     }

     With this file in place, double-clicking the Shell binary opens your game directly — no arguments needed. This is what actually makes the container double-click-runnable.

   • Pass the path as an argument, for a quick check without creating any file:

     ./play dist/index.html

     Any argument on the command line skips launch.json entirely, so use this for testing, not for what you hand to a player.

launch.json also accepts window_size and extra args — see the flags table further down for what each corresponds to; a hand-written file only needs url to work.

Building the Shell yourself

This is the least important section for most people. You only need this if you're working on Roves itself, need a flag Packmaster doesn't expose, or want to understand what's actually happening underneath the paths above.

Roves' Shell is not a from-scratch engine — it's a vendored, customized fork of Servo, built with Servo's own mach tooling. Every customization on top of stock Servo (no browser chrome, the single-executable bundle, the boot splash, the roves: protocol bridge, optional Steam) is tracked, file by file, in CUSTOMIZATIONS.md.

git clone https://github.com/DRincs-Productions/roves
cd roves

Build and bundle

./mach bootstrap
./mach build --release

Add --features steam if you need the Steam bridge compiled in.

./mach bundle --content-dir path/to/dist --output release

mach bundle is what turns that build plus your dist into the container described above, producing exactly the same launch.json-driven layout — no separate launcher process, no roves-content-packer binary shipped alongside it (packed-content extraction happens in-process, inside the engine binary itself, which already links that crate as a library):

Flags

Distributing installers

Each platform also has one installable alternative to the portable output above, wrapping the exact same staged files — nothing extra is left behind once the installer is built: