⌘K

Unreal Engine Integration

Track game engine builds with per-asset cooking metrics and shader compilation.

Overview
Configuration
1. Connection Settings
How It Works
1. Integration Methods
Build Phases
Webhook Endpoints
1. Phase Notifications
Asset Types
Jenkins Integration
1. Jenkinsfile Example
PowerShell Build Script
Metrics Tracked
1. Per-Build Metrics
2. Per-Asset Metrics
Troubleshooting
Best Practices

Overview

ButterStack observes your Unreal Engine builds to provide Stage 4 visibility:

Build phase tracking (cooking, shaders, packaging)
Per-asset cooking metrics
Shader permutation counts
DDC hit rates
Cook times by asset type
PAK file size tracking
Compression ratio analysis

This is Stage 4 of the Asset Lineage Pipeline - understanding what happens inside the game engine.

Configuration

Connection Settings

Field	Description	Required	Example
`engine_version`	Unreal Engine version	No	`5.4`
`target_platform`	Primary build platform	No	`Win64`

How It Works

ButterStack doesn’t run inside Unreal Engine. Instead, it receives events from your build pipeline via webhooks. This “observe, don’t interfere” approach means:

No plugin installation required
Works with any UE version
Compatible with existing build scripts
No engine modifications

Integration Methods

Webhook Callbacks - Send events from your build scripts
Jenkins Integration - Receive events via Jenkins build steps
Log Parsing - Parse Unreal build logs (requires additional setup)

Build Phases

ButterStack tracks these phases:

initializing → cooking → compiling_shaders → packaging → archiving → completed
                                                                    ↘ failed

Phase	Description
`initializing`	Build starting, environment setup
`cooking`	Asset cooking (converting to runtime format)
`compiling_shaders`	Shader compilation and permutation generation
`packaging`	Creating PAK files and final package
`archiving`	Copying to output directory
`completed`	Build finished successfully
`failed`	Build failed at any phase

Webhook Endpoints

Phase Notifications

Cooking Started:

POST /webhooks/game_engine/cooking_started
{
  "project_id": "abc123",
  "build_number": 456,
  "engine_version": "5.4",
  "platform": "Win64",
  "configuration": "Shipping"
}

Asset Cooked:

POST /webhooks/game_engine/asset_cooked
{
  "project_id": "abc123",
  "build_number": 456,
  "asset_path": "/Game/Characters/Hero/Hero_Mesh.uasset",
  "asset_type": "mesh",
  "cook_time_ms": 1234,
  "original_size": 15000000,
  "cooked_size": 8500000,
  "success": true
}

Shaders Started:

POST /webhooks/game_engine/shaders_started
{
  "project_id": "abc123",
  "build_number": 456,
  "shader_count": 50000
}

Shaders Completed:

POST /webhooks/game_engine/shaders_completed
{
  "project_id": "abc123",
  "build_number": 456,
  "shader_count": 50000,
  "duration_ms": 180000
}

Packaging Started:

POST /webhooks/game_engine/packaging_started
{
  "project_id": "abc123",
  "build_number": 456
}

Build Completed:

POST /webhooks/game_engine/build_completed
{
  "project_id": "abc123",
  "build_number": 456,
  "pak_size": 5000000000,
  "total_assets": 15000,
  "total_cook_time_ms": 3600000
}

Build Failed:

POST /webhooks/game_engine/build_failed
{
  "project_id": "abc123",
  "build_number": 456,
  "phase": "cooking",
  "error": "Failed to cook /Game/Maps/MainLevel.umap"
}

Asset Types

ButterStack categorizes cooked assets:

Type	Description	File Extensions
`texture`	Textures and images	`.uasset` (Texture2D)
`mesh`	Static and skeletal meshes	`.uasset` (StaticMesh, SkeletalMesh)
`material`	Materials and material instances	`.uasset` (Material, MaterialInstance)
`blueprint`	Blueprints and actors	`.uasset` (Blueprint)
`audio`	Sound files	`.uasset` (SoundWave)
`animation`	Animation sequences	`.uasset` (AnimSequence)
`level`	Maps and sublevels	`.umap`
`other`	All other asset types	Various

Jenkins Integration

Jenkinsfile Example

Add webhook calls to your build pipeline:

