GitHub - mystralengine/mystralnative: Native WebGPU JS runtime with SDL3

Note

Mystral Native.js is in early alpha. The core features work — execute JS against WebGPU, Canvas 2D, Web Audio, and fetch — with runtimes available for macOS, Windows, and Linux. Embedding is available for iOS and Android, with a future goal of console support. To see a production build, check out the Sponza demo on itch.io.

curl -fsSL https://mystralengine.github.io/mystralnative/install.sh | bash

irm https://mystralengine.github.io/mystralnative/install.ps1 | iex

# macOS / Linux
cd ~/.mystral
mystral run examples/triangle.js
mystral run examples/mystral-helmet.js  # GLTF loading demo

# Windows (PowerShell)
cd $HOME\.mystral
mystral run examples\triangle.js
mystral run examples\mystral-helmet.js  # GLTF loading demo

unzip mystral-macOS-arm64-v8-dawn.zip
cd mystral-macOS-arm64-v8-dawn
./mystral run examples/triangle.js

git clone https://github.com/mystralengine/mystralnative.git
cd mystralnative

# Install bun if you don't have it
curl -fsSL https://bun.sh/install | bash

# Download dependencies
bun install
bun run deps:download

# Configure with V8 + Dawn (recommended)
cmake -B build \
  -DMYSTRAL_USE_V8=ON \
  -DMYSTRAL_USE_DAWN=ON \
  -DMYSTRAL_USE_QUICKJS=OFF \
  -DMYSTRAL_USE_WGPU=OFF

# Build
cmake --build build --parallel

# Run an example
./build/mystral run examples/triangle.js

// hello-triangle.js
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const context = canvas.getContext("webgpu");
const format = navigator.gpu.getPreferredCanvasFormat();
context.configure({ device, format });

const shader = device.createShaderModule({
  code: `
    @vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
      var pos = array<vec2f, 3>(
        vec2f( 0.0,  0.5),
        vec2f(-0.5, -0.5),
        vec2f( 0.5, -0.5)
      );
      return vec4f(pos[i], 0.0, 1.0);
    }

    @fragment fn fs() -> @location(0) vec4f {
      return vec4f(1.0, 0.5, 0.2, 1.0); // orange
    }
  `,
});

const pipeline = device.createRenderPipeline({
  layout: "auto",
  vertex: { module: shader, entryPoint: "vs" },
  fragment: { module: shader, entryPoint: "fs", targets: [{ format }] },
});

function render() {
  const encoder = device.createCommandEncoder();
  const pass = encoder.beginRenderPass({
    colorAttachments: [{
      view: context.getCurrentTexture().createView(),
      clearValue: { r: 0.1, g: 0.1, b: 0.1, a: 1 },
      loadOp: "clear",
      storeOp: "store",
    }],
  });
  pass.setPipeline(pipeline);
  pass.draw(3);
  pass.end();
  device.queue.submit([encoder.finish()]);
  requestAnimationFrame(render);
}
render();

mystral run hello-triangle.js

# Basic WebGPU triangle
mystral run examples/triangle.js

# 3D rotating cube
mystral run examples/simple-cube.js

# Full 3D scene with PBR lighting (Dawn builds only)
mystral run examples/mystral-helmet.js

# Day/night cycle demo with atmosphere
mystral run examples/daynight.js

# Sponza palace with day/night, torches, fireflies (Dawn builds only)
mystral run examples/sponza.js

# Three.js WebGPU (requires bundling, see docs site for full guide)
npm install three@0.182.0
npx esbuild examples/threejs-cube-src.js --bundle --outfile=threejs-bundle.js --format=esm --platform=browser
mystral run threejs-bundle.js

# PixiJS v8 WebGPU (requires bundling, WebGPU renderer only)
npm install pixi.js@^8.0.0
npx esbuild examples/pixijs-sprite-src.js --bundle --outfile=pixijs-bundle.js --format=esm --platform=browser
mystral run pixijs-bundle.js

# Custom window size
mystral run examples/simple-cube.js --width 1920 --height 1080

# Watch mode — auto-reload on file changes
mystral run game.js --watch

# Headless screenshot (for CI/testing)
mystral run examples/simple-cube.js --headless --screenshot output.png

# Compile into a standalone binary (Linux/Windows)
mystral compile game.js --include assets --out dist/my-game
./dist/my-game

# Create a standalone .bundle for macOS .app packaging
mystral compile game.js --include assets --bundle-only --out dist/game.bundle

# Full production build of Sponza demo (strips binary, filters assets, creates .app + .zip)
./scripts/build-production.sh

# Build a different demo
./scripts/build-production.sh --demo helmet

# Skip cmake rebuild (repackage with existing binary)
./scripts/build-production.sh --skip-build

mystral run <script.js> [options]      Run a JavaScript/TypeScript file
mystral compile <entry.js> [options]   Bundle into single executable
mystral --version                      Show version
mystral --help                         Show help

Run Options:
  --width <n>           Window width (default: 1280)
  --height <n>          Window height (default: 720)
  --title <str>         Window title
  --headless            Run with hidden window
  --watch, -w           Auto-reload on file changes
  --screenshot <file>   Take screenshot and quit
  --frames <n>          Frames before screenshot (default: 60)
  --quiet, -q           Suppress output except errors

Compile Options:
  --include <dir>       Asset directory to bundle (repeatable)
  --output, -o <file>   Output path
  --bundle-only         Create .bundle file (for .app packaging)
  --root <dir>          Root directory for bundle paths (default: cwd)

┌─────────────────────────────────────────────────────────────┐
│                   Your Game (JS/TS)                          │
│             Uses WebGPU, Canvas, Audio APIs                  │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                  MystralNative Runtime                       │
│   WebGPU Bindings │ Canvas 2D │ Audio │ fetch │ Input       │
└─────────────────────────────────────────────────────────────┘
        │                │           │        │
        ▼                ▼           ▼        ▼
   ┌─────────┐    ┌───────────┐  ┌─────┐  ┌──────┐  ┌───────┐
   │ V8/JSC/ │    │   Dawn/   │  │SDL3 │  │libcurl│  │ libuv │
   │ QuickJS │    │ wgpu-native│  │     │  │      │  │       │
   └─────────┘    └───────────┘  └─────┘  └──────┘  └───────┘

cmake -B build \
  -DMYSTRAL_USE_V8=ON \
  -DMYSTRAL_USE_DAWN=ON \
  -DMYSTRAL_USE_QUICKJS=OFF \
  -DMYSTRAL_USE_WGPU=OFF

cmake -B build -DMYSTRAL_USE_V8=ON       # Recommended — Full V8 with JIT
cmake -B build -DMYSTRAL_USE_QUICKJS=ON  # Smallest binary, good for CI
cmake -B build -DMYSTRAL_USE_JSC=ON      # macOS/iOS system engine

cmake -B build -DMYSTRAL_USE_DAWN=ON     # Recommended — Chrome's implementation
cmake -B build -DMYSTRAL_USE_WGPU=ON     # Rust implementation, best iOS/Android support

#include "mystral/runtime.h"

int main() {
    mystral::RuntimeConfig config;
    config.width = 1280;
    config.height = 720;
    config.title = "My Game";

    auto runtime = mystral::Runtime::create(config);
    runtime->loadScript("game.js");
    runtime->run();
    return 0;
}