Make Your Own Event: Announce Victory With a HUD Widget

What you'll learn

So far you've been a listener — subscribing to events that devices broadcast. Now you become the announcer. You'll learn how to:

• Declare your own event(agent) that carries a player as its payload.
• Signal it from your game logic when something meaningful happens.
• Await it in a watcher loop — the custom-event twin of the Subscribe you use on devices.
• Have the handler show a real HUD widget on the winner's screen with GetPlayerUI[] and AddWidget.

How it works

Devices announce device things. But your game has moments no single device owns: a puzzle solved, a wave cleared, a boss defeated. Those are yours to announce.

Verse gives you a ready-made announcer type: event. You write the kind of data it carries inside parentheses. An event that carries a player (agent) looks like this:

BossDefeatedEvent : event(agent) = event(agent){}

Read it as: "BossDefeatedEvent is an event that carries an agent, starting as a fresh event."

There are two verbs:

• Signal(Payload) — the moment of "it happened!" Every task waiting on the event wakes up, each receiving the payload.
• Await() — inside a <suspends> context, pause (for free) until the next Signal, and receive the payload. Wrap it in a loop and you have a handler that runs on every Signal — your own version of the Subscribe you call on button.InteractedWithEvent. (Only device events are listenable, which is what carries Subscribe; your own event(t) pairs Signal with Await.)

To make the payoff visible, our handler reaches the winner's screen through the player-UI API. GetPlayerUI[Player] is fallible (note the []), so we bind it inside an if. Then we build a text_block, drop it in a canvas, and call PlayerUI.AddWidget(...).

Let's build it

A real button drives our own event. Pressing it calls DefeatBoss, which Signals BossDefeatedEvent, which wakes the Await loop that runs OnBossDefeated — so device event → your event → your handler → a widget on screen.

Try it yourself

1. Place a Button Device in your level and assign it to the BossButton field in the Details panel.
2. Push this Verse device, launch a session, and press the button.
3. Watch the log (The boss is down! then Victory!) and the HUD — the victory text appears on the presser's screen.
4. Extend it: spawn a second Await loop on BossDefeatedEvent (e.g. one that grants a reward, one that shows the widget) and watch both wake from a single Signal.
5. Cleanup practice: store the device subscription (ButtonSub := BossButton.InteractedWithEvent.Subscribe(...)) and call ButtonSub.Cancel() after the first press so the boss can only be defeated once.

Recap

• event(agent) declares your own announcer that carries a player payload.
• Signal(Winner) wakes every task paused in Await(); a loop: around Await is your handler — it runs once per Signal.
• Only device events (listenable) have .Subscribe; your own event(t) pairs Signal with Await.
• text_block.DefaultText takes a message — make one with a <localizes> function, never a raw string.
• GetPlayerUI[...] is fallible — bind it in an if, then AddWidget a canvas to actually put your announcement on screen.