TopDogLabs/CasinoGames
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
88d8c26865
CasinoGames/BRANDING_IMPLEMENTATION_GUIDE.md

20 KiB
Raw Blame History

Branding Implementation Guide

A step-by-step guide to implementing the CasinoKit branding system (app icon and launch screen) in your casino game app.

Table of Contents

  1. Overview
  2. Prerequisites
  3. Step 1: Copy Branding Files
  4. Step 2: Create BrandingConfig.swift
  5. Step 3: Add Launch Screen to App Entry Point
  6. Step 4: Add Branding Tools to Settings (Optional)
  7. Step 5: Generate Your App Icon
  8. Step 6: Add Icon to Xcode Assets
  9. Complete Example
  10. Troubleshooting

Overview

The CasinoKit branding system provides:

  • AppIconView: A customizable icon design with gradient backgrounds, SF Symbols, and text
  • LaunchScreenView: An animated launch screen that matches your icon
  • AppLaunchView: A wrapper that seamlessly transitions from launch to app
  • IconGeneratorView: A development tool to generate and export icon images
  • BrandingPreviewView: A preview tool to see icons and launch screens side-by-side

Key Files in CasinoKit:

  • AppIconView.swift - Icon design view
  • LaunchScreenView.swift - Launch screen design view
  • AppLaunchView.swift - Launch wrapper with animation
  • IconGeneratorView.swift - Icon export tool
  • IconRenderer.swift - Rendering utilities
  • BrandingPreviewView.swift - Preview tool

Prerequisites

If Using CasinoKit Package

Your app must have CasinoKit as a dependency. No additional files needed—everything is available through import CasinoKit.

If You Copied the Branding Folder

If you manually copied the branding views from CasinoKit into your app, ensure you have:

  1. All 6 files from CasinoKit/Sources/CasinoKit/Views/Branding/:

    • AppIconView.swift
    • LaunchScreenView.swift
    • AppLaunchView.swift
    • IconGeneratorView.swift
    • IconRenderer.swift
    • BrandingPreviewView.swift

  2. Dependencies these files require:

    • DiamondPatternView.swift (used by AppIconView)
    • DebugSection.swift (if using debug tools)

Step 1: Copy Branding Files

Skip this step if using CasinoKit as a package dependency.

If copying manually, create a Theme/ folder in your app target and copy all branding files:

YourApp/
  YourApp/
    Theme/
      AppIconView.swift
      LaunchScreenView.swift
      AppLaunchView.swift
      IconGeneratorView.swift
      IconRenderer.swift
      BrandingPreviewView.swift
      BrandingConfig.swift  ← You'll create this in Step 2

Important: Ensure you also have DiamondPatternView.swift if AppIconView references it, or copy that pattern code inline.

Step 2: Create BrandingConfig.swift

Create a new Swift file in your app's Theme/ folder called BrandingConfig.swift. This file defines your game's branding.

Template

//
//  BrandingConfig.swift
//  YourGame
//
//  App-specific branding configurations for icons and launch screens.
//

import SwiftUI
import CasinoKit  // Remove this line if not using CasinoKit package

// MARK: - App Icon Configuration

extension AppIconConfig {
    /// YourGame app icon configuration.
    static let yourGame = AppIconConfig(
        title: "YOUR GAME",           // App name (uppercase looks best)
        subtitle: "21",                 // Optional: number or short text below icon
        iconSymbol: "suit.club.fill",   // SF Symbol for the main icon
        primaryColor: Color(red: 0.1, green: 0.2, blue: 0.35),   // Top gradient color
        secondaryColor: Color(red: 0.05, green: 0.12, blue: 0.25), // Bottom gradient color
        accentColor: .yellow            // Color for icon and text
    )
}

// MARK: - Launch Screen Configuration

