Testing and debugging

Everything on this page is in the Plugins screen of the desktop app, with Developer mode on (Settings → Developer). The tabs are Plugins, Console, Test environment and SDK & reference.

The cycleCopy Anchor Link

1. Edit main.lua and save. The plugin reloads by itself (in Developer mode). If you edit from somewhere that doesn't notify ForgeCast, use Reload on the plugin's card, or Reload all at the top.
2. Look at its Console: it says loaded in 4 ms, or shows the error with the file and line.
3. Send make-believe chat from the Test environment, or follow a real stream.
4. Look at the Inspector when something doesn't add up.

The plugin's cardCopy Anchor Link

Each plugin is a card on the Plugins tab, with a switch to turn it on or off, a Permissions button (what it may do), Reload, a Console shortcut, and its settings panel if it has one. A plugin that failed shows its error right on the card. Plugins whose folder couldn't be read (a bad plugin.json, a folder name that doesn't match the id) are listed separately with the reason.

The consoleCopy Anchor Link

The console shows everything a plugin does:

• what it prints (print, log.info, log.warn, log.error, log.debug),
• every error with a traceback: click a line to open the traceback and the details,
• what the chat middleware blocked or changed, and why (the reason you returned),
• notes from ForgeCast itself: loading time, a callback that ran too long, console lines that were dropped.

Filter by level and by source (print, log, middleware, event, http, storage, ui, timer, system, repl), and search the text. Trace switches on a line for every API call the plugin makes, which is the quickest way to see what it actually does.

At the bottom is a prompt that runs Lua inside the running plugin: type chats.count(), storage.keys(), or a global your plugin defined, and see the answer. It is the plugin's own environment, with its own permissions, and it has 2 seconds.

-- in your plugin, a global function you can call from the prompt:
function reset() count = 0 draw() end
-- then type  reset()  in the console

(Global functions are fine for this. Prefer local for everything else.)

The inspectorCopy Anchor Link

Beside the console, the Inspector shows what the plugin has set up and what it costs:

• its permissions, the events it listens to, how many middleware functions and timers it has, which windows and Dashboard sections it has open, whether it has a settings panel, and how many web requests are waiting;
• how long it has been running, callbacks run, events delivered, errors, the time per callback and the slowest one, memory, and the API calls it makes, counted by function. It also lists the plugin's files, with Open folder.

A plugin that is slow, or spends its time in the wrong place, shows up here. Refresh editor files rewrites the plugin's .forgecast/ folder (the API definitions for your editor) from the version in the app, which you need after updating ForgeCast.

The test environmentCopy Anchor Link

You don't need to be live to try a plugin. The Test environment makes believe:

• Send chat. Pick the kind (a message, Super Chat, Super Sticker, new member, milestone, gift), who it is from (blank is someone random), a message (blank is a random line), the amount and currency for paid ones, the number of gifted memberships, and whether the sender is a member, moderator or the streamer. How many sends up to 200 at once, for testing a busy chat. The quick buttons send common cases in one click.
• Stream numbers. Set the viewers and likes (and title) of a make-believe stream, to try stream.on and milestones.

It all happens on a stream called Simulator (id = "simulator"). The chat goes through your plugins' middleware exactly like a real stream, so a blocking plugin really blocks it, then appears on the Dashboard and in your plugins' event handlers. Chat from the Test environment has chat.simulated == true, and the stream has simulated == true, so a plugin can tell and avoid doing real things (posting to a webhook, say) for a test.

Super Chats, memberships and gifts from the Simulator play on your alert box in OBS, like a widget test, and chat actions run on them without posting anything to YouTube. (alerts.show from a plugin shows an alert on your alert box too, because that is what you asked for.)

Test on a real streamCopy Anchor Link

Turn on Developer mode and add a live stream by link on the Dashboard: any public live stream works, so you can try a plugin against a busy chat without going live yourself. Several streams can be followed at once, and a plugin sees them merged.

Your editorCopy Anchor Link

Plugins → New plugin sets up the folder for VS Code: .forgecast/forgecast.d.lua (the API), .luarc.json (tells the Lua language server about it and about the sandbox's globals), .vscode/settings.json and a recommendation for the Lua extension by sumneko. You get completion for every function, the docs of each as you type, signature help, and warnings, for example for a mistyped name or a missing required field. The plugin.json has its own schema, so permissions complete too.

To work in another editor, take forgecast.d.lua and point your Lua language server at it.

When something doesn't workCopy Anchor Link

If you're stuck, open the API reference for the function in question, or copy the closest example and change it a step at a time.