Skip to main content

Type Alias: EventMapping

type EventMapping = {
  channel?: string;
  when?: (event: IngestEvent) => boolean;
  schema?: JsonSchema;
  entities: SceneEntities;
  updates: (event: IngestEvent) => EntityUpdate | EntityUpdate[] | null;
};

Defined in: livelink.clients/livelink.agent/sources/data/EventMapping.ts:297

Describes how ONE event type drives entities in the scene: which events it covers (channel / when), which entities those events drive (entities), and what each event does to them (updates).

A source carrying several event types (e.g. one schema per MQTT topic family) uses several mappings — each event is handled by every mapping whose selectors match it.

updates returns one EntityUpdate when an event is about a single object:

const mapping: EventMapping = {
  channel: "uagv/+/+/+/visualization",
  entities: { spawn: { name: "AGV-{id}", components: { scene_ref: { value: SCENE } } } },
  updates: event => ({
    id: event.channel.split("/")[3], // the serial number, from the topic
    update: { local_transform: agvPoseToTransform(event.payload.agvPosition) },
  }),
};

...or an array of them when one event carries the state of several objects at once, the norm for a machine publishing a whole-state frame:

const mapping: EventMapping = {
  entities: { byName: "{id}" },
  updates: ({ payload }) => [
    { id: "blade", update: { local_transform: { eulerOrientation: [0, payload.angle, 0] } } },
    { id: "carriage", update: { local_transform: { position: [0, payload.posZ, 0] } } },
  ],
};

The ids need not be written out: a controller publishing a whole data block names each value in the payload key, so walking the payload into one entry per key drives as many entities as the frame carries. Whichever way they are derived, they must be unique across everything the mapping drives — a key alone is not, once the channel pattern matches a second device.

Properties​

channel?​

optional channel?: string;

Defined in: livelink.clients/livelink.agent/sources/data/EventMapping.ts:306

Only handle events whose channel matches this MQTT-style pattern (+/* = one segment, trailing # = the rest). Omitted = all channels.

Note that channel is only a meaningful selector on transports that put routing information in it — see IngestEvent.channel. On an Azure Event Hub stream, select with when instead.

when?​

optional when?: (event: IngestEvent) => boolean;

Defined in: livelink.clients/livelink.agent/sources/data/EventMapping.ts:311

Only handle events for which this predicate returns true. Omitted = all events.

Parameters​

ParameterType
eventIngestEvent

Returns​

boolean

schema?​

optional schema?: JsonSchema;

Defined in: livelink.clients/livelink.agent/sources/data/EventMapping.ts:318

JSON Schema of this event type. The first matching event is validated against it (a cheap sanity check of the stream's shape); every event is validated when the pipeline's validate option is on (debugging).

entities​

entities: SceneEntities;

Defined in: livelink.clients/livelink.agent/sources/data/EventMapping.ts:324

The scene entities this mapping's events drive, and how the ids they carry find — or create — one. See SceneEntities.

updates​

updates: (event: IngestEvent) =>
  | EntityUpdate
  | EntityUpdate[]
  | null;

Defined in: livelink.clients/livelink.agent/sources/data/EventMapping.ts:336

What one event does: one EntityUpdate when it is about a single object, an array of them when it carries several at once. Return null (or an empty array) to ignore the event.

The whole event is passed, so an id can come from the payload, the channel, the metadata, or several fields combined.

Note that extracting this function to a bare const loses TypeScript's contextual typing of its parameter; annotate it EventMapping["updates"] if you do.

Parameters​

ParameterType
eventIngestEvent

Returns​

| EntityUpdate | EntityUpdate[] | null