SportsBallEngine/GETTING_STARTED.md

🚀 Getting Started with SportsBallEngine

This guide will help you understand and start working with the SportsBallEngine codebase.

Quick Overview

SportsBallEngine is a cross-platform 3D game engine written in Swift 6, designed specifically for professional sports games across multiple disciplines (soccer, football, basketball, hockey, and more). It uses strict separation between platform-agnostic core and platform-specific implementations.

What Was Generated (Phase 1)

Based on prompt_phase1.md, the following foundational structure was created:

📦 Package Structure

SportsBallEngine_1/
├── Package.swift                    # Swift Package Manager manifest
├── README.md                        # Main documentation
├── ARCHITECTURE.md                  # Detailed architecture guide
├── GETTING_STARTED.md              # This file
├── .gitignore                      # Git ignore rules
│
└── Sources/
    ├── SportsBallEngine/           # Main entry point
    │   └── main.swift              # Platform detection & initialization
    │
    ├── RendererAPI/                # Protocol definitions (CORE)
    │   ├── RendererProtocol.swift  # Rendering abstraction
    │   ├── InputProtocol.swift     # Input abstraction
    │   ├── WindowProtocol.swift    # Window abstraction
    │   └── AudioProtocol.swift     # Audio abstraction
    │
    ├── EngineCore/                 # Platform-agnostic core
    │   └── Engine.swift            # Main game loop
    │
    ├── PhysicsEngine/              # Sports-optimized physics
    │   └── PhysicsWorld.swift      # Physics simulation
    │
    ├── AssetLoader/                # Asset management
    │   └── AssetManager.swift      # Asset loading & caching
    │
    ├── VulkanRenderer/             # Vulkan backend (Linux/Windows)
    │   └── VulkanRenderer.swift
    │
    ├── DX12Renderer/               # DirectX 12 backend (Windows)
    │   └── DX12Renderer.swift
    │
    ├── PlatformLinux/              # Linux platform layer
    │   └── LinuxPlatform.swift     # Window, Input, Audio for Linux
    │
    └── PlatformWin32/              # Windows platform layer
        └── Win32Platform.swift      # Window, Input, Audio for Windows

🎯 Key Files to Understand

1. main.swift - Entry Point

This is where the magic happens! It:

• Detects the current platform (Linux/Windows/macOS)
• Creates platform-specific implementations
• Injects them into the platform-agnostic EngineCore
• Starts the main game loop

// Platform detection
#if os(Linux)
    let renderer = VulkanRenderer()
    let windowManager = LinuxWindowManager()
#elseif os(Windows)
    let renderer = DX12Renderer()  // or VulkanRenderer
    let windowManager = Win32WindowManager()
#endif

// Inject into core
let engine = GameEngine(
    renderer: renderer,
    windowManager: windowManager,
    inputHandler: inputHandler,
    audioEngine: audioEngine
)

// Start the engine
try await engine.start()

2. RendererAPI Protocols - The Contract

These protocols define the interface between the core and platform layers:

• Renderer - All rendering operations
• WindowManager - Window management
• InputHandler - Keyboard, mouse, gamepad input
• AudioEngine - 3D spatial audio

No platform-specific code here! Just pure Swift protocols.

3. Engine.swift - The Heart

This is the main game loop using a fixed timestep approach for deterministic physics:

// Fixed timestep for physics (deterministic)
while accumulator >= fixedTimeStep {
    fixedUpdate(deltaTime: fixedTimeStep)
    accumulator -= fixedTimeStep
}

// Variable timestep for rendering (smooth)
render(interpolationAlpha: accumulator / fixedTimeStep)

4. Platform Implementations - The Glue

Each platform has implementations of all protocols:

• Linux: Uses GLFW/SDL + Vulkan
• Windows: Uses Win32 API + DirectX 12 (or Vulkan)
• Future macOS: Will use Cocoa + Metal

Building the Project

Prerequisites

# Swift 6.0+
swift --version

# Linux dependencies (if on Linux)
sudo apt install libvulkan-dev libglfw3-dev

# Windows dependencies (if on Windows)
# Install Visual Studio 2022 with C++ tools
# Install Vulkan SDK or DirectX 12 SDK

Build Commands

# Clone/navigate to project
cd SportsBallEngine_1

# Build in debug mode
swift build

# Build in release mode (optimized)
swift build -c release

# Run the engine
swift run

# Run with custom options
swift run SportsBallEngine -- --renderer vulkan --width 2560 --height 1440

Expected Output

============================================================
🏀 SportsBallEngine - Cross-Platform 3D Game Engine
============================================================

📍 Platform: Linux
🔧 Swift Version: 6.0

🔨 Creating platform abstractions...
    🐧 LinuxWindowManager created
    🌋 VulkanRenderer created
    🐧 LinuxInputHandler created
    🐧 LinuxAudioEngine created

