How Events Work in AlertForge

AlertForge listens for Raw.Action events from Streamer.bot and converts them into named custom events that your overlay can react to.

Event Dispatch Flow

When a Raw.Action WebSocket payload is received:

The script attempts to map it to an official event like Twitch.Sub using: js AlertForge.mapRawToOfficial(category, triggerName, eventSource)
If a match is found, a new event is dispatched using: js window.dispatchEvent(new CustomEvent("Twitch.Sub", { detail: { flat, merged, data } }))
Your overlay listens for this in script.js: js window.addEventListener("Twitch.Sub", (e) => { const data = e.detail.flat; // show alert... });

The AlertForge object (automatically injected) provides helpers:

Function	Purpose
`AlertForge.lookup(obj, path)`	Safely access nested values (like `user.name`)
`AlertForge.flattenObject(obj)`	Turns nested data into a flat key:value map
`AlertForge.expandPaths(obj)`	Reconstructs nested structure from flat keys
`AlertForge.formatMessage(template, data)`	Replaces `{placeholders}` in a message
`AlertForge.getAllObservedEvents()`	Lists all known Streamer.bot events
`AlertForge.mapRawToOfficial()`	Matches Raw.Action triggers to official names

When formatting text like:

const output = AlertForge.formatMessage("{user} just followed!", data);

The function will replace the {user} token with the value from the event payload and return:

<span class="highlight">CoolViewer123</span> just followed!

The highlight class can be styled via CSS to control the appearance of dynamic values.

AlertForge automatically reloads the overlay in OBS or browser when a change is saved through Smithy or the Blueprint Editor.

This is done by:

Updating a hidden assets/version.txt file on every save
Polling that file in the background and triggering a reload when its content changes

This makes testing overlays smoother by removing the need to manually refresh after edits.