pipeline {
    agent any

    environment {
        BUTTERSTACK_URL = 'https://your-butterstack.com'
        BUTTERSTACK_TOKEN = credentials('butterstack-token')
    }

    stages {
        stage('Cook') {
            steps {
                // Notify cooking started
                httpRequest(
                    url: "${BUTTERSTACK_URL}/webhooks/game_engine/cooking_started",
                    httpMode: 'POST',
                    contentType: 'APPLICATION_JSON',
                    customHeaders: [[name: 'Authorization', value: "Bearer ${BUTTERSTACK_TOKEN}"]],
                    requestBody: """
                        {
                            "project_id": "${PROJECT_ID}",
                            "build_number": ${BUILD_NUMBER},
                            "engine_version": "5.4",
                            "platform": "Win64"
                        }
                    """
                )

                // Run UAT BuildCookRun
                bat '''
                    "%UE_ROOT%\\Engine\\Build\\BatchFiles\\RunUAT.bat" BuildCookRun ^
                        -project="%PROJECT_PATH%" ^
                        -platform=Win64 ^
                        -clientconfig=Shipping ^
                        -cook -build -stage -pak -archive
                '''
            }
        }

        stage('Notify Complete') {
            steps {
                httpRequest(
                    url: "${BUTTERSTACK_URL}/webhooks/game_engine/build_completed",
                    httpMode: 'POST',
                    contentType: 'APPLICATION_JSON',
                    customHeaders: [[name: 'Authorization', value: "Bearer ${BUTTERSTACK_TOKEN}"]],
                    requestBody: """
                        {
                            "project_id": "${PROJECT_ID}",
                            "build_number": ${BUILD_NUMBER}
                        }
                    """
                )
            }
        }
    }

    post {
        failure {
            httpRequest(
                url: "${BUTTERSTACK_URL}/webhooks/game_engine/build_failed",
                httpMode: 'POST',
                contentType: 'APPLICATION_JSON',
                customHeaders: [[name: 'Authorization', value: "Bearer ${BUTTERSTACK_TOKEN}"]],
                requestBody: """
                    {
                        "project_id": "${PROJECT_ID}",
                        "build_number": ${BUILD_NUMBER},
                        "error": "Build failed"
                    }
                """
            )
        }
    }
}

PowerShell Build Script

For local builds or Windows-based CI, use PowerShell:

# Build script with ButterStack notifications
$ProjectPath = "C:\Projects\MyGame\MyGame.uproject"
$UE5Root = "C:\Program Files\Epic Games\UE_5.4"
$OutputDir = "C:\Projects\MyGame\Build"
$ButterStackUrl = "https://your-butterstack.com"
$ButterStackToken = $env:BUTTERSTACK_TOKEN
$ProjectId = "your-project-id"
$BuildNumber = $env:BUILD_NUMBER

$UAT = Join-Path $UE5Root "Engine\Build\BatchFiles\RunUAT.bat"

# Notify cooking started
$body = @{
    project_id = $ProjectId
    build_number = $BuildNumber
    engine_version = "5.4"
    platform = "Win64"
} | ConvertTo-Json

Invoke-RestMethod -Uri "$ButterStackUrl/webhooks/game_engine/cooking_started" `
    -Method Post -Body $body -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $ButterStackToken" }

# Run build
& $UAT BuildCookRun `
    -project="$ProjectPath" `
    -platform=Win64 `
    -clientconfig=Shipping `
    -cook -build -stage -pak `
    -compressed -prereqs -distribution `
    -archive -archivedirectory="$OutputDir"

if ($LASTEXITCODE -eq 0) {
    # Notify success
    $body = @{
        project_id = $ProjectId
        build_number = $BuildNumber
    } | ConvertTo-Json

    Invoke-RestMethod -Uri "$ButterStackUrl/webhooks/game_engine/build_completed" `
        -Method Post -Body $body -ContentType "application/json" `
        -Headers @{ Authorization = "Bearer $ButterStackToken" }
} else {
    # Notify failure
    $body = @{
        project_id = $ProjectId
        build_number = $BuildNumber
        error = "Build failed with exit code $LASTEXITCODE"
    } | ConvertTo-Json

    Invoke-RestMethod -Uri "$ButterStackUrl/webhooks/game_engine/build_failed" `
        -Method Post -Body $body -ContentType "application/json" `
        -Headers @{ Authorization = "Bearer $ButterStackToken" }
}

Metrics Tracked

Per-Build Metrics

Metric	Description
Total cook time	Sum of all asset cook times
Asset count	Number of assets cooked
Shader permutations	Total shader variants compiled
DDC hit rate	Derived Data Cache effectiveness
PAK size	Final packaged size

Per-Asset Metrics

Metric	Description
Cook time	Time to cook this asset (ms)
Original size	Uncooked asset size
Cooked size	Final cooked size
Compression ratio	Size reduction percentage
Status	Success or failure
Error message	If failed, why

Troubleshooting

Webhooks Not Received

Verify webhook URL is correct
Check authentication token
Ensure network allows outbound HTTPS
Review ButterStack webhook logs

Missing Asset Data

Per-asset tracking requires parsing build logs or custom hooks. Without this:

Build phase tracking still works
Aggregate metrics available
Individual asset metrics not available

Build Not Linking

Ensure build_number matches between:

Jenkins build
Game engine webhooks
ButterStack build record

Best Practices

Start with phase tracking - Add cooking_started and build_completed first
Add asset details later - Per-asset tracking is optional
Use consistent build numbers - Match Jenkins BUILD_NUMBER
Include error details - Help debugging failed builds
Track multiple platforms - Send separate events per platform