KnockBox.Platform 1.0.0-prerelease

KnockBox.Platform

Hosting SDK for KnockBox game plugins.

KnockBox is a Blazor Server host that loads party games as runtime-discovered plugins. This package provides the bootstrap surface a host (dev or production) needs to discover plugins, wire their services into DI, serve their static assets, and render them through the platform's Home / Error / NotFound chrome.

Who references this? Your host project — a local DevHost for development, or a production host binary. Who does NOT reference this? Game plugins. A plugin referencing KnockBox.Platform breaks runtime AssemblyLoadContext isolation and will cause type-identity failures at plugin load. Plugins reference only KnockBox.Core.

Minimal host

using KnockBox.Platform;

var builder = WebApplication.CreateBuilder(args);

// Explicit-mode: register each game module directly. Ideal for DevHosts.
builder.AddKnockBoxPlatform(options =>
{
    options.PluginDiscovery = PluginDiscoveryMode.Explicit;
    options.AddGameModule<MyGameModule>();
    // options.AddGameModule<AnotherGameModule>();
});

var app = builder.Build();
app.UseKnockBoxPlatform();
app.Run();

For a production host that loads plugins from a directory:

builder.AddKnockBoxPlatform(options =>
{
    options.PluginDiscovery = PluginDiscoveryMode.Directory; // default
    options.PluginsPaths.Clear();
    options.PluginsPaths.Add("games");                  // relative to AppContext.BaseDirectory
    options.PluginsPaths.Add("/var/lib/knockbox/games");  // or an absolute path
    options.Branding.AppTitle = "My KnockBox Party";
    options.Branding.HomeHeroTitle = "My KnockBox Party";
});

Each plugin subfolder under the configured PluginsPaths (games/MyGame/, games/AnotherGame/, …) is loaded into its own AssemblyLoadContext. The loader reflects each assembly for IGameModule implementations, activates them, and calls RegisterServices.

Host override hook: IGameAvailabilityService

The Platform ships a default AllGamesEnabledService that reports every game as enabled. Hosts that want per-game gating (disable cards, admin toggles, etc.) should register their own implementation on the service collection before calling AddKnockBoxPlatform:

builder.Services.AddSingleton<IGameAvailabilityService, MyFileBackedAvailabilityService>();
builder.AddKnockBoxPlatform(options => { ... });

The order matters: AddKnockBoxPlatform uses TryAddSingleton so a pre-existing registration wins. If the default fallback was installed (because the host registered after AddKnockBoxPlatform or forgot to register at all), the Platform logs an Information-level message at startup so misorders are diagnosable.

Plugin discovery modes

Configuration options

Extension points

• AddKnockBoxPlatform(configure) — registers all platform services, performs plugin discovery, configures Razor components.
• UseKnockBoxPlatform() — convenience wrapper around UseKnockBoxPlatformMiddleware() + MapKnockBoxPlatformEndpoints(). Good for dev hosts with no host-specific middleware.
• UseKnockBoxPlatformMiddleware() — Serilog request logging, exception handler, HSTS, status-code pages, HTTPS redirect, anti-forgery. Call this before any host-specific middleware (auth, rate limiting, admin port filtering).
• MapKnockBoxPlatformEndpoints() / MapKnockBoxPlatformEndpoints<TRootComponent>() — maps static assets, per-plugin /_content/{PluginName} mounts, and Blazor endpoints. Use the generic overload if your host supplies its own App.razor.
• IGameAvailabilityService — override with a host-supplied implementation (e.g., file-backed or admin-toggled) to gate individual games. The platform registers a default "all enabled" fallback via TryAddSingleton.

Package contents at a glance

• Bootstrap extensions: KnockBoxPlatformExtensions, KnockBoxPlatformOptions, KnockBoxPlatformOptionsExtensions.
• Platform pages: Home, Error, NotFound, MainLayout, ReconnectModal (served at /, /error, /not-found).
• Lobby management: LobbyService, LobbyCodeService (6-character profanity-filtered codes).
• Session infrastructure: SessionServiceProvider, SessionTokenProvider, UserService, TickService.
• Client storage: ILocalStorageService, ISessionStorageService (JS-interop browser storage wrappers).
• Profanity filter: Aho-Corasick automaton over an embedded English word list; used by LobbyCodeService.

Developer reference

Full end-to-end walkthrough for building a plugin (from scaffolding through shipping):

https://github.com/jcub1011/KnockBox/blob/main/docs/making-a-game-plugin.md

Related packages

• KnockBox.Core — the contract package plugins reference.
• KnockBox.Templates — dotnet new scaffolding for a plugin + dev host + tests.

License

MIT. See LICENSE.txt in the repository.