extension LaunchScreenConfig {
    /// YourGame launch screen configuration.
    static let yourGame = LaunchScreenConfig(
        title: "YOUR GAME",            // App name (uppercase looks best)
        subtitle: "21",                 // Optional: appears below icon symbols
        tagline: "Beat the Dealer",     // Optional: tagline at bottom
        iconSymbols: [                  // 1-3 SF Symbols for the launch logo
            "suit.club.fill",
            "suit.diamond.fill"
        ],
        primaryColor: Color(red: 0.1, green: 0.2, blue: 0.35),   // Top gradient color
        secondaryColor: Color(red: 0.05, green: 0.12, blue: 0.25), // Bottom gradient color
        accentColor: .yellow            // Color for text and accents
    )
}

Customization Tips

Title:

  • Use uppercase for a casino aesthetic
  • Keep it concise (6-9 characters max)
  • The view automatically scales longer titles

Subtitle:

  • Optional, best for short numbers or text ("21", "DELUXE", etc.)
  • Appears larger and more prominent than the title

Icon Symbol:

  • Use SF Symbols names (e.g., "suit.spade.fill", "diamond.fill")
  • Browse available symbols in Xcode: Editor → Insert SF Symbol
  • Card suits work great: suit.spade.fill, suit.heart.fill, suit.diamond.fill, suit.club.fill

Colors:

  • Use Color(red:green:blue:) with values 0.0-1.0
  • Primary color = top of gradient
  • Secondary color = bottom of gradient (usually darker)
  • Accent color = icon symbol and text highlights

Launch Screen Icon Symbols:

  • Use 1-3 symbols for visual variety
  • Hearts and diamonds automatically render red
  • Spades and clubs render white

Real Examples

Blackjack:

extension AppIconConfig {
    static let blackjack = AppIconConfig(
        title: "BLACKJACK",
        subtitle: "21",
        iconSymbol: "suit.club.fill",
        primaryColor: Color(red: 0.05, green: 0.35, blue: 0.15),    // Green felt
        secondaryColor: Color(red: 0.03, green: 0.2, blue: 0.1),
        accentColor: .yellow
    )
}

extension LaunchScreenConfig {
    static let blackjack = LaunchScreenConfig(
        title: "BLACKJACK",
        subtitle: "21",
        tagline: "Beat the Dealer",
        iconSymbols: ["suit.club.fill", "suit.diamond.fill"],
        primaryColor: Color(red: 0.05, green: 0.35, blue: 0.15),
        secondaryColor: Color(red: 0.03, green: 0.2, blue: 0.1),
        accentColor: .yellow
    )
}

Baccarat:

extension AppIconConfig {
    static let baccarat = AppIconConfig(
        title: "BACCARAT",
        iconSymbol: "suit.spade.fill",
        primaryColor: Color(red: 0.1, green: 0.2, blue: 0.35),      // Blue elegant
        secondaryColor: Color(red: 0.05, green: 0.12, blue: 0.25)
    )
}

extension LaunchScreenConfig {
    static let baccarat = LaunchScreenConfig(
        title: "BACCARAT",
        tagline: "The Classic Casino Card Game",
        iconSymbols: ["suit.spade.fill", "suit.heart.fill"]
    )
}

Step 3: Add Launch Screen to App Entry Point

Update your @main App struct to wrap your content with AppLaunchView.

Before

@main
struct YourGameApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

After

import SwiftUI
import CasinoKit  // If using the package

@main
struct YourGameApp: App {
    var body: some Scene {
        WindowGroup {
            AppLaunchView(config: .yourGame) {
                ContentView()
            }
        }
    }
}

What this does:

  • Shows an animated launch screen for ~2 seconds
  • Fades smoothly into your main content
  • Creates a polished, professional app opening experience

Note: Replace .yourGame with the static property name you defined in BrandingConfig.swift (e.g., .blackjack, .poker, .roulette).

Step 4: Add Branding Tools to Settings (Optional)

Add debug tools to your settings view so you can easily generate and preview icons during development.

If Using CasinoKit Package

Add this to your settings view inside a #if DEBUG block:

