FS.GG.Game.Render 0.19.0

FS.GG.Game.Render

Pure Scene adapter for FS.GG.Game — projects FS.GG.Game.Core simulation primitives (Point/Rect/Cell and pathfinding routes) onto FS.GG.UI.Scene drawables at the render edge (ADR-0022 §2).

This is the one place in FS.GG.Game that reaches up to Rendering: Game.Core reaches up to nothing; this adapter reaches up to FS.GG.UI.Scene (FSharp.Core-only, Skia-free). Deterministic, no I/O.

FS.GG.Game.Render ──▶ FS.GG.UI.Scene   (adapter reaches UP — allowed)
FS.GG.Game.Core   ──▶ (nothing)        (bottom layer)

Renderer backend selection

RendererSelection is a pure Elmish init/update for choosing how a game state is presented at runtime. RendererRegistry<'State> holds the adapters for one game-state type; a backend is offered (RendererRegistry.available) only when an adapter is registered for it. RendererRegistry.svg registers the existing Scene path as the default SVG backend. RendererBackend.Pixi and RendererBackend.Babylon are declared but this package ships no adapter for either (the Pixi and Babylon adapters live in the Fable-only FS.GG.Game.Render.Browser package), so a backend nobody registered is refused with RendererRefusal.Unavailable.

Switching (RendererMsg.SelectBackend) keeps Model.State and emits Unmount/Mount effects. RendererHost performs those effects, owns the mounted backend's resources outside the model and disposes each mount exactly once.

Ordering contract: unmount-then-mount, with SVG fallback.

• A switch always unmounts the current backend before it mounts the next one, so two backends never own resources at the same time.
• Each Mount carries a new attempt token. Failure feedback from a superseded attempt is ignored.
• If a non-default backend fails to mount, or throws from Present, the selection falls back to SVG with the same game state.
• If SVG itself fails to mount, nothing is mounted and Model.Status is Failed, with every reason that led there. Selecting SVG again, or the next game state, retries it. An unrelated refusal never hides that failure.
• No adapter exception escapes RendererHost.Run. A throwing Dispose becomes DisposeFailed, and the pending Mount still runs.
• A Present that throws is contained (nothing escapes Run), the host releases that mount, and the model mounts again with the latest state: SVG replaces a failed canvas backend, and the default SVG backend is remounted itself (RendererMsg.PresentFailed). Refusal names the cause. If the remount fails too, Status is Failed with the cause, and the next StateChanged mounts again, so a throwing Present is never a silent blank.
• A mount is fixed to the viewport it was created for. RendererRegistry.withViewport backend viewport declares how a state sizes that backend (the remount rule): when the viewport changes between states, the model unmounts and mounts the backend with the new state instead of presenting, so a game never remounts inside its own Present. A game whose viewport comes from the window keeps it in its state. A backend with no declaration owns its viewport itself (it may resize in place).
• Adapters must not dispatch messages synchronously from Mount, Present or Dispose, because Run is not reentrant.

Three-adapter authoring path

For one game-state type, the SVG, Pixi and Babylon adapters differ only in the surface that presents a FS.GG.UI.Scene; what the game writes is the Scene description of its state. SceneSurface.create backend mountScene is a backend's surface, SceneSurface.adapter view surface is its adapter for a state type, and SceneRenderers<'State> is the declaration a game makes once. The kit's types are opaque and built by functions, so later additions do not break callers:

let renderers =
    SceneRenderers.create view svgMountScene        // the shared view; SVG is always declared
    |> SceneRenderers.withSurface pixiSurface
    |> SceneRenderers.withSurface babylonSurface
    // optional: |> SceneRenderers.withView RendererBackend.Babylon babylonView
let registry = SceneRenderers.registry renderers    // offers exactly the declared backends

In the browser host (src/Render.Browser), BrowserRenderers.declare container options route view declares all three surfaces at one size, and BrowserRenderers.start route registry state onChange starts the RendererDriver and binds the LateFailureRoute that Pixi reports an asynchronous initialisation failure to, so a game never wires failBackend by hand. Each Pixi mount captures the driver bound when it is created, so a late report never reaches a driver started later on the same route.

Walkthrough for a new game:

