kaiwyvern.notes
← Notes

Toast system

plugins/module/push/main.js

Skin notifications arrive over the client websocket and are shown as toasts in the bottom-right corner. The module keeps its own queue of visible toasts so they can be stacked without overlapping.

Start: subscribe and warm the cache

The cache is filled first, because a toast needs a skin name and a splash image the moment an event arrives. Only after that does the module subscribe to PartyPushEvent.

async start() {
    await this.loadSkinsData();          // skins.json -> Map<id, {name, splashPath}>

    this.coreWs.subscribe(this.subscriberId, {
        message: (data) => this.handleMessage(data)
    });

    this.setupDebugApi();                // window.SYNC.push
}

Filtering the event

The channel carries more than skins, so the handler checks the type and tolerates three different spellings of the same fields — the payload comes from an external service and the names are not stable.

handleMessage(data) {
    if (!data || data.type !== 'skin_update') return;

    const payload = data.payload || {};
    const skinId = payload.skin_id || payload.skinId;
    if (!skinId) return;

    const playerName = payload.player_name || payload.player || payload.playerName || 'Player';
    const skinInfo = this.getSkinInfo(skinId);

    this.showToast(playerName, skinInfo.name, skinInfo.splashPath);
}

Building the node

Everything is created with document.createElement and textContent, never with an HTML string: player names come from outside, so they must not be parsed as markup.

createToast(playerName, skinName, splashPath) {
    const toast = document.createElement('div');
    toast.className = 'toast-notification';

    if (splashPath) {                      // skin artwork as background
        const bg = document.createElement('div');
        bg.className = 'toast-bg';
        bg.style.backgroundImage = `url('${splashPath}')`;
        toast.appendChild(bg);
    }

    const content = document.createElement('div');
    content.className = 'toast-content';
    // ... player name + skin name ...

    document.body.appendChild(toast);
    this.activeToasts.push(toast);
    this.updateToastPositions();           // re-stack
    toast.style.animation = 'toastSlideIn 0.3s ease-out';

    return toast;
}

Stacking

The list of active toasts is the source of truth: after adding or removing one, updateToastPositions() walks the array and sets bottom for every element, adding up the heights and the fixed gap. That is why a toast can disappear from the middle and the rest close the hole.

updateToastPositions() {
    let offset = CONFIG.TOAST_OFFSET_BOTTOM;

    for (const toast of this.activeToasts) {
        toast.style.bottom = offset + 'px';
        offset += toast.offsetHeight + CONFIG.TOAST_GAP;
    }
}

Debug hook

Waiting for a real queue is impractical while developing, so the module exposes window.SYNC.push(name, skinId). It is removed in stop(), and only if it is still the same function — another plugin may have replaced it meanwhile.

window.SYNC.push = push;

// later, in stop():
if (window.SYNC && window.SYNC.push === this._pushFn) {
    delete window.SYNC.push;
}