') + ')') + html.br();
+ topicKeys.forEach(k => {
+ var t = helpData.topics[k];
+ var vTag = '';
+ if (isNewVersion(t.version, reg)) vTag = ' ' + html.newBadge();
+ if (t.deprecated) vTag = ' ' + html.deprecatedBadge();
+ out += '• ' + html.bold(html.escape(t.title || k)) + vTag;
+ if (t.description) out += ' — ' + html.escape(t.description);
+ out += html.br();
+ });
+ }
+ }
+
+ if (!out) {
+ out = 'No results for "' + html.escape(search) + '".';
+ }
+
+ reply(msg, scriptName, 'Help', out);
+ };
+
+ /**
+ * Show man page (detailed topic lookup with tiered search).
+ */
+ const showMan = (msg, scriptName, reg, args) => {
+ const helpData = reg.help;
+ if (!helpData || !helpData.topics) {
+ reply(msg, scriptName, 'Man', 'No documentation registered for ' + scriptName + '.');
+ return;
+ }
+
+ const topics = helpData.topics;
+ const search = args.length > 0 ? args.join(' ').toLowerCase() : null;
+ var manCmd = Array.isArray(reg.aliases.man) ? reg.aliases.man[0] : reg.aliases.man;
+
+ // No search — list all topics
+ if (!search) {
+ let out = html.bold(html.escape(scriptName) + ' — Topics:') + html.paragraph('');
+ Object.entries(topics).forEach(([key, t]) => {
+ if (t.deleted) return;
+ out += '• ' + html.button(t.title || key, reg.command + ' ' + manCmd + ' ' + key);
+ if (t.description) out += ' — ' + html.escape(t.description);
+ out += html.br();
+ });
+ reply(msg, scriptName, 'Man', out);
+ return;
+ }
+
+ // Tier 1: exact topic key match
+ if (topics[search] && !topics[search].deleted) {
+ renderManTopic(msg, scriptName, reg, search, topics[search]);
+ return;
+ }
+
+ // Tier 1a: command lookup by first word of syntax
+ if (helpData.commands) {
+ var flatCmds = [];
+ var flattenC = (items) => { items.forEach(c => { if (c.group) flattenC(c.commands || []); else flatCmds.push(c); }); };
+ flattenC(helpData.commands);
+ var cmdMatch = flatCmds.find(c => !c.deleted && c.items && c.syntax.split(' ')[0].toLowerCase() === search);
+ if (cmdMatch) {
+ renderManCommand(msg, scriptName, reg, cmdMatch);
+ return;
+ }
+ }
+
+ // Tier 1b: exact title match
+ const titleMatch = Object.entries(topics).find(([k, t]) =>
+ !t.deleted && (t.title || k).toLowerCase() === search
+ );
+ if (titleMatch) {
+ renderManTopic(msg, scriptName, reg, titleMatch[0], titleMatch[1]);
+ return;
+ }
+
+ // Tier 2: search within topic items/body
+ const results = [];
+ Object.entries(topics).forEach(([key, t]) => {
+ if (t.deleted) return;
+ // Check items array if present
+ if (t.items && Array.isArray(t.items)) {
+ t.items.forEach(item => {
+ const nameMatch = (item.name || '').toLowerCase().indexOf(search) !== -1;
+ const descMatch = (item.description || '').toLowerCase().indexOf(search) !== -1;
+ if (nameMatch || descMatch) {
+ results.push({ topicKey: key, topic: t, item: item, exact: nameMatch });
+ }
+ });
+ }
+ // Check body text
+ var bodyText = typeof t.body === 'function' ? '' : (t.body || '');
+ if (bodyText && bodyText.toLowerCase().indexOf(search) !== -1) {
+ results.push({ topicKey: key, topic: t, item: null, exact: false });
+ }
+ // Check title/description
+ if ((t.title || '').toLowerCase().indexOf(search) !== -1 ||
+ (t.description || '').toLowerCase().indexOf(search) !== -1) {
+ results.push({ topicKey: key, topic: t, item: null, exact: true });
+ }
+ });
+
+ // Also search command items
+ var flatCommands = [];
+ var flattenCmds = (items) => { items.forEach(c => { if (c.group) flattenCmds(c.commands || []); else flatCommands.push(c); }); };
+ if (helpData.commands) flattenCmds(helpData.commands);
+ flatCommands.forEach(c => {
+ if (c.deleted || !c.items) return;
+ var cmdKey = c.syntax.split(' ')[0];
+ c.items.forEach(item => {
+ const nameMatch = (item.name || '').toLowerCase().indexOf(search) !== -1;
+ const descMatch = (item.description || '').toLowerCase().indexOf(search) !== -1;
+ if (nameMatch || descMatch) {
+ results.push({ topicKey: cmdKey, topic: { title: reg.command + ' ' + c.syntax, description: c.description }, item: item, exact: nameMatch, _cmd: c });
+ }
+ });
+ });
+
+ if (results.length === 0) {
+ reply(msg, scriptName, 'Man', 'No results for "' + html.escape(search) + '".');
+ return;
+ }
+
+ // If exactly one topic matched, show it fully
+ const uniqueTopics = [...new Set(results.map(r => r.topicKey))];
+ if (uniqueTopics.length === 1 && results.some(r => r.exact)) {
+ renderManTopic(msg, scriptName, reg, uniqueTopics[0], topics[uniqueTopics[0]]);
+ return;
+ }
+
+ // Multiple matches — show condensed results with links
+ let out = html.bold('Results for "' + html.escape(search) + '":') + html.paragraph('');
+ const shown = new Set();
+ results.sort((a, b) => (b.exact ? 1 : 0) - (a.exact ? 1 : 0));
+ results.forEach(r => {
+ if (shown.has(r.topicKey + '/' + (r.item ? r.item.name : ''))) return;
+ shown.add(r.topicKey + '/' + (r.item ? r.item.name : ''));
+ if (r.item) {
+ out += '• ' + html.bold(html.escape(r.item.name));
+ if (r.item.description) out += ' — ' + html.escape(r.item.description).slice(0, 80);
+ out += html.br() + html.indent(2) + html.italic('in ' + html.button(r.topic.title || r.topicKey, reg.command + ' ' + manCmd + ' ' + r.topicKey)) + html.br();
+ } else {
+ out += '• ' + html.button(r.topic.title || r.topicKey, reg.command + ' ' + manCmd + ' ' + r.topicKey);
+ if (r.topic.description) out += ' — ' + html.escape(r.topic.description);
+ out += html.br();
+ }
+ });
+ reply(msg, scriptName, 'Man', out);
+ };
+
+ /**
+ * Render a full man topic.
+ */
+ const renderManTopic = (msg, scriptName, reg, key, topic) => {
+ let out = html.bold(html.escape(topic.title || key));
+ if (topic.version) out += ' ' + html.italic('(v' + topic.version + ')');
+ out += html.br();
+ if (topic.description) out += html.escape(topic.description) + html.br();
+ out += html.br();
+
+ // Render body (supports string or function)
+ if (topic.body) {
+ var body = typeof topic.body === 'function' ? topic.body() : topic.body;
+ out += html.render(body) + html.paragraph('');
+ }
+
+ // Render items (structured entries within a topic)
+ if (topic.items && Array.isArray(topic.items)) {
+ topic.items.forEach(item => {
+ if (item.deleted) return;
+ var vTag = '';
+ if (item.version && isNewVersion(item.version, reg)) vTag = ' ' + html.newBadge();
+ if (item.deprecated) vTag = ' ' + html.deprecatedBadge();
+ out += html.bold(html.escape(item.name)) + vTag;
+ if (item.syntax) out += ' ' + html.code(item.syntax);
+ out += html.br();
+ if (item.description) out += html.render(item.description) + html.br();
+ out += html.br();
+ });
+ }
+
+ reply(msg, scriptName, 'Man', out);
+ };
+
+ /**
+ * Render a command's man page (details + items).
+ */
+ const renderManCommand = (msg, scriptName, reg, cmd) => {
+ let out = html.bold(html.code(reg.command + ' ' + cmd.syntax));
+ if (cmd.version) out += ' ' + html.italic('(v' + cmd.version + ')');
+ out += html.br();
+ if (cmd.description) out += html.escape(cmd.description) + html.br();
+ if (cmd.details) out += html.br() + html.render(cmd.details) + html.br();
+ out += html.br();
+
+ if (cmd.items) {
+ cmd.items.forEach(item => {
+ if (item.deleted) return;
+ var vTag = '';
+ if (isNewVersion(item.version, reg)) vTag = ' ' + html.newBadge();
+ if (item.deprecated) vTag = ' ' + html.deprecatedBadge();
+ out += html.bold(html.escape(item.name)) + vTag;
+ out += html.br();
+ if (item.description) out += html.render(item.description) + html.br();
+ out += html.br();
+ });
+ }
+
+ reply(msg, scriptName, 'Man', out);
+ };
+
+ /**
+ * Show what's new in current version (chat command).
+ */
+ const showWhatsNew = (msg, scriptName, reg) => {
+ const helpData = reg.help;
+ if (!helpData) {
+ reply(msg, scriptName, 'What\'s New', 'No help data registered.');
+ return;
+ }
+
+ const version = reg.version;
+ const commands = helpData.commands || [];
+ const topics = helpData.topics || {};
+
+ let out = html.bold(html.escape(scriptName) + ' — What\'s New') + html.paragraph('');
+
+ // Explicit changelog entries
+ if (helpData.changelog && helpData.changelog.length > 0) {
+ var relevant = helpData.changelog.filter(e => isNewVersion(e.version, reg));
+ if (relevant.length > 0) {
+ relevant.forEach(e => {
+ out += html.bold('v' + e.version) + html.br();
+ if (Array.isArray(e.changes)) {
+ out += html.list(e.changes.map(c => html.escape(c)));
+ } else if (e.changes) {
+ out += html.escape(e.changes) + html.br();
+ }
+ });
+ out += html.line();
+ }
+ }
+
+ // Auto-detected new items
+ var newItems = [];
+
+ // New commands
+ var flatCommands = [];
+ var flattenCmds = (items) => { items.forEach(c => { if (c.group) flattenCmds(c.commands || []); else flatCommands.push(c); }); };
+ flattenCmds(commands);
+ flatCommands.forEach(c => {
+ if (!c.deleted && isNewVersion(c.version, reg)) {
+ newItems.push(html.code(reg.command + ' ' + c.syntax) + ' — ' + html.escape(c.description));
+ }
+ });
+
+ // New topics
+ Object.entries(topics).forEach(([k, t]) => {
+ if (t.deleted) return;
+ if (isNewVersion(t.version, reg)) {
+ newItems.push(html.bold(t.title || k) + (t.description ? ' — ' + html.escape(t.description) : ''));
+ }
+ // New items within existing topics
+ if (t.items) {
+ t.items.forEach(item => {
+ if (!item.deleted && isNewVersion(item.version, reg) && !isNewVersion(t.version, reg)) {
+ newItems.push(html.bold(item.name) + ' in ' + html.italic(t.title || k) + (item.description ? ' — ' + item.description : ''));
+ }
+ });
+ }
+ });
+
+ if (newItems.length > 0) {
+ out += html.bold('New Features:') + html.br();
+ out += html.list(newItems);
+ }
+
+ if (!newItems.length && !(helpData.changelog && helpData.changelog.length)) {
+ out += 'Nothing new since last version.';
+ }
+
+ reply(msg, scriptName, 'What\'s New', out);
+ };
+
+ // =========================================================================
+ // Handout Generation
+ // =========================================================================
+
+ /**
+ * Generate a help or dev handout from the registered help data.
+ * @param {object|null} msg Chat message (null for auto-generation on startup)
+ * @param {string} scriptName
+ * @param {object} reg Registration object
+ * @param {string} mode 'usr' or 'dev'
+ */
+ const generateHelpHandout = (msg, scriptName, reg, mode) => {
+ const helpData = reg.help;
+ if (!helpData) {
+ if (msg) reply(msg, scriptName, 'Error', 'No help data registered.');
+ return;
+ }
+
+ const version = reg.version;
+ const handoutName = 'Help: ' + scriptName + (mode === 'dev' ? '/Dev' : '');
+ const topics = helpData.topics || {};
+ const commands = helpData.commands || [];
+
+ // Filter topics by handouts field
+ const matchesMode = (t) => {
+ var h = t.handouts !== undefined ? t.handouts : 'usr';
+ if (h === null) return false;
+ if (Array.isArray(h)) return h.indexOf(mode) !== -1;
+ return h === mode;
+ };
+
+ // Auto-inject ScriptKit examples topic for dev handout unless explicitly set to null
+ if (mode === 'dev' && !topics.hasOwnProperty('scriptKit')) {
+ topics.scriptKit = {
+ title: 'Registering Examples',
+ description: 'How to register examples for ' + scriptName + ' that show off your script\'s integration',
+ handouts: 'dev',
+ body: 'Other scripts can register examples targeting **' + scriptName + '**:\n\n'
+ + '```ScriptKit.' + scriptName + '.registerExample(\'YourScript\', {\n'
+ + ' name: \'example-name\',\n'
+ + ' description: \'What this example does\',\n'
+ + ' guide: [ /* guide steps */ ],\n'
+ + ' handout: { notes: \'...\' }\n'
+ + '});```\n\n'
+ + 'See the ScriptKit wiki or run `!scriptkit ' + registrations[SCRIPT_NAME].aliases.genDev + '` for more information on examples and guides.',
+ };
+ }
+
+ const filteredTopicKeys = Object.keys(topics).filter(k => topics[k] && !topics[k].deleted && matchesMode(topics[k]));
+
+ // Build "What's New" section (items matching current version)
+ var whatsNew = [];
+ var whatsNewSeen = {};
+ var flatCmds = [];
+ var flattenC = (items) => { items.forEach(c => { if (c.group) flattenC(c.commands || []); else flatCmds.push(c); }); };
+ flattenC(commands);
+ flatCmds.forEach(c => {
+ if (!c.deleted && isNewVersion(c.version, reg)) whatsNew.push(html.code(reg.command + ' ' + c.syntax) + ' — ' + html.escape(c.description));
+ if (c.items) {
+ c.items.forEach(item => {
+ if (!item.deleted && isNewVersion(item.version, reg) && !isNewVersion(c.version, reg)) {
+ if (!whatsNewSeen[item.name]) {
+ whatsNewSeen[item.name] = true;
+ whatsNew.push(html.code(item.name) + ' in ' + html.code(reg.command + ' ' + c.syntax) + ' — ' + html.escape(item.description));
+ }
+ }
+ });
+ }
+ });
+ filteredTopicKeys.forEach(k => {
+ var t = topics[k];
+ if (isNewVersion(t.version, reg)) whatsNew.push(html.bold(t.title || k) + (t.description ? ' — ' + html.escape(t.description) : ''));
+ if (t.items) {
+ t.items.forEach(item => {
+ if (!item.deleted && isNewVersion(item.version, reg) && !whatsNewSeen[item.name]) {
+ whatsNewSeen[item.name] = true;
+ whatsNew.push(html.bold(item.name) + (item.description ? ' — ' + item.description : ''));
+ }
+ });
+ }
+ });
+
+ // Build "Removed" section (deleted items)
+ var removed = [];
+ commands.forEach(c => {
+ if (c.deleted) removed.push(html.code(reg.command + ' ' + c.syntax) + ' — removed in v' + c.deleted);
+ });
+ Object.keys(topics).forEach(k => {
+ var t = topics[k];
+ if (!t) return;
+ if (t.deleted) removed.push(html.bold(t.title || k) + ' — removed in v' + t.deleted);
+ if (t.items) {
+ t.items.forEach(item => {
+ if (item.deleted) removed.push(html.bold(item.name) + ' — removed in v' + item.deleted);
+ });
+ }
+ });
+
+ // Render HTML
+ var out = '';
+ out += '' + html.escape(scriptName) + (version ? ' v' + version : '') + '
';
+ if (helpData.description) out += '' + html.render(helpData.description) + '
';
+
+ // Quick Start / Examples callout (user handout only)
+ var hasExamples = reg.aliases && reg.aliases.examples && Object.values(examples).filter(e => e.target === scriptName).length > 0;
+ var examplesBtn = hasExamples ? ' ' + html.button('📖 Examples', reg.command + ' ' + reg.aliases.examples, { background: '#444', fontSize: '11px' }) : '';
+ if (mode === 'usr') {
+ if (helpData.quickStart) {
+ out += 'Quick Start' + examplesBtn + '
';
+ var qs = helpData.quickStart;
+ if (typeof qs === 'function') qs = qs();
+ if (Array.isArray(qs)) out += html.orderedList(qs);
+ else out += '' + qs + '
';
+ } else if (hasExamples) {
+ out += '' + examplesBtn + ' — ready-made examples you can install and learn from.
';
+ }
+ }
+
+ // What's New
+ if (helpData.changelog && helpData.changelog.length > 0) {
+ var relevant = helpData.changelog.filter(e => isNewVersion(e.version, reg));
+ relevant.forEach(e => {
+ if (Array.isArray(e.changes)) {
+ e.changes.forEach(c => whatsNew.push(html.escape(c)));
+ } else if (e.changes) {
+ whatsNew.push(html.escape(e.changes));
+ }
+ });
+ }
+ if (whatsNew.length > 0) {
+ out += 'What\'s New in v' + version + '
';
+ out += html.list(whatsNew);
+ }
+
+ // Commands (usr handout only)
+ if (mode === 'usr' && commands.length > 0) {
+ var renderCmdsHandout = function(items) {
+ var result = '';
+ items.forEach(c => {
+ if (c.group) {
+ var inner = renderCmdsHandout(c.commands || []);
+ if (inner) result += '' + html.escape(c.group) + '
' + inner;
+ } else {
+ if (c.deleted) return;
+ var badge = '';
+ var cmdIsNew = isNewVersion(c.version, reg);
+ if (cmdIsNew) badge = ' ' + html.newBadge();
+ if (c.deprecated) badge = ' ' + html.deprecatedBadge();
+ if (mode === 'dev' && c.version) badge += ' ' + html.version(c.version);
+ result += '' + html.code(reg.command + ' ' + c.syntax) + ' — ' + html.escape(c.description) + badge + '
';
+ if (c.details) result += '' + html.render(c.details) + '
';
+ if (c.items) {
+ result += '';
+ c.items.forEach(item => {
+ if (item.deleted) return;
+ var iBadge = '';
+ if (!cmdIsNew && isNewVersion(item.version, reg)) iBadge = ' ' + html.newBadge();
+ if (item.deprecated) iBadge = ' ' + html.deprecatedBadge();
+ if (mode === 'dev' && item.version) iBadge += ' ' + html.version(item.version);
+ result += '- ' + html.code(item.name) + ' — ' + html.escape(item.description) + iBadge + '
';
+ });
+ result += '
';
+ }
+ }
+ });
+ return result;
+ };
+ out += 'Commands
';
+ out += renderCmdsHandout(commands);
+ }
+
+ // Topics
+ filteredTopicKeys.forEach(k => {
+ var t = topics[k];
+ var badge = '';
+ var topicIsNew = isNewVersion(t.version, reg);
+ if (topicIsNew) badge = ' ' + html.newBadge();
+ if (t.deprecated) badge = ' ' + html.deprecatedBadge();
+ if (mode === 'dev' && t.version) badge += ' ' + html.version(t.version);
+ out += '' + html.escape(t.title || k) + badge + '
';
+ if (t.description) out += '' + html.escape(t.description) + '
';
+ if (t.details) out += '' + html.render(t.details) + '
';
+ if (t.body) {
+ var body = typeof t.body === 'function' ? t.body() : t.body;
+ out += '' + html.render(body) + '
';
+ }
+ if (t.items) {
+ t.items.forEach(item => {
+ if (item.deleted) return;
+ var iBadge = '';
+ if (!topicIsNew && isNewVersion(item.version, reg)) iBadge = ' ' + html.newBadge();
+ if (item.deprecated) iBadge = ' ' + html.deprecatedBadge();
+ if (mode === 'dev' && item.version) iBadge += ' ' + html.version(item.version);
+ out += '' + html.bold(html.escape(item.name)) + iBadge;
+ if (item.syntax) out += ' ' + html.code(item.syntax);
+ out += '
';
+ if (item.description) out += '' + html.render(item.description) + '
';
+ if (item.details) out += '' + html.render(item.details) + '
';
+ });
+ }
+ });
+
+ // Removed section
+ if (removed.length > 0) {
+ out += 'Removed
';
+ out += html.list(removed);
+ }
+
+ // Examples footer
+ if (reg.aliases && reg.aliases.examples) {
+ var examplesForScript = Object.values(examples).filter(e => e.target === scriptName);
+ if (examplesForScript.length > 0) {
+ out += '
' + html.button('📖 Browse Examples', reg.command + ' ' + reg.aliases.examples, { background: '#444', fontSize: '11px' }) + ' — ' + examplesForScript.length + ' ready-made example' + (examplesForScript.length === 1 ? '' : 's') + ' available.
';
+ }
+ }
+
+ // Create/update handout
+ var handout = findObjs({ type: 'handout', name: handoutName })[0];
+ if (!handout) {
+ handout = createObj('handout', {
+ name: handoutName,
+ inplayerjournals: '',
+ archived: false,
+ avatar: 'https://files.d20.io/images/127392204/tAiDP73rpSKQobEYm5QZUw/thumb.png?15878425385',
+ });
+ }
+ setHandoutNotes(handout, out);
+
+ if (msg) {
+ reply(msg, scriptName, mode === 'dev' ? 'Dev Docs' : 'Help',
+ 'Generated ' + html.bold(handoutName) + '. ' + html.handoutLink('[Open]', handout.get('id')));
+ } else {
+ log(SCRIPT_NAME + ': Generated ' + handoutName + ' for ' + scriptName);
+ }
+ };
+
+ // =========================================================================
+ // Examples Listing
+ // =========================================================================
+
+ const showExamples = (msg, scriptName, reg, args) => {
+ // Parse search filters
+ let pluginFilter = null, nameFilter = null, descFilter = null;
+ const filterArgs = [];
+ args.forEach(a => {
+ if (a.toLowerCase().startsWith('script:')) pluginFilter = a.slice(7).toLowerCase();
+ else if (a.toLowerCase().startsWith('name:')) nameFilter = a.slice(5).toLowerCase();
+ else if (a.toLowerCase().startsWith('desc:')) descFilter = a.slice(5).toLowerCase();
+ else filterArgs.push(a);
+ });
+ const remainingFilter = filterArgs.length > 0 ? filterArgs.join(' ').toLowerCase() : null;
+ nameFilter = nameFilter || remainingFilter;
+ descFilter = descFilter || remainingFilter;
+
+ // Get examples targeting this script
+ const scriptExamples = Object.values(examples).filter(ex => ex.target === scriptName);
+ if (scriptExamples.length === 0) {
+ reply(msg, scriptName, 'Examples', 'No examples registered.');
+ return;
+ }
+
+ const hasSearch = pluginFilter || nameFilter || descFilter;
+ const matches = (body, filter) => filter ? (body || '').toLowerCase().indexOf(filter) !== -1 : true;
+ const isExact = (body, filter) => filter ? (body || '').toLowerCase() === filter : false;
+
+ // Tier matching
+ const tier1 = [], tier2 = [], tier3 = [];
+ const tier1Sources = new Set();
+
+ if (pluginFilter) {
+ scriptExamples.forEach(ex => {
+ if (ex.source.toLowerCase() === pluginFilter) {
+ tier1.push(ex);
+ tier1Sources.add(ex.source);
+ }
+ });
+ }
+
+ scriptExamples.forEach(ex => {
+ if (tier1Sources.has(ex.source)) return;
+ if (pluginFilter && ex.source.toLowerCase().indexOf(pluginFilter) === -1) return;
+ if (!hasSearch) { tier3.push(ex); return; }
+ if (!matches(ex.name, nameFilter) && !matches(ex.description, descFilter)) return;
+ if (isExact(ex.name, nameFilter) || isExact(ex.description, descFilter)) tier2.push(ex);
+ else tier3.push(ex);
+ });
+
+ const allMatches = [...tier1, ...tier2, ...tier3];
+ if (allMatches.length === 0) {
+ reply(msg, scriptName, 'Examples', 'No examples match. Use ' + html.code(reg.command + ' ' + reg.aliases.examples) + ' to see all.');
+ return;
+ }
+
+ // Group by source
+ const groups = [];
+ const groupMap = {};
+ allMatches.forEach(ex => {
+ if (!groupMap[ex.source]) {
+ groupMap[ex.source] = [];
+ groups.push({ source: ex.source, items: groupMap[ex.source] });
+ }
+ groupMap[ex.source].push(ex);
+ });
+ const tier2Sources = new Set(tier2.map(ex => ex.source));
+ groups.sort((a, b) => {
+ const ta = tier1Sources.has(a.source) ? 0 : tier2Sources.has(a.source) ? 1 : 2;
+ const tb = tier1Sources.has(b.source) ? 0 : tier2Sources.has(b.source) ? 1 : 2;
+ if (ta !== tb) return ta - tb;
+ return a.source.localeCompare(b.source);
+ });
+
+ let out = 'Filter: ' + html.code(reg.command + ' ' + reg.aliases.examples + ' ') + ', ' + html.code('script:') + html.paragraph('');
+ groups.forEach(g => {
+ out += html.bold(html.escape(g.source) + ':') + html.br();
+ g.items.forEach(ex => {
+ out += html.indent(2) + '• ' + renderExampleEntry(ex, reg, nameFilter, descFilter) + html.br();
+ });
+ });
+ reply(msg, scriptName, 'Examples', out);
+ };
+
+ /**
+ * Render a single example entry with name, description, and action buttons.
+ */
+ const renderExampleEntry = (ex, reg, nameHighlight, descHighlight) => {
+ const highlightMatch = (text, filter) => {
+ if (!filter) return html.escape(text);
+ const lower = text.toLowerCase();
+ let result = '', lastIdx = 0, idx = lower.indexOf(filter);
+ if (idx === -1) return html.escape(text);
+ while (idx !== -1) {
+ result += html.escape(text.slice(lastIdx, idx));
+ result += html.bold(html.escape(text.slice(idx, idx + filter.length)));
+ lastIdx = idx + filter.length;
+ idx = lower.indexOf(filter, lastIdx);
+ }
+ result += html.escape(text.slice(lastIdx));
+ return result;
+ };
+
+ const hasHandler = reg.exampleHandler || ex.handout;
+ const handoutName = hasHandler ? getHandoutName(reg.tag, ex.source, ex.name, null) : null;
+ const exists = handoutName ? findObjs({ type: 'handout', name: handoutName })[0] : null;
+ var entry = html.underline(highlightMatch(ex.name, nameHighlight || ''));
+ if (ex.description) entry += ' — ' + highlightMatch(ex.description, descHighlight || '');
+ entry += ' ';
+ if (ex.handout || reg.exampleHandler) {
+ if (exists) {
+ entry += html.button('🔄 Regen', reg.command + ' ' + reg.aliases.generate + ' ' + ex.name) + ' ';
+ if (ex.guide && ex.guide.length > 0) {
+ entry += html.button('🧭 Guide', reg.command + ' ' + reg.aliases.guide + ' ' + ex.name) + ' ';
+ }
+ entry += html.handoutLink('[Open]', exists.get('id'));
+ } else {
+ entry += html.button('+ Generate', reg.command + ' ' + reg.aliases.generate + ' ' + ex.name);
+ }
+ } else if (ex.guide && ex.guide.length > 0) {
+ entry += html.button('🧭 Guide', reg.command + ' ' + reg.aliases.guide + ' ' + ex.name);
+ }
+ return entry;
+ };
+
+ // =========================================================================
+ // Example Generation
+ // =========================================================================
+
+ const getHandoutName = (defaultTag, source, exampleName, handlerResult) => {
+ const tag = (handlerResult && handlerResult.tag) || defaultTag;
+ return (tag ? '[' + tag + '] ' : '') + source + '/example-' + exampleName;
+ };
+
+ const defaultExampleHandler = (example, msg) => {
+ const h = example.handout || {};
+ return {
+ notes: h.notes || '',
+ gmnotes: h.gmnotes || '',
+ avatar: h.avatar || '',
+ inplayerjournals: h.inplayerjournals || '',
+ archived: h.archived !== undefined ? h.archived : true,
+ };
+ };
+
+ const generateExample = (msg, scriptName, reg, args) => {
+ const exName = args[0];
+ const key = scriptName + '/' + exName;
+ const ex = examples[key];
+ if (!ex) {
+ replyError(msg, scriptName, 'No example named "' + (exName || '') + '". Use ' + html.code(reg.command + ' ' + reg.aliases.examples) + ' to see all.');
+ return;
+ }
+
+ const handoutName = ex.handout ? getHandoutName(reg.tag, ex.source, ex.name, null) : null;
+
+ // Build effective guide steps — inject _generate step if not explicitly placed
+ const hasGuide = ex.guide && ex.guide.length > 0;
+ const hasExplicitGenerate = hasGuide && ex.guide.some(s => s === HANDOUT_STEP);
+
+ if (hasGuide && !hasExplicitGenerate && ex.handout) {
+ // Auto-inject: function handout → append, object handout → prepend
+ if (typeof ex.handout === 'function') {
+ ex._effectiveGuide = ex.guide.concat([HANDOUT_STEP]);
+ } else {
+ ex._effectiveGuide = [HANDOUT_STEP].concat(ex.guide);
+ }
+ } else if (!hasGuide && ex.handout) {
+ // No guide at all — just a handout step
+ ex._effectiveGuide = [HANDOUT_STEP];
+ } else {
+ ex._effectiveGuide = ex.guide || [];
+ }
+
+ startGuide(msg, scriptName, reg, ex, handoutName);
+ };
+
+ // =========================================================================
+ // Guide Engine
+ // =========================================================================
+
+ const startGuideByName = (msg, scriptName, reg, args) => {
+ const exName = args[0];
+ const key = scriptName + '/' + exName;
+ const ex = examples[key];
+ if (!ex) {
+ replyError(msg, scriptName, 'No example named "' + (exName || '') + '".');
+ return;
+ }
+ if (!ex.guide || ex.guide.length === 0) {
+ replyError(msg, scriptName, 'Example "' + exName + '" has no setup guide.');
+ return;
+ }
+ const handoutName = getHandoutName(reg.tag, ex.source, ex.name, null);
+ startGuide(msg, scriptName, reg, ex, handoutName);
+ };
+
+ const startGuide = (msg, scriptName, reg, example, handoutName) => {
+ const guideId = 'guide-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8);
+
+ // Process steps — use _effectiveGuide if set by generateExample, otherwise guide
+ const steps = (example._effectiveGuide || example.guide || []).slice();
+
+ activeGuides[guideId] = {
+ steps: steps,
+ currentStep: 0,
+ selections: {},
+ params: {},
+ _lastQueryValues: {},
+ _queryErrors: {},
+ _hue: Math.floor(Math.random() * 360),
+ msg: msg,
+ handoutName: handoutName,
+ source: scriptName,
+ example: example,
+ reg: reg,
+ };
+
+ enterStep(guideId);
+ };
+
+ const performDeferredGeneration = (g) => {
+ const reg = registrations[g.source];
+ if (!reg) return;
+ const ex = g.example;
+ const ctx = { selections: g.selections, params: g.params, msg: g.msg, handoutName: g.handoutName, player: getObj('player', g.msg.playerid) };
+ const handoutData = typeof ex.handout === 'function' ? ex.handout(ctx) : ex.handout;
+ if (!handoutData) {
+ log(SCRIPT_NAME + ': handout step in "' + ex.name + '" but no handout data provided.');
+ return;
+ }
+ const handler = reg.exampleHandler || defaultExampleHandler;
+ const result = handler(Object.assign({}, ex, { handout: handoutData }), g.msg);
+ const handoutName = getHandoutName(reg.tag, ex.source, ex.name, result);
+ g.handoutName = handoutName;
+ var handout = findObjs({ type: 'handout', name: handoutName })[0];
+ if (!handout) {
+ handout = createObj('handout', { name: handoutName });
+ }
+ if (result.notes) setHandoutNotes(handout, result.notes);
+ if (result.gmnotes) handout.set('gmnotes', result.gmnotes);
+ if (result.avatar) handout.set('avatar', result.avatar);
+ if (result.inplayerjournals !== undefined) handout.set('inplayerjournals', result.inplayerjournals);
+ if (result.archived !== undefined) handout.set('archived', result.archived);
+ };
+
+ const enterStep = (guideId) => {
+ const g = activeGuides[guideId];
+ if (!g) return;
+ clearAnnotations();
+
+ if (g.currentStep >= g.steps.length) {
+ // All steps complete — call onComplete
+ completeGuide(guideId);
+ return;
+ }
+
+ const step = g.steps[g.currentStep];
+
+ // Conditional step — check 'when'
+ if (typeof step.when === 'function') {
+ const ctx = { selections: g.selections, params: g.params, msg: g.msg, player: getObj('player', g.msg.playerid) };
+ if (!step.when(ctx)) {
+ g.currentStep++;
+ enterStep(guideId);
+ return;
+ }
+ }
+
+ // Handout step — create/update the handout at this point
+ if (step === HANDOUT_STEP) {
+ performDeferredGeneration(g);
+ g.currentStep++;
+ enterStep(guideId);
+ return;
+ }
+
+ // Auto steps advance immediately
+ if (step.auto) {
+ if (typeof step.action === 'function') {
+ const ctx = { selections: g.selections, params: g.params, msg: g.msg, handoutName: g.handoutName, player: getObj('player', g.msg.playerid) };
+ step.action(ctx);
+ }
+ g.currentStep++;
+ enterStep(guideId);
+ return;
+ }
+
+ // Interactive step — show prompt
+ const interactiveSteps = g.steps.filter(s => !s.auto && s !== HANDOUT_STEP);
+ const interactiveIdx = interactiveSteps.indexOf(step) + 1;
+ const interactiveTotal = interactiveSteps.length;
+ const hasPriorInteractive = g.steps.slice(0, g.currentStep).some(s => !s.auto && s !== HANDOUT_STEP);
+
+ // Compute hue-rotated background color for this step
+ const hueIncrement = Math.max(60, 360 / (interactiveTotal || 1)) + 15;
+ const stepHue = (g._hue + (interactiveIdx - 1) * hueIncrement) % 360;
+ // Convert HSL(hue, 30%, 20%) to hex for Roll20 compatibility
+ const h = stepHue / 360, s = 0.3, l = 0.2;
+ const hue2rgb = (p, q, t) => { if (t < 0) t += 1; if (t > 1) t -= 1; if (t < 1/6) return p + (q - p) * 6 * t; if (t < 1/2) return q; if (t < 2/3) return p + (q - p) * (2/3 - t) * 6; return p; };
+ const q = l < 0.5 ? l * (1 + s) : l + s - l * s, p = 2 * l - q;
+ const r = Math.round(hue2rgb(p, q, h + 1/3) * 255), gr = Math.round(hue2rgb(p, q, h) * 255), b = Math.round(hue2rgb(p, q, h - 1/3) * 255);
+ const bgColor = '#' + ((1 << 24) + (r << 16) + (gr << 8) + b).toString(16).slice(1);
+
+ // Call onEnter if present, pass advance callback
+ if (typeof step.onEnter === 'function') {
+ const advance = (error) => {
+ if (typeof error === 'string') { replyError(g.msg, g.source, error); return; }
+ handleGuideContinue(g.msg, guideId, []);
+ };
+ const ctx = { selections: g.selections, params: g.params, msg: g.msg, handoutName: g.handoutName, advance: advance, player: getObj('player', g.msg.playerid) };
+ step.onEnter(ctx, advance);
+ }
+
+ const ctx = { selections: g.selections, params: g.params, msg: g.msg, handoutName: g.handoutName, player: getObj('player', g.msg.playerid) };
+ const promptText = typeof step.prompt === 'function' ? step.prompt(ctx) : step.prompt;
+
+ let prompt = html.div(
+ html.bold(html.escape(g.handoutName || g.example.name)) + ' — Setup (step ' + interactiveIdx + '/' + interactiveTotal + ')' + html.paragraph('')
+ + html.render(promptText) + html.paragraph('')
+ + (step.select ? (() => {
+ const plural = !step.max || step.max > 1;
+ const label = step.select + (plural ? 's' : '');
+ const parts = [];
+ if (step.min) parts.push('min: ' + step.min);
+ if (step.max) parts.push('max: ' + step.max);
+ return parts.length > 0 ? html.italic('Select ' + parts.join(', ') + ' ' + label) + html.paragraph('') : '';
+ })() : '')
+ + (step.query ? (() => {
+ const queries = Array.isArray(step.query) ? step.query : [step.query];
+ const lastVals = g._lastQueryValues || {};
+ const errors = g._queryErrors || {};
+ let qOut = '';
+ queries.forEach(q => {
+ if (errors[q.name]) qOut += html.span('⚠ ' + html.escape(errors[q.name]), { color: '#c33' }) + ' ';
+ qOut += html.bold(html.escape(q.name));
+ if (q.options) qOut += ' [dropdown]';
+ else if (lastVals[q.name] !== undefined) qOut += ' [' + html.escape(lastVals[q.name]) + ']';
+ else if (q.default !== undefined && q.default !== null) qOut += ' [' + html.escape(String(q.default)) + ']';
+ if (q.description) qOut += ' — ' + html.italic(html.escape(q.description));
+ qOut += html.br();
+ });
+ qOut += html.br();
+ const escQ = (v) => String(v).replace(/\|/g, '|').replace(/,/g, ',');
+ const queryParts = queries.map(q => {
+ var def = lastVals[q.name] !== undefined ? lastVals[q.name] : (q.default !== undefined && q.default !== null ? q.default : '');
+ if (q.options) {
+ var opts = q.options.map(o => typeof o === 'string' ? escQ(o) + ',' + escQ(o) : escQ(o.label) + ',' + escQ(o.value)).join('|');
+ return '--' + q.name + ' `?{' + q.name + '|' + opts + '}`';
+ }
+ if (q.type === Boolean) return '--' + q.name + ' `?{' + q.name + '|true|false}`';
+ if (def !== '') return '--' + q.name + ' `?{' + q.name + '|' + escQ(def) + '}`';
+ return '--' + q.name + ' `?{' + q.name + '}`';
+ }).join(' ');
+ qOut += html.button('✅ Continue', g.reg.command + ' ' + g.reg.aliases.guideContinue + ' ' + guideId + ' ' + queryParts);
+ return qOut;
+ })() : html.button('✅ Continue', g.reg.command + ' ' + g.reg.aliases.guideContinue + ' ' + guideId))
+ + (hasPriorInteractive ? ' ' + html.button('⬅ Back', g.reg.command + ' ' + g.reg.aliases.guideBack + ' ' + guideId) : '')
+ + ' ' + html.button('✖ Cancel', g.reg.command + ' ' + g.reg.aliases.guideCancel + ' ' + guideId)
+ + (step.offerExamples ? (() => {
+ var offered = '';
+ offered += html.paragraph('') + html.bold('What\'s Next?') + html.br();
+ step.offerExamples.forEach(function(name) {
+ var ex = Object.values(examples).find(function(e) { return e.name === name && e.target === g.source; });
+ if (!ex) return;
+ offered += '• ' + renderExampleEntry(ex, g.reg) + html.br();
+ });
+ return offered;
+ })() : ''),
+ { background: bgColor, color: '#fff', padding: '8px', borderRadius: '4px', fontSize: '12px' }
+ );
+
+ reply(g.msg, g.source, 'Guide', prompt);
+ };
+
+ const handleGuideContinue = (msg, guideId, queryArgs) => {
+ const g = activeGuides[guideId];
+ if (!g) { replyError(msg, SCRIPT_NAME, 'No active guide with that ID.'); return; }
+
+ const step = g.steps[g.currentStep];
+ const selected = (msg.selected || []).map(s => getObj(s._type, s._id)).filter(Boolean);
+
+ // Handle select steps
+ if (step.select) {
+ const selectType = step.select;
+ const isSubtype = selectType === 'token' || selectType === 'card';
+ const matchType = isSubtype ? 'graphic' : selectType;
+ const filtered = selected.filter(obj => {
+ if (obj.get('_type') !== matchType) return false;
+ if (isSubtype && obj.get('_subtype') !== selectType) return false;
+ return true;
+ });
+ const plural = !step.max || step.max > 1;
+ const label = selectType + (plural ? 's' : '');
+ if (filtered.length === 0) {
+ replyError(msg, g.source, 'Select at least one ' + selectType + ', then click Continue.');
+ return;
+ }
+ if (step.min && filtered.length < step.min) {
+ replyError(msg, g.source, 'Select at least ' + step.min + ' ' + label + ', then click Continue.');
+ return;
+ }
+ if (step.max && filtered.length > step.max) {
+ replyError(msg, g.source, 'Select at most ' + step.max + ' ' + label + ', then click Continue.');
+ return;
+ }
+ g.selections[step.as] = plural ? filtered : filtered[0];
+ }
+
+ // Handle query steps (parse --key value from pre-parsed args, coerce types)
+ if (step.query) {
+ const queries = Array.isArray(step.query) ? step.query : [step.query];
+ if (!g._lastQueryValues) g._lastQueryValues = {};
+ var queryErrors = {};
+ var coercedValues = {};
+
+ queries.forEach(q => {
+ // Find --name in queryArgs, value is the next arg
+ var raw = undefined;
+ var idx = (queryArgs || []).indexOf('--' + q.name);
+ if (idx !== -1 && idx + 1 < queryArgs.length) raw = queryArgs[idx + 1];
+
+ if (raw === undefined) {
+ if (q.default !== undefined && q.default !== null) {
+ coercedValues[q.name] = q.default;
+ g._lastQueryValues[q.name] = String(q.default);
+ } else {
+ queryErrors[q.name] = 'Required';
+ }
+ return;
+ }
+
+ g._lastQueryValues[q.name] = raw;
+
+ // Normalize type to a coercion function
+ var coerce = q.type || String;
+ if (coerce === Boolean) coerce = (v) => { if (v !== 'true' && v !== 'false') throw 'Must be true or false'; return v === 'true'; };
+ if (coerce === Number) coerce = (v) => { var n = Number(v); if (isNaN(n)) throw 'Invalid number'; return n; };
+
+ try {
+ coercedValues[q.name] = coerce(raw);
+ } catch (e) {
+ queryErrors[q.name] = typeof e === 'string' ? e : (e.message || 'Invalid value');
+ }
+ });
+
+ if (Object.keys(queryErrors).length > 0) {
+ g._queryErrors = queryErrors;
+ enterStep(guideId);
+ return;
+ }
+
+ // All passed — store coerced values in params, clear errors
+ Object.assign(g.params, coercedValues);
+ g._queryErrors = {};
+ }
+
+ // Role assignment (Choreograph compatibility)
+ if (step.role) {
+ if (!g.selections._roles) g.selections._roles = {};
+ g.selections._roles[step.role] = selected;
+ }
+
+ // onContinue callback — if it returns a string or html.raw(), treat as validation error
+ if (typeof step.onContinue === 'function') {
+ const ctx = { selections: g.selections, params: g.params, selected: selected, msg: msg, player: getObj('player', msg.playerid) };
+ const err = step.onContinue(ctx);
+ if (typeof err === 'string') {
+ replyError(msg, g.source, err);
+ return;
+ }
+ if (err && err.__raw) {
+ replyError(msg, g.source, err);
+ return;
+ }
+ }
+
+ g.currentStep++;
+ enterStep(guideId);
+ };
+
+ const handleGuideBack = (msg, guideId) => {
+ const g = activeGuides[guideId];
+ if (!g || g.currentStep <= 0) return;
+
+ // Call onExit on the step we're leaving
+ const leavingStep = g.steps[g.currentStep];
+ if (leavingStep && typeof leavingStep.onExit === 'function') {
+ const ctx = { selections: g.selections, params: g.params, msg: msg, handoutName: g.handoutName, player: getObj('player', msg.playerid) };
+ leavingStep.onExit(ctx);
+ }
+
+ // Undo current step
+ const currentStep = g.steps[g.currentStep];
+ if (currentStep && currentStep.as) delete g.selections[currentStep.as];
+ if (currentStep && currentStep.role && g.selections._roles) delete g.selections._roles[currentStep.role];
+
+ // Step backward
+ g.currentStep--;
+ const step = g.steps[g.currentStep];
+
+ // onBack callback
+ if (typeof step.onBack === 'function') {
+ const ctx = { selections: g.selections, params: g.params, msg: msg, player: getObj('player', msg.playerid) };
+ step.onBack(ctx);
+ }
+
+ // Undo this step's data
+ if (step.as) delete g.selections[step.as];
+ if (step.role && g.selections._roles) delete g.selections._roles[step.role];
+
+ // Skip past auto steps when backing up
+ if (step.auto && g.currentStep > 0) {
+ handleGuideBack(msg, guideId);
+ return;
+ }
+
+ enterStep(guideId);
+ };
+
+ const handleGuideCancel = (msg, guideId) => {
+ const g = activeGuides[guideId];
+ if (!g) return;
+
+ // onBack for all steps
+ for (let i = g.currentStep; i >= 0; i--) {
+ const step = g.steps[i];
+ if (typeof step.onBack === 'function') {
+ const ctx = { selections: g.selections, params: g.params, msg: msg, player: getObj('player', msg.playerid) };
+ step.onBack(ctx);
+ }
+ }
+
+ delete activeGuides[guideId];
+ reply(msg, g.source, 'Guide', 'Setup cancelled.');
+ };
+
+ const completeGuide = (guideId) => {
+ const g = activeGuides[guideId];
+ if (!g) return;
+
+ const handout = g.handoutName ? findObjs({ type: 'handout', name: g.handoutName })[0] : null;
+
+ const ctx = {
+ selections: g.selections,
+ params: g.params,
+ msg: g.msg,
+ handoutName: g.handoutName,
+ handout: handout || null,
+ example: g.example,
+ };
+
+ // Call script-level onComplete if registered
+ const reg = registrations[g.source];
+ if (reg && typeof reg.onComplete === 'function') {
+ reg.onComplete(ctx);
+ }
+
+ // Call example-level onComplete if present
+ if (typeof g.example.onComplete === 'function') {
+ g.example.onComplete(ctx);
+ }
+
+ let outMsg = 'Setup complete for ' + html.bold(html.escape(g.handoutName || g.example.name)) + '.';
+ if (handout) outMsg += ' [Open]';
+ reply(g.msg, g.source, 'Guide', outMsg);
+
+ delete activeGuides[guideId];
+ };
+
+ // =========================================================================
+ // Ping Command
+ // =========================================================================
+
+ /**
+ * Build a !scriptkit ping command string.
+ * @param {string|object} target - An object ID string, or { pageid, x, y }
+ * @param {object} [opts] - Options: color, moveAll, visibleTo (string of comma-delimited IDs or array)
+ * @returns {string} The chat command string
+ */
+ const pingCommand = (target, opts) => {
+ opts = opts || {};
+ var cmd;
+ if (typeof target === 'string') {
+ cmd = '!scriptkit ping ' + target;
+ } else {
+ cmd = '!scriptkit ping ' + target.pageid + ' ' + target.x + ' ' + target.y;
+ }
+ if (opts.color) cmd += ' --color ' + opts.color;
+ if (opts.moveAll) cmd += ' --moveAll';
+ if (opts.visibleTo) {
+ // Normalize: array → comma-joined, strip all spaces
+ var vt = Array.isArray(opts.visibleTo) ? opts.visibleTo.join(',') : String(opts.visibleTo);
+ cmd += ' --visibleTo ' + vt.replace(/\s+/g, '');
+ }
+ return cmd;
+ };
+
+ /**
+ * Handle !scriptkit ping [--color X] [--moveAll] [--visibleTo X,Y,Z]
+ */
+ const doPing = (msg, content) => {
+ var parts = content.split(/\s+/);
+ var positional = [];
+ var color = null;
+ var moveAll = false;
+ var visibleTo = null;
+
+ for (var i = 0; i < parts.length; i++) {
+ if (parts[i] === '--color' && i + 1 < parts.length) {
+ color = parts[++i];
+ } else if (parts[i] === '--moveAll') {
+ moveAll = true;
+ } else if (parts[i] === '--visibleTo' && i + 1 < parts.length) {
+ // Comma-delimited, no spaces (stripped by pingCommand)
+ visibleTo = parts[++i].split(',').filter(Boolean);
+ } else {
+ positional.push(parts[i]);
+ }
+ }
+
+ var pageId, x, y;
+
+ if (positional.length === 1) {
+ // Object ID mode — try graphic, then pin, then pathv2
+ var objId = positional[0];
+ var obj = getObj('graphic', objId) || getObj('pin', objId) || getObj('pathv2', objId);
+ if (!obj) {
+ sendChat('ScriptKit', '/w "' + msg.who.replace(/\s+\(GM\)$/, '') + '" Ping: object not found: ' + objId);
+ return;
+ }
+ pageId = obj.get('_pageid') || obj.get('pageid');
+ x = obj.get('left') !== undefined ? obj.get('left') : obj.get('x');
+ y = obj.get('top') !== undefined ? obj.get('top') : obj.get('y');
+ } else if (positional.length === 3) {
+ // Coordinate mode: pageId x y
+ pageId = positional[0];
+ x = parseFloat(positional[1]);
+ y = parseFloat(positional[2]);
+ } else {
+ sendChat('ScriptKit', '/w "' + msg.who.replace(/\s+\(GM\)$/, '') + '" Usage: !scriptkit ping <objId> | !scriptkit ping <pageId> <x> <y>');
+ return;
+ }
+
+ var player = getObj('player', msg.playerid);
+ guidePing(pageId, x, y, {
+ player: player,
+ playerId: msg.playerid,
+ color: color,
+ moveAll: moveAll,
+ visibleTo: visibleTo,
+ });
+ };
+
+ // =========================================================================
+ // Public API
+ // =========================================================================
+
+ // =========================================================================
+ // Public API (Proxy-based for namespace access)
+ // =========================================================================
+
+ const api = {
+ VERSION: SCRIPT_VERSION,
+ register,
+ registerExample,
+ handleInput,
+ html,
+ handout: () => HANDOUT_STEP,
+ ping: guidePing,
+ pingCommand,
+ annotate: guideAnnotate,
+ clearAnnotations: clearAnnotations,
+ waitForCommand: (cmd) => ({
+ onEnter: (ctx, advance) => {
+ ctx._waitFired = false;
+ on('chat:message', (msg) => {
+ if (ctx._waitFired) return;
+ if (msg.type === 'api' && msg.content.split(' ').slice(0, cmd.split(' ').length).join(' ') === cmd) {
+ ctx._waitFired = true;
+ advance();
+ }
+ });
+ },
+ onExit: (ctx) => {
+ ctx._waitFired = true;
+ },
+ }),
+ getHandoutName,
+ startGuide: (msg, scriptName, example, handoutName) => {
+ const reg = registrations[scriptName];
+ if (!reg) return;
+ startGuide(msg, scriptName, reg, example, handoutName);
+ },
+ getExamples: (scriptName) => Object.values(examples).filter(ex => ex.target === scriptName),
+ getActiveGuides: () => activeGuides,
+ generateHandoutImmediately: (scriptName, mode) => {
+ if (!mode) { log(SCRIPT_NAME + ': generateHandoutImmediately requires mode ("usr" or "dev").'); return; }
+ const reg = registrations[scriptName];
+ if (!reg) { log(SCRIPT_NAME + ': generateHandoutImmediately — "' + scriptName + '" is not registered.'); return; }
+ generateHelpHandout(null, scriptName, reg, mode);
+ },
+ updateHandoutImmediately: (scriptName, mode) => {
+ if (!mode) { log(SCRIPT_NAME + ': updateHandoutImmediately requires mode ("usr" or "dev").'); return; }
+ const reg = registrations[scriptName];
+ if (!reg) { log(SCRIPT_NAME + ': updateHandoutImmediately — "' + scriptName + '" is not registered.'); return; }
+ var handoutName = 'Help: ' + scriptName + (mode === 'dev' ? '/Dev' : '');
+ if (!findObjs({ type: 'handout', name: handoutName })[0]) return;
+ generateHelpHandout(null, scriptName, reg, mode);
+ },
+ generateHandout: (scriptName, mode, delay = 2000) => {
+ if (!mode) { log(SCRIPT_NAME + ': generateHandout requires mode ("usr" or "dev").'); return; }
+ var key = scriptName + ':' + mode + ':gen';
+ if (!api._handoutTimers) api._handoutTimers = {};
+ if (api._handoutTimers[key]) clearTimeout(api._handoutTimers[key]);
+ api._handoutTimers[key] = setTimeout(() => { delete api._handoutTimers[key]; api.generateHandoutImmediately(scriptName, mode); }, delay);
+ },
+ updateHandout: (scriptName, mode, delay = 2000) => {
+ if (!mode) { log(SCRIPT_NAME + ': updateHandout requires mode ("usr" or "dev").'); return; }
+ var key = scriptName + ':' + mode + ':upd';
+ if (!api._handoutTimers) api._handoutTimers = {};
+ if (api._handoutTimers[key]) clearTimeout(api._handoutTimers[key]);
+ api._handoutTimers[key] = setTimeout(() => { delete api._handoutTimers[key]; api.updateHandoutImmediately(scriptName, mode); }, delay);
+ },
+ };
+
+ // Tutorial.Choreograph.registerExample('Sequence', { ... })
+ // Auto-creates namespace proxy for any unrecognized property access
+ return new Proxy(api, {
+ get(target, prop) {
+ if (prop in target) return target[prop];
+ if (typeof prop === 'symbol') return undefined;
+ return {
+ registerExample: (registeredBy, struct) => registerExample(String(prop), registeredBy, struct),
+ };
+ },
+ });
+})();
+
+
+on('ready', () => {
+ 'use strict';
+ // Clean up any annotations from a previous session/crash
+ if (state.ScriptKit && state.ScriptKit._annotations && state.ScriptKit._annotations.length > 0) {
+ state.ScriptKit._annotations.forEach(function(id) {
+ var obj = getObj('pathv2', id);
+ if (obj) obj.remove();
+ });
+ state.ScriptKit._annotations = [];
+ }
+ on('chat:message', (msg) => {
+ if (msg.type === 'api' && msg.content.split(' ')[0] === '!scriptkit') {
+ ScriptKit.handleInput(msg);
+ }
+ });
+ ScriptKit.register('ScriptKit', {
+ version: ScriptKit.VERSION,
+ command: 'scriptkit',
+ handout: 'manual',
+ aliases: new Proxy({}, { get: (_, key) => key === 'genDev' ? undefined : null }),
+ help: {
+ description: 'Generic framework library for Roll20 API scripts.',
+ changelog: [
+ { version: '1.2.0', changes: [
+ 'Added `!scriptkit ping` command — ping an object by ID or by coordinates',
+ 'Added `ScriptKit.pingCommand(target, opts)` — build ping command strings for chat links',
+ 'Added `html.pingObjBtn(target, opts)` / `html.pingObjImg(target, opts)` — clickable ping buttons/images',
+ '`visibleTo` now accepts array of player IDs or comma-delimited string',
+ ]},
+ { version: '1.1.0', changes: [
+ 'Prevent double-registration (same script calling register() twice is now a no-op)',
+ 'Added ScriptKit.generateHandout / updateHandout (debounced, default 2s) for deferred handout regeneration',
+ 'Added ScriptKit.generateHandoutImmediately / updateHandoutImmediately for synchronous generation',
+ ]},
+ ],
+ topics: {
+ textRendering: {
+ title: '⚠️ Text Rendering',
+ description: 'How ScriptKit handles all text output',
+ handouts: 'dev',
+ version: '1.0.0',
+ body: '**All text in ScriptKit is auto-formatted by default.** Any string you provide for descriptions, prompts, bodies, item names, motd, etc. will have HTML escaped, markdown converted (`` `code` `` → code, `**bold**` → bold, `*italic*` → italic), and `\\n` converted to line breaks.\n\nIf you need to pass **raw HTML** (e.g. from `html.bold()`, `html.table()`, or hand-crafted HTML), wrap it in `html.raw(...)`.\n\nWithout `html.raw()`, HTML tags would be escaped and displayed as literal text.',
+ },
+ registration: {
+ title: 'Registering Your Script',
+ description: 'How to register with ScriptKit',
+ handouts: 'dev',
+ version: '1.0.0',
+ body: 'Call `ScriptKit.register(name, opts)` to gain help, man, examples, handout generation, and migration commands. The `!` prefix on command is optional — it is auto-prepended.',
+ items: [
+ { name: 'command (required)', description: 'Your script\'s chat command prefix (e.g. "myscript" or "!myscript")', version: '1.0.0' },
+ { name: 'version (required)', description: 'Current script version string (e.g. "1.2.0")', version: '1.0.0' },
+ { name: 'tag', description: 'Example handout prefix: [Tag] source/example-name. Optional.', version: '1.0.0' },
+ { name: 'help', description: 'Object with description, quickStart, changelog, commands, topics', version: '1.0.0' },
+ { name: 'aliases', description: 'Override command keywords. Set to null to disable. Proxy-friendly.', version: '1.0.0' },
+ { name: 'newSince', description: 'Version threshold for [new] badges. Default: auto-detect from major.minor change.', version: '1.0.0' },
+ { name: 'handout', description: 'User help handout mode: "auto" (default) | "update" | "manual"', version: '1.0.0' },
+ { name: 'devHandout', description: 'Dev docs handout mode: "auto" | "update" (default) | "manual"', version: '1.0.0' },
+ { name: 'state', description: 'Reference to your persistent state object (for migrations)', version: '1.0.0' },
+ { name: 'migrations', description: 'Object keyed by version: { up: fn, down: "string" }', version: '1.0.0' },
+ { name: 'motd', description: 'Array of tip strings — random one whispered to GM on startup', version: '1.0.0' },
+ { name: 'motdHeader', description: 'Custom header for MOTD card (string or function)', version: '1.0.0' },
+ { name: 'motdStyle', description: 'CSS style override object for MOTD card', version: '1.0.0' },
+ { name: 'exampleHandler', description: 'Custom (example, msg) => handoutFields function for non-default example generation', version: '1.0.0' },
+ { name: 'onComplete', description: 'Callback fired when any guide completes: (ctx) => void', version: '1.0.0' },
+ { name: 'onMigrationFailure', description: 'Callback on migration error: ({ version, direction, error, currentStoredVersion }) => void', version: '1.0.0' },
+ ],
+ },
+ helpData: {
+ title: 'Help Data Structure',
+ description: 'Defining commands, topics, and changelog',
+ handouts: 'dev',
+ version: '1.0.0',
+ body: 'The `help` object defines what appears in chat help, man search, whatsnew, and generated handouts.',
+ items: [
+ { name: 'description', description: 'Short text shown at top of help and handout', version: '1.0.0' },
+ { name: 'quickStart', description: 'Array of strings — rendered as ordered list in handout', version: '1.0.0' },
+ { name: 'changelog', description: 'Array of { version, changes[] } — explicit whatsnew entries', version: '1.0.0' },
+ { name: 'commands', description: 'Array of { group, commands[] } — grouped command list', version: '1.0.0' },
+ { name: 'command.syntax', description: 'Usage string (e.g. "run [--flag]")', version: '1.0.0' },
+ { name: 'command.description', description: 'Short description for help list', version: '1.0.0' },
+ { name: 'command.details', description: 'Longer explanation — handout only', version: '1.0.0' },
+ { name: 'command.items', description: 'Sub-items (flags/args) — rendered as bullet list', version: '1.0.0' },
+ { name: 'command.version', description: 'Version when added — used for [new] badge', version: '1.0.0' },
+ { name: 'topics', description: 'Object keyed by id — detailed help topics for man/handout', version: '1.0.0' },
+ { name: 'topic.title', description: 'Display title', version: '1.0.0' },
+ { name: 'topic.body', description: 'Main content — string or () => string', version: '1.0.0' },
+ { name: 'topic.handouts', description: '"usr" (default) | "dev" | ["usr","dev"] | null (man-only)', version: '1.0.0' },
+ { name: 'topic.items', description: 'Array of { name, description, version } sub-items', version: '1.0.0' },
+ ],
+ },
+ examples: {
+ title: 'Registering Examples',
+ description: 'How to add examples for any script',
+ handouts: 'dev',
+ version: '1.0.0',
+ body: '`ScriptKit.TargetScript.registerExample(yourScript, struct)` — registers an example for any ScriptKit-enabled script.\n\nLoad order does not matter — examples queue via Proxy and drain when the target registers. Your script can register examples for itself or for other scripts.',
+ items: [
+ { name: 'name', description: 'Unique example name (required)', version: '1.0.0' },
+ { name: 'description', description: 'Shown in examples menu', version: '1.0.0' },
+ { name: 'guide', description: 'Array of guide steps — required if no handout', version: '1.0.0' },
+ { name: 'handout', description: 'Object or (ctx) => object — required if no guide', version: '1.0.0' },
+ { name: 'handout.notes', description: 'Main handout content', version: '1.0.0' },
+ { name: 'handout.gmnotes', description: 'GM-only notes', version: '1.0.0' },
+ { name: 'handout.archived', description: 'Archive on create (default: true)', version: '1.0.0' },
+ { name: 'onComplete', description: '(ctx) => void — called when guide finishes', version: '1.0.0' },
+ ],
+ },
+ guides: {
+ title: 'Guide Steps',
+ description: 'Interactive wizard step API',
+ handouts: 'dev',
+ version: '1.0.0',
+ body: 'Each step is an object with `prompt` (string or (ctx) => string, supports `` `code` ``, `**bold**`, `*italic*`).\n\n**ctx object:** `selections`, `params`, `msg`, `handoutName`, `selected`\n\nSteps render with hue-rotating backgrounds for visual progression. Errors support markdown formatting.',
+ items: [
+ { name: 'prompt', description: 'String or (ctx) => string — step text with markdown support', version: '1.0.0' },
+ { name: 'select', description: 'Roll20 _type filter: "token", "card", "pin", "path"', version: '1.0.0' },
+ { name: 'as', description: 'Key to store selection result in ctx.selections', version: '1.0.0' },
+ { name: 'min / max', description: 'Selection count constraints', version: '1.0.0' },
+ { name: 'query', description: 'Object or array: { name, default?, type?, options? }', version: '1.0.0' },
+ { name: 'query.type', description: 'Number, Boolean, String (default), or custom (v) => value that throws on error', version: '1.0.0' },
+ { name: 'query.options', description: 'Array of { label, value } or strings — renders as Roll20 dropdown', version: '1.0.0' },
+ { name: 'onContinue', description: '(ctx) => errorString? — validate before advancing', version: '1.0.0' },
+ { name: 'onEnter', description: '(ctx, advance) => void — called on step entry. advance(error?) to continue.', version: '1.0.0' },
+ { name: 'onExit', description: '(ctx) => void — cleanup on Back navigation', version: '1.0.0' },
+ { name: 'auto: true', description: 'Skip without user interaction (not counted in step total)', version: '1.0.0' },
+ { name: 'ScriptKit.handout()', description: 'Sentinel step — generates handout at this point in the guide', version: '1.0.0' },
+ { name: '...ScriptKit.waitForCommand(cmd)', description: 'Spread onto step — auto-advances when cmd detected in chat', version: '1.0.0' },
+ { name: 'offerExamples', description: 'Array of example names — renders "What\'s Next?" buttons below the step', version: '1.0.0' },
+ ],
+ },
+ guideAnnotations: {
+ title: 'Guide Annotations',
+ description: 'Temporary visual aids for interactive guides',
+ handouts: 'dev',
+ version: '1.0.0',
+ body: 'Draw temporary shapes on the map during guide steps to highlight elements. Annotations auto-clear on step transition and are persisted in state for crash recovery.',
+ items: [
+ { name: 'ScriptKit.ping(pageId, x, y, opts)', description: 'Ping the map and move camera. opts: { player, color, moveAll, visibleTo, playerId }', version: '1.0.0' },
+ { name: 'ScriptKit.pingCommand(target, opts)', description: 'Build a !scriptkit ping command string. target: objId string or { pageid, x, y }. opts: color, moveAll, visibleTo', version: '1.2.0' },
+ { name: 'ScriptKit.annotate(pageId, shape, x, y, opts)', description: 'Draw a temporary pathv2. Returns the object. Shapes: circle, arrow, line, rect', version: '1.0.0' },
+ { name: 'ScriptKit.clearAnnotations()', description: 'Remove all active annotations manually', version: '1.0.0' },
+ { name: 'circle opts', description: 'radius (default 40), color, strokeWidth, fill', version: '1.0.0' },
+ { name: 'arrow opts', description: 'fromX, fromY (tail position), chevronDepth, chevronWidth, color, strokeWidth, fill', version: '1.0.0' },
+ { name: 'line opts', description: 'fromX, fromY (start position), color, strokeWidth, fill', version: '1.0.0' },
+ { name: 'rect opts', description: 'width (default 80), height (default 80), color, strokeWidth, fill', version: '1.0.0' },
+ { name: 'ping opts.color', description: 'Temporarily swaps player color before pinging (100ms delay, restores after 200ms)', version: '1.0.0' },
+ ],
+ },
+ handouts: {
+ title: 'Example Handouts',
+ description: 'Static and dynamic handout generation',
+ handouts: 'dev',
+ version: '1.0.0',
+ body: 'The `handout` field can be a static object (generated before guide) or a function receiving `ctx` (generated after guide collects params).\n\nPlace `ScriptKit.handout()` in guide to control generation timing. Without it: function handouts generate at end, object handouts at start.\n\n**Naming:** `[tag] source/example-name` (no tag prefix if tag is not set).',
+ },
+ htmlHelpers: {
+ title: 'HTML Helpers',
+ description: 'Formatting utilities via ScriptKit.html',
+ handouts: 'dev',
+ version: '1.0.0',
+ body: 'Available via `ScriptKit.html`. Use these in topic bodies, prompts, and handout content.',
+ items: [
+ { name: 'escape(str)', description: 'HTML entities + \\n →
', version: '1.0.0' },
+ { name: 'format(str)', description: 'Escape + `code`, **bold**, *italic*', version: '1.0.0' },
+ { name: 'bold / italic / underline / small / sup / code / pre', description: 'Tag wrappers with optional style object', version: '1.0.0' },
+ { name: 'button(label, cmd, style?)', description: 'Clickable command link', version: '1.0.0' },
+ { name: 'table(headers, rows, style?)', description: 'HTML table', version: '1.0.0' },
+ { name: 'list(items)', description: 'Unordered list (<ul>)', version: '1.0.0' },
+ { name: 'orderedList(items)', description: 'Ordered list (<ol>)', version: '1.0.0' },
+ { name: 'handoutLink(text, id)', description: 'Journal link', version: '1.0.0' },
+ { name: 'newBadge() / deprecatedBadge()', description: 'Version badge markers', version: '1.0.0' },
+ { name: 'style(obj)', description: 'Convert camelCase object to CSS string', version: '1.0.0' },
+ { name: 'pingObjBtn(target, opts?)', description: 'Clickable text button that pings an object location. opts: color, moveAll, visibleTo, label, style', version: '1.2.0' },
+ { name: 'pingObjImg(target, opts?)', description: 'Clickable token image that pings on click. opts: color, moveAll, visibleTo, imgsrc, width, height, label. Falls back to pingObjBtn', version: '1.2.0' },
+ ],
+ },
+ migrations: {
+ title: 'State Migrations',
+ description: 'Versioned state upgrades and rollbacks',
+ handouts: 'dev',
+ version: '1.0.0',
+ body: 'Register `state` and `migrations` to enable auto-upgrade and manual rollback.\n\n**up** — function, runs on upgrade. Receives state reference.\n**down** — string, persisted in state.ScriptKit.migrations for rollback after code swap.\n**Working copy** — all migrations run on a JSON clone. Committed only if all succeed.\n**Failure** — throw to abort. State remains untouched.\n\n**Rollback scenario:** Install v1.2.0 (down strings stored) → downgrade to v1.0.0 → run `!cmd migrate` → stored strings eval\'d → state rolled back.',
+ items: [
+ { name: 'up: (state) => { ... }', description: 'Forward migration function', version: '1.0.0' },
+ { name: 'down: "(state) => { ... }"', description: 'Rollback as string — must be self-contained, no closures', version: '1.0.0' },
+ { name: '!cmd migrate', description: 'Syncs state to current script version (forward or backward)', version: '1.0.0' },
+ ],
+ },
+ motd: {
+ title: 'MOTD',
+ description: 'Message of the Day — random tips on startup',
+ handouts: 'dev',
+ version: '1.0.0',
+ body: 'Whispers a random tip from `motd` array to the GM on sandbox restart. Styled as a card with customizable header and frame.',
+ items: [
+ { name: 'motd', description: 'Array of tip strings (supports markdown formatting). Empty = disabled.', version: '1.0.0' },
+ { name: 'motdHeader', description: 'String or (version) => string. Default: "💡 ScriptName vX.Y.Z"', version: '1.0.0' },
+ { name: 'motdStyle', description: 'CSS style object merged with default card appearance', version: '1.0.0' },
+ ],
+ },
+ readySignal: {
+ title: 'Ready Signal',
+ description: 'Load-order coordination between scripts',
+ handouts: 'dev',
+ version: '1.0.0',
+ body: '`ScriptKit.register()` automatically sends `!-ready` to chat. Other scripts listen for this to know when your script is available for direct API calls.\n\nExample registration does NOT require the ready signal — the Proxy queues automatically regardless of load order.',
+ },
+ dynamicHandouts: {
+ title: 'Dynamic Handout Content',
+ description: 'Keeping handouts up-to-date with post-init registrations',
+ handouts: 'dev',
+ version: '1.1.0',
+ body: 'If your script has topics with dynamic content (e.g. listing registered extensions), the handout generated at startup may be incomplete — other scripts register after yours.\n\n'
+ + '**Step 1: Function bodies** — Use `body: () => ...` in topics. Chat commands (`man`) always evaluate live, giving users current info. Without this, content is static and regeneration has no effect.\n\n'
+ + '**Step 2: Programmatic regeneration** — Call `ScriptKit.generateHandout()` or `ScriptKit.updateHandout()` after extensions finish registering. This re-renders the handout, invoking your function bodies with up-to-date data.\n\n'
+ + '**Pattern:** Debounce a timer in your extension registration functions. After the last registration, the timer fires and regenerates the handout once.',
+ items: [
+ { name: 'ScriptKit.generateHandout(scriptName, mode, delay?)', description: 'Schedule handout generation (debounced, default 2000ms). Creates handout if missing. Repeated calls reset the timer.', version: '1.1.0' },
+ { name: 'ScriptKit.updateHandout(scriptName, mode, delay?)', description: 'Schedule handout regeneration only if it already exists (debounced, default 2000ms). No-op if handout is missing.', version: '1.1.0' },
+ { name: 'ScriptKit.generateHandoutImmediately(scriptName, mode)', description: 'Generate handout synchronously without debounce. Creates if missing.', version: '1.1.0' },
+ { name: 'ScriptKit.updateHandoutImmediately(scriptName, mode)', description: 'Regenerate handout synchronously only if it exists.', version: '1.1.0' },
+ { name: 'body: () => string', description: 'Topic body as a function — evaluated at render time (chat man) and at handout generation. Always reflects current state.', version: '1.0.0' },
+ ],
+ },
+ scriptKit: null,
+ }
+ }
+ });
+});
\ No newline at end of file
diff --git a/ScriptKit/README.md b/ScriptKit/README.md
index 36162261a..1545fe138 100644
--- a/ScriptKit/README.md
+++ b/ScriptKit/README.md
@@ -332,6 +332,22 @@ Available via `ScriptKit.html`:
| `list(items)` / `orderedList(items)` | `` / `` |
| `handoutLink(text, id)` | Journal link |
| `newBadge()` / `deprecatedBadge()` | Version badges |
+| `pingObjBtn(target, opts?)` | Clickable text button that pings an object's location |
+| `pingObjImg(target, opts?)` | Clickable token image that pings an object's location |
+
+**`pingObjBtn(target, opts)`** — Renders a styled button that runs `!scriptkit ping` when clicked.
+- `target` — Object ID string, or `{ pageid, x, y }`
+- `opts.color` — Ping color
+- `opts.moveAll` — Move all players' cameras
+- `opts.visibleTo` — Player ID(s) as string (comma-delimited) or array
+- `opts.label` — Button text (default: the object ID)
+- `opts.style` — CSS style overrides
+
+**`pingObjImg(target, opts)`** — Renders a token image thumbnail that pings when clicked. Falls back to `pingObjBtn` if no image.
+- Inherits all `pingObjBtn` options, plus:
+- `opts.imgsrc` — Token image URL (auto-converted to `/thumb.` for chat)
+- `opts.width` / `opts.height` — Thumbnail size in pixels (default: 40×40)
+- `opts.label` — Shown below the image as `` text
### Query Type Coercion
@@ -423,6 +439,22 @@ onEnter: (ctx) => {
**`ScriptKit.clearAnnotations()`** — Remove all active annotations manually.
+**`ScriptKit.pingCommand(target, opts)`** — Build a `!scriptkit ping` command string (for embedding in chat messages).
+- `target` — Object ID string, or `{ pageid, x, y }`
+- `opts.color` — Ping color
+- `opts.moveAll` — Move all players' cameras (flag present = true)
+- `opts.visibleTo` — Player ID(s) as comma-delimited string or array
+
+```js
+// Build a ping command for a token
+var cmd = ScriptKit.pingCommand(token.get('id'), { color: '#ff0000', moveAll: true });
+// → "!scriptkit ping -ABC123xyz --color #ff0000 --moveAll"
+
+// Build a ping command for coordinates
+var cmd = ScriptKit.pingCommand({ pageid: pageId, x: 350, y: 700 });
+// → "!scriptkit ping -PageId123 350 700"
+```
+
### MOTD (Message of the Day)
Display a random tip to the GM on sandbox startup. Helps with feature discoverability.
@@ -446,8 +478,59 @@ ScriptKit.register('MyScript', {
A random tip is whispered to the GM once per sandbox restart, styled as a compact card.
+### Dynamic Handout Content
+
+If your script has help topics with dynamic content (e.g. listing registered extensions from other scripts), the handout generated at startup may be incomplete — other scripts register their extensions after yours.
+
+**Step 1: Use function bodies** — topics with `body: () => ...` are evaluated at render time. Chat commands (`man`) always show live data. Without function bodies, content is static and regeneration has no effect.
+
+```js
+topics: {
+ registeredFunctions: {
+ title: 'Registered Functions',
+ body: () => {
+ const fns = Object.values(MY_REGISTRY);
+ if (fns.length === 0) return '*None registered.*';
+ return fns.map(f => '**' + f.name + '()** — ' + f.description).join('\n');
+ },
+ }
+}
+```
+
+**Step 2: Trigger regeneration** — call `ScriptKit.updateHandout()` after extensions finish registering. It debounces by default (2s), so repeated calls within the window only fire once:
+
+```js
+// Call this at the end of each successful extension registration
+const onExtensionRegistered = () => {
+ if (typeof ScriptKit !== 'undefined') ScriptKit.updateHandout('MyScript', 'usr');
+};
+```
+
+**`ScriptKit.generateHandout(scriptName, mode, delay?)`** — Schedule handout generation/regeneration (debounced, default 2000ms). Creates the handout if it doesn't exist. `mode` is required: `'usr'` or `'dev'`.
+
+**`ScriptKit.updateHandout(scriptName, mode, delay?)`** — Same as above, but no-op if the handout doesn't exist yet. Use this when you don't want to create handouts that the user hasn't explicitly requested.
+
+**`ScriptKit.generateHandoutImmediately(scriptName, mode)`** — Generate synchronously, no debounce.
+
+**`ScriptKit.updateHandoutImmediately(scriptName, mode)`** — Regenerate synchronously, only if exists.
+
## Changelog
+### v1.2.0
+- Added `!scriptkit ping` chat command — pings an object's location by ID or by pageId/x/y coordinates
+- Added `ScriptKit.pingCommand(target, opts)` — builds a ping command string for embedding in chat links
+- Added `ScriptKit.html.pingObjBtn(target, opts)` — clickable text button that pings on click
+- Added `ScriptKit.html.pingObjImg(target, opts)` — clickable token image thumbnail that pings on click
+- `visibleTo` option now accepts an array of player IDs or a comma-delimited string
+
+### v1.1.0
+- Prevent double-registration (same script calling `register()` twice is now a no-op)
+- Added `ScriptKit.generateHandout(scriptName, mode, delay?)` — debounced handout generation (default 2s)
+- Added `ScriptKit.updateHandout(scriptName, mode, delay?)` — debounced, only if handout exists
+- Added `ScriptKit.generateHandoutImmediately(scriptName, mode)` — synchronous generation
+- Added `ScriptKit.updateHandoutImmediately(scriptName, mode)` — synchronous, only if exists
+- Added `SCRIPT_VERSION` constant
+
### v1.0.0
- Initial release
- Help/Man system with grouped commands, searchable topics, version badges
diff --git a/ScriptKit/ScriptKit.js b/ScriptKit/ScriptKit.js
index b6fac11d5..17a377d9b 100644
--- a/ScriptKit/ScriptKit.js
+++ b/ScriptKit/ScriptKit.js
@@ -1,6 +1,6 @@
// =============================================================================
-// ScriptKit v1.0.0
-// Last Updated: 2026-07-20
+// ScriptKit v1.2.0
+// Last Updated: 2026-08-03
// Author: Kenan Millet
//
// Description:
@@ -17,6 +17,7 @@ var ScriptKit = ScriptKit || (() => {
'use strict';
const SCRIPT_NAME = 'ScriptKit';
+ const SCRIPT_VERSION = '1.2.0';
const HANDOUT_STEP = Object.freeze({ auto: true });
// =========================================================================
@@ -113,6 +114,8 @@ var ScriptKit = ScriptKit || (() => {
return obj;
};
+ var _pingColorState = {}; // playerId → { originalColor, pending }
+
const guidePing = (pageId, x, y, opts) => {
opts = opts || {};
var player = opts.player || null;
@@ -122,12 +125,22 @@ var ScriptKit = ScriptKit || (() => {
var color = opts.color || null;
if (color && player) {
- var originalColor = player.get('color');
+ var pid = player.get('id');
+ if (!_pingColorState[pid]) {
+ _pingColorState[pid] = { originalColor: player.get('color'), pending: 0 };
+ }
+ _pingColorState[pid].pending++;
player.set('color', color);
setTimeout(function() {
sendPing(x, y, pageId, playerId, moveAll, visibleTo);
- setTimeout(function() { player.set('color', originalColor); }, 200);
- }, 100);
+ setTimeout(function() {
+ _pingColorState[pid].pending--;
+ if (_pingColorState[pid].pending <= 0) {
+ player.set('color', _pingColorState[pid].originalColor);
+ delete _pingColorState[pid];
+ }
+ }, 500);
+ }, 150);
} else {
sendPing(x, y, pageId, playerId, moveAll, visibleTo);
}
@@ -203,11 +216,47 @@ var ScriptKit = ScriptKit || (() => {
},
table: (headers, rows, style) => {
var tableStyle = style ? html.style(style) : 'border-collapse:collapse';
- var h = '' + headers.map(col => '| ' + col + ' | ').join('') + '
';
+ var h = '' + headers.map(col => '| ' + col + ' | ').join('') + '
';
h += rows.map(row => '' + row.map(cell => '| ' + cell + ' | ').join('') + '
').join('');
- h += '
';
+ h += '
';
return h;
},
+ /**
+ * Clickable text button that pings an object's location.
+ * @param {string|object} target - Object ID string, or { pageid, x, y }
+ * @param {object} [opts] - color, moveAll, visibleTo, label, style
+ */
+ pingObjBtn: (target, opts) => {
+ opts = opts || {};
+ var cmd = pingCommand(target, opts);
+ var label = opts.label || (typeof target === 'string' ? target : 'Ping');
+ var defaultStyle = { background: '#333', color: '#fff', padding: '1px 6px', borderRadius: '3px', textDecoration: 'none' };
+ var merged = opts.style ? Object.assign({}, defaultStyle, opts.style) : defaultStyle;
+ return '' + label + '';
+ },
+ /**
+ * Clickable token image that pings an object's location.
+ * @param {string|object} target - Object ID string, or { pageid, x, y }
+ * @param {object} [opts] - color, moveAll, visibleTo, imgsrc, width, height, label (shown below image or as fallback text)
+ */
+ pingObjImg: (target, opts) => {
+ opts = opts || {};
+ var cmd = pingCommand(target, opts);
+ var width = opts.width || 40;
+ var height = opts.height || 40;
+ var imgsrc = opts.imgsrc || null;
+ if (imgsrc) {
+ // Ensure thumb version for Roll20 chat rendering
+ imgsrc = imgsrc.replace(/\/(?:max|med|original)\.(png|jpg|jpeg|webp)/i, '/thumb.$1');
+ var imgStyle = 'width:' + width + 'px;height:' + height + 'px;border-radius:4px;';
+ var label = opts.label ? '
' + opts.label + '' : '';
+ return ''
+ + '
' + label + '';
+ }
+ // Fallback: text button
+ var fallbackLabel = opts.label || (typeof target === 'string' ? target.slice(0, 8) + '...' : 'Ping');
+ return html.pingObjBtn(target, Object.assign({}, opts, { label: fallbackLabel }));
+ },
};
// =========================================================================
@@ -225,7 +274,7 @@ var ScriptKit = ScriptKit || (() => {
sendChat(scriptName + (tag ? ' [' + tag + ']' : ''), '/w "' + recipient + '" ' + text, null, { noarchive: true });
};
- const replyError = (msg, scriptName, text) => reply(msg, scriptName, 'Error', html.format(text));
+ const replyError = (msg, scriptName, text) => reply(msg, scriptName, 'Error', html.render(text));
const setHandoutNotes = (handout, notes) => {
// Retry pattern for Roll20's async handout issues
@@ -256,6 +305,7 @@ var ScriptKit = ScriptKit || (() => {
log(SCRIPT_NAME + ': register requires scriptName, command, and version.');
return false;
}
+ if (registrations[scriptName]) return true; // already registered
registrations[scriptName] = {
_scriptName: scriptName,
command: opts.command.startsWith('!') ? opts.command : '!' + opts.command,
@@ -657,6 +707,12 @@ var ScriptKit = ScriptKit || (() => {
}
const cmd = (args.shift() || '').toLowerCase();
+ // Internal subcommands (ScriptKit-only, not alias-routed)
+ if (scriptName === SCRIPT_NAME && cmd === 'ping') {
+ doPing(msg, args.join(' '));
+ return true;
+ }
+
// Alias matcher — supports string or array of strings
const matchAlias = (alias) => {
if (!alias) return false;
@@ -1634,7 +1690,7 @@ var ScriptKit = ScriptKit || (() => {
let prompt = html.div(
html.bold(html.escape(g.handoutName || g.example.name)) + ' — Setup (step ' + interactiveIdx + '/' + interactiveTotal + ')' + html.paragraph('')
- + html.format(promptText) + html.paragraph('')
+ + html.render(promptText) + html.paragraph('')
+ (step.select ? (() => {
const plural = !step.max || step.max > 1;
const label = step.select + (plural ? 's' : '');
@@ -1778,7 +1834,7 @@ var ScriptKit = ScriptKit || (() => {
g.selections._roles[step.role] = selected;
}
- // onContinue callback — if it returns a string, treat as validation error
+ // onContinue callback — if it returns a string or html.raw(), treat as validation error
if (typeof step.onContinue === 'function') {
const ctx = { selections: g.selections, params: g.params, selected: selected, msg: msg, player: getObj('player', msg.playerid) };
const err = step.onContinue(ctx);
@@ -1786,6 +1842,10 @@ var ScriptKit = ScriptKit || (() => {
replyError(msg, g.source, err);
return;
}
+ if (err && err.__raw) {
+ replyError(msg, g.source, err);
+ return;
+ }
}
g.currentStep++;
@@ -1881,6 +1941,90 @@ var ScriptKit = ScriptKit || (() => {
delete activeGuides[guideId];
};
+ // =========================================================================
+ // Ping Command
+ // =========================================================================
+
+ /**
+ * Build a !scriptkit ping command string.
+ * @param {string|object} target - An object ID string, or { pageid, x, y }
+ * @param {object} [opts] - Options: color, moveAll, visibleTo (string of comma-delimited IDs or array)
+ * @returns {string} The chat command string
+ */
+ const pingCommand = (target, opts) => {
+ opts = opts || {};
+ var cmd;
+ if (typeof target === 'string') {
+ cmd = '!scriptkit ping ' + target;
+ } else {
+ cmd = '!scriptkit ping ' + target.pageid + ' ' + target.x + ' ' + target.y;
+ }
+ if (opts.color) cmd += ' --color ' + opts.color;
+ if (opts.moveAll) cmd += ' --moveAll';
+ if (opts.visibleTo) {
+ // Normalize: array → comma-joined, strip all spaces
+ var vt = Array.isArray(opts.visibleTo) ? opts.visibleTo.join(',') : String(opts.visibleTo);
+ cmd += ' --visibleTo ' + vt.replace(/\s+/g, '');
+ }
+ return cmd;
+ };
+
+ /**
+ * Handle !scriptkit ping [--color X] [--moveAll] [--visibleTo X,Y,Z]
+ */
+ const doPing = (msg, content) => {
+ var parts = content.split(/\s+/);
+ var positional = [];
+ var color = null;
+ var moveAll = false;
+ var visibleTo = null;
+
+ for (var i = 0; i < parts.length; i++) {
+ if (parts[i] === '--color' && i + 1 < parts.length) {
+ color = parts[++i];
+ } else if (parts[i] === '--moveAll') {
+ moveAll = true;
+ } else if (parts[i] === '--visibleTo' && i + 1 < parts.length) {
+ // Comma-delimited, no spaces (stripped by pingCommand)
+ visibleTo = parts[++i].split(',').filter(Boolean);
+ } else {
+ positional.push(parts[i]);
+ }
+ }
+
+ var pageId, x, y;
+
+ if (positional.length === 1) {
+ // Object ID mode — try graphic, then pin, then pathv2
+ var objId = positional[0];
+ var obj = getObj('graphic', objId) || getObj('pin', objId) || getObj('pathv2', objId);
+ if (!obj) {
+ sendChat('ScriptKit', '/w "' + msg.who.replace(/\s+\(GM\)$/, '') + '" Ping: object not found: ' + objId);
+ return;
+ }
+ pageId = obj.get('_pageid') || obj.get('pageid');
+ x = obj.get('left') !== undefined ? obj.get('left') : obj.get('x');
+ y = obj.get('top') !== undefined ? obj.get('top') : obj.get('y');
+ } else if (positional.length === 3) {
+ // Coordinate mode: pageId x y
+ pageId = positional[0];
+ x = parseFloat(positional[1]);
+ y = parseFloat(positional[2]);
+ } else {
+ sendChat('ScriptKit', '/w "' + msg.who.replace(/\s+\(GM\)$/, '') + '" Usage: !scriptkit ping <objId> | !scriptkit ping <pageId> <x> <y>');
+ return;
+ }
+
+ var player = getObj('player', msg.playerid);
+ guidePing(pageId, x, y, {
+ player: player,
+ playerId: msg.playerid,
+ color: color,
+ moveAll: moveAll,
+ visibleTo: visibleTo,
+ });
+ };
+
// =========================================================================
// Public API
// =========================================================================
@@ -1890,12 +2034,14 @@ var ScriptKit = ScriptKit || (() => {
// =========================================================================
const api = {
+ VERSION: SCRIPT_VERSION,
register,
registerExample,
handleInput,
html,
handout: () => HANDOUT_STEP,
ping: guidePing,
+ pingCommand,
annotate: guideAnnotate,
clearAnnotations: clearAnnotations,
waitForCommand: (cmd) => ({
@@ -1921,6 +2067,34 @@ var ScriptKit = ScriptKit || (() => {
},
getExamples: (scriptName) => Object.values(examples).filter(ex => ex.target === scriptName),
getActiveGuides: () => activeGuides,
+ generateHandoutImmediately: (scriptName, mode) => {
+ if (!mode) { log(SCRIPT_NAME + ': generateHandoutImmediately requires mode ("usr" or "dev").'); return; }
+ const reg = registrations[scriptName];
+ if (!reg) { log(SCRIPT_NAME + ': generateHandoutImmediately — "' + scriptName + '" is not registered.'); return; }
+ generateHelpHandout(null, scriptName, reg, mode);
+ },
+ updateHandoutImmediately: (scriptName, mode) => {
+ if (!mode) { log(SCRIPT_NAME + ': updateHandoutImmediately requires mode ("usr" or "dev").'); return; }
+ const reg = registrations[scriptName];
+ if (!reg) { log(SCRIPT_NAME + ': updateHandoutImmediately — "' + scriptName + '" is not registered.'); return; }
+ var handoutName = 'Help: ' + scriptName + (mode === 'dev' ? '/Dev' : '');
+ if (!findObjs({ type: 'handout', name: handoutName })[0]) return;
+ generateHelpHandout(null, scriptName, reg, mode);
+ },
+ generateHandout: (scriptName, mode, delay = 2000) => {
+ if (!mode) { log(SCRIPT_NAME + ': generateHandout requires mode ("usr" or "dev").'); return; }
+ var key = scriptName + ':' + mode + ':gen';
+ if (!api._handoutTimers) api._handoutTimers = {};
+ if (api._handoutTimers[key]) clearTimeout(api._handoutTimers[key]);
+ api._handoutTimers[key] = setTimeout(() => { delete api._handoutTimers[key]; api.generateHandoutImmediately(scriptName, mode); }, delay);
+ },
+ updateHandout: (scriptName, mode, delay = 2000) => {
+ if (!mode) { log(SCRIPT_NAME + ': updateHandout requires mode ("usr" or "dev").'); return; }
+ var key = scriptName + ':' + mode + ':upd';
+ if (!api._handoutTimers) api._handoutTimers = {};
+ if (api._handoutTimers[key]) clearTimeout(api._handoutTimers[key]);
+ api._handoutTimers[key] = setTimeout(() => { delete api._handoutTimers[key]; api.updateHandoutImmediately(scriptName, mode); }, delay);
+ },
};
// Tutorial.Choreograph.registerExample('Sequence', { ... })
@@ -1953,12 +2127,25 @@ on('ready', () => {
}
});
ScriptKit.register('ScriptKit', {
- version: '1.0.0',
+ version: ScriptKit.VERSION,
command: 'scriptkit',
handout: 'manual',
aliases: new Proxy({}, { get: (_, key) => key === 'genDev' ? undefined : null }),
help: {
description: 'Generic framework library for Roll20 API scripts.',
+ changelog: [
+ { version: '1.2.0', changes: [
+ 'Added `!scriptkit ping` command — ping an object by ID or by coordinates',
+ 'Added `ScriptKit.pingCommand(target, opts)` — build ping command strings for chat links',
+ 'Added `html.pingObjBtn(target, opts)` / `html.pingObjImg(target, opts)` — clickable ping buttons/images',
+ '`visibleTo` now accepts array of player IDs or comma-delimited string',
+ ]},
+ { version: '1.1.0', changes: [
+ 'Prevent double-registration (same script calling register() twice is now a no-op)',
+ 'Added ScriptKit.generateHandout / updateHandout (debounced, default 2s) for deferred handout regeneration',
+ 'Added ScriptKit.generateHandoutImmediately / updateHandoutImmediately for synchronous generation',
+ ]},
+ ],
topics: {
textRendering: {
title: '⚠️ Text Rendering',
@@ -2063,6 +2250,7 @@ on('ready', () => {
body: 'Draw temporary shapes on the map during guide steps to highlight elements. Annotations auto-clear on step transition and are persisted in state for crash recovery.',
items: [
{ name: 'ScriptKit.ping(pageId, x, y, opts)', description: 'Ping the map and move camera. opts: { player, color, moveAll, visibleTo, playerId }', version: '1.0.0' },
+ { name: 'ScriptKit.pingCommand(target, opts)', description: 'Build a !scriptkit ping command string. target: objId string or { pageid, x, y }. opts: color, moveAll, visibleTo', version: '1.2.0' },
{ name: 'ScriptKit.annotate(pageId, shape, x, y, opts)', description: 'Draw a temporary pathv2. Returns the object. Shapes: circle, arrow, line, rect', version: '1.0.0' },
{ name: 'ScriptKit.clearAnnotations()', description: 'Remove all active annotations manually', version: '1.0.0' },
{ name: 'circle opts', description: 'radius (default 40), color, strokeWidth, fill', version: '1.0.0' },
@@ -2096,6 +2284,8 @@ on('ready', () => {
{ name: 'handoutLink(text, id)', description: 'Journal link', version: '1.0.0' },
{ name: 'newBadge() / deprecatedBadge()', description: 'Version badge markers', version: '1.0.0' },
{ name: 'style(obj)', description: 'Convert camelCase object to CSS string', version: '1.0.0' },
+ { name: 'pingObjBtn(target, opts?)', description: 'Clickable text button that pings an object location. opts: color, moveAll, visibleTo, label, style', version: '1.2.0' },
+ { name: 'pingObjImg(target, opts?)', description: 'Clickable token image that pings on click. opts: color, moveAll, visibleTo, imgsrc, width, height, label. Falls back to pingObjBtn', version: '1.2.0' },
],
},
migrations: {
@@ -2129,6 +2319,23 @@ on('ready', () => {
version: '1.0.0',
body: '`ScriptKit.register()` automatically sends `!-ready` to chat. Other scripts listen for this to know when your script is available for direct API calls.\n\nExample registration does NOT require the ready signal — the Proxy queues automatically regardless of load order.',
},
+ dynamicHandouts: {
+ title: 'Dynamic Handout Content',
+ description: 'Keeping handouts up-to-date with post-init registrations',
+ handouts: 'dev',
+ version: '1.1.0',
+ body: 'If your script has topics with dynamic content (e.g. listing registered extensions), the handout generated at startup may be incomplete — other scripts register after yours.\n\n'
+ + '**Step 1: Function bodies** — Use `body: () => ...` in topics. Chat commands (`man`) always evaluate live, giving users current info. Without this, content is static and regeneration has no effect.\n\n'
+ + '**Step 2: Programmatic regeneration** — Call `ScriptKit.generateHandout()` or `ScriptKit.updateHandout()` after extensions finish registering. This re-renders the handout, invoking your function bodies with up-to-date data.\n\n'
+ + '**Pattern:** Debounce a timer in your extension registration functions. After the last registration, the timer fires and regenerates the handout once.',
+ items: [
+ { name: 'ScriptKit.generateHandout(scriptName, mode, delay?)', description: 'Schedule handout generation (debounced, default 2000ms). Creates handout if missing. Repeated calls reset the timer.', version: '1.1.0' },
+ { name: 'ScriptKit.updateHandout(scriptName, mode, delay?)', description: 'Schedule handout regeneration only if it already exists (debounced, default 2000ms). No-op if handout is missing.', version: '1.1.0' },
+ { name: 'ScriptKit.generateHandoutImmediately(scriptName, mode)', description: 'Generate handout synchronously without debounce. Creates if missing.', version: '1.1.0' },
+ { name: 'ScriptKit.updateHandoutImmediately(scriptName, mode)', description: 'Regenerate handout synchronously only if it exists.', version: '1.1.0' },
+ { name: 'body: () => string', description: 'Topic body as a function — evaluated at render time (chat man) and at handout generation. Always reflects current state.', version: '1.0.0' },
+ ],
+ },
scriptKit: null,
}
}
diff --git a/ScriptKit/script.json b/ScriptKit/script.json
index d2523ae97..f8cffea1c 100644
--- a/ScriptKit/script.json
+++ b/ScriptKit/script.json
@@ -1,9 +1,12 @@
{
"name": "ScriptKit",
"script": "ScriptKit.js",
- "version": "1.0.0",
- "previousversions": [],
- "description": "Generic framework library for Roll20 API scripts. Not a standalone script — provides infrastructure for other scripts to build on.\n\nFeatures:\n- **Help & Man system** — Structured command reference with grouped commands, searchable topics, version badges, and What's New display\n- **Handout generation** — Auto-generated help handouts on version bump with Quick Start, commands, topics, and examples footer\n- **Examples & Guides** — Interactive multi-step setup wizards with token/pin selection, query prompts with type coercion, and validation\n- **State migrations** — Semver-based sequential up/down migrations with auto-upgrade and manual rollback\n- **Ready signal coordination** — `!scriptkit-ready` broadcast for load-order-independent registration\n- **HTML helpers** — Full suite of formatting functions (escape, bold, italic, code, table, button, format with markdown support)\n\nScripts register via `ScriptKit.register(name, opts)` and gain help, man, examples, whatsnew, and handout generation commands automatically.\n\nFor script developers — see the generated Help handout or run `! help` after registering.",
+ "version": "1.2.0",
+ "previousversions": [
+ "1.0.0",
+ "1.1.0"
+ ],
+ "description": "Generic framework library for Roll20 API scripts. Not a standalone script -- provides infrastructure for other scripts to build on.\n\nFeatures:\n- **Help & Man system** -- Structured command reference with grouped commands, searchable topics, version badges, and What's New display\n- **Handout generation** -- Auto-generated help handouts on version bump with Quick Start, commands, topics, and examples footer\n- **Examples & Guides** -- Interactive multi-step setup wizards with token/pin selection, query prompts with type coercion, and validation\n- **State migrations** -- Semver-based sequential up/down migrations with auto-upgrade and manual rollback\n- **Ready signal coordination** -- `!scriptkit-ready` broadcast for load-order-independent registration\n- **HTML helpers** -- Full suite of formatting functions (escape, bold, italic, code, table, button, format with markdown support)\n\nScripts register via `ScriptKit.register(name, opts)` and gain help, man, examples, whatsnew, and handout generation commands automatically.\n\nFor script developers -- see the generated Help handout or run `! help` after registering.\n\n**v1.2.0 - New features:**\n- Added `!scriptkit ping` command — ping an object by ID or by coordinates\n- Added `ScriptKit.pingCommand(target, opts)` — build ping command strings for chat links\n- Added `html.pingObjBtn(target, opts)` / `html.pingObjImg(target, opts)` — clickable ping buttons/images\n- `visibleTo` now accepts array of player IDs or comma-delimited string",
"authors": "Kenan Millet",
"roll20userid": "2614613",
"dependencies": [],