Metal StateReporting & Long-Session Performance Tracing

import Metal
import MetalStateReporting // Part of Metal tooling in iOS/macOS 27

// MARK: - StateReporting Domain Setup

class GameStateReporter {
    // Create a domain using reverse-DNS naming convention
    private let levelReporter: MTLStateReporter
    private let graphicsReporter: MTLStateReporter

    init() {
        // Obtain reporters for each domain (finite state machines)
        levelReporter = MTLStateReporter(domain: "com.mygame.level")
        graphicsReporter = MTLStateReporter(domain: "com.mygame.graphics")
    }

    // Call when the player enters a new level
    func playerEnteredLevel(id: Int, biome: String) {
        levelReporter.reportTransition(
            label: "Level \(id)",
            stableMetadata: [
                "biome": biome,
                "id": String(id)
            ]
        )
    }

    // Call each frame or on timer to update mutable state
    func updatePlayerPosition(x: Float, y: Float, z: Float) {
        levelReporter.reportVolatileMetadataUpdate([
            "playerX": String(format: "%.1f", x),
            "playerY": String(format: "%.1f", y),
            "playerZ": String(format: "%.1f", z)
        ])
    }

    // Call when graphics quality changes
    func graphicsQualityChanged(to preset: String, resolutionScale: Float) {
        graphicsReporter.reportTransition(
            label: preset,
            stableMetadata: [
                "resolutionScale": String(format: "%.2f", resolutionScale)
            ]
        )
    }
}

// MARK: - Usage in Game Loop

let reporter = GameStateReporter()

// On level load:
reporter.playerEnteredLevel(id: 3, biome: "Arctic")
reporter.graphicsQualityChanged(to: "High", resolutionScale: 1.0)

// Each frame or on position change:
reporter.updatePlayerPosition(x: 128.5, y: 0.0, z: -64.3)

// The Metal Performance HUD, Instruments, and metalperftrace CLI
// will now annotate all FPS/GPU metrics with this game context,
// allowing correlation like:
// $ metalperftrace overview --aggregate-state com.mygame.graphics:High game.ptrace