#if DEBUG
SheetSection(title: "DEBUG", icon: "ant.fill") {
    BrandingDebugRows(
        iconConfig: .yourGame,
        launchConfig: .yourGame,
        appName: "YourGame"
    )
}
#endif

Full Example in Settings

import SwiftUI
import CasinoKit

struct SettingsView: View {
    @Environment(\.dismiss) private var dismiss
    
    var body: some View {
        SheetContainerView(
            title: "Settings",
            content: {
                // ... your normal settings sections ...
                
                // DEBUG section at the bottom
                #if DEBUG
                SheetSection(title: "DEBUG", icon: "ant.fill") {
                    BrandingDebugRows(
                        iconConfig: .yourGame,
                        launchConfig: .yourGame,
                        appName: "YourGame"
                    )
                }
                #endif
            },
            onCancel: nil,
            onDone: {
                dismiss()
            }
        )
    }
}

What this adds:

  • Icon Generator button: Generates and saves a 1024px PNG to the Files app
  • Branding Preview button: Shows a live preview of your icon and launch screen

Important: This only appears in DEBUG builds and will automatically be excluded from App Store releases.

Step 5: Generate Your App Icon

Now it's time to create your actual app icon image.

Method 1: Using IconGeneratorView (Recommended)

  1. Build and run your app (simulator or device)
  2. Open Settings in your app
  3. Scroll to the DEBUG section (only visible in DEBUG builds)
  4. Tap "Icon Generator"
  5. Tap "Generate & Save Icon"
  6. Wait for confirmation: "✅ Icon saved to Documents folder!"

The icon is now saved as AppIcon.png (1024×1024) in your app's Documents folder.

Method 2: Using Xcode Previews

  1. Open BrandingConfig.swift in Xcode
  2. Add a preview at the bottom:
#Preview("App Icon") {
    AppIconView(config: .yourGame, size: 512)
        .clipShape(.rect(cornerRadius: 512 * 0.22))
        .padding()
        .background(Color.gray)
}
  1. Open the Canvas (Editor → Canvas)
  2. Take a screenshot of the preview
  3. Crop and scale to 1024×1024 in an image editor

Method 3: Programmatic Export

Create a temporary view or function:

@MainActor
func exportIcon() {
    let config = AppIconConfig.yourGame
    let view = AppIconView(config: config, size: 1024)
    let renderer = ImageRenderer(content: view)
    renderer.scale = 1.0
    
    if let image = renderer.uiImage,
       let data = image.pngData() {
        let url = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
            .appending(path: "AppIcon.png")
        try? data.write(to: url)
        print("Icon saved to: \(url.path)")
    }
}

Step 6: Add Icon to Xcode Assets

Retrieve the Icon from Device/Simulator

On Simulator:

  1. Open Finder
  2. Go to: ~/Library/Developer/CoreSimulator/Devices/
  3. Find your simulator device folder
  4. Navigate to: data/Containers/Data/Application/[YourApp]/Documents/
  5. Copy AppIcon.png to your Mac desktop

On Physical Device:

  1. Open the Files app on your device
  2. Navigate to: On My iPhone → YourGame
  3. Find AppIcon.png
  4. AirDrop or share it to your Mac

Alternative (Xcode):

  1. In Xcode, go to Window → Devices and Simulators
  2. Select your device/simulator
  3. Find your app in the Installed Apps list
  4. Click the ⚙️ gear icon → Download Container
  5. Right-click the downloaded .xcappdata file → Show Package Contents
  6. Navigate to AppData/Documents/ and copy AppIcon.png

Add to Xcode Assets

  1. Open your Xcode project
  2. Navigate to Assets.xcassets in the Project Navigator
  3. Click on AppIcon (the app icon asset)
  4. Drag AppIcon.png from Finder into the 1024×1024 slot (labeled "iOS App Store")
  5. Xcode automatically generates all required sizes from this single image

Important: Modern iOS projects only need the 1024×1024 image. Xcode generates all other sizes automatically.

