Example: Diagnostics#

A walkthrough of examples/diagnostics.cpp — a system health-check plugin that continuously tests all SDK subsystems and displays results via both a HUD overlay and an interactive menu panel.

This is the most comprehensive example in the SDK, demonstrating TextBuilder, multi-category test organization, HUD rendering, and advanced menu patterns.

Overview#

The plugin runs 17 tests across 7 categories:

Category	Tests	What it checks
Core	Time, Screen, Hero	`GetTime`, `ScreenSize`, `GetCurrentHero`
Entity	LocalPlayer, PlayerCount, Positions, Bones, Teams	Entity system integrity
Raycast	RayReady, RayDown, RayUp	Raycast initialization and accuracy
Network	ClientPing, ServerPing	Network latency queries
W2S	Center, Behind	`WorldToScreen` correctness and crash safety
Targeting	FindTarget	`FindBestTarget` call safety
Perf	FrameTime	Frame delta time monitoring

Tests run on a configurable interval (default 2s), except the frame time test which runs every frame.

Key Patterns#

Test Status System#

enum TestStatus : int32_t { PENDING = 0, PASS = 1, WARN = 2, FAIL = 3 };

struct TestResult
{
    TestStatus status;
    float numericValue;
    float lastRunTime;
};

Each test returns a status, a numeric value for display, and the time it last ran. The HUD shows per-category worst-case status.

TextBuilder for Dynamic Text#

The plugin makes heavy use of TextBuilder for all dynamic text — HUD labels, log messages, and menu entries:

// HUD title
TextBuilder<64> title;
title.put("DIAG  ").putInt(pass).put("/").putInt(TEST_COUNT).put(" OK");
if (warn > 0) title.put("  ").putInt(warn).put(" WARN");
if (fail > 0) title.put("  ").putInt(fail).put(" FAIL");
Draw::Text(tx, ty, StatusColor(overall), title.c_str());

// Performance line
TextBuilder<48> perfLine;
perfLine.putFloat(ms, 1).put("ms / ").putInt(static_cast<int>(fps)).put("fps");

Raycast Validation#

Tests the raycast system by casting downward (expecting to hit the floor) and upward:

// Down ray — expect hit
Vector3 down = head;
down.y -= 3.f;
RaycastResult rDown = Raycast(head, down);
TestStatus downStatus = FAIL;
if (rDown.fraction < 0.5f) downStatus = PASS;
else if (rDown.fraction < 0.8f) downStatus = WARN;

HUD Corner Selection#

The overlay panel can be positioned in any screen corner via a combo menu:

ImGui::Combo("HUD Corner", &g_hudCorner,
    "Top-Left\0" "Top-Right\0" "Bottom-Left\0" "Bottom-Right\0");

Manual Test Trigger#

Uses a checkbox that auto-resets as a button:

bool triggerBtn = false;
ImGui::Checkbox("Run Tests Now", &triggerBtn);
if (triggerBtn) g_manualTrigger = true;

The menu uses per-category collapsing sections with dynamic status labels:

TextBuilder<64> catLabel;
catLabel.put(g_categories[c].name).put(" [").put(StatusLabel(catStatus)).put("]");

if (ImGui::CollapsingHeader(catLabel.c_str()))
{
    // Per-test detail lines
}

Build#

build.bat examples\diagnostics.cpp

Output: output/diagnostics.wasm