118 lines
5.1 KiB
Markdown
118 lines
5.1 KiB
Markdown
# Examples/Web — raylib-cs in the browser (WebAssembly)
|
|
|
|
A small browser app that runs raylib examples in the browser via WebAssembly, with a dropdown to
|
|
switch between them. It exists to **prove the `Raylib-cs` NuGet package's `browser-wasm` support
|
|
works end-to-end**: the package's `buildTransitive/Raylib-cs.targets` automatically links the
|
|
shipped `runtimes/browser-wasm/native/raylib.a` (and adds `-sUSE_GLFW=3`) into the .NET wasm
|
|
runtime. The browser host lives in `Examples/Web`, while `Examples.csproj` remains the single
|
|
examples project.
|
|
|
|
The browser-wasm configuration is enabled only when publishing `Examples` with
|
|
`RuntimeIdentifier=browser-wasm`, so normal solution builds do not require the `wasm-tools`
|
|
workload.
|
|
|
|
## Prerequisites
|
|
|
|
- .NET 10 SDK
|
|
- `dotnet workload install wasm-tools`
|
|
- The `Raylib-cs` package matching `$(RaylibCsVersion)` (see `Directory.Build.props`) — from
|
|
nuget.org, or built locally into the repo's `./nuget` feed (`dotnet pack Raylib-cs -c Release --output nuget`).
|
|
|
|
## Build
|
|
|
|
```bash
|
|
dotnet publish Examples -f net10.0 -r browser-wasm -c Release
|
|
# -> Examples/bin/Release/net10.0/browser-wasm/AppBundle/
|
|
```
|
|
|
|
### Toolchain caveat
|
|
|
|
If the link step fails with:
|
|
|
|
```
|
|
wasm-opt: Unknown option '--enable-bulk-memory-opt'
|
|
```
|
|
|
|
your installed `wasm-tools` workload (Binaryen) is out of sync with the SDK — emscripten passes a
|
|
feature flag the bundled `wasm-opt` doesn't understand (commonly caused by a stale workload band
|
|
or a conflicting system EMSDK on PATH/`$EMSDK`). Proper fix:
|
|
|
|
```bash
|
|
dotnet workload update
|
|
```
|
|
|
|
`Examples.csproj` defaults browser-wasm publishes to unoptimized native linking so the standard
|
|
publish command works on affected local toolchains. A fully optimized publish can override those
|
|
MSBuild properties after updating the workload/toolchain.
|
|
|
|
## Run
|
|
|
|
WebAssembly must be served over HTTP (not `file://`):
|
|
|
|
```bash
|
|
dotnet serve -d Examples/bin/Release/net10.0/browser-wasm/AppBundle # dotnet tool install -g dotnet-serve
|
|
# or: npx http-server Examples/bin/Release/net10.0/browser-wasm/AppBundle
|
|
```
|
|
|
|
Open the printed URL and use the **Example** dropdown to switch examples.
|
|
|
|
## Canvas scaling modes
|
|
|
|
The browser host keeps raylib's internal render buffer fixed to `800x450` and applies display
|
|
scaling in CSS. Use the **Scale** dropdown (or `?scale=` query param) to choose behavior:
|
|
|
|
- `native` (default): exact `800x450` CSS pixels (1x), no resizing.
|
|
- `integer`: largest whole-number multiple that fits the viewport, centered with letterboxing.
|
|
Best for pixel-perfect presentation.
|
|
- `fit`: fills available viewport while preserving aspect ratio (can be fractional, less crisp on
|
|
some DPI/zoom combinations).
|
|
|
|
Scaling is computed in **device pixels first** and then converted back to CSS pixels using current
|
|
`devicePixelRatio`, which decouples the modes from needing a specific browser zoom level on
|
|
125%/150% OS scale displays.
|
|
|
|
`main.js` also shows runtime diagnostics in the status bar (`DPR`, CSS size, backing size, scale)
|
|
to help debug OS scaling / browser zoom behavior across monitors.
|
|
|
|
### Manual validation matrix (expected behavior)
|
|
|
|
- OS scale `100%`, browser zoom `100%`: `integer` should appear crisp and stable (`Scale 1.00` or
|
|
higher if viewport allows).
|
|
- OS scale `125%` and `150%`, browser zoom `100%`: `integer` should stay crisp (no subpixel CSS
|
|
scaling); perceived physical size changes with OS scale are expected.
|
|
- Browser zoom `80%`, `100%`, `125%`: `integer` should continue using whole-number scaling;
|
|
`fit` may show softening at non-integer effective scales.
|
|
- `native` mode should always report `CSS 800x450` and `Scale 1.00`.
|
|
- During window resize, there should be no frame-by-frame jitter because scale updates run on
|
|
resize/mode changes, not per animation frame.
|
|
|
|
## How it works
|
|
|
|
A browser can't run raylib's blocking `while (!WindowShouldClose())` loop (it would freeze the
|
|
page), so frames are driven from JavaScript:
|
|
|
|
- `Host.Main()` calls `InitWindow` once and selects the default example (`main.js` runs it via
|
|
`runMain()`).
|
|
- `main.js` binds the page `<canvas>` to the runtime, then calls `Host.UpdateFrame()` every
|
|
`requestAnimationFrame` tick. `UpdateFrame`, `SetExample`, and `GetExampleNames` are `[JSExport]`.
|
|
- Each base example implements `IExample` (`Init` / `Update` / `Unload`) in `#if BROWSER` partials.
|
|
The host owns the window;
|
|
examples never call `InitWindow`/`CloseWindow`.
|
|
|
|
## Adding more examples
|
|
|
|
For a new desktop example (`../Core/...`, `../Shaders/...`, etc.), add a browser partial
|
|
(`*.Browser.cs`) that implements `IExample` and mirrors the split of its monolithic `Main`:
|
|
|
|
```
|
|
Main() { <setup>; while(!WindowShouldClose()){ <body> } <cleanup> }
|
|
-> Init() { <setup, minus InitWindow/SetTargetFPS> } // loop-spanning locals become fields
|
|
Update(){ <body> } // keep BeginDrawing..EndDrawing
|
|
Unload(){ <cleanup, minus CloseWindow> }
|
|
```
|
|
|
|
Then add `new YourExample()` to the `Examples` list in `Host.cs`.
|
|
|
|
Examples that load files (`resources/...`) also need those assets in the wasm virtual filesystem.
|
|
`Examples.csproj` bundles `../resources/` into the browser app when publishing with
|
|
`RuntimeIdentifier=browser-wasm`.
|