Verify the Icon

  1. Build and run your app
  2. Press the Home button (or swipe up)
  3. Check that your new icon appears on the home screen
  4. If it doesn't update immediately, delete the app and reinstall

Complete Example

Here's a full example for a Poker game:

File: Poker/Theme/BrandingConfig.swift

//
//  BrandingConfig.swift
//  Poker
//

import SwiftUI
import CasinoKit

extension AppIconConfig {
    static let poker = AppIconConfig(
        title: "POKER",
        iconSymbol: "suit.diamond.fill",
        primaryColor: Color(red: 0.2, green: 0.05, blue: 0.1),
        secondaryColor: Color(red: 0.1, green: 0.02, blue: 0.05),
        accentColor: Color(red: 1.0, green: 0.85, blue: 0.3)  // Gold
    )
}

extension LaunchScreenConfig {
    static let poker = LaunchScreenConfig(
        title: "POKER",
        tagline: "All In",
        iconSymbols: ["suit.diamond.fill", "suit.heart.fill", "suit.club.fill"],
        primaryColor: Color(red: 0.2, green: 0.05, blue: 0.1),
        secondaryColor: Color(red: 0.1, green: 0.02, blue: 0.05),
        accentColor: Color(red: 1.0, green: 0.85, blue: 0.3)
    )
}

File: Poker/PokerApp.swift

import SwiftUI
import CasinoKit

@main
struct PokerApp: App {
    var body: some Scene {
        WindowGroup {
            AppLaunchView(config: .poker) {
                ContentView()
            }
        }
    }
}

File: Poker/Views/SettingsView.swift

import SwiftUI
import CasinoKit

struct SettingsView: View {
    @Environment(\.dismiss) private var dismiss
    
    var body: some View {
        SheetContainerView(
            title: "Settings",
            content: {
                // Game settings sections...
                
                SheetSection(title: "SOUND", icon: "speaker.wave.2.fill") {
                    // Sound settings...
                }
                
                #if DEBUG
                SheetSection(title: "DEBUG", icon: "ant.fill") {
                    BrandingDebugRows(
                        iconConfig: .poker,
                        launchConfig: .poker,
                        appName: "Poker"
                    )
                }
                #endif
            },
            onDone: {
                dismiss()
            }
        )
    }
}

Troubleshooting

Issue: Can't find AppIconView or other branding types

Solution:

  • If using CasinoKit package: Ensure import CasinoKit is at the top of your file
  • If copying manually: Ensure all 6 branding files are in your app target
  • Check that files are added to your target's "Compile Sources" in Build Phases

Issue: Launch screen doesn't appear

Solution:

  • Verify AppLaunchView wraps your content in the App struct
  • Check that you're using the correct config name (e.g., .poker not .example)
  • Ensure the config extension is defined in BrandingConfig.swift

Issue: Icon looks cut off at the edges

Explanation: iOS applies a superellipse mask to all app icons. The branding system accounts for this, but if you see clipping:

Solution:

  • Don't add rounded corners yourself—iOS does this automatically
  • Ensure decorative borders are inset from edges
  • The system is designed to work with iOS's mask; trust the 22% corner radius preview

Issue: "Icon saved" message appears but can't find the file

Solution:

  • Open the Files app on your device/simulator
  • Navigate to: Browse → On My iPhone/iPad → [Your App Name]
  • If folder doesn't exist, try granting Files access in Settings

Alternative: Use Xcode's Devices and Simulators window to download the app container (see Step 6).

Issue: Icon doesn't update after adding to Assets

Solution:

  1. Clean build folder: Product → Clean Build Folder (Cmd+Shift+K)
  2. Delete app from device/simulator
  3. Rebuild and reinstall
  4. If still not working, check that the 1024×1024 slot is filled in Assets.xcassets

Issue: BrandingDebugRows not showing in settings

Solution:

  • Ensure you're running a DEBUG build (not Release)
  • Wrap the section in #if DEBUG ... #endif
  • Verify import CasinoKit if using the package
  • Check that your settings view is inside a NavigationStack (required for navigation rows)

