Reference

Web API (JSON commands)

The JSON protocol shared by Pixel Streaming, the kiosk WebSocket and any transport you build: commands, responses, the catalog and the image-set manifest.

Every front end speaks the same JSON. The controller's Handle Json Command takes a command string; On Json Response emits response strings. The Pixel Streaming and kiosk controllers just move these messages. Neither adds a command of its own.

Safety rules that hold over every transport:

  • A command is at most 64 KiB.
  • Asset paths and console commands are never accepted.
  • Every ID must exist in the connected product's catalog.
  • A command that would break a compatibility rule is refused whole.

Commands

{"command":"material","zone":"body_paint","id":"Red","requestId":"r1"}
{"command":"variant","zone":"wheels","id":"sport"}
{"command":"style","id":"sport_package"}
{"command":"poi","id":"Wheel"}
{"command":"play","id":"doors"}
{"command":"reverse","id":"doors"}
{"command":"pause"}
{"command":"resume"}
{"command":"stop"}
{"command":"panel","visible":false}
{"command":"reducedMotion","enabled":true}
{"command":"reset"}
{"command":"state"}
{"command":"catalog"}
{"command":"import","configuration":{"version":2,"product":"Lamp","materials":{},"variants":{}}}
{"command":"keepAlive"}
{"command":"product","id":"Sofa"}
{"command":"skipIntro"}
CommandNotes
material, variantChange one zone. Only that zone is touched.
styleApply a style by ID.
poiFly to a camera by ID.
play, reverse, pause, resume, stopMotion sequences by ID.
panelWithout a HUD it only reframes the camera; the browser owns its panel.
reducedMotionOverrides the product setting for this session. Omit enabled to hand control back.
resetCatalog defaults.
state, catalogAsk for the current state or the full catalog.
importApply a version-2 preset.
keepAliveCancels a pending kiosk idle reset and changes nothing else.
product, skipIntroProduct switcher and intro.

While an intro plays, configuration commands, poi, reset and import are refused with Intro playing. product, skipIntro, panel and read-only commands still work.

Blueprint sending a JSON variant command through the BAKR controller
Handle JSON Command lets a custom integration send the same commands used by web and kiosk clients.

Responses

{"type":"ack","command":"variant","accepted":true,"requestId":"r1"}
{"type":"state","configuration":{"version":2,"product":"Lamp","materials":{},"variants":{}}}
{"type":"poi","id":"Wheel","zone":"wheels"}
{"type":"motion","id":"doors","status":"Playing","progress":0.46}
{"type":"busy","busy":true}
{"type":"idle","phase":"warning","seconds":10}
{"type":"product","id":"Sofa"}
{"type":"intro","product":"Sofa","status":"started","skippable":true}
{"type":"error","message":"Unknown variant/zone: wheels / Invalid"}
  • ack means accepted, not finished. Watch state for the applied result and error for failures. Several quick commands can merge into one state.
  • requestId is echoed on the ack only.
  • poi, motion and busy report every change, whatever caused it, so a page stays in sync with things it did not start.
  • idle phases are warning, cancelled and reset.
  • intro statuses are started, finished and skipped.
Blueprint binding an On JSON Response event
The JSON response event provides results and updates to a custom integration.

The catalog

catalog returns everything a front end needs to build itself. Adding an option to the product is enough for it to appear.

{
  "type": "catalog",
  "version": 2,
  "product": "Lamp",
  "productLabel": "Studio Lamp",
  "titles": {"materials": "Materials", "variants": "Variants", "motion": "Motion",
             "styles": "Styles", "summary": "Configuration Summary"},
  "zones": [
    {"id": "Shade", "label": "Shade",
     "materials": [{"id": "Red", "label": "Signal Red", "hex": "C8102EFF"}],
     "variants": []}
  ],
  "styles": [{"id": "classic", "label": "Classic",
              "selection": {"materials": {"Shade": "Silver"}, "variants": {}}}],
  "pois": [{"id": "Overview", "label": "Overview", "zone": "", "interior": false}],
  "sequences": [{"id": "doors", "label": "Doors",
                 "buttons": [{"label": "Close", "action": "reverse"}, {"label": "Open", "action": "play"}]}],
  "defaults": {"materials": {"Shade": "Silver"}, "variants": {}},
  "state": {"materials": {"Shade": "Silver"}, "variants": {}},
  "activePOI": "Overview",
  "panelVisible": true
}
  • Swatches travel as sRGB RRGGBBAA. No textures are sent; cameras have labels, not pictures.
  • Hidden variant options are left out.
  • With no native HUD, the catalog is pushed unprompted when the product becomes ready.
  • products (two or more switchable products) and intro appear only when relevant.

Zones and categories

A zone with categories adds a categories array. materials stays the flat, authoritative list. BAKR.Ungrouped holds the zone's own options. There is no category command: filtering is up to the page.

