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"}
| Command | Notes |
|---|---|
material, variant | Change one zone. Only that zone is touched. |
style | Apply a style by ID. |
poi | Fly to a camera by ID. |
play, reverse, pause, resume, stop | Motion sequences by ID. |
panel | Without a HUD it only reframes the camera; the browser owns its panel. |
reducedMotion | Overrides the product setting for this session. Omit enabled to hand control back. |
reset | Catalog defaults. |
state, catalog | Ask for the current state or the full catalog. |
import | Apply a version-2 preset. |
keepAlive | Cancels a pending kiosk idle reset and changes nothing else. |
product, skipIntro | Product 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.
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"}
ackmeans accepted, not finished. Watchstatefor the applied result anderrorfor failures. Several quick commands can merge into onestate.requestIdis echoed on theackonly.poi,motionandbusyreport every change, whatever caused it, so a page stays in sync with things it did not start.idlephases arewarning,cancelledandreset.introstatuses arestarted,finishedandskipped.
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) andintroappear 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
| Transport | Details |
|---|---|
| Pixel Streaming | UIInteraction descriptors containing command go to BAKR. Receipts go to the sender; state changes go to every viewer of that streamer. |
| Kiosk WebSocket | ws://<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 own | Call 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": {}}}]
}
varyingAxeslists the zones that were rendered. Others were held atbaselinein every image.lookupism:orv:+zone=optionper varying zone, joined by|. Build it from the current selection and match it. Never derive a path from IDs; readpathfrom the entry.- bakr-imageset.js implements the lookup,
imageFor(poi, selection)andallPaths()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.
| Script | Use it for |
|---|---|
| bakr-client.js | A page of your own over Pixel Streaming. It sends commands and passes BAKR's responses to your code. |
| bakr-imageset.js | A 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
- Set up Epic's Pixel Streaming frontend library on your page and connect it to the signalling server's viewer port. See Pixel Streaming.
- Pass the connected
PixelStreaminginstance toattachBAKRConfig, with a function that receives every BAKR message. - 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
- Batch render the product and copy the output folder, with its
manifest.json, to your web server. - Load the manifest and pass it to
attachBAKRImageSetwith the folder's URL. - 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:
| Function | Returns |
|---|---|
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. |