game-ui

Game UI Patterns

HUD Overlay Architecture

Use SwiftUI overlays on SpriteView — NOT SKLabelNode/SKSpriteNode for HUD:

struct GameView: View {
    @State var gameState = GameState()

    var body: some View {
        ZStack {
            SpriteView(scene: scene, isPaused: gameState.isPaused)
                .ignoresSafeArea()

            // HUD overlay — uses AppTheme
            VStack {
                HStack {
                    ScoreView(score: gameState.score)
                    Spacer()
                    LivesView(lives: gameState.lives)
                }
                .padding(.horizontal, AppTheme.Spacing.lg)
                .padding(.top, AppTheme.Spacing.md)

                Spacer()
            }
            .allowsHitTesting(false) // Let touches pass through to SpriteView

            // Pause/Game Over modals
            if gameState.phase == .paused { PauseMenuView(gameState: gameState) }
            if gameState.phase == .gameOver { GameOverView(gameState: gameState) }
        }
    }
}

Rules:

• HUD elements in SwiftUI use AppTheme tokens (colors, fonts, spacing)
• Use .allowsHitTesting(false) on non-interactive overlays
• Interactive buttons (pause, menu) need .allowsHitTesting(true)
• Score/lives/timer update via @Observable GameState shared with SKScene

Menu Flow

MainMenu → Game (Playing) → Pause → Resume / Quit
                          → GameOver → PlayAgain / MainMenu

Implementation:

@Observable
class GameState {
    var phase: GamePhase = .menu

    enum GamePhase: Equatable {
        case menu
        case playing
        case paused
        case gameOver(winner: String)
    }
}

// In MainView
switch gameState.phase {
case .menu:
    MainMenuView(gameState: gameState)
case .playing, .paused, .gameOver:
    GameView(gameState: gameState)
}

Score Display

struct ScoreView: View {
    let score: Int

    var body: some View {
        Text("\(score)")
            .font(AppTheme.Fonts.largeTitle)
            .foregroundStyle(AppTheme.Colors.textPrimary)
            .contentTransition(.numericText())
            .animation(.spring(duration: 0.3), value: score)
    }
}