Metal StateReporting API & Performance Trace Tools

import Metal
import MetalStateReporting // part of Metal tooling umbrella in iOS 27
import simd

// MARK: - Domain & Reporter setup (do once at app launch)
final class GameStateReporter {
    // Domain identifier: reverse-DNS string, unique to your app
    private static let levelDomain = "com.mygame.state.level"
    private static let graphicsDomain = "com.mygame.state.graphics"

    private let levelReporter: MTLStateReporter
    private let graphicsReporter: MTLStateReporter

    init() {
        levelReporter = MTLStateReporter(domain: GameStateReporter.levelDomain)
        graphicsReporter = MTLStateReporter(domain: GameStateReporter.graphicsDomain)
    }

    // MARK: - Report a level transition with stable metadata
    func enterLevel(id: Int, biome: String) {
        // stableMetadata is immutable for the duration of this state
        levelReporter.reportTransition(
            label: "Level \(id)",
            stableMetadata: [
                "id": id,
                "biome": biome
            ]
        )
    }

    // MARK: - Update volatile metadata without a state transition
    func updatePlayerPosition(_ position: SIMD3<Float>, health: Int) {
        // Called every frame or on a timer; HUD shows latest value
        levelReporter.reportVolatileMetadataUpdate([
            "playerX": position.x,
            "playerY": position.y,
            "playerZ": position.z,
            "health": health
        ])
    }

    // MARK: - Report graphics preset changes
    func applyGraphicsPreset(_ preset: String) {
        // e.g. "Low", "Medium", "High", "Ultra"
        graphicsReporter.reportTransition(
            label: preset,
            stableMetadata: ["preset": preset]
        )
    }
}

// MARK: - Usage in your game loop / scene manager
let reporter = GameStateReporter()

// When the player loads Level 3 in a jungle biome:
reporter.enterLevel(id: 3, biome: "Jungle")
reporter.applyGraphicsPreset("High")

// Each frame (or via a 1 Hz timer) update volatile position:
let pos = SIMD3<Float>(12.5, 0.0, -44.3)
reporter.updatePlayerPosition(pos, health: 87)