1. Generate the module. scripts/new-game-renderers.sh --namespace MyGame.Client --module Renderers --state MyGame.Model --label "My game" --output src/Client/Renderers.fs writes a module from eng/render-kit/GameRenderers.fs.template with view, declare, start and conformance.
2. Write view. Replace the placeholder (which shades the scene by the state's hash) with a projection of the state onto SceneNode values. The canvas backends draw Rectangle, FilledEllipse and Circle and treat Group, Translate and Empty as structure; other nodes are counted as unsupported and skipped. Use the data constructors, not the .NET-only Scene builder or Adapter, so the file also compiles with Fable.
3. Start and switch. let driver = Renderers.start container initial onChange. Dispatch RendererMsg.StateChanged state for each new state, and RendererMsg.SelectBackend backend to switch at runtime. Offer RendererSelection.available driver.Model in the selector. The game state survives every switch.
4. Prove it. Run the conformance kit in a browser test: BrowserConformance.installContextProbe (), then RendererConformance.run (Renderers.conformance container states shows), and require RendererConformance.failures to be empty. states must look different from each other, and shows reads a backend's output back (the SVG DOM, or a pixel through BrowserConformance.readPixel) and must reject a state that is not shown.

The reference game does exactly this: src/ReferenceGame/Renderers.fs declares its renderers, and the browser smoke runs the kit on it on all three real backends. tests/Render.Browser.Smoke/GeneratedRenderers.fs is the generator's unedited output, compiled and run through the kit too.

Registering a ready adapter

A game with its own retained SVG surface (selectable objects, accessible labels, a camera, an input host) has no Scene to hand to RendererRegistry.svg, and SceneSurface would flatten that surface into one non-selectable object. RendererRegistry.create adapter registers the ready adapter as the default instead: no placeholder is built, and Error says why when the adapter is not an SVG adapter (only SVG can be the default). Canvas adapters join with RendererRegistry.register, and the kit runs on the result like on any other registry.

match RendererRegistry.create { Backend = RendererBackend.Svg; Mount = mountMyBoard } with
| Ok registry -> registry |> RendererRegistry.register myCanvasAdapter
| Error reason -> failwith reason

In the browser host, RetainedSvgSurface is that adapter for any game whose state projects onto a FS.GG.UI.Scene.RetainedScene: RetainedSvgSurface.create container label size scene, with withSelection selected onSelect and withInput attach, and RetainedSvgSurface.registry. It owns the scene revisions, keeps the user's camera across presents, keeps the surface's selection in step with the state (and reports the user's own selections), and releases the input host with the mount.

The conformance kit

RendererConformance.run takes a ConformanceSubject and returns one ConformanceResult per requirement. It needs no test framework, so an Expecto suite, a browser page or a script can each report the results. It instruments the registry's adapters (mounts, presented states and disposals are counted, behaviour unchanged) and drives a host through the Elmish messages:

Resources must observe the page independently of the adapter. BrowserConformance.resources counts SVG roots, canvases, Babylon engines, Pixi applications and live WebGL contexts. The kit also asserts its subject: a probe that never sees a mounted backend fails, and so does fewer than two distinct states. In .NET, RendererConformance.subject uses the in-process host (RendererConformance.inProcess); withStart, withWaitUntil and withLateFailure adjust it. tests/Game.Render.Tests/RendererConformanceTests.fs shows the shape, with negative controls.

Interaction contract (FS.GG.Game#751)

A game whose play is selection stays playable on every backend through one contract, SceneInteraction:

let selection = SelectionRoute.create ()
let interaction = SceneInteraction.create objects selected select   // 'State -> objects; 'State -> id; request -> 'State -> 'State
let renderers =
    BrowserRenderers.declare container options route view
    |> SceneRenderers.withInteraction interaction selection
// When the game runs: send each SelectionRequest to the game's own update.
selection |> SelectionRoute.bind (fun request -> game.Dispatch(SelectionChanged request))

• Hit test. A primary pointer press on the topmost object containing the point asks to Select it. SVG uses the browser's own hit test over transparent hit shapes, Pixi its EventBoundary over hit regions kept off the stage, Babylon Scene.pick through its camera over invisible meshes. All three agree with the reference SceneInteraction.hitTest.
• Keyboard. The surface is focusable (role="application", tabindex="0"). Arrows move the focus, Enter or Space selects and Escape clears: the retained SVG surface's keys, through SceneInteraction.key on canvases.
• Accessible mirror. An HTML group (data-scene-controls, data-renderer) holds one button per object in order, labelled, with aria-pressed on the selected one, and a polite status naming the selection.
• Input-host disposal. The mount's Dispose removes the input host's listeners and the mirror.

The selection is game state: a backend shows it and asks to change it (only for a change), so it survives every switch. RendererConformance.withInteraction interaction route probe adds the interaction section; BrowserConformance.interactionProbe container plays the real input hosts with real input: the page asks the test driver (window.__fsggInput, Playwright page.mouse and page.keyboard; tests/Render.Browser.Smoke/driver/run-smoke.mjs) for each click, move and key, never dispatching synthetic events. A page-level census (BrowserConformance.installInputProbe) counts the input hosts' listeners and writes to their live status. The mirror writes only what changed, so focus and the live region stay quiet across Presents. The SVG surface's retained host (FS.GG.UI.Scene 0.31.0) still rewrites its mirror on each Present; the smoke asserts that known gap until FS.GG.Rendering#1504 lands. The reference game (ReferenceRenderers.interaction) selects its token and aim marker and draws a ring around the selection.

Adapter authors keep two obligations the kit checks:

• Mount returns Error instead of acquiring half a backend, and Dispose releases everything, including the WebGL context.
• An adapter that initialises asynchronously reports a late failure only while its own mount is undisposed. The driver cannot tell two mounts of the same backend apart.

Fable and the browser host

The package also ships a bounded Fable source view (fable/RendererSelection, SceneInteraction, SceneRenderers and RendererConformance, each .fsi and .fs) so a Fable-compiled browser host can register adapters against the same RendererRegistry and run the conformance kit. Adapter and DefaultKeymap are .NET-only and are not in that view. The view is first published in 0.18.0 (0.17.0 carries no Fable view). Its packed fable/FS.GG.Game.Render.fsproj lists its sources unconditionally, because Fable does not evaluate MSBuild conditions in a package's project file. An earlier unreleased form, added after v0.17.0 by #733, used conditional item groups, and they would have compiled no sources for a package consumer. It was fixed before publication.

The browser host is the FS.GG.Game.Render.Browser package (from src/Render.Browser, first published in 0.18.0). It mounts the existing SVG surface (SvgBrowser), hosts the BabylonJS and PixiJS adapters (over the Templates#809 and #808 bindings, shipped as source), and adds BrowserRenderers and BrowserConformance for the authoring path. A game references that one package from its Fable project. scripts/test-render-browser-host.sh proves the host in a headless browser and compiles a clean consumer of both packages (tests/release/test-render-browser-package-consumer.sh).

House style: .fsi is the sole public surface; net10.0; -preview channel. See FS-GG/FS.GG.Game and ADR-0022.