Mediabot v3 continues its 3.4 development cycle with another script-bridge round focused on practical examples, documentation truth and safer configuration.

This update is not about adding noise. It is about making the new event system easier to understand, easier to copy and harder to misconfigure.

🖼️ The promised portraits are now on the wall

The previous event-routing documentation already showed examples for channel events such as join and topic.

There was one annoying problem: the sample configuration referenced scripts that did not exist yet.

That is now fixed.

Two new reference scripts are available:

plugins/scripts/examples/greet.pl
plugins/scripts/examples/topicwatch.pl

greet.pl demonstrates a safe welcome script for join events.

topicwatch.pl demonstrates how to react to topic changes, including the dedicated topic field provided by the event envelope.

In Hogwarts terms: the portraits mentioned on the map are finally hanging on the wall. 🖼️

👋 greet.pl — a cautious welcome charm

The new greet.pl example shows how to welcome users when a join event is routed to a script.

It also documents an important operational rule: event cooldowns mean a join script must not assume it sees every single join.

That matters during reconnects, netsplits or busy channels. A welcome script should be friendly, not a fork storm wearing a smile.

🧾 topicwatch.pl — watching the notice board

The new topicwatch.pl example shows how a script can react to topic changes.

It demonstrates:

• reading the dedicated topic field;
• handling an empty topic as (cleared);
• staying silent on IRC if the script is routed to the wrong kind of event;
• trusting the bridge for JSON encoding and reply bounds instead of reimplementing them badly.

That is exactly what a reference script should do: teach the pattern without becoming a framework.

🛡️ Documentation truth is now tested

This round also adds a useful guard: routes documented in the sample configuration must point to scripts that actually exist.

That means a future example cannot silently become a dead link in mediabot.sample.conf.

If the parchment says a portrait exists, the test suite now checks that it is really on the wall.

👜 Hermione’s route-config bag

The second part of this round adds per-route configuration.

A route can now carry a small configuration map into the script envelope:

CONFIG_premind=max_delay=1800
CONFIG_join=welcome=Bienvenue sur ce canal
CONFIG_pcfg=greeting=Bonjour, à tous; max=5

Scripts receive that data under:

data.config

This is useful for small per-route settings such as welcome text, thresholds, labels or limits.

No environment hack.
No script duplication.
No redeploy just to change a tiny phrase.

🧷 Guardrails

The route configuration system is deliberately bounded:

• keys must stay simple and short;
• values are capped;
• overlong values are rejected, not silently truncated;
• each route has a maximum number of config entries;
• scripts receive a defensive copy;
• routes without config simply do not get a config field;
• timer callbacks keep the config snapshot they originally received.

That last part matters: if a script schedules a delayed timer, the timer sees the same route config that existed when it was armed.

A proper Extension Charm, but with inventory control. 👜

🧪 Validation

This round was validated with:

10342/10342 tests passed  — event example scripts
10372/10372 tests passed  — per-route configuration

The update does not require a database schema change.

It also keeps the event-routing model cautious: event scripts remain opt-in, scoped and guarded.

🧙 Summary

This round makes the script bridge more usable for real people:

• the documented event examples now exist;
• join and topic scripts have clean reference implementations;
• sample configuration truth is enforced by tests;
• scripts can receive route-specific config safely;
• timer callbacks preserve their original route configuration.

Small details, but important ones.

Mediabot’s script bridge is no longer just powerful — it is becoming teachable, inspectable and harder to misuse. 🪄