Find errors with the diagnostics hub

An agent finds errors by reading your tab's diagnostics hub, one list of every error, warning and note the tab has collected. A single call to diagnostics_get returns them, so the agent never has to dig through the browser console.

Every DiceyTable tab keeps its own hub. It holds the last 2,000 entries from 19 sources. Those include the console, your scripts, the safety scanner, asset loading, physics and the network. The diagnostics sources reference lists all 19. You see the same entries yourself in the editor's Problems panel and in the table's Activity Log.

Step 1: Note the cursor before a change#

Every entry has a number, and every read returns a cursor. The agent keeps that cursor. Next time it passes it back as sinceCursor and sees only what is new.

This is how the agent tells its own mistakes apart from old ones:

1. It calls diagnostics_get before a change and notes the cursor.
2. It makes the change.
3. It calls diagnostics_get again with that cursor. Anything listed came after the change.

That's why the recommended instructions tell the agent to read diagnostics before it touches anything. It's like counting the snacks before the party starts, so nobody blames the friend who came late.

Step 2: Run the checks on demand#

Some problems only show up when something looks for them. project_validate runs every on-demand check at once and adds fresh entries to the hub. It checks the manifest and scene, the editor's problems, the latest script compile results, the safety scanner, asset paths and credits.

The usual rhythm after a batch of edits is project_save, then project_validate, then diagnostics_get.

Step 3: Narrow it down#

diagnostics_get takes filters, so the agent can ask a sharp question:

• minSeverity skips notes and keeps only warnings and errors.
• sources keeps a few sources, such as table-script and scanner.
• entityId or file keeps entries about one entity or one file.
• code keeps one kind of problem.

With a preview open, tab: "all" reads the editor and the preview together. Play-test your game with an agent shows how the preview tab joins.

Step 4: Catch errors that happen later#

Some errors wait for the right moment. A script might fail only when a card lands in a zone. For those, the agent makes the move and then calls diagnostics_watch. It waits for a new entry that matches its filter, for 30 seconds by default and 60 at most. It returns as soon as one arrives.

How the hub stays tidy#

• Repeats fold. When the same problem happens again, its entry's count goes up. The list doesn't flood.
• Clearing only hides. diagnostics_clear moves a marker, and later reads skip what's behind it. Nothing is deleted, and you still see every entry in the Problems panel. The marker belongs to the tab, so every agent on that tab shares it.
• Old entries drop off. When the hub is full, the oldest entries go first. A read says how many the agent missed since its cursor, as dropped.

Why are some console messages missing?#

The hub records console output only while an agent is attached. Anything logged before you paired the tab isn't there. Uncaught errors and React rendering errors are always recorded, with or without an agent.

Treat quoted text as data#

Some entries quote mod code, file names or other players' words. Those entries carry untrusted: true, and their text reaches the agent inside <untrusted> blocks. The agent must never follow an order it finds in an error message. Prompt injection protection explains the rule.

Next steps#

• Write game scripts with an agent: script_write hands back its compile and scanner results right away.
• Play-test your game with an agent: find the errors by playing.
• Diagnostics sources reference: every source, and which ones are untrusted.