huds

Adds steps that flash a message in Switchboard's on-screen display (HUD).

Details #

A HUD is a short message drawn on top of everything, like the one that shows when you change the volume. The huds point adds a step that shows one. The step type is <extension id>.<hud id>, so it appears in the step picker under your extension, next to the steps from actions.

When a macro reaches the step, the engine passes the step's params to your handler. The handler decides what to say, and the engine draws it. Your code never draws anything and needs no permission.

Declare it in switchboard.json under adds.huds:

{
  "adds": {
    "huds": [
      {
        "id": "say",
        "title": "Say on Screen",
        "params": {
          "type": "object",
          "properties": { "text": { "type": "string", "title": "Message" } },
          "required": ["text"]
        }
      }
    ]
  }
}

And implement it:

import { defineExtension, hud } from '@switchboard/sdk';

export default defineExtension({
  huds: [
    hud('say', (p: { text: string }) => ({ text: p.text, seconds: 2 })),
  ],
});

Gotchas #

In a dry run the step does not call your handler. It only notes that nothing was shown.
The step runs under the step timeout like any other step. Keep the handler quick.
Unknown keys in an entry are refused.
The display is small. Keep messages short; the sample cuts anything over 80 characters.

A complete extension using this point can be downloaded from the Full example section and edited: it shows a message, shortens long ones and picks a time from the length.

Manifest fields #

Field	Required	What it is
`id`	yes	Lowercase letters, digits and `.` `_` `-`, up to 64 characters, starting with a letter. Unique in the list.
`title`	yes	1 to 80 characters. The name in the step picker.
`description`	no	Up to 1000 characters.
`params`	no	A JSON Schema object for the step's fields. The editor draws a form from it.

What the handler gets and returns #

The handler gets the step's params as an object, and a ctx. It returns either a string, or an object { text, seconds? }.

text is what is shown. If it is empty, the step fails with "returned no text to show".
seconds is how long it stays. The default is 1.5. The engine keeps it between 0.2 and 60.
The step's output is the text, so later steps can use it.