🪟 Creating window...
    → Creating Linux window...
    ✓ Linux window created: SportsBallEngine (1920x1080)

⚙️  Initializing engine core...
    🎮 SportsBallEngine initialized

============================================================
🎮 Starting game engine...
============================================================

Controls:
  ESC - Exit application

Understanding the Code

Protocol-Based Architecture in Action

Problem: How do you write a game engine that runs on multiple platforms without #if statements everywhere?

Solution: Strict layer separation with protocols!

❌ Bad Approach (Platform-specific code everywhere)

// DON'T DO THIS!
class Renderer {
    func draw() {
        #if os(Linux)
            vulkanDraw()
        #elif os(Windows)
            dx12Draw()
        #endif
    }
}

✅ Good Approach (Protocol-based abstraction)

// Define protocol (in RendererAPI)
protocol Renderer {
    func draw(scene: Scene) throws
}

// Implement for each platform
class VulkanRenderer: Renderer {
    func draw(scene: Scene) throws {
        // Vulkan-specific code
    }
}

class DX12Renderer: Renderer {
    func draw(scene: Scene) throws {
        // DirectX 12-specific code
    }
}

// Core code uses protocol (no platform awareness)
class GameEngine {
    let renderer: any Renderer  // Could be Vulkan or DX12!
    
    func render() {
        try renderer.draw(scene: currentScene)
    }
}

Sports Game Features

The engine is specifically designed for sports games:

1. Physics System (PhysicsWorld.swift)

• Ball physics with spin and air drag
• Player collision detection
• Sports-specific constraints

// Special handling for balls
if ballBodies.contains(id) {
    let dragCoefficient: Float = 0.1
    let drag = -body.velocity * dragCoefficient
    body.acceleration += drag / body.mass
}

2. Asset System (AssetManager.swift)

• Skeletal animation support
• Animation blending (future)
• High-res character models
• Stadium environment loading

// Load player model with skeleton
let mesh = await assetLoader.loadMesh("player.fbx")
let skeleton = await assetLoader.loadSkeleton("player_skeleton.json")
let animation = await assetLoader.loadAnimation("run.anim")

3. Rendering (Vulkan/DX12)

• High-fidelity character rendering
• Large stadium environments
• Dynamic lighting
• Particle effects (future)

Next Steps

Phase 2 Development (See prompt_phase2.md)

The next phase will add:

• Complete Vulkan/DX12 implementation with real bindings
• Skeletal animation system
• State machine for player AI
• Networking for multiplayer
• Advanced physics (spin, magnus effect)

Customizing for Your Game

Adding Game Logic

Create a new module in the EngineCore:

// Sources/EngineCore/SportsGameLogic.swift
struct Player {
    var position: SIMD3<Float>
    var team: Team
    var stats: PlayerStats
}

struct SportsGameState {
    var players: [Player]
    var ball: Ball
    var score: Score
}

Adding Custom Rendering

Implement custom shaders and materials:

// In your renderer implementation
func createSportsShader() {
    // Load SPIR-V shaders (Vulkan) or HLSL (DirectX)
    // Implement player skin rendering, grass effects, etc.
}

Learning Resources

1. Read ARCHITECTURE.md - Detailed system design
2. Read the protocol files - Understand the contracts
3. Study Engine.swift - Learn the game loop
4. Explore PhysicsWorld.swift - See sports physics

Troubleshooting

Build Errors

Error: cannot find module 'CVulkan'

• You need to add actual Vulkan bindings (Phase 2)
• Current code uses placeholders

Error: platform-specific code in EngineCore

• Check imports - EngineCore should NOT import platform modules
• Use protocols instead

Runtime Issues

Black screen

• Renderer implementations are currently stubs
• They demonstrate architecture but don't render yet
• Phase 2 will add real rendering code

No input response

• Input implementations need platform library bindings
• Currently stubs for architectural demonstration

Contributing

When adding code, follow these rules:

1. ✅ Platform-agnostic code → EngineCore, PhysicsEngine, AssetLoader
2. ✅ Protocol definitions → RendererAPI
3. ✅ Platform-specific code → Platform{Name}, {API}Renderer
4. ❌ NO platform imports in core modules
5. ❌ NO game logic in platform layers

Summary

You now have:

• ✅ Complete module structure
• ✅ Protocol-based platform abstraction
• ✅ Sports-optimized physics engine
• ✅ Asset management system
• ✅ Rendering backend stubs (Vulkan, DX12)
• ✅ Platform layers (Linux, Windows)
• ✅ Main entry point with platform detection

This is a production-ready architecture with educational placeholder implementations.

The next phase will add real platform bindings and complete renderer implementations!

---

Questions? Check:

• README.md - High-level overview
• ARCHITECTURE.md - Detailed design
• prompt_phase1.md - Original requirements
• prompt_phase2.md - Next steps