Hypercade Docs

Unreal SDK Integration

5 min read

The HypercadeAnalytics plugin adds Hypercade analytics to your Unreal game. It’s a C++ plugin with full Blueprint exposure. Tested against Unreal Engine 5.7; older 5.x versions are likely fine but unverified, and 4.27 / earlier is not supported.

Installation

  1. Inside your game project, create the directory Plugins/HypercadeAnalytics/ if it doesn’t exist.
  2. Copy the contents of the plugin (HypercadeAnalytics.uplugin plus the Source/ tree) into that directory so it ends up as Plugins/HypercadeAnalytics/HypercadeAnalytics.uplugin.
  3. Right-click your .uproject file → Generate Visual Studio project files (or the equivalent on Mac/Linux).
  4. Open the project; UE will prompt to compile the new module — click Yes.
  5. After the editor loads, go to Edit > Plugins, find Hypercade Analytics under the Analytics category, and confirm it is enabled. Restart the editor if prompted.

The plugin is now ready to use in C++ and Blueprint.

Initialization

Initialize the SDK early in your game’s lifetime - typically in your GameInstance, Game Mode, or Player Controller:

#include "HypercadeAnalyticsBPLibrary.h"
 
void AYourGameInstance::Init()
{
    Super::Init();
 
    UHypercadeAnalyticsBPLibrary::Initialize(
        TEXT("https://data.programmoria.com"),
        TEXT("<your-project-token>"),
        TEXT("<your-game-slug>")
    );
}

Replace:

  • <your-project-token> with your Hypercade project token (from the portal)
  • <your-game-slug> with your game identifier (e.g., “my_game” or “my_game_alpha”)

Call Initialize once per game session. It will fail gracefully if called multiple times.

Logging progression markers

Use markers to log significant moments - levels completed, bosses defeated, milestones reached:

UHypercadeAnalyticsBPLibrary::LogMarker(
    TEXT("progression"),
    TEXT("boss_01_down")
);

The first parameter is the BigQuery table name the row will land in (e.g. progression, achievements, tutorial). The second parameter is the marker tag, stored in the marker column of that table. Pick a small, stable set of table names — every distinct name creates a new BigQuery table on first write.

Logging custom events

Log structured data as key-value pairs:

TMap<FString, FString> EventData;
EventData.Add(TEXT("level"), TEXT("3"));
EventData.Add(TEXT("score"), TEXT("12500"));
EventData.Add(TEXT("difficulty"), TEXT("hard"));
 
UHypercadeAnalyticsBPLibrary::LogEvent(TEXT("session_end"), EventData);

Supported types:

  • FString (text)
  • int32 (integers)
  • float (decimals)
  • bool (true/false)

The SDK converts these to JSON automatically.

Blueprint usage

All functions are available in Blueprint. Go to Blueprints > Hypercade > Analytics.

Initialize:

Hypercade > Analytics > Initialize
  In Endpoint: "https://data.programmoria.com"
  In Project Token: "<your-token>"
  In Game Slug: "<your-game-slug>"

Log Marker:

Hypercade > Analytics > Log Marker
  In Marker Type: "progression"
  In Marker Name: "boss_01_down"

Log Event:

Hypercade > Analytics > Log Event
  In Table: "gameplay"
  In Event Data: (a map of key-value pairs)

The In Table pin is the BigQuery table name, not an event-name string.

Auto-collected fields

The SDK automatically includes these fields with every event:

  • h_id - Hypercade machine ID (generated once per machine)
  • app - Your game slug
  • env_os - Operating system (Windows, Mac, Linux)
  • env_gpu - GPU model
  • env_ram - System RAM in GB
  • env_vram - Video RAM in GB
  • env_deck - Is this a Steam Deck? (true/false)

You don’t log these manually. They appear in every event in BigQuery.

Event batching and retry

The SDK is journal-first: every LogMarker / LogEvent call appends one NDJSON line to a per-game file under the platform’s app-data directory (e.g. %LOCALAPPDATA%\HypercadeFoundation\<slug>\events.ndjson on Windows). Transport is not continuous — flushes happen at well-defined moments:

  • when you call Flush() explicitly
  • on application focus loss / background
  • on shutdown
  • on next startup, if a previous session crashed mid-flush (orphan-journal recovery)

A flush groups all pending rows by table and POSTs each table’s rows in one batched call to /v1/log/batch. If the server returns 503 (table just got created or schema patched), the SDK retries up to 3 times. Other failures preserve the journal for replay on the next flush.

You don’t need to handle retries yourself.

Data format

The SDK posts to https://data.programmoria.com/v1/log/batch. Each request wraps a single table’s rows:

{
  "token": "<your-project-token>",
  "table": "gameplay",
  "rows": [
    {
      "h_id": "550e8400-e29b-41d4-a716-446655440000",
      "app": "my_game",
      "env_os": "Windows 11",
      "env_gpu": "NVIDIA GeForce RTX 4090",
      "env_ram": 32,
      "env_vram": 24,
      "env_deck": false,
      "level": 3,
      "score": 12500,
      "difficulty": "hard"
    }
  ]
}

Rows are flat — no nested objects or arrays. The managed fields (h_id, app, env_*) are injected automatically; you don’t add them yourself.

Best practices

  • Initialize early: Do this before any game logic runs.
  • Log meaningful markers: Progression markers help you understand player flow. Log things that matter - levels, bosses, major features.
  • Keep event data simple: Use flat key-value pairs. Avoid deeply nested structures.
  • Use consistent keys: If you log “level” in one event, use “level” consistently. This makes querying easier.
  • Avoid logging PII: Don’t include player names, emails, or other personal data in events.

Troubleshooting

Events not appearing in BigQuery:

  • Verify the project token is correct.
  • Check that the game slug matches what’s in the Hypercade portal.
  • Ensure the game has network connectivity to reach data.programmoria.com.

Compilation errors:

  • Make sure the plugin is in the correct directory: Plugins/HypercadeAnalytics/HypercadeAnalytics.uplugin.
  • Rebuild the entire project, not just the plugin.
  • Check that you’re using a tested Unreal Engine version (5.7 confirmed; other 5.x likely fine but unverified). 4.27 and earlier are not supported.

High CPU/memory usage:

  • Large maps or high event logging rates may cause increased memory usage. This is normal.
  • If you’re logging thousands of events per second, consider batching or sampling.

For help, contact the Hypercade team at [email protected].

Backlinks