Gondwana.Blazor 2.6.1

Gondwana.Blazor

Gondwana.Blazor provides Blazor adapters for rendering and input, enabling Gondwana games to run as ASP.NET Blazor WebAssembly applications with standard cross-platform WASM support.

It mirrors the Gondwana.Avalonia package but targets the Blazor component model instead of Avalonia UI.

Features

• WebGL rendering through SKGLView and GpuBackbuffer, with no per-frame pixel transfer to JavaScript
• Preserved bitmap rendering through Canvas 2D for compatibility and diagnostics
• Keyboard input integration via Blazor keyboard events on the canvas element
• Mouse / pointer input integration
• Touch input integration
• Browser localStorage persistence through BrowserLocalStorageEngineConfigurationStore
• Browser developer-console logging through BrowserConsoleLoggerProvider
• External-link launching through BlazorExternalUriLauncher for Widgets such as HyperlinkWidget and AboutBox
• BlazorKey enum mapping browser KeyboardEvent.code values to integer key codes

Installation

dotnet add package Gondwana.Blazor

Usage

Add <BlazorGpuRenderSurfaceComponent> to your Blazor page or layout and capture a reference to it using @ref:

@using Gondwana.Blazor.Rendering

<BlazorGpuRenderSurfaceComponent @ref="_surface" style="width: 800px; height: 600px;" />

Then initialize your game host in the component's OnAfterRenderAsync:

@code {
    private BlazorGpuRenderSurfaceComponent _surface = null!;
    private MyGameHost? _host;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (!firstRender) return;
        _host = new MyGameHost(_surface);
        _host.Initialize();
    }
}

Derive the host from BlazorGpuGameHost. The WebGL component uses SKGLView's animation loop as the single browser requestAnimationFrame source. Each WebGL paint callback advances the timer-driven engine and renders a new scene frame only when Gondwana's foreground cadence requires one; otherwise it re-presents the current GPU backbuffer. Rendering remains entirely inside the WebGL paint callback while its GPU context is current.

Render resolution

Engine.Instance.Configuration.RenderScale establishes the Backbuffer resolution from the first valid canvas size. Later canvas resizes change presentation only, preserving aspect ratio and centering the image. Changing RenderScale explicitly establishes a new resolution from the current canvas dimensions. RenderScalingFilter selects Linear or NearestNeighbor, and Host.PresentationScale reports the derived fit. Pointer input is normalized into logical ScreenPx before routing; canvas margins are outside the game area. Existing browser/DPI sizing semantics are preserved.

Linear WebGL scaling uses a scoped GPU texture snapshot because Skia's direct DrawSurface does not expose sampling options. It performs no CPU pixel transfer. Nearest-neighbor and unscaled presentation retain the direct-surface path. See viewport scaling notes.

Bitmap compatibility path

The original Canvas 2D path remains available. Use BlazorBitmapRenderSurfaceComponent with a host derived from BlazorGameHost when CPU-backed rendering or bitmap frame inspection is needed. The bitmap path retains Gondwana's JavaScript requestAnimationFrame loop.

Key codes

BlazorKeyboardAdapter uses (int)BlazorKey values as key codes. Use BlazorKeyboardAdapter.GetKeyCodeFromString("ArrowLeft") to resolve a key name at runtime, or use the BlazorKey enum directly:

Engine.Instance.Input.KeyboardEventPoller!.StartMonitoringKey(
    (int)BlazorKey.Space, "Jump");

Browser console logging

Blazor game hosts automatically attach BrowserConsoleLoggerProvider after Gondwana configures the requested log level. Normal ILogger calls therefore appear in the browser developer console while continuing to use Gondwana's logging mode and queue.

For example:

Engine.Logger.LogInformation(
    "Renderer initialized at {Width}x{Height}",
    width,
    height);

With the default EngineLoggingMode.Asynchronous, the game or engine call enqueues the record and returns; the logging worker later invokes the browser-console provider. The provider uses the .NET WebAssembly console bridge rather than the desktop Microsoft.Extensions.Logging.Console provider.

Warning, error, and critical records use Console.Error; lower levels use Console.Out.

Browser configuration and external links

Use BrowserLocalStorageEngineConfigurationStore when the same EngineConfiguration should persist in browser localStorage instead of a desktop file:

var store = new BrowserLocalStorageEngineConfigurationStore(
    JS,
    "my-game.configuration",
    autoSave: true);

host.InitializeWithConfigurationStore(store);

Widgets that open an external URI can use the browser implementation directly:

var launcher = new BlazorExternalUriLauncher(JS);

Widget text input

TextBoxWidget uses host keyboard codes. For Blazor-hosted text boxes, apply the built-in Blazor mapping:

BlazorTextBoxInput.Configure(textBox);

This configures the text box's special-key codes and printable-character resolver for BlazorKey values without changing the public Blazor keyboard-code contract.

Touch input

Enable touch input by calling InitializeBlazorTouchAdapter:

Engine.Instance.InitializeBlazorTouchAdapter(renderSurface);

After initialization, the touch system is accessible via Engine.Instance.Input.TouchEventPoller.

Documentation

• Source Code
• Architecture & Guides
• API Reference (Doxygen)
• Release History

Related Packages

• Gondwana --- Core engine
• Gondwana.Audio.Browser --- Browser-based audio playback support
• Gondwana.Blazor.Hosting --- Blazor-specific game host that integrates rendering and input into the Gondwana lifecycle
• Gondwana.Widgets --- UI widget library for creating in-game menus, HUDs, and overlays

License

MIT