Issue: Colors don't match between icon and launch screen

Solution:

  • Ensure both configs use identical color values
  • Copy-paste color definitions to avoid typos
  • Consider extracting colors to a shared constant:
extension Color {
    static let pokerPrimary = Color(red: 0.2, green: 0.05, blue: 0.1)
    static let pokerSecondary = Color(red: 0.1, green: 0.02, blue: 0.05)
}

extension AppIconConfig {
    static let poker = AppIconConfig(
        title: "POKER",
        iconSymbol: "suit.diamond.fill",
        primaryColor: .pokerPrimary,
        secondaryColor: .pokerSecondary
    )
}

Issue: Title text is too small or too large

Solution: The system automatically scales titles based on length:

  • 6 characters or less: Full size (100%)
  • 7 characters: 95% scale
  • 8 characters: 85% scale
  • 9 characters: 75% scale
  • 10+ characters: 65% scale

If your title is very long, consider:

  • Using an abbreviation in the icon
  • Using subtitle for additional text
  • Manually adjusting the titleSize calculation in AppIconView.swift

Additional Resources

Color Palette Ideas

Classic Casino:

primaryColor: Color(red: 0.1, green: 0.2, blue: 0.35)    // Deep blue
secondaryColor: Color(red: 0.05, green: 0.12, blue: 0.25)
accentColor: .yellow

Luxury Gold:

primaryColor: Color(red: 0.2, green: 0.15, blue: 0.05)   // Deep gold
secondaryColor: Color(red: 0.1, green: 0.08, blue: 0.02)
accentColor: Color(red: 1.0, green: 0.85, blue: 0.3)     // Bright gold

Green Felt:

primaryColor: Color(red: 0.05, green: 0.35, blue: 0.15)  // Casino green
secondaryColor: Color(red: 0.03, green: 0.2, blue: 0.1)
accentColor: .yellow

Elegant Red:

primaryColor: Color(red: 0.3, green: 0.05, blue: 0.1)    // Deep red
secondaryColor: Color(red: 0.15, green: 0.02, blue: 0.05)
accentColor: Color(red: 1.0, green: 0.85, blue: 0.3)

SF Symbol Recommendations

Card Suits:

  • suit.spade.fill - Classic, elegant
  • suit.heart.fill - Warm, friendly
  • suit.diamond.fill - Luxurious
  • suit.club.fill - Traditional

Other Casino Icons:

  • diamond.fill - Luxury, wealth
  • star.fill - Premium, winning
  • crown.fill - VIP, royalty
  • dollarsign.circle.fill - Money, stakes

Launch Screen Animation Timing

The default timing is:

  • Logo fade-in: 0.6 seconds
  • Tagline fade-in: 0.6 seconds (delayed by 0.3s)
  • Total display: 2.0 seconds
  • Fade-out: 0.5 seconds

To customize, modify AppLaunchView.swift:

.task {
    try? await Task.sleep(for: .seconds(3.0))  // Change display duration
    withAnimation(.easeOut(duration: 1.0)) {    // Change fade-out duration
        showLaunchScreen = false
    }
}

Summary Checklist

  • Copy branding files from CasinoKit or ensure package dependency is set up
  • Create BrandingConfig.swift with your game's configurations
  • Add AppLaunchView wrapper to your App entry point
  • (Optional) Add BrandingDebugRows to your settings view
  • Build and run app in DEBUG mode
  • Generate icon using Icon Generator tool
  • Retrieve icon PNG from device/simulator
  • Add 1024×1024 PNG to Assets.xcassets AppIcon slot
  • Clean build and reinstall to verify icon appears
  • Test launch screen animation on device

Need Help?

  • Check the BrandingPreviewView to see your icon and launch screen side-by-side
  • Use Xcode previews to iterate on colors and layout quickly
  • Test on multiple device sizes to ensure text scales properly
  • Remember: DEBUG tools are automatically excluded from Release builds

Happy Branding! 🎰✨