"categories": [
  {"id": "BAKR.Ungrouped", "label": "Standard",  "options": ["Original"]},
  {"id": "paint",          "label": "Car paint", "options": ["paint.black", "paint.silver"]}
]

Compatibility

An option with a rule carries incompatibleWith. Check each option's own list and whether a committed option elsewhere names it, to gray out options ahead of a click. The server enforces the rule regardless.

{"id": "Matte", "label": "Matte", "hex": "333333FF",
 "incompatibleWith": [{"zone": "trim", "id": "leather"}]}

Product switch order

On a switch every client receives product, then the new catalog. On product, drop everything from the old product and rebuild from the catalog that follows.

Transports

TransportDetails
Pixel StreamingUIInteraction descriptors containing command go to BAKR. Receipts go to the sender; state changes go to every viewer of that streamer.
Kiosk WebSocketws://<host>:<port>/ with the binary subprotocol. Unreal sends binary frames: set binaryType = "arraybuffer" and decode with TextDecoder. Send text frames. Receipts go to the sender; everything else to every client. A new client gets the catalog unprompted.
Your ownCall Handle Json Command and bind On Json Response.
const socket = new WebSocket(`ws://${location.host}/`, "binary");
socket.binaryType = "arraybuffer";
socket.onmessage = (e) => handle(JSON.parse(new TextDecoder().decode(e.data)));
socket.send(JSON.stringify({ command: "material", zone: "Shade", id: "Red" }));

Image sets

The batch render writes manifest.json: the catalog's zones, pois, styles and defaults, plus an image index. type is imageset, version is 1, and there is no state.

{
  "type": "imageset", "version": 1, "product": "Lamp",
  "image": {"width": 1600, "height": 900, "format": "png", "background": "scene"},
  "baseline": {"materials": {"Shade": "Silver"}, "variants": {"Base": "Round"}},
  "varyingAxes": [{"kind": "material", "zone": "Shade"}],
  "images": [{"poi": "Overview", "key": "shade-red",
              "lookup": "m:Shade=Red",
              "path": "overview/shade-red.png",
              "selection": {"materials": {"Shade": "Red"}, "variants": {}}}]
}
  • varyingAxes lists the zones that were rendered. Others were held at baseline in every image.
  • lookup is m: or v: + zone=option per varying zone, joined by |. Build it from the current selection and match it. Never derive a path from IDs; read path from the entry.
  • bakr-imageset.js implements the lookup, imageFor(poi, selection) and allPaths() for preloading.

Example scripts

Two small JavaScript modules handle the protocol on this page for you. They have no dependencies. Download them, copy them into your web project and import them as ES modules.

ScriptUse it for
bakr-client.jsA page of your own over Pixel Streaming. It sends commands and passes BAKR's responses to your code.
bakr-imageset.jsA 2D configurator built from a batch render. It finds the image for the current camera and selection. No Unreal runs.

The kiosk page and the BAKR player page don't need either script. Both are already built into the plugin.

bakr-client.js

  1. Set up Epic's Pixel Streaming frontend library on your page and connect it to the signalling server's viewer port. See Pixel Streaming.
  2. Pass the connected PixelStreaming instance to attachBAKRConfig, with a function that receives every BAKR message.
  3. Ask for the catalog and build your UI from it.
import { attachBAKRConfig } from "./bakr-client.js";

const bakr = attachBAKRConfig(pixelStreaming, (message) => {
  if (message.type === "catalog") buildUI(message);
  if (message.type === "state") showSelection(message.configuration);
  if (message.type === "error") showError(message.message);
});

bakr.send("catalog");
bakr.send("material", { zone: "body_paint", id: "Red" });
bakr.send("poi", { id: "Wheel" });

send(command, fields) accepts every command and returns the requestId it attached. The client also has keepAlive(), switchProduct(id), skipIntro() and dispose(), which removes its listener.

bakr-imageset.js

  1. Batch render the product and copy the output folder, with its manifest.json, to your web server.
  2. Load the manifest and pass it to attachBAKRImageSet with the folder's URL.
  3. Keep a selection in your page and ask the set for the matching image.
import { attachBAKRImageSet } from "./bakr-imageset.js";

const manifest = await (await fetch("images/manifest.json")).json();
const set = attachBAKRImageSet(manifest, "images/");

let selection = structuredClone(set.baseline);
selection.materials.body_paint = "Blue";
view.src = set.imageFor("Overview", selection);

The set returns zones, pois, styles, baseline and varyingAxes from the manifest. It also has these functions:

FunctionReturns
imageFor(poi, selection)The image URL. It throws when that combination wasn't rendered.
entryFor(poi, selection)The manifest entry, or undefined.
isRendered(zone)Whether the zone was varied in the render. Hide or disable the options of zones that weren't.
allPaths()Every image URL, for preloading.