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:139

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] } } },
    ],
};

Properties​

channel?​

optional channel?: string;

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

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:153

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:160

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:166

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:178

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