Diagnostics for addon authors
✅ Source verified 🛠 Supportability pattern
A public API becomes much easier to support when an addon author can produce one compact diagnostic report instead of manually describing internal state.
Political World’s inspected API contains a lightweight diagnostics subsystem with no separate Update loop.
Public report methods
Section titled “Public report methods”The source exposes:
PoliticalWorldAPI.GetAddonDiagnostics(addonId)PoliticalWorldAPI.GetDiagnosticsReport(addonId)PoliticalWorldAPI.GetAllDiagnosticsReports()PoliticalWorldAPI.LogDiagnosticsReport(addonId)What the report tracks
Section titled “What the report tracks”Per addon:
registered ideologiesregistered governmentsregistered actionsregistered rare political eventsevent subscriptionscallback errorswarningserrorsrecent diagnostic entriesThe recent-entry buffer is capped at:
32 entriesOlder entries are dropped from that small history.
Why counters and recent entries are both useful
Section titled “Why counters and recent entries are both useful”A counter answers:
“Has this addon had callback failures?”
Recent entries answer:
“What failed most recently?”
You need both.
A huge unbounded log stored in memory is unnecessary. A tiny recent ring-like history plus counters gives useful support information at low cost.
Example runtime report
Section titled “Example runtime report”A real development runtime report for Scenario Tools included:
[Political World API]API: 1.14.0Addon: Scenario Tools [Lous12.ScenarioTools]Registered ideologies: 0Registered governments: 0Registered actions: 0Registered rare political events: 0Event subscriptions: 0Callback errors: 0Warnings: 0Errors: 0Recent diagnostics:- INFO PWDIAG001: Addon registered: Scenario ToolsThat runtime belongs to a newer local build than the GitHub API 1.9 source snapshot documented elsewhere.
Structured diagnostic codes
Section titled “Structured diagnostic codes”Examples verified in the source include:
PWDIAG001 addon registeredPWDIAG010 ideology registeredPWDIAG015 government registeredPWDIAG016 rare political event registeredPWDIAG020 action registeredPWDIAG030 event subscription addedPWDIAG040 callback failedValidation and registration code also records specific warning/error codes.
Stable codes are useful because users, documentation and AI can search for:
PWDIAG040instead of matching translated or changing prose.
Callback errors are attributed to the addon
Section titled “Callback errors are attributed to the addon”When an Event Bus callback throws, the diagnostics system increments:
CallbackErrorsErrorsfor the subscriber addon and records the event involved.
This is much more actionable than one generic core-mod exception.
Diagnostics should be copy-pasteable
Section titled “Diagnostics should be copy-pasteable”GetDiagnosticsReport() formats a plain-text support report.
This has several advantages:
- easy to paste into GitHub Issues or Discord;
- easy for AI to parse;
- survives without a custom UI;
- useful in
Player.log; - independent of localization.
Minimal support button/action
Section titled “Minimal support button/action”An addon developer can expose a debug action that simply calls:
PoliticalWorldAPI.LogDiagnosticsReport(AddonId);Then a bug report can request:
1. reproduce the problem;2. run the diagnostic action;3. attach Player.log.General lesson
Section titled “General lesson”When building a public mod API, include observability as a feature.
Do not wait until users report:
“It doesn’t work.”
A good framework can already answer:
Was the addon registered?How much content registered?How many subscriptions exist?Did callbacks throw?What were the latest warnings/errors?Which API version generated the report?