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

```swift
// 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:

```swift
// 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

```bash
# 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

```bash
# 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)
```swift
// DON'T DO THIS!
class Renderer {
    func draw() {
        #if os(Linux)
            vulkanDraw()
        #elif os(Windows)
            dx12Draw()
        #endif
    }
}
```

#### ✅ Good Approach (Protocol-based abstraction)
```swift
// 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

```swift
// 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

```swift
// 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`:

```swift
// 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:

```swift
// 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