Hypercade Docs

Unreal SDK Integration

4 min read

The HypercadeAnalytics plugin adds Hypercade analytics to your Unreal game. It’s a simple C++ plugin with optional Blueprint support.

Installation

  1. In your game project, create the directory Plugins/HypercadeAnalytics/.
  2. Copy the plugin files (provided by Hypercade) into that directory.
  3. Rebuild the project. The plugin will compile automatically.
  4. In the Unreal Editor, go to Edit > Plugins, search for “Hypercade,” and enable it.
  5. Restart the editor.

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 marker type (e.g., “progression,” “achievement,” “tutorial”). The second is a descriptive string. Both are logged as events and useful for analysis and debugging.

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 Event Name: "session_end"
  In Event Data: (a map of key-value pairs)

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

Events are batched and sent periodically (roughly every 30-60 seconds). If the service is unavailable (returns 503), the SDK:

  1. Queues the event locally
  2. Retries when the service comes back online
  3. Sends all queued events when connectivity is restored

You don’t need to handle retries yourself. The SDK does it automatically.

Data format

Events are sent as flat JSON to the endpoint https://data.programmoria.com/v1/log/. Example:

{
  "h_id": "550e8400-e29b-41d4-a716-446655440000",
  "app": "my_game",
  "env_os": "Windows",
  "env_gpu": "NVIDIA GeForce RTX 4090",
  "env_ram": 32,
  "env_vram": 24,
  "env_deck": false,
  "event_name": "session_end",
  "level": 3,
  "score": 12500,
  "difficulty": "hard"
}

No nested objects. Keep the structure flat.

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/.
  • Rebuild the entire project, not just the plugin.
  • Check that you’re using a compatible Unreal Engine version (4.27 and later 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 hello@hypercade.io.

Backlinks