initial commit

.gitignore

@@ -0,0 +1,38 @@
+# Swift Package Manager
+.build/
+.swiftpm/
+Package.resolved
+
+# Xcode
+xcuserdata/
+*.xcworkspace
+*.xcodeproj
+DerivedData/
+
+# macOS
+.DS_Store
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Build artifacts
+*.o
+*.a
+*.so
+*.dylib
+*.dll
+*.exe
+
+# Logs
+*.log
+
+# Temporary files
+*.tmp
+*.temp
+
+# Prompts
+prompt*.md

ARCHITECTURE.md

@@ -0,0 +1,396 @@
+# 🏗️ SportsBallEngine Architecture
+
+This document provides a detailed overview of the engine's architecture, following industry-standard design patterns for cross-platform game development.
+
+## Core Principles
+
+### 1. Strict Layer Separation
+
+The engine is divided into two distinct categories:
+
+#### **Platform-Agnostic Layer (Engine Core)**
+- Pure Swift code with **ZERO** platform-specific imports
+- Contains all game logic, physics, and asset management
+- Can be tested and developed independently of any platform
+- Modules: `EngineCore`, `PhysicsEngine`, `AssetLoader`
+
+#### **Platform Abstraction Layer (PAL)**
+- Thin wrappers around OS-specific APIs
+- Implements protocols defined by the core layer
+- Only place where platform-specific code exists
+- Modules: `PlatformLinux`, `PlatformWin32`, `VulkanRenderer`, `DX12Renderer`
+
+### 2. Protocol-Oriented Design
+
+All platform-dependent functionality is accessed through Swift protocols:
+
+```swift
+// RendererAPI module (platform-agnostic)
+public protocol Renderer: Sendable {
+    func initialize(config: RendererConfig) async throws
+    func beginFrame() throws
+    func draw(scene: Scene) throws
+    func endFrame() throws
+    func shutdown() async
+    // ... more methods
+}
+
+// VulkanRenderer module (platform-specific)
+public final class VulkanRenderer: Renderer {
+    // Concrete Vulkan implementation
+}
+
+// DX12Renderer module (platform-specific)
+public final class DX12Renderer: Renderer {
+    // Concrete DirectX 12 implementation
+}
+```
+
+### 3. Dependency Injection
+
+Platform implementations are created and injected at startup:
+
+```swift
+// main.swift
+let renderer = PlatformFactory.createRenderer()      // Creates Vulkan or DX12
+let windowManager = PlatformFactory.createWindowManager()
+let inputHandler = PlatformFactory.createInputHandler()
+let audioEngine = PlatformFactory.createAudioEngine()
+
+// Inject into engine core
+let engine = GameEngine(
+    renderer: renderer,
+    windowManager: windowManager,
+    inputHandler: inputHandler,
+    audioEngine: audioEngine
+)
+```
+
+## Module Dependency Graph
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         main.swift                          │
+│                  (Platform Detection)                       │
+└────────────────┬────────────────────────────────────────────┘
+                 │
+                 │ Creates & Injects
+                 │
+                 ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       EngineCore                            │
+│  ┌────────────┐  ┌────────────┐  ┌────────────┐           │
+│  │ Main Loop  │  │   Scene    │  │  Systems   │           │
+│  │ (Fixed Δt) │  │ Management │  │Coordinator │           │
+│  └────────────┘  └────────────┘  └────────────┘           │
+│                                                             │
+│  Depends on protocols only:                                │
+│    - Renderer (draw calls)                                 │
+│    - WindowManager (events)                                │
+│    - InputHandler (keyboard/mouse)                         │
+│    - AudioEngine (sound)                                   │
+└────────┬───────────────────┬──────────────────────────────┘
+         │                   │
+         │                   │
+    ┌────▼────┐         ┌────▼────┐
+    │ Physics │         │  Asset  │
+    │ Engine  │         │ Loader  │
+    └─────────┘         └─────────┘
+
+
+┌─────────────────────────────────────────────────────────────┐
+│                    RendererAPI (Protocols)                  │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
+│  │ Renderer │  │  Window  │  │  Input   │  │  Audio   │  │
+│  │ Protocol │  │ Protocol │  │ Protocol │  │ Protocol │  │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
+│                                                             │
+│  Also defines: Scene, Camera, Entity, Transform, etc.     │
+└────┬─────────────┬─────────────┬─────────────┬────────────┘
+     │             │             │             │
+     │             │             │             │
+     │             │             │             │
+┌────▼────┐   ┌────▼────┐   ┌────▼────┐   ┌────▼────┐
+│ Vulkan  │   │  DX12   │   │ Platform│   │ Platform│
+│Renderer │   │Renderer │   │  Linux  │   │  Win32  │
+└─────────┘   └─────────┘   └─────────┘   └─────────┘
+     │             │             │             │
+     │             │             │             │
+┌────▼────────────▼─────────────▼─────────────▼────┐
+│           Operating System APIs                   │
+│  Vulkan | DirectX 12 | X11 | Wayland | Win32     │
+└───────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+### Frame Rendering Flow
+
+```
+1. main.swift
+   └─> GameEngine.runMainLoop()
+
+2. EngineCore
+   ├─> windowManager.processEvents()        [Platform layer]
+   ├─> inputHandler.pollEvents()            [Platform layer]
+   │
+   ├─> fixedUpdate(deltaTime) [Fixed timestep]
+   │   ├─> physicsEngine.step()             [Core layer]
+   │   ├─> audioEngine.update()             [Platform layer]
+   │   └─> updateGameLogic()                [Core layer]
+   │
+   └─> render(interpolationAlpha)
+       ├─> renderer.beginFrame()            [Platform layer]
+       ├─> renderer.draw(scene)             [Platform layer]
+       └─> renderer.endFrame()              [Platform layer]
+
+3. Renderer (Vulkan or DX12)
+   ├─> Acquire swapchain image
+   ├─> Record command buffer
+   │   ├─> Bind pipeline
+   │   ├─> Set viewport/scissor
+   │   └─> For each entity:
+   │       ├─> Bind vertex/index buffers
+   │       └─> Draw indexed
+   ├─> Submit command buffer
+   └─> Present to window
+```
+
+### Asset Loading Flow
+
+```
+1. EngineCore
+   └─> assetLoader.loadMesh("player.fbx")
+
+2. AssetLoader
+   ├─> Read file from disk
+   ├─> Parse FBX format
+   ├─> Extract vertices, indices, bones
+   └─> Return MeshData (CPU-side)
+
+3. EngineCore
+   └─> renderer.loadMesh(vertices, indices)
+
+4. Renderer (Vulkan or DX12)
+   ├─> Allocate GPU buffer
+   ├─> Upload data to GPU
+   └─> Return MeshHandle (GPU resource)
+
+5. EngineCore
+   └─> Store MeshHandle for rendering
+```
+
+## Key Abstractions
+
+### Renderer Protocol
+
+Handles all graphics API calls:
+- Frame management (begin/end)
+- Scene rendering
+- Resource loading (meshes, textures)
+- Material creation
+
+**Implementations**: `VulkanRenderer`, `DX12Renderer`
+
+### WindowManager Protocol
+
+Handles OS window management:
+- Window creation/destruction
+- Event processing (resize, close, etc.)
+- Native handle retrieval (for surface creation)
+- Fullscreen toggling
+
+**Implementations**: `LinuxWindowManager`, `Win32WindowManager`
+
+### InputHandler Protocol
+
+Handles user input:
+- Keyboard state
+- Mouse state and position
+- Gamepad/controller support
+- Input events
+
+**Implementations**: `LinuxInputHandler`, `Win32InputHandler`
+
+### AudioEngine Protocol
+
+Handles 3D audio:
+- Audio loading and playback
+- 3D spatial audio
+- Listener position (camera)
+- Volume control
+
+**Implementations**: `LinuxAudioEngine`, `Win32AudioEngine`
+
+## Sports Game Optimizations
+
+### Physics System
+
+The `PhysicsEngine` is optimized for sports scenarios:
+
+```swift
+// Special tracking for sports entities
+private var ballBodies: Set<UUID> = []      // Balls/pucks
+private var playerBodies: Set<UUID> = []    // Players
+
+// Custom physics for balls
+if ballBodies.contains(id) {
+    // Apply spin, air drag, magnus effect
+    let drag = -body.velocity * dragCoefficient
+    body.acceleration += drag / body.mass
+}
+```
+
+### Animation System (Future)
+
+Skeletal animation with state machines:
+- Running → Shooting transition
+- Tackling animations
+- Celebration sequences
+- Injury reactions
+
+### Stadium Rendering (Future)
+
+Large environment optimizations:
+- LOD (Level of Detail) for distant objects
+- Occlusion culling
+- Crowd rendering (instancing)
+- Particle systems (grass, dust)
+
+## Thread Safety
+
+The engine uses Swift 6 concurrency features:
+
+- `actor` for thread-safe state management
+- `Sendable` protocols for cross-thread data
+- `async/await` for asynchronous operations
+- `@unchecked Sendable` for platform handles
+
+```swift
+// EngineCore is an actor - all access is serialized
+public actor GameEngine {
+    private let physicsEngine: PhysicsWorld
+    private var currentScene: Scene
+    // ...
+}
+```
+
+## Build System
+
+Uses Swift Package Manager with modular targets:
+
+```swift
+// Package.swift structure
+targets: [
+    // Executable
+    .executableTarget(name: "SportsBallEngine", dependencies: [...]),
+    
+    // Core modules (platform-agnostic)
+    .target(name: "EngineCore", dependencies: ["RendererAPI", ...]),
+    .target(name: "RendererAPI", dependencies: []),
+    .target(name: "PhysicsEngine", dependencies: []),
+    .target(name: "AssetLoader", dependencies: []),
+    
+    // Platform modules (platform-specific)
+    .target(name: "VulkanRenderer", dependencies: ["RendererAPI"]),
+    .target(name: "DX12Renderer", dependencies: ["RendererAPI"]),
+    .target(name: "PlatformLinux", dependencies: ["RendererAPI", "VulkanRenderer"]),
+    .target(name: "PlatformWin32", dependencies: ["RendererAPI", "DX12Renderer"]),
+]
+```
+
+## Testing Strategy
+
+### Unit Tests
+
+- Test core modules in isolation (no platform dependencies)
+- Mock platform implementations using protocols
+- Physics simulation verification
+- Asset parsing validation
+
+### Integration Tests
+
+- Test platform implementations on target OS
+- Renderer functionality tests
+- Window management tests
+- Input handling tests
+
+### Performance Tests
+
+- Frame time consistency
+- Physics simulation speed
+- Asset loading performance
+- Memory usage profiling
+
+## Extension Points
+
+### Adding a New Platform
+
+1. Create `Sources/Platform{Name}/`
+2. Implement all protocols:
+   - `WindowManager`
+   - `InputHandler`
+   - `AudioEngine`
+3. Choose or implement renderer
+4. Update `PlatformFactory` in `main.swift`
+
+### Adding a New Renderer
+
+1. Create `Sources/{API}Renderer/`
+2. Implement `Renderer` protocol
+3. Handle resource loading (meshes, textures)
+4. Implement draw commands
+5. Add to `PlatformFactory`
+
+### Adding Game-Specific Features
+
+All game logic stays in `EngineCore` or custom modules:
+- Player AI systems
+- Ball physics customization
+- Game rules and scoring
+- Network synchronization
+
+**Never** add game logic to platform layers!
+
+## Performance Considerations
+
+### Fixed Timestep
+
+Uses fixed timestep for deterministic physics:
+
+```swift
+// Variable framerate for rendering
+// Fixed 60Hz for physics/gameplay
+while accumulator >= fixedTimeStep {
+    fixedUpdate(deltaTime: fixedTimeStep)
+    accumulator -= fixedTimeStep
+}
+
+// Interpolate between physics states for smooth rendering
+render(interpolationAlpha: accumulator / fixedTimeStep)
+```
+
+### Memory Management
+
+- GPU resources managed through opaque handles
+- Asset caching with LRU eviction (future)
+- Pool allocators for frequent objects (future)
+- Reference counting for shared resources
+
+### Multithreading (Future)
+
+- Physics on separate thread
+- Async asset loading
+- GPU command recording parallelization
+- Job system for parallel tasks
+
+---
+
+This architecture ensures:
+- ✅ Clean separation of concerns
+- ✅ Easy platform porting
+- ✅ Testable core logic
+- ✅ Maintainable codebase
+- ✅ Performance optimization opportunities
+- ✅ Sports game-specific features
+

GETTING_STARTED.md

@@ -0,0 +1,375 @@
+# 🚀 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
+

Package.swift

@@ -0,0 +1,103 @@
+// swift-tools-version: 6.0
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "SportsBallEngine",
+    platforms: [
+        .macOS(.v14),
+        .linux
+    ],
+    products: [
+        .executable(
+            name: "SportsBallEngine",
+            targets: ["SportsBallEngine"]
+        ),
+    ],
+    dependencies: [
+        // Add external dependencies here (e.g., GLFW/SDL bindings, Vulkan bindings)
+        // .package(url: "https://github.com/example/swift-vulkan.git", from: "1.0.0"),
+    ],
+    targets: [
+        // Main executable target
+        .executableTarget(
+            name: "SportsBallEngine",
+            dependencies: [
+                "EngineCore",
+                "PlatformWin32",
+                "PlatformLinux"
+            ]
+        ),
+        
+        // ====== PLATFORM-AGNOSTIC CORE MODULES ======
+        
+        // Engine Core - Main loop and scene management
+        .target(
+            name: "EngineCore",
+            dependencies: [
+                "RendererAPI",
+                "PhysicsEngine",
+                "AssetLoader"
+            ]
+        ),
+        
+        // Renderer API - Protocol definitions only
+        .target(
+            name: "RendererAPI",
+            dependencies: []
+        ),
+        
+        // Physics Engine - Sports-optimized physics simulation
+        .target(
+            name: "PhysicsEngine",
+            dependencies: []
+        ),
+        
+        // Asset Loader - 3D models, textures, animations
+        .target(
+            name: "AssetLoader",
+            dependencies: []
+        ),
+        
+        // ====== PLATFORM-SPECIFIC MODULES ======
+        
+        // Windows Platform Layer
+        .target(
+            name: "PlatformWin32",
+            dependencies: [
+                "RendererAPI",
+                "DX12Renderer"
+            ]
+        ),
+        
+        // Linux Platform Layer
+        .target(
+            name: "PlatformLinux",
+            dependencies: [
+                "RendererAPI",
+                "VulkanRenderer"
+            ]
+        ),
+        
+        // Vulkan Renderer Implementation
+        .target(
+            name: "VulkanRenderer",
+            dependencies: ["RendererAPI"]
+        ),
+        
+        // DirectX 12 Renderer Implementation
+        .target(
+            name: "DX12Renderer",
+            dependencies: ["RendererAPI"]
+        ),
+        
+        // ====== TESTS ======
+        
+        .testTarget(
+            name: "EngineCoreTests",
+            dependencies: ["EngineCore"]
+        ),
+    ]
+)
+

README.md

@@ -0,0 +1,270 @@
+# 🏀 SportsBallEngine
+
+A high-performance, cross-platform 3D game engine written in Swift 6, designed for professional sports games across multiple disciplines. Built with strict platform abstraction and protocol-oriented design.
+
+## 🎯 Design Philosophy
+
+### Clean Architecture
+
+This engine follows industry-standard architectural principles:
+
+1. **Strict Code Separation**
+   - **Platform-Agnostic Core**: Pure Swift modules with NO platform-specific imports
+   - **Platform Abstraction Layers (PAL)**: Thin, platform-specific modules that interact with OS APIs
+
+2. **Protocol-Oriented Design**
+   - All platform-dependent systems use Swift protocols
+   - EngineCore depends only on protocols, never concrete implementations
+   - Platform layers are dependency-injected at startup
+
+3. **Explicit Rendering APIs**
+   - Vulkan (primary cross-platform)
+   - DirectX 12 (Windows optimization)
+   - Metal (future macOS support)
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      main.swift                         │
+│           (Platform Detection & Injection)              │
+└────────────┬────────────────────────────────────────────┘
+             │
+             ├──────────────┬──────────────┬──────────────┐
+             │              │              │              │
+             ▼              ▼              ▼              ▼
+     ┌──────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
+     │ EngineCore   │ │ Renderer │ │  Window  │ │  Input   │
+     │ (Protocol-   │ │ Protocol │ │ Protocol │ │ Protocol │
+     │  Agnostic)   │ └──────────┘ └──────────┘ └──────────┘
+     └───┬──────────┘      │             │             │
+         │                 │             │             │
+         ├─────────┬───────┘             │             │
+         │         │                     │             │
+         ▼         ▼                     ▼             ▼
+   ┌─────────┐ ┌─────────┐      ┌─────────────┐ ┌─────────────┐
+   │ Physics │ │  Asset  │      │ Linux/Win32 │ │ Linux/Win32 │
+   │ Engine  │ │ Loader  │      │   Window    │ │    Input    │
+   └─────────┘ └─────────┘      └─────────────┘ └─────────────┘
+                                          │
+                                          ▼
+                                 ┌─────────────────┐
+                                 │ Vulkan / DX12   │
+                                 │    Renderer     │
+                                 └─────────────────┘
+```
+
+## 📦 Module Structure
+
+### Platform-Agnostic Core Modules
+
+#### **EngineCore**
+- Main game loop (Carmack-style fixed timestep)
+- Scene management
+- System coordination
+- **NO platform imports allowed**
+
+#### **RendererAPI**
+- Protocol definitions for rendering
+- Camera, Scene, Entity types
+- Vertex, Mesh, Material handles
+- **NO platform imports allowed**
+
+#### **PhysicsEngine**
+- Sports-optimized physics simulation
+- Ball/puck physics with spin and drag
+- Player collision detection
+- Impulse-based collision resolution
+- **NO platform imports allowed**
+
+#### **AssetLoader**
+- 3D model loading (FBX, GLTF, OBJ)
+- Texture loading (DDS, PNG, JPG)
+- Skeletal animation data
+- Animation blending system
+- **NO platform imports allowed**
+
+### Platform-Specific Modules
+
+#### **PlatformLinux**
+- GLFW/SDL windowing (X11/Wayland)
+- Linux input handling
+- ALSA/PulseAudio audio
+
+#### **PlatformWin32**
+- Win32 API windowing
+- Raw Input / XInput
+- WASAPI/XAudio2 audio
+
+#### **VulkanRenderer**
+- Vulkan 1.3 rendering backend
+- Cross-platform (Linux + Windows)
+- Explicit GPU resource management
+
+#### **DX12Renderer**
+- DirectX 12 rendering backend
+- Windows-optimized path
+- Low-level GPU control
+
+## 🎮 Sports Game Optimizations
+
+This engine is specifically designed for professional sports games across multiple disciplines:
+
+### Character Rendering
+- High-fidelity player models with PBR materials
+- Skeletal animation with smooth blending
+- State machine-driven movement (running, shooting, tackling)
+- Facial animation support
+
+### Physics
+- Fast ball/puck simulation with spin
+- Player-to-player collision detection
+- Ball-to-player interaction physics
+- Field boundaries and out-of-bounds detection
+
+### Rendering
+- Large stadium/arena rendering with LOD
+- Crowd rendering and animation
+- Dynamic lighting for different times of day
+- Particle effects (grass, dust, sweat)
+
+### Performance
+- Fixed timestep physics (60 Hz)
+- Multithreaded asset streaming
+- GPU-driven rendering
+- Spatial culling and occlusion
+
+## 🚀 Building & Running
+
+### Prerequisites
+
+- **Swift 6.0+**
+- **Platform-specific dependencies:**
+  - Linux: Vulkan SDK, GLFW/SDL
+  - Windows: DirectX 12 SDK, GLFW/SDL or Win32 API
+
+### Build Commands
+
+```bash
+# Build the engine
+swift build
+
+# Build release version
+swift build -c release
+
+# Run the engine
+swift run
+
+# Run with options
+swift run SportsBallEngine -- --renderer vulkan --width 2560 --height 1440
+```
+
+### Command-Line Options
+
+```
+Usage: SportsBallEngine [OPTIONS]
+
+Options:
+  --renderer, -r <api>     Renderer API (vulkan, dx12) [Windows only]
+  --title, -t <title>      Window title
+  --width, -w <pixels>     Window width (default: 1920)
+  --height, -h <pixels>    Window height (default: 1080)
+  --help                   Show this help message
+
+Examples:
+  SportsBallEngine --renderer vulkan --width 2560 --height 1440
+  SportsBallEngine --title "My Sports Game"
+```
+
+## 🔧 Development
+
+### Adding New Platform Support
+
+1. Create new module: `Sources/Platform{Name}/`
+2. Implement protocols: `WindowManager`, `InputHandler`, `AudioEngine`
+3. Add to `PlatformFactory` in `main.swift`
+4. Update `Package.swift` dependencies
+
+### Adding New Renderer
+
+1. Create new module: `Sources/{API}Renderer/`
+2. Implement `Renderer` protocol from `RendererAPI`
+3. Add to `PlatformFactory.createRenderer()`
+4. Update `Package.swift` dependencies
+
+### Project Structure
+
+```
+SportsBallEngine_1/
+├── Package.swift              # Swift Package Manager manifest
+├── README.md                  # This file
+├── Sources/
+│   ├── SportsBallEngine/     # Main entry point
+│   │   └── main.swift
+│   ├── EngineCore/           # Platform-agnostic core
+│   │   └── Engine.swift
+│   ├── RendererAPI/          # Protocol definitions
+│   │   ├── RendererProtocol.swift
+│   │   ├── InputProtocol.swift
+│   │   ├── WindowProtocol.swift
+│   │   └── AudioProtocol.swift
+│   ├── PhysicsEngine/        # Physics simulation
+│   │   └── PhysicsWorld.swift
+│   ├── AssetLoader/          # Asset management
+│   │   └── AssetManager.swift
+│   ├── VulkanRenderer/       # Vulkan backend
+│   │   └── VulkanRenderer.swift
+│   ├── DX12Renderer/         # DirectX 12 backend
+│   │   └── DX12Renderer.swift
+│   ├── PlatformLinux/        # Linux platform layer
+│   │   └── LinuxPlatform.swift
+│   └── PlatformWin32/        # Windows platform layer
+│       └── Win32Platform.swift
+└── Tests/
+    └── EngineCoreTests/
+```
+
+## 🎯 Sports Game Features (Roadmap)
+
+### Phase 1: Core Engine ✅
+- [x] Platform abstraction layer
+- [x] Renderer protocols (Vulkan, DX12)
+- [x] Physics engine
+- [x] Asset loading system
+- [x] Main game loop
+
+### Phase 2: Sports-Specific Features
+- [ ] Skeletal animation system
+- [ ] Animation blending
+- [ ] State machines for player AI
+- [ ] Ball physics with spin
+- [ ] Stadium rendering
+- [ ] Crowd simulation
+
+### Phase 3: Advanced Features
+- [ ] Networking (multiplayer)
+- [ ] Replay system
+- [ ] Statistics tracking
+- [ ] Dynamic weather
+- [ ] Commentary system
+
+## 📝 License
+
+Copyright (c) 2025. All rights reserved.
+
+## 🙏 Acknowledgments
+
+- **Swift Community** - For excellent cross-platform support
+- **Open Source Contributors** - For graphics API bindings and tooling
+
+---
+
+**Note**: This is a foundational structure. Renderer implementations are currently stubs that demonstrate the architecture. Production use would require:
+- Actual Vulkan/DirectX 12 C bindings
+- Complete shader pipeline
+- Full asset format parsers
+- Advanced physics optimizations
+- Networking layer
+
+The architecture is production-ready; the implementations are educational scaffolding.
+

Sources/AssetLoader/AssetManager.swift

@@ -0,0 +1,464 @@
+/// AssetLoader - Asset management and loading system
+/// NO PLATFORM-SPECIFIC IMPORTS ALLOWED IN THIS MODULE
+/// Handles loading of 3D models, textures, animations, and audio files
+
+import Foundation
+
+// MARK: - Asset Types
+
+/// Asset loading result
+public enum AssetResult<T> {
+    case success(T)
+    case failure(AssetError)
+}
+
+/// Asset loading errors
+public enum AssetError: Error, LocalizedError {
+    case fileNotFound(String)
+    case invalidFormat(String)
+    case corruptedData(String)
+    case unsupportedVersion(String)
+    case outOfMemory
+    
+    public var errorDescription: String? {
+        switch self {
+        case .fileNotFound(let path):
+            return "Asset file not found: \(path)"
+        case .invalidFormat(let format):
+            return "Invalid asset format: \(format)"
+        case .corruptedData(let reason):
+            return "Corrupted asset data: \(reason)"
+        case .unsupportedVersion(let version):
+            return "Unsupported asset version: \(version)"
+        case .outOfMemory:
+            return "Out of memory while loading asset"
+        }
+    }
+}
+
+/// Asset handle for reference counting and management
+public struct AssetHandle<T>: Hashable, Sendable where T: Hashable {
+    public let id: UUID
+    public let path: String
+    
+    public init(id: UUID = UUID(), path: String) {
+        self.id = id
+        self.path = path
+    }
+    
+    public func hash(into hasher: inout Hasher) {
+        hasher.combine(id)
+    }
+}
+
+// MARK: - Mesh Data
+
+/// Mesh data structure (vertex and index buffers)
+public struct MeshData: Sendable, Hashable {
+    public var name: String
+    public var vertices: [MeshVertex]
+    public var indices: [UInt32]
+    public var bounds: BoundingBox
+    
+    public init(name: String, vertices: [MeshVertex], indices: [UInt32], bounds: BoundingBox) {
+        self.name = name
+        self.vertices = vertices
+        self.indices = indices
+        self.bounds = bounds
+    }
+    
+    public func hash(into hasher: inout Hasher) {
+        hasher.combine(name)
+    }
+}
+
+/// Vertex structure for mesh data
+public struct MeshVertex: Sendable, Hashable {
+    public var position: SIMD3<Float>
+    public var normal: SIMD3<Float>
+    public var uv: SIMD2<Float>
+    public var tangent: SIMD3<Float>
+    public var boneIndices: SIMD4<UInt8> // For skeletal animation
+    public var boneWeights: SIMD4<Float> // For skeletal animation
+    
+    public init(position: SIMD3<Float>, normal: SIMD3<Float>, uv: SIMD2<Float>,
+                tangent: SIMD3<Float> = .zero, boneIndices: SIMD4<UInt8> = .zero,
+                boneWeights: SIMD4<Float> = .zero) {
+        self.position = position
+        self.normal = normal
+        self.uv = uv
+        self.tangent = tangent
+        self.boneIndices = boneIndices
+        self.boneWeights = boneWeights
+    }
+}
+
+/// Bounding box for culling
+public struct BoundingBox: Sendable, Hashable {
+    public var min: SIMD3<Float>
+    public var max: SIMD3<Float>
+    
+    public init(min: SIMD3<Float>, max: SIMD3<Float>) {
+        self.min = min
+        self.max = max
+    }
+}
+
+// MARK: - Texture Data
+
+/// Texture data structure
+public struct TextureData: Sendable, Hashable {
+    public var name: String
+    public var width: Int
+    public var height: Int
+    public var format: TextureFormat
+    public var data: Data
+    public var mipLevels: Int
+    
+    public init(name: String, width: Int, height: Int, format: TextureFormat, data: Data, mipLevels: Int = 1) {
+        self.name = name
+        self.width = width
+        self.height = height
+        self.format = format
+        self.data = data
+        self.mipLevels = mipLevels
+    }
+    
+    public func hash(into hasher: inout Hasher) {
+        hasher.combine(name)
+    }
+}
+
+/// Texture format
+public enum TextureFormat: Sendable, Hashable {
+    case rgba8
+    case rgba16f
+    case rgba32f
+    case dxt1
+    case dxt5
+    case bc7
+}
+
+// MARK: - Animation Data
+
+/// Skeletal animation data
+public struct AnimationData: Sendable, Hashable {
+    public var name: String
+    public var duration: Float
+    public var ticksPerSecond: Float
+    public var channels: [AnimationChannel]
+    
+    public init(name: String, duration: Float, ticksPerSecond: Float, channels: [AnimationChannel]) {
+        self.name = name
+        self.duration = duration
+        self.ticksPerSecond = ticksPerSecond
+        self.channels = channels
+    }
+    
+    public func hash(into hasher: inout Hasher) {
+        hasher.combine(name)
+    }
+}
+
+/// Animation channel (per-bone)
+public struct AnimationChannel: Sendable, Hashable {
+    public var boneName: String
+    public var positionKeys: [KeyFrame<SIMD3<Float>>]
+    public var rotationKeys: [KeyFrame<SIMD4<Float>>]
+    public var scaleKeys: [KeyFrame<SIMD3<Float>>]
+    
+    public init(boneName: String, positionKeys: [KeyFrame<SIMD3<Float>>],
+                rotationKeys: [KeyFrame<SIMD4<Float>>], scaleKeys: [KeyFrame<SIMD3<Float>>]) {
+        self.boneName = boneName
+        self.positionKeys = positionKeys
+        self.rotationKeys = rotationKeys
+        self.scaleKeys = scaleKeys
+    }
+}
+
+/// Animation keyframe
+public struct KeyFrame<T: Sendable & Hashable>: Sendable, Hashable {
+    public var time: Float
+    public var value: T
+    
+    public init(time: Float, value: T) {
+        self.time = time
+        self.value = value
+    }
+}
+
+// MARK: - Skeleton Data
+
+/// Skeletal hierarchy for character animation
+public struct SkeletonData: Sendable, Hashable {
+    public var bones: [Bone]
+    public var rootBoneIndex: Int
+    
+    public init(bones: [Bone], rootBoneIndex: Int = 0) {
+        self.bones = bones
+        self.rootBoneIndex = rootBoneIndex
+    }
+}
+
+/// Individual bone in skeleton
+public struct Bone: Sendable, Hashable {
+    public var name: String
+    public var parentIndex: Int?
+    public var offsetMatrix: float4x4
+    
+    public init(name: String, parentIndex: Int?, offsetMatrix: float4x4) {
+        self.name = name
+        self.parentIndex = parentIndex
+        self.offsetMatrix = offsetMatrix
+    }
+}
+
+// MARK: - Asset Manager
+
+/// Main asset management system
+public actor AssetManager {
+    
+    private var meshCache: [String: MeshData] = [:]
+    private var textureCache: [String: TextureData] = [:]
+    private var animationCache: [String: AnimationData] = [:]
+    private var skeletonCache: [String: SkeletonData] = [:]
+    
+    private var loadedAssets: Set<String> = []
+    
+    public init() {}
+    
+    // MARK: - Lifecycle
+    
+    public func initialize() {
+        print("    ✓ Asset manager initialized")
+    }
+    
+    public func shutdown() {
+        meshCache.removeAll()
+        textureCache.removeAll()
+        animationCache.removeAll()
+        skeletonCache.removeAll()
+        loadedAssets.removeAll()
+        
+        print("    ✓ Asset manager shutdown (cleared caches)")
+    }
+    
+    // MARK: - Mesh Loading
+    
+    /// Load a 3D mesh from file
+    public func loadMesh(path: String) async -> AssetResult<MeshData> {
+        // Check cache first
+        if let cached = meshCache[path] {
+            return .success(cached)
+        }
+        
+        // Load from disk
+        guard let data = try? Data(contentsOf: URL(fileURLWithPath: path)) else {
+            return .failure(.fileNotFound(path))
+        }
+        
+        // Parse mesh format (OBJ, FBX, GLTF, etc.)
+        guard let mesh = parseMeshData(data: data, path: path) else {
+            return .failure(.invalidFormat(path))
+        }
+        
+        // Cache and return
+        meshCache[path] = mesh
+        loadedAssets.insert(path)
+        
+        return .success(mesh)
+    }
+    
+    private func parseMeshData(data: Data, path: String) -> MeshData? {
+        // Simplified placeholder - would parse actual formats
+        // For sports games: support FBX (player models), GLTF (stadiums), custom formats
+        
+        // Create a simple test mesh (placeholder)
+        return createTestMesh(name: path)
+    }
+    
+    private func createTestMesh(name: String) -> MeshData {
+        // Create a simple cube for testing
+        let vertices: [MeshVertex] = [
+            MeshVertex(position: SIMD3<Float>(-1, -1, -1), normal: SIMD3<Float>(0, 0, -1), uv: SIMD2<Float>(0, 0)),
+            MeshVertex(position: SIMD3<Float>(1, -1, -1), normal: SIMD3<Float>(0, 0, -1), uv: SIMD2<Float>(1, 0)),
+            MeshVertex(position: SIMD3<Float>(1, 1, -1), normal: SIMD3<Float>(0, 0, -1), uv: SIMD2<Float>(1, 1)),
+            MeshVertex(position: SIMD3<Float>(-1, 1, -1), normal: SIMD3<Float>(0, 0, -1), uv: SIMD2<Float>(0, 1)),
+        ]
+        
+        let indices: [UInt32] = [0, 1, 2, 0, 2, 3]
+        
+        let bounds = BoundingBox(
+            min: SIMD3<Float>(-1, -1, -1),
+            max: SIMD3<Float>(1, 1, 1)
+        )
+        
+        return MeshData(name: name, vertices: vertices, indices: indices, bounds: bounds)
+    }
+    
+    // MARK: - Texture Loading
+    
+    /// Load a texture from file
+    public func loadTexture(path: String) async -> AssetResult<TextureData> {
+        // Check cache first
+        if let cached = textureCache[path] {
+            return .success(cached)
+        }
+        
+        // Load from disk
+        guard let data = try? Data(contentsOf: URL(fileURLWithPath: path)) else {
+            return .failure(.fileNotFound(path))
+        }
+        
+        // Parse texture format (PNG, JPG, DDS, KTX, etc.)
+        guard let texture = parseTextureData(data: data, path: path) else {
+            return .failure(.invalidFormat(path))
+        }
+        
+        // Cache and return
+        textureCache[path] = texture
+        loadedAssets.insert(path)
+        
+        return .success(texture)
+    }
+    
+    private func parseTextureData(data: Data, path: String) -> TextureData? {
+        // Simplified placeholder - would use image decoding libraries
+        // For sports games: support DDS (compressed), PNG, JPG, HDR textures
+        
+        // Create a simple test texture
+        return createTestTexture(name: path)
+    }
+    
+    private func createTestTexture(name: String) -> TextureData {
+        // Create a 2x2 test texture (white)
+        let width = 2
+        let height = 2
+        var data = Data(count: width * height * 4)
+        for i in 0..<(width * height * 4) {
+            data[i] = 255
+        }
+        
+        return TextureData(name: name, width: width, height: height, format: .rgba8, data: data)
+    }
+    
+    // MARK: - Animation Loading
+    
+    /// Load skeletal animation from file
+    public func loadAnimation(path: String) async -> AssetResult<AnimationData> {
+        // Check cache first
+        if let cached = animationCache[path] {
+            return .success(cached)
+        }
+        
+        // Load from disk
+        guard let data = try? Data(contentsOf: URL(fileURLWithPath: path)) else {
+            return .failure(.fileNotFound(path))
+        }
+        
+        // Parse animation format
+        guard let animation = parseAnimationData(data: data, path: path) else {
+            return .failure(.invalidFormat(path))
+        }
+        
+        // Cache and return
+        animationCache[path] = animation
+        loadedAssets.insert(path)
+        
+        return .success(animation)
+    }
+    
+    private func parseAnimationData(data: Data, path: String) -> AnimationData? {
+        // Simplified placeholder - would parse FBX/GLTF animations
+        // For sports games: running, shooting, passing, tackling animations
+        return createTestAnimation(name: path)
+    }
+    
+    private func createTestAnimation(name: String) -> AnimationData {
+        // Create a simple test animation
+        let channel = AnimationChannel(
+            boneName: "Root",
+            positionKeys: [
+                KeyFrame(time: 0.0, value: SIMD3<Float>(0, 0, 0)),
+                KeyFrame(time: 1.0, value: SIMD3<Float>(1, 0, 0))
+            ],
+            rotationKeys: [
+                KeyFrame(time: 0.0, value: SIMD4<Float>(0, 0, 0, 1)),
+                KeyFrame(time: 1.0, value: SIMD4<Float>(0, 0, 0, 1))
+            ],
+            scaleKeys: [
+                KeyFrame(time: 0.0, value: SIMD3<Float>(1, 1, 1)),
+                KeyFrame(time: 1.0, value: SIMD3<Float>(1, 1, 1))
+            ]
+        )
+        
+        return AnimationData(name: name, duration: 1.0, ticksPerSecond: 30.0, channels: [channel])
+    }
+    
+    // MARK: - Skeleton Loading
+    
+    /// Load skeletal hierarchy from file
+    public func loadSkeleton(path: String) async -> AssetResult<SkeletonData> {
+        // Check cache first
+        if let cached = skeletonCache[path] {
+            return .success(cached)
+        }
+        
+        // Load from disk
+        guard let data = try? Data(contentsOf: URL(fileURLWithPath: path)) else {
+            return .failure(.fileNotFound(path))
+        }
+        
+        // Parse skeleton format
+        guard let skeleton = parseSkeletonData(data: data, path: path) else {
+            return .failure(.invalidFormat(path))
+        }
+        
+        // Cache and return
+        skeletonCache[path] = skeleton
+        loadedAssets.insert(path)
+        
+        return .success(skeleton)
+    }
+    
+    private func parseSkeletonData(data: Data, path: String) -> SkeletonData? {
+        // Simplified placeholder
+        return createTestSkeleton()
+    }
+    
+    private func createTestSkeleton() -> SkeletonData {
+        let rootBone = Bone(name: "Root", parentIndex: nil, offsetMatrix: matrix_identity_float4x4)
+        return SkeletonData(bones: [rootBone], rootBoneIndex: 0)
+    }
+    
+    // MARK: - Cache Management
+    
+    public func unloadAsset(path: String) {
+        meshCache.removeValue(forKey: path)
+        textureCache.removeValue(forKey: path)
+        animationCache.removeValue(forKey: path)
+        skeletonCache.removeValue(forKey: path)
+        loadedAssets.remove(path)
+    }
+    
+    public func clearCache() {
+        meshCache.removeAll()
+        textureCache.removeAll()
+        animationCache.removeAll()
+        skeletonCache.removeAll()
+        loadedAssets.removeAll()
+    }
+    
+    public func getCacheSize() -> (meshes: Int, textures: Int, animations: Int, skeletons: Int) {
+        return (meshCache.count, textureCache.count, animationCache.count, skeletonCache.count)
+    }
+}
+
+// MARK: - Matrix Helper
+
+extension float4x4 {
+    static var identity: float4x4 {
+        return matrix_identity_float4x4
+    }
+}
+

Sources/DX12Renderer/DX12Renderer.swift

@@ -0,0 +1,370 @@
+/// DX12Renderer - DirectX 12 rendering backend implementation
+/// This is a PLATFORM-SPECIFIC module (DirectX 12 API on Windows)
+
+import Foundation
+import RendererAPI
+
+#if os(Windows)
+// Note: In a real implementation, this would import DirectX 12 C bindings
+// import CDirectX12 or similar Swift DirectX wrapper
+#endif
+
+/// DirectX 12-based renderer implementation
+public final class DX12Renderer: Renderer, @unchecked Sendable {
+    
+    private var config: RendererConfig?
+    private var isInitialized: Bool = false
+    
+    // DirectX 12 handles (placeholders - would be actual D3D12 types)
+    private var device: UnsafeMutableRawPointer?
+    private var commandQueue: UnsafeMutableRawPointer?
+    private var swapChain: UnsafeMutableRawPointer?
+    private var rtvHeap: UnsafeMutableRawPointer? // Render Target View heap
+    private var dsvHeap: UnsafeMutableRawPointer? // Depth Stencil View heap
+    private var commandAllocator: UnsafeMutableRawPointer?
+    private var commandList: UnsafeMutableRawPointer?
+    private var pipelineState: UnsafeMutableRawPointer?
+    private var rootSignature: UnsafeMutableRawPointer?
+    
+    // Synchronization
+    private var fence: UnsafeMutableRawPointer?
+    private var fenceValue: UInt64 = 0
+    private var fenceEvent: UnsafeMutableRawPointer?
+    
+    // Resource storage
+    private var meshes: [MeshHandle: DX12Mesh] = [:]
+    private var textures: [TextureHandle: DX12Texture] = [:]
+    private var materials: [MaterialHandle: DX12Material] = [:]
+    
+    private var currentFrameIndex: UInt32 = 0
+    private let maxFramesInFlight: UInt32 = 2
+    
+    public init() {
+        print("    🪟 DX12Renderer created")
+    }
+    
+    // MARK: - Renderer Protocol Implementation
+    
+    public func initialize(config: RendererConfig) async throws {
+        print("    → Initializing DirectX 12 renderer...")
+        self.config = config
+        
+        #if os(Windows)
+        // 1. Enable debug layer in debug builds
+        try enableDebugLayer()
+        
+        // 2. Create DXGI Factory
+        try createFactory()
+        
+        // 3. Create D3D12 Device
+        try createDevice()
+        
+        // 4. Create Command Queue
+        try createCommandQueue()
+        
+        // 5. Create Swap Chain
+        try createSwapChain(windowHandle: config.windowHandle, width: config.width, height: config.height)
+        
+        // 6. Create Descriptor Heaps
+        try createDescriptorHeaps()
+        
+        // 7. Create Render Target Views
+        try createRenderTargets()
+        
+        // 8. Create Command Allocator and List
+        try createCommandAllocatorAndList()
+        
+        // 9. Create Root Signature
+        try createRootSignature()
+        
+        // 10. Create Pipeline State Object (PSO)
+        try createPipelineState()
+        
+        // 11. Create Fence for synchronization
+        try createFence()
+        #else
+        throw RendererError.unsupportedPlatform("DirectX 12 is only available on Windows")
+        #endif
+        
+        isInitialized = true
+        print("    ✓ DirectX 12 renderer initialized")
+    }
+    
+    public func beginFrame() throws {
+        guard isInitialized else { throw RendererError.notInitialized }
+        
+        #if os(Windows)
+        // Wait for previous frame
+        // Reset command allocator
+        // Reset command list
+        // Set render target
+        // Clear render target and depth buffer
+        #endif
+    }
+    
+    public func draw(scene: Scene) throws {
+        guard isInitialized else { throw RendererError.notInitialized }
+        
+        #if os(Windows)
+        // Set root signature
+        // Set pipeline state
+        // Set viewport and scissor rect
+        
+        // Draw each entity
+        for entity in scene.entities {
+            // Set root parameters (CBV/SRV/UAV)
+            // Set vertex and index buffers
+            // Draw indexed
+            drawEntity(entity, camera: scene.camera)
+        }
+        #endif
+    }
+    
+    public func endFrame() throws {
+        guard isInitialized else { throw RendererError.notInitialized }
+        
+        #if os(Windows)
+        // Transition render target to present state
+        // Close command list
+        // Execute command list on queue
+        // Present swap chain
+        // Signal fence
+        
+        currentFrameIndex = (currentFrameIndex + 1) % maxFramesInFlight
+        #endif
+    }
+    
+    public func shutdown() async {
+        print("    → Shutting down DirectX 12 renderer...")
+        
+        #if os(Windows)
+        // Wait for GPU to finish
+        // Destroy all resources in reverse order
+        destroyFence()
+        destroyPipelineState()
+        destroyRootSignature()
+        destroyCommandResources()
+        destroyRenderTargets()
+        destroyDescriptorHeaps()
+        destroySwapChain()
+        destroyCommandQueue()
+        destroyDevice()
+        #endif
+        
+        isInitialized = false
+        print("    ✓ DirectX 12 renderer shutdown complete")
+    }
+    
+    public func loadMesh(vertices: [Vertex], indices: [UInt32]) async throws -> MeshHandle {
+        let handle = MeshHandle()
+        
+        #if os(Windows)
+        // Create D3D12 vertex buffer (committed resource)
+        // Create D3D12 index buffer (committed resource)
+        // Upload data to GPU using upload heap
+        #endif
+        
+        let dx12Mesh = DX12Mesh(
+            vertexBuffer: nil,
+            indexBuffer: nil,
+            vertexBufferView: nil,
+            indexBufferView: nil,
+            indexCount: UInt32(indices.count)
+        )
+        
+        meshes[handle] = dx12Mesh
+        return handle
+    }
+    
+    public func loadTexture(data: Data, width: Int, height: Int, format: TextureFormat) async throws -> TextureHandle {
+        let handle = TextureHandle()
+        
+        #if os(Windows)
+        // Create D3D12 texture resource
+        // Create Shader Resource View (SRV)
+        // Upload texture data via upload heap
+        #endif
+        
+        let dx12Texture = DX12Texture(
+            resource: nil,
+            srvHeapIndex: 0,
+            width: width,
+            height: height
+        )
+        
+        textures[handle] = dx12Texture
+        return handle
+    }
+    
+    public func createMaterial(albedoTexture: TextureHandle?, normalTexture: TextureHandle?) async throws -> MaterialHandle {
+        let handle = MaterialHandle()
+        
+        #if os(Windows)
+        // Create material constant buffer
+        // Set up descriptor table for textures
+        #endif
+        
+        let dx12Material = DX12Material(
+            constantBuffer: nil,
+            albedoTexture: albedoTexture,
+            normalTexture: normalTexture
+        )
+        
+        materials[handle] = dx12Material
+        return handle
+    }
+    
+    public var info: RendererInfo {
+        return RendererInfo(
+            apiName: "DirectX 12",
+            apiVersion: "12.0",
+            deviceName: "D3D12 Device (placeholder)",
+            maxTextureSize: 16384
+        )
+    }
+    
+    // MARK: - DirectX 12-Specific Implementation
+    
+    #if os(Windows)
+    
+    private func enableDebugLayer() throws {
+        print("      • Enabling D3D12 debug layer...")
+        // ID3D12Debug::EnableDebugLayer()
+    }
+    
+    private func createFactory() throws {
+        print("      • Creating DXGI factory...")
+        // CreateDXGIFactory2(...)
+    }
+    
+    private func createDevice() throws {
+        print("      • Creating D3D12 device...")
+        // D3D12CreateDevice(...) with hardware adapter
+    }
+    
+    private func createCommandQueue() throws {
+        print("      • Creating command queue...")
+        // ID3D12Device::CreateCommandQueue(D3D12_COMMAND_LIST_TYPE_DIRECT)
+    }
+    
+    private func createSwapChain(windowHandle: UnsafeMutableRawPointer?, width: Int, height: Int) throws {
+        print("      • Creating swap chain (\(width)x\(height))...")
+        // IDXGIFactory::CreateSwapChainForHwnd(...)
+    }
+    
+    private func createDescriptorHeaps() throws {
+        print("      • Creating descriptor heaps...")
+        // ID3D12Device::CreateDescriptorHeap for RTV, DSV, CBV/SRV/UAV
+    }
+    
+    private func createRenderTargets() throws {
+        print("      • Creating render target views...")
+        // ID3D12Device::CreateRenderTargetView for each swap chain buffer
+    }
+    
+    private func createCommandAllocatorAndList() throws {
+        print("      • Creating command allocator and list...")
+        // ID3D12Device::CreateCommandAllocator
+        // ID3D12Device::CreateCommandList
+    }
+    
+    private func createRootSignature() throws {
+        print("      • Creating root signature...")
+        // ID3D12Device::CreateRootSignature with CBVs, SRVs, samplers
+    }
+    
+    private func createPipelineState() throws {
+        print("      • Creating pipeline state...")
+        // Compile HLSL shaders
+        // ID3D12Device::CreateGraphicsPipelineState with shaders and state
+    }
+    
+    private func createFence() throws {
+        print("      • Creating fence...")
+        // ID3D12Device::CreateFence
+        // CreateEventEx for CPU-side waiting
+    }
+    
+    private func drawEntity(_ entity: Entity, camera: Camera) {
+        // ID3D12GraphicsCommandList::SetGraphicsRootConstantBufferView (MVP matrix)
+        // ID3D12GraphicsCommandList::SetGraphicsRootDescriptorTable (textures)
+        // ID3D12GraphicsCommandList::IASetVertexBuffers
+        // ID3D12GraphicsCommandList::IASetIndexBuffer
+        // ID3D12GraphicsCommandList::DrawIndexedInstanced
+    }
+    
+    // MARK: - Cleanup
+    
+    private func destroyFence() {
+        // CloseHandle(fenceEvent)
+        // fence->Release()
+    }
+    
+    private func destroyPipelineState() {
+        // pipelineState->Release()
+    }
+    
+    private func destroyRootSignature() {
+        // rootSignature->Release()
+    }
+    
+    private func destroyCommandResources() {
+        // commandList->Release()
+        // commandAllocator->Release()
+    }
+    
+    private func destroyRenderTargets() {
+        // Release all RTV resources
+    }
+    
+    private func destroyDescriptorHeaps() {
+        // rtvHeap->Release()
+        // dsvHeap->Release()
+    }
+    
+    private func destroySwapChain() {
+        // swapChain->Release()
+    }
+    
+    private func destroyCommandQueue() {
+        // commandQueue->Release()
+    }
+    
+    private func destroyDevice() {
+        // device->Release()
+    }
+    
+    #endif
+}
+
+// MARK: - DirectX 12 Resource Types
+
+private struct DX12Mesh {
+    var vertexBuffer: UnsafeMutableRawPointer?
+    var indexBuffer: UnsafeMutableRawPointer?
+    var vertexBufferView: UnsafeMutableRawPointer?
+    var indexBufferView: UnsafeMutableRawPointer?
+    var indexCount: UInt32
+}
+
+private struct DX12Texture {
+    var resource: UnsafeMutableRawPointer?
+    var srvHeapIndex: Int
+    var width: Int
+    var height: Int
+}
+
+private struct DX12Material {
+    var constantBuffer: UnsafeMutableRawPointer?
+    var albedoTexture: TextureHandle?
+    var normalTexture: TextureHandle?
+}
+
+// MARK: - Errors
+
+private enum RendererError: Error {
+    case notInitialized
+    case unsupportedPlatform(String)
+    case dx12Error(String)
+}
+

Sources/EngineCore/Engine.swift

@@ -0,0 +1,334 @@
+/// EngineCore - Platform-agnostic game engine core
+/// NO PLATFORM-SPECIFIC IMPORTS ALLOWED IN THIS MODULE
+
+import Foundation
+import RendererAPI
+import PhysicsEngine
+import AssetLoader
+
+// MARK: - Engine Configuration
+
+/// Configuration for the game engine
+public struct EngineConfig: Sendable {
+    public var targetFrameRate: Int
+    public var fixedTimeStep: Double
+    public var maxFrameSkip: Int
+    
+    public init(targetFrameRate: Int = 60, fixedTimeStep: Double = 1.0/60.0, maxFrameSkip: Int = 5) {
+        self.targetFrameRate = targetFrameRate
+        self.fixedTimeStep = fixedTimeStep
+        self.maxFrameSkip = maxFrameSkip
+    }
+}
+
+// MARK: - Game Engine
+
+/// Main game engine class - coordinates all subsystems
+public actor GameEngine {
+    
+    // Platform abstraction layers (injected by platform-specific code)
+    private let renderer: any Renderer
+    private let windowManager: any WindowManager
+    private let inputHandler: any InputHandler
+    private let audioEngine: any AudioEngine
+    
+    // Core systems
+    private let physicsEngine: PhysicsWorld
+    private let assetLoader: AssetManager
+    
+    // Engine state
+    private var isRunning: Bool = false
+    private var config: EngineConfig
+    
+    // Scene management
+    private var currentScene: Scene
+    
+    // Timing
+    private var lastFrameTime: Double = 0
+    private var accumulator: Double = 0
+    private var frameCount: UInt64 = 0
+    
+    // MARK: - Initialization
+    
+    /// Initialize the engine with platform-specific abstractions
+    public init(
+        renderer: any Renderer,
+        windowManager: any WindowManager,
+        inputHandler: any InputHandler,
+        audioEngine: any AudioEngine,
+        config: EngineConfig = EngineConfig()
+    ) {
+        self.renderer = renderer
+        self.windowManager = windowManager
+        self.inputHandler = inputHandler
+        self.audioEngine = audioEngine
+        self.config = config
+        
+        // Initialize core systems (platform-agnostic)
+        self.physicsEngine = PhysicsWorld()
+        self.assetLoader = AssetManager()
+        
+        // Create default scene
+        self.currentScene = Scene(
+            entities: [],
+            camera: Camera(),
+            lights: []
+        )
+        
+        print("🎮 SportsBallEngine initialized")
+    }
+    
+    // MARK: - Engine Lifecycle
+    
+    /// Start the engine and run the main loop
+    public func start() async throws {
+        print("🚀 Starting engine...")
+        
+        // Initialize all systems
+        try await initializeSystems()
+        
+        // Load initial scene/assets
+        try await loadInitialScene()
+        
+        // Start the main loop
+        isRunning = true
+        lastFrameTime = getCurrentTime()
+        
+        print("✅ Engine started successfully")
+        
+        // Run the game loop
+        await runMainLoop()
+    }
+    
+    /// Stop the engine and cleanup
+    public func stop() async {
+        print("🛑 Stopping engine...")
+        isRunning = false
+        
+        await shutdownSystems()
+        
+        print("✅ Engine stopped")
+    }
+    
+    // MARK: - System Initialization
+    
+    private func initializeSystems() async throws {
+        print("  → Initializing renderer...")
+        let windowSize = windowManager.getSize()
+        let rendererConfig = RendererConfig(
+            windowHandle: windowManager.getNativeHandle(),
+            width: windowSize.width,
+            height: windowSize.height,
+            vsyncEnabled: true,
+            msaaSamples: 4
+        )
+        try await renderer.initialize(config: rendererConfig)
+        print("    ✓ Renderer: \(renderer.info.apiName) \(renderer.info.apiVersion)")
+        print("    ✓ Device: \(renderer.info.deviceName)")
+        
+        print("  → Initializing input system...")
+        try await inputHandler.initialize()
+        
+        print("  → Initializing audio system...")
+        try await audioEngine.initialize(config: AudioConfig())
+        
+        print("  → Initializing physics engine...")
+        await physicsEngine.initialize()
+        
+        print("  → Initializing asset loader...")
+        await assetLoader.initialize()
+    }
+    
+    private func shutdownSystems() async {
+        await renderer.shutdown()
+        await inputHandler.shutdown()
+        await audioEngine.shutdown()
+        await physicsEngine.shutdown()
+        await assetLoader.shutdown()
+    }
+    
+    // MARK: - Main Game Loop (Carmack-style fixed timestep)
+    
+    private func runMainLoop() async {
+        while isRunning {
+            let currentTime = getCurrentTime()
+            let frameTime = currentTime - lastFrameTime
+            lastFrameTime = currentTime
+            
+            // Cap frame time to prevent spiral of death
+            let clampedFrameTime = min(frameTime, config.fixedTimeStep * Double(config.maxFrameSkip))
+            accumulator += clampedFrameTime
+            
+            // Process window events
+            let windowEvents = windowManager.processEvents()
+            for event in windowEvents {
+                handleWindowEvent(event)
+            }
+            
+            // Check if window should close
+            if windowManager.shouldClose() {
+                isRunning = false
+                break
+            }
+            
+            // Process input events
+            let inputEvents = inputHandler.pollEvents()
+            handleInputEvents(inputEvents)
+            
+            // Fixed timestep update loop (deterministic physics/gameplay)
+            while accumulator >= config.fixedTimeStep {
+                try? await fixedUpdate(deltaTime: Float(config.fixedTimeStep))
+                accumulator -= config.fixedTimeStep
+            }
+            
+            // Variable timestep render
+            let alpha = Float(accumulator / config.fixedTimeStep)
+            try? await render(interpolationAlpha: alpha)
+            
+            frameCount += 1
+        }
+    }
+    
+    // MARK: - Update & Render
+    
+    /// Fixed timestep update for physics and gameplay logic
+    private func fixedUpdate(deltaTime: Float) async throws {
+        // Update physics simulation
+        await physicsEngine.step(deltaTime: deltaTime)
+        
+        // Update audio engine
+        try audioEngine.update(deltaTime: deltaTime)
+        
+        // Update game logic (this would call game-specific code)
+        updateGameLogic(deltaTime: deltaTime)
+        
+        // Sync physics state to scene entities
+        syncPhysicsToScene()
+    }
+    
+    /// Render the current frame
+    private func render(interpolationAlpha: Float) async throws {
+        try renderer.beginFrame()
+        
+        // Interpolate entity positions for smooth rendering
+        let interpolatedScene = interpolateScene(currentScene, alpha: interpolationAlpha)
+        
+        // Draw the scene
+        try renderer.draw(scene: interpolatedScene)
+        
+        try renderer.endFrame()
+        try windowManager.swapBuffers()
+    }
+    
+    // MARK: - Scene Management
+    
+    private func loadInitialScene() async throws {
+        print("  → Loading initial scene...")
+        
+        // Create a simple test scene (stadium environment)
+        let stadium = try await createStadiumScene()
+        currentScene = stadium
+        
+        print("    ✓ Scene loaded: \(currentScene.entities.count) entities")
+    }
+    
+    private func createStadiumScene() async throws -> Scene {
+        // This would load actual assets, for now create a placeholder
+        let camera = Camera(
+            position: SIMD3<Float>(0, 10, 20),
+            rotation: SIMD4<Float>(0, 0, 0, 1),
+            fieldOfView: 60.0
+        )
+        
+        let sunLight = Light(
+            type: .directional,
+            direction: SIMD3<Float>(-0.3, -1, -0.3),
+            color: SIMD3<Float>(1, 0.95, 0.8),
+            intensity: 1.0
+        )
+        
+        return Scene(
+            entities: [],
+            camera: camera,
+            lights: [sunLight]
+        )
+    }
+    
+    // MARK: - Event Handling
+    
+    private func handleWindowEvent(_ event: WindowEvent) {
+        switch event {
+        case .close:
+            isRunning = false
+        case .resize(let width, let height):
+            print("  ↔ Window resized: \(width)x\(height)")
+            // Notify renderer of resize
+        case .focus(let focused):
+            print("  👁 Window focus changed: \(focused)")
+        case .minimize:
+            print("  ⬇ Window minimized")
+        case .maximize:
+            print("  ⬆ Window maximized")
+        case .restore:
+            print("  ↕ Window restored")
+        }
+    }
+    
+    private func handleInputEvents(_ events: [InputEvent]) {
+        for event in events {
+            switch event {
+            case .keyEvent(let key, let action):
+                if key == .escape && action == .press {
+                    isRunning = false
+                }
+            default:
+                break
+            }
+        }
+    }
+    
+    // MARK: - Game Logic
+    
+    private func updateGameLogic(deltaTime: Float) {
+        // This is where sports game logic would go:
+        // - Player AI
+        // - Ball physics
+        // - Animation state machines
+        // - Collision detection
+        // - Score tracking
+        // etc.
+    }
+    
+    private func syncPhysicsToScene() {
+        // Sync physics simulation results back to scene entities
+        // This would update entity transforms based on physics bodies
+    }
+    
+    private func interpolateScene(_ scene: Scene, alpha: Float) -> Scene {
+        // Interpolate between previous and current physics state for smooth rendering
+        // For now, just return the scene as-is
+        return scene
+    }
+    
+    // MARK: - Public API
+    
+    public func loadScene(_ scene: Scene) {
+        currentScene = scene
+    }
+    
+    public func getFrameCount() -> UInt64 {
+        return frameCount
+    }
+    
+    public func getFPS() -> Double {
+        // Calculate FPS based on frame timing
+        return 60.0 // Placeholder
+    }
+    
+    // MARK: - Utilities
+    
+    private func getCurrentTime() -> Double {
+        return Double(DispatchTime.now().uptimeNanoseconds) / 1_000_000_000.0
+    }
+}
+

Sources/PhysicsEngine/PhysicsWorld.swift

@@ -0,0 +1,317 @@
+/// PhysicsEngine - Sports-optimized physics simulation
+/// NO PLATFORM-SPECIFIC IMPORTS ALLOWED IN THIS MODULE
+
+import Foundation
+
+// MARK: - Physics Types
+
+/// A physics body in the simulation
+public struct PhysicsBody: Sendable {
+    public var id: UUID
+    public var position: SIMD3<Float>
+    public var velocity: SIMD3<Float>
+    public var acceleration: SIMD3<Float>
+    public var mass: Float
+    public var restitution: Float // Bounciness (0-1)
+    public var friction: Float
+    public var isStatic: Bool
+    
+    public init(id: UUID = UUID(), position: SIMD3<Float> = .zero, velocity: SIMD3<Float> = .zero,
+                mass: Float = 1.0, restitution: Float = 0.5, friction: Float = 0.5, isStatic: Bool = false) {
+        self.id = id
+        self.position = position
+        self.velocity = velocity
+        self.acceleration = .zero
+        self.mass = mass
+        self.restitution = restitution
+        self.friction = friction
+        self.isStatic = isStatic
+    }
+}
+
+/// Collision shapes
+public enum CollisionShape: Sendable {
+    case sphere(radius: Float)
+    case box(halfExtents: SIMD3<Float>)
+    case capsule(radius: Float, height: Float)
+    case mesh(vertices: [SIMD3<Float>], indices: [UInt32])
+}
+
+/// Collision data
+public struct Collision: Sendable {
+    public var bodyA: UUID
+    public var bodyB: UUID
+    public var contactPoint: SIMD3<Float>
+    public var normal: SIMD3<Float>
+    public var penetrationDepth: Float
+    
+    public init(bodyA: UUID, bodyB: UUID, contactPoint: SIMD3<Float>, 
+                normal: SIMD3<Float>, penetrationDepth: Float) {
+        self.bodyA = bodyA
+        self.bodyB = bodyB
+        self.contactPoint = contactPoint
+        self.normal = normal
+        self.penetrationDepth = penetrationDepth
+    }
+}
+
+// MARK: - Physics World
+
+/// Main physics simulation world - optimized for sports game scenarios
+public actor PhysicsWorld {
+    private var bodies: [UUID: PhysicsBody] = [:]
+    private var shapes: [UUID: CollisionShape] = [:]
+    private var gravity: SIMD3<Float> = SIMD3<Float>(0, -9.81, 0)
+    private var collisions: [Collision] = []
+    
+    // Sports-specific optimizations
+    private var ballBodies: Set<UUID> = [] // Track ball/puck for special handling
+    private var playerBodies: Set<UUID> = [] // Track player bodies
+    
+    public init() {}
+    
+    // MARK: - Lifecycle
+    
+    public func initialize() {
+        print("    ✓ Physics engine initialized (gravity: \(gravity))")
+    }
+    
+    public func shutdown() {
+        bodies.removeAll()
+        shapes.removeAll()
+        collisions.removeAll()
+    }
+    
+    // MARK: - Body Management
+    
+    public func addBody(_ body: PhysicsBody, shape: CollisionShape, isBall: Bool = false, isPlayer: Bool = false) {
+        bodies[body.id] = body
+        shapes[body.id] = shape
+        
+        if isBall {
+            ballBodies.insert(body.id)
+        }
+        if isPlayer {
+            playerBodies.insert(body.id)
+        }
+    }
+    
+    public func removeBody(_ id: UUID) {
+        bodies.removeValue(forKey: id)
+        shapes.removeValue(forKey: id)
+        ballBodies.remove(id)
+        playerBodies.remove(id)
+    }
+    
+    public func getBody(_ id: UUID) -> PhysicsBody? {
+        return bodies[id]
+    }
+    
+    public func updateBody(_ id: UUID, transform: (inout PhysicsBody) -> Void) {
+        guard var body = bodies[id] else { return }
+        transform(&body)
+        bodies[id] = body
+    }
+    
+    // MARK: - Simulation
+    
+    /// Step the physics simulation forward by deltaTime
+    public func step(deltaTime: Float) {
+        // Apply forces
+        applyForces(deltaTime: deltaTime)
+        
+        // Integrate velocities
+        integrateVelocities(deltaTime: deltaTime)
+        
+        // Detect collisions
+        detectCollisions()
+        
+        // Resolve collisions
+        resolveCollisions()
+        
+        // Integrate positions
+        integratePositions(deltaTime: deltaTime)
+        
+        // Apply sports-specific constraints (e.g., keep ball in bounds)
+        applySportsConstraints()
+    }
+    
+    private func applyForces(deltaTime: Float) {
+        for (id, var body) in bodies {
+            guard !body.isStatic else { continue }
+            
+            // Apply gravity
+            body.acceleration = gravity
+            
+            // Apply custom forces (wind, drag, etc.)
+            // For sports games: apply spin to balls, player momentum, etc.
+            if ballBodies.contains(id) {
+                // Apply air drag to ball
+                let dragCoefficient: Float = 0.1
+                let drag = -body.velocity * dragCoefficient
+                body.acceleration += drag / body.mass
+            }
+            
+            bodies[id] = body
+        }
+    }
+    
+    private func integrateVelocities(deltaTime: Float) {
+        for (id, var body) in bodies {
+            guard !body.isStatic else { continue }
+            
+            // Semi-implicit Euler integration
+            body.velocity += body.acceleration * deltaTime
+            
+            bodies[id] = body
+        }
+    }
+    
+    private func integratePositions(deltaTime: Float) {
+        for (id, var body) in bodies {
+            guard !body.isStatic else { continue }
+            
+            body.position += body.velocity * deltaTime
+            
+            bodies[id] = body
+        }
+    }
+    
+    private func detectCollisions() {
+        collisions.removeAll()
+        
+        let bodyArray = Array(bodies.values)
+        
+        // Broad phase - simple N^2 check (would use spatial partitioning in production)
+        for i in 0..<bodyArray.count {
+            for j in (i+1)..<bodyArray.count {
+                let bodyA = bodyArray[i]
+                let bodyB = bodyArray[j]
+                
+                // Skip if both are static
+                if bodyA.isStatic && bodyB.isStatic { continue }
+                
+                // Narrow phase collision detection
+                if let collision = checkCollision(bodyA: bodyA, bodyB: bodyB) {
+                    collisions.append(collision)
+                }
+            }
+        }
+    }
+    
+    private func checkCollision(bodyA: PhysicsBody, bodyB: PhysicsBody) -> Collision? {
+        guard let shapeA = shapes[bodyA.id], let shapeB = shapes[bodyB.id] else {
+            return nil
+        }
+        
+        // Simplified collision detection (sphere-sphere for now)
+        switch (shapeA, shapeB) {
+        case (.sphere(let radiusA), .sphere(let radiusB)):
+            return checkSphereSphere(bodyA: bodyA, radiusA: radiusA, bodyB: bodyB, radiusB: radiusB)
+        default:
+            return nil // Other collision shapes not implemented yet
+        }
+    }
+    
+    private func checkSphereSphere(bodyA: PhysicsBody, radiusA: Float, 
+                                   bodyB: PhysicsBody, radiusB: Float) -> Collision? {
+        let delta = bodyB.position - bodyA.position
+        let distanceSquared = simd_length_squared(delta)
+        let radiusSum = radiusA + radiusB
+        
+        if distanceSquared < radiusSum * radiusSum {
+            let distance = sqrt(distanceSquared)
+            let normal = distance > 0.001 ? delta / distance : SIMD3<Float>(0, 1, 0)
+            let penetration = radiusSum - distance
+            let contactPoint = bodyA.position + normal * radiusA
+            
+            return Collision(
+                bodyA: bodyA.id,
+                bodyB: bodyB.id,
+                contactPoint: contactPoint,
+                normal: normal,
+                penetrationDepth: penetration
+            )
+        }
+        
+        return nil
+    }
+    
+    private func resolveCollisions() {
+        for collision in collisions {
+            guard var bodyA = bodies[collision.bodyA],
+                  var bodyB = bodies[collision.bodyB] else {
+                continue
+            }
+            
+            // Position correction (separate bodies)
+            let correctionPercent: Float = 0.8
+            let correction = collision.normal * collision.penetrationDepth * correctionPercent
+            
+            if !bodyA.isStatic && !bodyB.isStatic {
+                let totalMass = bodyA.mass + bodyB.mass
+                bodyA.position -= correction * (bodyB.mass / totalMass)
+                bodyB.position += correction * (bodyA.mass / totalMass)
+            } else if !bodyA.isStatic {
+                bodyA.position -= correction
+            } else if !bodyB.isStatic {
+                bodyB.position += correction
+            }
+            
+            // Velocity resolution (impulse-based)
+            let relativeVelocity = bodyB.velocity - bodyA.velocity
+            let velocityAlongNormal = simd_dot(relativeVelocity, collision.normal)
+            
+            // Don't resolve if bodies are separating
+            if velocityAlongNormal > 0 {
+                continue
+            }
+            
+            // Calculate restitution (bounciness)
+            let restitution = min(bodyA.restitution, bodyB.restitution)
+            
+            // Calculate impulse scalar
+            let j = -(1 + restitution) * velocityAlongNormal
+            let impulseScalar = bodyA.isStatic ? j / bodyB.mass :
+                               bodyB.isStatic ? j / bodyA.mass :
+                               j / (1/bodyA.mass + 1/bodyB.mass)
+            
+            // Apply impulse
+            let impulse = collision.normal * impulseScalar
+            
+            if !bodyA.isStatic {
+                bodyA.velocity -= impulse / bodyA.mass
+            }
+            if !bodyB.isStatic {
+                bodyB.velocity += impulse / bodyB.mass
+            }
+            
+            bodies[collision.bodyA] = bodyA
+            bodies[collision.bodyB] = bodyB
+        }
+    }
+    
+    private func applySportsConstraints() {
+        // Keep ball in play bounds, apply field friction, etc.
+        // This would contain sports-specific rules
+    }
+    
+    // MARK: - Public API
+    
+    public func setGravity(_ gravity: SIMD3<Float>) {
+        self.gravity = gravity
+    }
+    
+    public func getGravity() -> SIMD3<Float> {
+        return gravity
+    }
+    
+    public func getAllBodies() -> [PhysicsBody] {
+        return Array(bodies.values)
+    }
+    
+    public func getCollisions() -> [Collision] {
+        return collisions
+    }
+}
+

Sources/PlatformLinux/LinuxPlatform.swift

@@ -0,0 +1,294 @@
+/// PlatformLinux - Linux platform abstraction layer
+/// This module provides window management and input handling for Linux
+/// Uses X11/Wayland via GLFW or SDL bindings
+
+import Foundation
+import RendererAPI
+
+// Note: In a real implementation, this would import GLFW or SDL bindings
+// import CGLFW or import CSDL2
+
+// MARK: - Linux Window Manager
+
+public final class LinuxWindowManager: WindowManager, @unchecked Sendable {
+    
+    private var window: UnsafeMutableRawPointer?
+    private var config: WindowConfig?
+    private var shouldCloseFlag: Bool = false
+    private var currentWidth: Int = 0
+    private var currentHeight: Int = 0
+    
+    public init() {
+        print("    🐧 LinuxWindowManager created")
+    }
+    
+    public func createWindow(config: WindowConfig) async throws {
+        print("    → Creating Linux window...")
+        self.config = config
+        self.currentWidth = config.width
+        self.currentHeight = config.height
+        
+        // Initialize GLFW or SDL
+        // glfwInit() or SDL_Init(SDL_INIT_VIDEO)
+        
+        // Set window hints for Vulkan (no OpenGL context)
+        // glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API)
+        // glfwWindowHint(GLFW_RESIZABLE, config.resizable ? GLFW_TRUE : GLFW_FALSE)
+        
+        // Create window
+        // window = glfwCreateWindow(width, height, title, monitor, share)
+        // or
+        // window = SDL_CreateWindow(title, x, y, width, height, SDL_WINDOW_VULKAN)
+        
+        // Set up event callbacks
+        // glfwSetWindowSizeCallback(window, sizeCallback)
+        // glfwSetWindowCloseCallback(window, closeCallback)
+        
+        print("    ✓ Linux window created: \(config.title) (\(config.width)x\(config.height))")
+    }
+    
+    public func shouldClose() -> Bool {
+        // return glfwWindowShouldClose(window) != 0
+        // or check SDL event queue for SDL_QUIT
+        return shouldCloseFlag
+    }
+    
+    public func processEvents() -> [WindowEvent] {
+        var events: [WindowEvent] = []
+        
+        // Poll events from GLFW or SDL
+        // glfwPollEvents()
+        // or
+        // while SDL_PollEvent(&event) {
+        //     switch event.type {
+        //         case SDL_QUIT: events.append(.close)
+        //         case SDL_WINDOWEVENT: ...
+        //     }
+        // }
+        
+        return events
+    }
+    
+    public func getSize() -> (width: Int, height: Int) {
+        // glfwGetWindowSize(window, &width, &height)
+        // or SDL_GetWindowSize(window, &width, &height)
+        return (currentWidth, currentHeight)
+    }
+    
+    public func setSize(width: Int, height: Int) throws {
+        currentWidth = width
+        currentHeight = height
+        // glfwSetWindowSize(window, width, height)
+        // or SDL_SetWindowSize(window, width, height)
+    }
+    
+    public func setTitle(_ title: String) throws {
+        // glfwSetWindowTitle(window, title)
+        // or SDL_SetWindowTitle(window, title)
+    }
+    
+    public func setFullscreen(_ fullscreen: Bool) throws {
+        // glfwSetWindowMonitor(...) for GLFW
+        // or SDL_SetWindowFullscreen(window, fullscreen ? SDL_WINDOW_FULLSCREEN : 0)
+    }
+    
+    public func getNativeHandle() -> UnsafeMutableRawPointer? {
+        // For Vulkan surface creation on Linux:
+        // X11: glfwGetX11Window(window) or SDL_GetProperty(window, SDL_PROP_WINDOW_X11_WINDOW_POINTER)
+        // Wayland: glfwGetWaylandWindow(window) or SDL_GetProperty(window, SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER)
+        return window
+    }
+    
+    public func swapBuffers() throws {
+        // Not needed for Vulkan (presentation is handled by renderer)
+        // For OpenGL: glfwSwapBuffers(window) or SDL_GL_SwapWindow(window)
+    }
+    
+    public func destroyWindow() async {
+        print("    → Destroying Linux window...")
+        
+        // glfwDestroyWindow(window)
+        // glfwTerminate()
+        // or
+        // SDL_DestroyWindow(window)
+        // SDL_Quit()
+        
+        window = nil
+        print("    ✓ Linux window destroyed")
+    }
+}
+
+// MARK: - Linux Input Handler
+
+public final class LinuxInputHandler: InputHandler, @unchecked Sendable {
+    
+    private var window: UnsafeMutableRawPointer?
+    private var keyStates: [KeyCode: Bool] = [:]
+    private var mouseButtonStates: [MouseButton: Bool] = [:]
+    private var mousePosition: (x: Double, y: Double) = (0, 0)
+    private var eventQueue: [InputEvent] = []
+    
+    public init() {
+        print("    🐧 LinuxInputHandler created")
+    }
+    
+    public func initialize() async throws {
+        print("    → Initializing Linux input system...")
+        
+        // Set up GLFW or SDL input callbacks
+        // glfwSetKeyCallback(window, keyCallback)
+        // glfwSetMouseButtonCallback(window, mouseButtonCallback)
+        // glfwSetCursorPosCallback(window, cursorPosCallback)
+        // glfwSetScrollCallback(window, scrollCallback)
+        // glfwSetJoystickCallback(joystickCallback)
+        
+        print("    ✓ Linux input system initialized")
+    }
+    
+    public func pollEvents() -> [InputEvent] {
+        // Events are accumulated in callbacks, return and clear the queue
+        let events = eventQueue
+        eventQueue.removeAll()
+        return events
+    }
+    
+    public func isKeyPressed(_ key: KeyCode) -> Bool {
+        return keyStates[key] ?? false
+    }
+    
+    public func isMouseButtonPressed(_ button: MouseButton) -> Bool {
+        return mouseButtonStates[button] ?? false
+    }
+    
+    public func getMousePosition() -> (x: Double, y: Double) {
+        // glfwGetCursorPos(window, &xpos, &ypos)
+        // or SDL_GetMouseState(&x, &y)
+        return mousePosition
+    }
+    
+    public func setCursorVisible(_ visible: Bool) {
+        // glfwSetInputMode(window, GLFW_CURSOR, visible ? GLFW_CURSOR_NORMAL : GLFW_CURSOR_HIDDEN)
+        // or SDL_ShowCursor(visible ? SDL_ENABLE : SDL_DISABLE)
+    }
+    
+    public func setCursorMode(_ mode: CursorMode) {
+        // switch mode {
+        // case .normal:
+        //     glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL)
+        // case .hidden:
+        //     glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN)
+        // case .locked:
+        //     glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED)
+        // }
+    }
+    
+    public func getGamepadCount() -> Int {
+        // Check for connected joysticks
+        // glfwJoystickPresent(GLFW_JOYSTICK_1) through GLFW_JOYSTICK_16
+        // or SDL_NumJoysticks()
+        return 0
+    }
+    
+    public func isGamepadConnected(_ gamepadId: Int) -> Bool {
+        // glfwJoystickPresent(gamepadId) != 0
+        // or SDL_JoystickGetAttached(joystick)
+        return false
+    }
+    
+    public func getGamepadName(_ gamepadId: Int) -> String? {
+        // glfwGetJoystickName(gamepadId)
+        // or SDL_JoystickName(joystick)
+        return nil
+    }
+    
+    public func shutdown() async {
+        print("    → Shutting down Linux input system...")
+        keyStates.removeAll()
+        mouseButtonStates.removeAll()
+        eventQueue.removeAll()
+        print("    ✓ Linux input system shutdown")
+    }
+    
+    // MARK: - Event Processing Helpers
+    
+    internal func handleKeyEvent(key: KeyCode, action: InputAction) {
+        keyStates[key] = (action == .press || action == .repeat_)
+        eventQueue.append(.keyEvent(key: key, action: action))
+    }
+    
+    internal func handleMouseButton(button: MouseButton, action: InputAction) {
+        mouseButtonStates[button] = (action == .press)
+        eventQueue.append(.mouseButton(button: button, action: action))
+    }
+    
+    internal func handleMouseMove(x: Double, y: Double) {
+        mousePosition = (x, y)
+        eventQueue.append(.mouseMove(x: x, y: y))
+    }
+    
+    internal func handleMouseScroll(xOffset: Double, yOffset: Double) {
+        eventQueue.append(.mouseScroll(xOffset: xOffset, yOffset: yOffset))
+    }
+}
+
+// MARK: - Linux Audio Engine (Stub)
+
+public final class LinuxAudioEngine: AudioEngine, @unchecked Sendable {
+    
+    public init() {
+        print("    🐧 LinuxAudioEngine created")
+    }
+    
+    public func initialize(config: AudioConfig) async throws {
+        print("    → Initializing Linux audio (ALSA/PulseAudio/PipeWire)...")
+        // Initialize audio backend (ALSA, PulseAudio, PipeWire, or OpenAL)
+        print("    ✓ Linux audio initialized")
+    }
+    
+    public func loadAudio(path: String) async throws -> AudioHandle {
+        // Load audio file (WAV, OGG, MP3)
+        return AudioHandle()
+    }
+    
+    public func loadAudioFromData(data: Data, sampleRate: Int, channels: Int) async throws -> AudioHandle {
+        return AudioHandle()
+    }
+    
+    public func play(handle: AudioHandle, source: AudioSource3D) throws {
+        // Play audio source
+    }
+    
+    public func stop(handle: AudioHandle) throws {
+        // Stop audio source
+    }
+    
+    public func pause(handle: AudioHandle) throws {
+        // Pause audio source
+    }
+    
+    public func resume(handle: AudioHandle) throws {
+        // Resume audio source
+    }
+    
+    public func updateSource(handle: AudioHandle, source: AudioSource3D) throws {
+        // Update 3D audio properties
+    }
+    
+    public func setListener(listener: AudioListener) throws {
+        // Set listener (camera) position and orientation
+    }
+    
+    public func setMasterVolume(_ volume: Float) throws {
+        // Set master volume
+    }
+    
+    public func update(deltaTime: Float) throws {
+        // Update audio system
+    }
+    
+    public func shutdown() async {
+        print("    → Shutting down Linux audio...")
+        print("    ✓ Linux audio shutdown")
+    }
+}
+

Sources/PlatformWin32/Win32Platform.swift

@@ -0,0 +1,338 @@
+/// PlatformWin32 - Windows platform abstraction layer
+/// This module provides window management and input handling for Windows
+/// Uses Win32 API or GLFW/SDL bindings
+
+import Foundation
+import RendererAPI
+
+#if os(Windows)
+// Note: In a real implementation, this would import Win32 API bindings
+// import WinSDK or CGLFW
+#endif
+
+// MARK: - Windows Window Manager
+
+public final class Win32WindowManager: WindowManager, @unchecked Sendable {
+    
+    private var hwnd: UnsafeMutableRawPointer? // HWND handle
+    private var hinstance: UnsafeMutableRawPointer? // HINSTANCE
+    private var config: WindowConfig?
+    private var shouldCloseFlag: Bool = false
+    private var currentWidth: Int = 0
+    private var currentHeight: Int = 0
+    
+    public init() {
+        print("    🪟 Win32WindowManager created")
+    }
+    
+    public func createWindow(config: WindowConfig) async throws {
+        print("    → Creating Windows window...")
+        self.config = config
+        self.currentWidth = config.width
+        self.currentHeight = config.height
+        
+        #if os(Windows)
+        // Get HINSTANCE
+        // hinstance = GetModuleHandleW(nil)
+        
+        // Register window class
+        // WNDCLASSEXW wc = { ... }
+        // wc.lpfnWndProc = WindowProc
+        // wc.lpszClassName = L"SportsBallEngineWindowClass"
+        // RegisterClassExW(&wc)
+        
+        // Calculate window size (client area vs window size)
+        // RECT rect = { 0, 0, width, height }
+        // AdjustWindowRect(&rect, WS_OVERLAPPEDWINDOW, FALSE)
+        
+        // Create window
+        // hwnd = CreateWindowExW(
+        //     0, L"SportsBallEngineWindowClass", title,
+        //     WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, CW_USEDEFAULT,
+        //     rect.right - rect.left, rect.bottom - rect.top,
+        //     nil, nil, hinstance, nil
+        // )
+        
+        // Show window
+        // ShowWindow(hwnd, SW_SHOW)
+        // UpdateWindow(hwnd)
+        
+        print("    ✓ Windows window created: \(config.title) (\(config.width)x\(config.height))")
+        #else
+        throw PlatformError.unsupportedPlatform("Win32 platform is only available on Windows")
+        #endif
+    }
+    
+    public func shouldClose() -> Bool {
+        return shouldCloseFlag
+    }
+    
+    public func processEvents() -> [WindowEvent] {
+        var events: [WindowEvent] = []
+        
+        #if os(Windows)
+        // Process Win32 message queue
+        // MSG msg
+        // while PeekMessageW(&msg, nil, 0, 0, PM_REMOVE) {
+        //     if msg.message == WM_QUIT {
+        //         shouldCloseFlag = true
+        //         events.append(.close)
+        //     }
+        //     TranslateMessage(&msg)
+        //     DispatchMessageW(&msg)
+        // }
+        #endif
+        
+        return events
+    }
+    
+    public func getSize() -> (width: Int, height: Int) {
+        #if os(Windows)
+        // RECT rect
+        // GetClientRect(hwnd, &rect)
+        // return (rect.right - rect.left, rect.bottom - rect.top)
+        #endif
+        return (currentWidth, currentHeight)
+    }
+    
+    public func setSize(width: Int, height: Int) throws {
+        currentWidth = width
+        currentHeight = height
+        #if os(Windows)
+        // SetWindowPos(hwnd, nil, 0, 0, width, height, SWP_NOMOVE | SWP_NOZORDER)
+        #endif
+    }
+    
+    public func setTitle(_ title: String) throws {
+        #if os(Windows)
+        // SetWindowTextW(hwnd, wideTitle)
+        #endif
+    }
+    
+    public func setFullscreen(_ fullscreen: Bool) throws {
+        #if os(Windows)
+        // if fullscreen {
+        //     SetWindowLongPtrW(hwnd, GWL_STYLE, WS_POPUP)
+        //     SetWindowPos(hwnd, HWND_TOP, 0, 0, screenWidth, screenHeight, SWP_FRAMECHANGED)
+        // } else {
+        //     SetWindowLongPtrW(hwnd, GWL_STYLE, WS_OVERLAPPEDWINDOW)
+        //     SetWindowPos(hwnd, nil, x, y, width, height, SWP_FRAMECHANGED)
+        // }
+        #endif
+    }
+    
+    public func getNativeHandle() -> UnsafeMutableRawPointer? {
+        // Return HWND for DirectX 12 or Vulkan surface creation
+        return hwnd
+    }
+    
+    public func swapBuffers() throws {
+        // Not needed for Vulkan or DirectX 12 (presentation is handled by renderer)
+    }
+    
+    public func destroyWindow() async {
+        print("    → Destroying Windows window...")
+        
+        #if os(Windows)
+        // DestroyWindow(hwnd)
+        // UnregisterClassW(L"SportsBallEngineWindowClass", hinstance)
+        #endif
+        
+        hwnd = nil
+        print("    ✓ Windows window destroyed")
+    }
+    
+    // MARK: - Win32 Window Procedure (would be separate C function)
+    
+    // static LRESULT CALLBACK WindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam) {
+    //     switch (uMsg) {
+    //         case WM_CLOSE:
+    //             PostQuitMessage(0)
+    //             return 0
+    //         case WM_SIZE:
+    //             // Handle resize
+    //             return 0
+    //         case WM_KEYDOWN:
+    //         case WM_KEYUP:
+    //             // Handle keyboard
+    //             return 0
+    //         default:
+    //             return DefWindowProcW(hwnd, uMsg, wParam, lParam)
+    //     }
+    // }
+}
+
+// MARK: - Windows Input Handler
+
+public final class Win32InputHandler: InputHandler, @unchecked Sendable {
+    
+    private var keyStates: [KeyCode: Bool] = [:]
+    private var mouseButtonStates: [MouseButton: Bool] = [:]
+    private var mousePosition: (x: Double, y: Double) = (0, 0)
+    private var eventQueue: [InputEvent] = []
+    
+    public init() {
+        print("    🪟 Win32InputHandler created")
+    }
+    
+    public func initialize() async throws {
+        print("    → Initializing Windows input system...")
+        
+        #if os(Windows)
+        // Initialize Raw Input or XInput for gamepads
+        // RAWINPUTDEVICE rid[2]
+        // rid[0].usUsagePage = 0x01  // HID_USAGE_PAGE_GENERIC
+        // rid[0].usUsage = 0x02      // HID_USAGE_GENERIC_MOUSE
+        // rid[1].usUsagePage = 0x01
+        // rid[1].usUsage = 0x06      // HID_USAGE_GENERIC_KEYBOARD
+        // RegisterRawInputDevices(rid, 2, sizeof(RAWINPUTDEVICE))
+        #endif
+        
+        print("    ✓ Windows input system initialized")
+    }
+    
+    public func pollEvents() -> [InputEvent] {
+        let events = eventQueue
+        eventQueue.removeAll()
+        return events
+    }
+    
+    public func isKeyPressed(_ key: KeyCode) -> Bool {
+        #if os(Windows)
+        // GetAsyncKeyState(virtualKeyCode) & 0x8000
+        #endif
+        return keyStates[key] ?? false
+    }
+    
+    public func isMouseButtonPressed(_ button: MouseButton) -> Bool {
+        #if os(Windows)
+        // GetAsyncKeyState(VK_LBUTTON/VK_RBUTTON/VK_MBUTTON) & 0x8000
+        #endif
+        return mouseButtonStates[button] ?? false
+    }
+    
+    public func getMousePosition() -> (x: Double, y: Double) {
+        #if os(Windows)
+        // POINT pt
+        // GetCursorPos(&pt)
+        // ScreenToClient(hwnd, &pt)
+        #endif
+        return mousePosition
+    }
+    
+    public func setCursorVisible(_ visible: Bool) {
+        #if os(Windows)
+        // ShowCursor(visible ? TRUE : FALSE)
+        #endif
+    }
+    
+    public func setCursorMode(_ mode: CursorMode) {
+        #if os(Windows)
+        // switch mode {
+        // case .normal:
+        //     ShowCursor(TRUE)
+        //     ClipCursor(nil)
+        // case .hidden:
+        //     ShowCursor(FALSE)
+        // case .locked:
+        //     ShowCursor(FALSE)
+        //     RECT rect; GetClientRect(hwnd, &rect)
+        //     ClipCursor(&rect) // Confine cursor to window
+        // }
+        #endif
+    }
+    
+    public func getGamepadCount() -> Int {
+        #if os(Windows)
+        // Check XInput connected controllers (max 4)
+        // for i in 0..<4 {
+        //     XINPUT_STATE state
+        //     if XInputGetState(i, &state) == ERROR_SUCCESS {
+        //         count++
+        //     }
+        // }
+        #endif
+        return 0
+    }
+    
+    public func isGamepadConnected(_ gamepadId: Int) -> Bool {
+        #if os(Windows)
+        // XINPUT_STATE state
+        // return XInputGetState(gamepadId, &state) == ERROR_SUCCESS
+        #endif
+        return false
+    }
+    
+    public func getGamepadName(_ gamepadId: Int) -> String? {
+        return "Xbox Controller \(gamepadId)"
+    }
+    
+    public func shutdown() async {
+        print("    → Shutting down Windows input system...")
+        keyStates.removeAll()
+        mouseButtonStates.removeAll()
+        eventQueue.removeAll()
+        print("    ✓ Windows input system shutdown")
+    }
+    
+    // MARK: - Event Processing Helpers
+    
+    internal func handleKeyEvent(key: KeyCode, action: InputAction) {
+        keyStates[key] = (action == .press || action == .repeat_)
+        eventQueue.append(.keyEvent(key: key, action: action))
+    }
+    
+    internal func handleMouseButton(button: MouseButton, action: InputAction) {
+        mouseButtonStates[button] = (action == .press)
+        eventQueue.append(.mouseButton(button: button, action: action))
+    }
+    
+    internal func handleMouseMove(x: Double, y: Double) {
+        mousePosition = (x, y)
+        eventQueue.append(.mouseMove(x: x, y: y))
+    }
+}
+
+// MARK: - Windows Audio Engine (Stub)
+
+public final class Win32AudioEngine: AudioEngine, @unchecked Sendable {
+    
+    public init() {
+        print("    🪟 Win32AudioEngine created")
+    }
+    
+    public func initialize(config: AudioConfig) async throws {
+        print("    → Initializing Windows audio (WASAPI/XAudio2)...")
+        // Initialize audio backend (WASAPI, XAudio2, or OpenAL)
+        print("    ✓ Windows audio initialized")
+    }
+    
+    public func loadAudio(path: String) async throws -> AudioHandle {
+        return AudioHandle()
+    }
+    
+    public func loadAudioFromData(data: Data, sampleRate: Int, channels: Int) async throws -> AudioHandle {
+        return AudioHandle()
+    }
+    
+    public func play(handle: AudioHandle, source: AudioSource3D) throws {}
+    public func stop(handle: AudioHandle) throws {}
+    public func pause(handle: AudioHandle) throws {}
+    public func resume(handle: AudioHandle) throws {}
+    public func updateSource(handle: AudioHandle, source: AudioSource3D) throws {}
+    public func setListener(listener: AudioListener) throws {}
+    public func setMasterVolume(_ volume: Float) throws {}
+    public func update(deltaTime: Float) throws {}
+    
+    public func shutdown() async {
+        print("    → Shutting down Windows audio...")
+        print("    ✓ Windows audio shutdown")
+    }
+}
+
+// MARK: - Errors
+
+private enum PlatformError: Error {
+    case unsupportedPlatform(String)
+}
+

Sources/RendererAPI/AudioProtocol.swift

@@ -0,0 +1,103 @@
+/// Audio System Protocol - Platform-agnostic audio handling
+/// This module contains ONLY protocol definitions with no platform-specific imports
+
+import Foundation
+
+// MARK: - Audio Types
+
+/// Audio source handle
+public struct AudioHandle: Hashable, Sendable {
+    public let id: UUID
+    public init(id: UUID = UUID()) { self.id = id }
+}
+
+/// Audio configuration
+public struct AudioConfig: Sendable {
+    public var sampleRate: Int
+    public var channels: Int
+    public var bufferSize: Int
+    
+    public init(sampleRate: Int = 44100, channels: Int = 2, bufferSize: Int = 4096) {
+        self.sampleRate = sampleRate
+        self.channels = channels
+        self.bufferSize = bufferSize
+    }
+}
+
+/// 3D audio source properties
+public struct AudioSource3D: Sendable {
+    public var position: SIMD3<Float>
+    public var velocity: SIMD3<Float>
+    public var volume: Float
+    public var pitch: Float
+    public var looping: Bool
+    public var spatialize: Bool
+    
+    public init(position: SIMD3<Float> = .zero, velocity: SIMD3<Float> = .zero,
+                volume: Float = 1.0, pitch: Float = 1.0, looping: Bool = false, spatialize: Bool = true) {
+        self.position = position
+        self.velocity = velocity
+        self.volume = volume
+        self.pitch = pitch
+        self.looping = looping
+        self.spatialize = spatialize
+    }
+}
+
+/// Audio listener properties (typically the camera)
+public struct AudioListener: Sendable {
+    public var position: SIMD3<Float>
+    public var velocity: SIMD3<Float>
+    public var forward: SIMD3<Float>
+    public var up: SIMD3<Float>
+    
+    public init(position: SIMD3<Float> = .zero, velocity: SIMD3<Float> = .zero,
+                forward: SIMD3<Float> = SIMD3<Float>(0, 0, -1), up: SIMD3<Float> = SIMD3<Float>(0, 1, 0)) {
+        self.position = position
+        self.velocity = velocity
+        self.forward = forward
+        self.up = up
+    }
+}
+
+// MARK: - Audio Engine Protocol
+
+/// Audio system abstraction - all platform-specific audio implementations must conform
+public protocol AudioEngine: Sendable {
+    /// Initialize the audio system
+    func initialize(config: AudioConfig) async throws
+    
+    /// Load an audio clip from file
+    func loadAudio(path: String) async throws -> AudioHandle
+    
+    /// Load audio from raw PCM data
+    func loadAudioFromData(data: Data, sampleRate: Int, channels: Int) async throws -> AudioHandle
+    
+    /// Play an audio source
+    func play(handle: AudioHandle, source: AudioSource3D) throws
+    
+    /// Stop an audio source
+    func stop(handle: AudioHandle) throws
+    
+    /// Pause an audio source
+    func pause(handle: AudioHandle) throws
+    
+    /// Resume a paused audio source
+    func resume(handle: AudioHandle) throws
+    
+    /// Update audio source properties
+    func updateSource(handle: AudioHandle, source: AudioSource3D) throws
+    
+    /// Set listener properties (camera/player position)
+    func setListener(listener: AudioListener) throws
+    
+    /// Set master volume
+    func setMasterVolume(_ volume: Float) throws
+    
+    /// Update audio system (called each frame)
+    func update(deltaTime: Float) throws
+    
+    /// Shutdown the audio system
+    func shutdown() async
+}
+

Sources/RendererAPI/InputProtocol.swift

@@ -0,0 +1,125 @@
+/// Input System Protocol - Platform-agnostic input handling
+/// This module contains ONLY protocol definitions with no platform-specific imports
+
+import Foundation
+
+// MARK: - Input Types
+
+/// Keyboard key codes
+public enum KeyCode: Int, Sendable {
+    case unknown = 0
+    case space = 32
+    case apostrophe = 39
+    case comma = 44
+    case minus = 45
+    case period = 46
+    case slash = 47
+    case key0 = 48, key1, key2, key3, key4, key5, key6, key7, key8, key9
+    case semicolon = 59
+    case equal = 61
+    case a = 65, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z
+    case leftBracket = 91
+    case backslash = 92
+    case rightBracket = 93
+    case graveAccent = 96
+    case escape = 256
+    case enter = 257
+    case tab = 258
+    case backspace = 259
+    case insert = 260
+    case delete = 261
+    case right = 262
+    case left = 263
+    case down = 264
+    case up = 265
+    case pageUp = 266
+    case pageDown = 267
+    case home = 268
+    case end = 269
+    case capsLock = 280
+    case scrollLock = 281
+    case numLock = 282
+    case printScreen = 283
+    case pause = 284
+    case f1 = 290, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12
+    case leftShift = 340
+    case leftControl = 341
+    case leftAlt = 342
+    case leftSuper = 343
+    case rightShift = 344
+    case rightControl = 345
+    case rightAlt = 346
+    case rightSuper = 347
+}
+
+/// Mouse button codes
+public enum MouseButton: Int, Sendable {
+    case left = 0
+    case right = 1
+    case middle = 2
+    case button4 = 3
+    case button5 = 4
+}
+
+/// Input action state
+public enum InputAction: Sendable {
+    case press
+    case release
+    case repeat_
+}
+
+/// Input event types
+public enum InputEvent: Sendable {
+    case keyEvent(key: KeyCode, action: InputAction)
+    case mouseButton(button: MouseButton, action: InputAction)
+    case mouseMove(x: Double, y: Double)
+    case mouseScroll(xOffset: Double, yOffset: Double)
+    case gamepadButton(gamepadId: Int, button: Int, action: InputAction)
+    case gamepadAxis(gamepadId: Int, axis: Int, value: Float)
+}
+
+// MARK: - Input Handler Protocol
+
+/// Input system abstraction - all platform-specific input implementations must conform
+public protocol InputHandler: Sendable {
+    /// Initialize the input system
+    func initialize() async throws
+    
+    /// Poll for input events (called each frame)
+    func pollEvents() -> [InputEvent]
+    
+    /// Check if a key is currently pressed
+    func isKeyPressed(_ key: KeyCode) -> Bool
+    
+    /// Check if a mouse button is currently pressed
+    func isMouseButtonPressed(_ button: MouseButton) -> Bool
+    
+    /// Get current mouse position
+    func getMousePosition() -> (x: Double, y: Double)
+    
+    /// Set mouse cursor visibility
+    func setCursorVisible(_ visible: Bool)
+    
+    /// Set mouse cursor mode (normal, hidden, locked)
+    func setCursorMode(_ mode: CursorMode)
+    
+    /// Get connected gamepad count
+    func getGamepadCount() -> Int
+    
+    /// Check if a gamepad is connected
+    func isGamepadConnected(_ gamepadId: Int) -> Bool
+    
+    /// Get gamepad name
+    func getGamepadName(_ gamepadId: Int) -> String?
+    
+    /// Shutdown the input system
+    func shutdown() async
+}
+
+/// Cursor display mode
+public enum CursorMode: Sendable {
+    case normal
+    case hidden
+    case locked
+}
+

Sources/RendererAPI/RendererProtocol.swift

@@ -0,0 +1,197 @@
+/// RendererAPI - Protocol Definitions for Platform Abstraction
+/// This module contains ONLY protocol definitions with no platform-specific imports
+
+import Foundation
+
+// MARK: - Core Rendering Types
+
+/// Represents a 3D scene to be rendered
+public struct Scene {
+    public var entities: [Entity]
+    public var camera: Camera
+    public var lights: [Light]
+    
+    public init(entities: [Entity] = [], camera: Camera, lights: [Light] = []) {
+        self.entities = entities
+        self.camera = camera
+        self.lights = lights
+    }
+}
+
+/// Represents a renderable entity in the scene
+public struct Entity {
+    public var id: UUID
+    public var transform: Transform
+    public var mesh: MeshHandle
+    public var material: MaterialHandle
+    
+    public init(id: UUID = UUID(), transform: Transform, mesh: MeshHandle, material: MaterialHandle) {
+        self.id = id
+        self.transform = transform
+        self.mesh = mesh
+        self.material = material
+    }
+}
+
+/// Camera configuration
+public struct Camera {
+    public var position: SIMD3<Float>
+    public var rotation: SIMD4<Float> // Quaternion
+    public var fieldOfView: Float
+    public var nearPlane: Float
+    public var farPlane: Float
+    
+    public init(position: SIMD3<Float> = .zero, rotation: SIMD4<Float> = SIMD4<Float>(0, 0, 0, 1),
+                fieldOfView: Float = 60.0, nearPlane: Float = 0.1, farPlane: Float = 1000.0) {
+        self.position = position
+        self.rotation = rotation
+        self.fieldOfView = fieldOfView
+        self.nearPlane = nearPlane
+        self.farPlane = farPlane
+    }
+}
+
+/// Transform component
+public struct Transform {
+    public var position: SIMD3<Float>
+    public var rotation: SIMD4<Float> // Quaternion
+    public var scale: SIMD3<Float>
+    
+    public init(position: SIMD3<Float> = .zero, rotation: SIMD4<Float> = SIMD4<Float>(0, 0, 0, 1),
+                scale: SIMD3<Float> = SIMD3<Float>(1, 1, 1)) {
+        self.position = position
+        self.rotation = rotation
+        self.scale = scale
+    }
+}
+
+/// Light source
+public struct Light {
+    public enum LightType {
+        case directional
+        case point
+        case spot
+    }
+    
+    public var type: LightType
+    public var position: SIMD3<Float>
+    public var direction: SIMD3<Float>
+    public var color: SIMD3<Float>
+    public var intensity: Float
+    
+    public init(type: LightType, position: SIMD3<Float> = .zero, direction: SIMD3<Float> = SIMD3<Float>(0, -1, 0),
+                color: SIMD3<Float> = SIMD3<Float>(1, 1, 1), intensity: Float = 1.0) {
+        self.type = type
+        self.position = position
+        self.direction = direction
+        self.color = color
+        self.intensity = intensity
+    }
+}
+
+/// Opaque handle for mesh resources
+public struct MeshHandle: Hashable {
+    public let id: UUID
+    public init(id: UUID = UUID()) { self.id = id }
+}
+
+/// Opaque handle for material resources
+public struct MaterialHandle: Hashable {
+    public let id: UUID
+    public init(id: UUID = UUID()) { self.id = id }
+}
+
+/// Opaque handle for texture resources
+public struct TextureHandle: Hashable {
+    public let id: UUID
+    public init(id: UUID = UUID()) { self.id = id }
+}
+
+// MARK: - Renderer Protocol
+
+/// Primary rendering abstraction - all rendering backends must conform to this
+public protocol Renderer: Sendable {
+    /// Initialize the renderer with the given configuration
+    func initialize(config: RendererConfig) async throws
+    
+    /// Begin a new frame
+    func beginFrame() throws
+    
+    /// Draw the current scene
+    func draw(scene: Scene) throws
+    
+    /// End the current frame and present
+    func endFrame() throws
+    
+    /// Shutdown and cleanup resources
+    func shutdown() async
+    
+    /// Load a mesh into GPU memory
+    func loadMesh(vertices: [Vertex], indices: [UInt32]) async throws -> MeshHandle
+    
+    /// Load a texture into GPU memory
+    func loadTexture(data: Data, width: Int, height: Int, format: TextureFormat) async throws -> TextureHandle
+    
+    /// Create a material
+    func createMaterial(albedoTexture: TextureHandle?, normalTexture: TextureHandle?) async throws -> MaterialHandle
+    
+    /// Get renderer capabilities and information
+    var info: RendererInfo { get }
+}
+
+/// Renderer configuration
+public struct RendererConfig: Sendable {
+    public var windowHandle: UnsafeMutableRawPointer?
+    public var width: Int
+    public var height: Int
+    public var vsyncEnabled: Bool
+    public var msaaSamples: Int
+    
+    public init(windowHandle: UnsafeMutableRawPointer? = nil, width: Int = 1920, height: Int = 1080,
+                vsyncEnabled: Bool = true, msaaSamples: Int = 4) {
+        self.windowHandle = windowHandle
+        self.width = width
+        self.height = height
+        self.vsyncEnabled = vsyncEnabled
+        self.msaaSamples = msaaSamples
+    }
+}
+
+/// Renderer information
+public struct RendererInfo: Sendable {
+    public var apiName: String
+    public var apiVersion: String
+    public var deviceName: String
+    public var maxTextureSize: Int
+    
+    public init(apiName: String, apiVersion: String, deviceName: String, maxTextureSize: Int) {
+        self.apiName = apiName
+        self.apiVersion = apiVersion
+        self.deviceName = deviceName
+        self.maxTextureSize = maxTextureSize
+    }
+}
+
+/// Vertex data structure
+public struct Vertex: Sendable {
+    public var position: SIMD3<Float>
+    public var normal: SIMD3<Float>
+    public var uv: SIMD2<Float>
+    public var tangent: SIMD3<Float>
+    
+    public init(position: SIMD3<Float>, normal: SIMD3<Float>, uv: SIMD2<Float>, tangent: SIMD3<Float> = .zero) {
+        self.position = position
+        self.normal = normal
+        self.uv = uv
+        self.tangent = tangent
+    }
+}
+
+/// Texture format enumeration
+public enum TextureFormat: Sendable {
+    case rgba8
+    case rgba16f
+    case rgba32f
+    case depth24stencil8
+}
+

Sources/RendererAPI/WindowProtocol.swift

@@ -0,0 +1,72 @@
+/// Window Management Protocol - Platform-agnostic window handling
+/// This module contains ONLY protocol definitions with no platform-specific imports
+
+import Foundation
+
+// MARK: - Window Types
+
+/// Window configuration
+public struct WindowConfig: Sendable {
+    public var title: String
+    public var width: Int
+    public var height: Int
+    public var fullscreen: Bool
+    public var resizable: Bool
+    public var vsyncEnabled: Bool
+    
+    public init(title: String = "SportsBallEngine", width: Int = 1920, height: Int = 1080,
+                fullscreen: Bool = false, resizable: Bool = true, vsyncEnabled: Bool = true) {
+        self.title = title
+        self.width = width
+        self.height = height
+        self.fullscreen = fullscreen
+        self.resizable = resizable
+        self.vsyncEnabled = vsyncEnabled
+    }
+}
+
+/// Window event types
+public enum WindowEvent: Sendable {
+    case close
+    case resize(width: Int, height: Int)
+    case focus(focused: Bool)
+    case minimize
+    case maximize
+    case restore
+}
+
+// MARK: - Window Manager Protocol
+
+/// Window system abstraction - all platform-specific window implementations must conform
+public protocol WindowManager: Sendable {
+    /// Create and initialize a window with the given configuration
+    func createWindow(config: WindowConfig) async throws
+    
+    /// Check if the window should close
+    func shouldClose() -> Bool
+    
+    /// Process window events (called each frame)
+    func processEvents() -> [WindowEvent]
+    
+    /// Get current window size
+    func getSize() -> (width: Int, height: Int)
+    
+    /// Set window size
+    func setSize(width: Int, height: Int) throws
+    
+    /// Set window title
+    func setTitle(_ title: String) throws
+    
+    /// Toggle fullscreen mode
+    func setFullscreen(_ fullscreen: Bool) throws
+    
+    /// Get native window handle (for renderer initialization)
+    func getNativeHandle() -> UnsafeMutableRawPointer?
+    
+    /// Swap buffers / present frame
+    func swapBuffers() throws
+    
+    /// Destroy the window and cleanup
+    func destroyWindow() async
+}
+

Sources/SportsBallEngine/main.swift

@@ -0,0 +1,312 @@
+/// SportsBallEngine - Main Entry Point
+/// This file handles platform detection and initializes the appropriate platform layers
+/// before handing off to the platform-agnostic EngineCore
+
+import Foundation
+import EngineCore
+import RendererAPI
+
+// Platform-specific imports (conditionally compiled)
+#if os(Linux)
+import PlatformLinux
+import VulkanRenderer
+#elseif os(Windows)
+import PlatformWin32
+import DX12Renderer
+import VulkanRenderer // Vulkan is also supported on Windows
+#elseif os(macOS)
+// Future: import PlatformMacOS and MetalRenderer
+#endif
+
+// MARK: - Platform Detection and Initialization
+
+print("=" * 60)
+print("🏀 SportsBallEngine - Cross-Platform 3D Game Engine")
+print("=" * 60)
+print()
+
+// Detect platform
+#if os(Linux)
+print("📍 Platform: Linux")
+let platformName = "Linux"
+#elseif os(Windows)
+print("📍 Platform: Windows")
+let platformName = "Windows"
+#elseif os(macOS)
+print("📍 Platform: macOS")
+let platformName = "macOS"
+#else
+print("📍 Platform: Unknown")
+let platformName = "Unknown"
+#endif
+
+print("🔧 Swift Version: \(#swiftVersion)")
+print()
+
+// MARK: - Platform Layer Factory
+
+/// Creates platform-specific implementations based on the current OS
+struct PlatformFactory {
+    
+    static func createRenderer(preferredAPI: String? = nil) -> any Renderer {
+        #if os(Linux)
+        // Linux: Vulkan only
+        print("🎨 Creating Vulkan renderer...")
+        return VulkanRenderer()
+        
+        #elseif os(Windows)
+        // Windows: DirectX 12 (default) or Vulkan
+        if let api = preferredAPI?.lowercased(), api == "vulkan" {
+            print("🎨 Creating Vulkan renderer...")
+            return VulkanRenderer()
+        } else {
+            print("🎨 Creating DirectX 12 renderer...")
+            return DX12Renderer()
+        }
+        
+        #elseif os(macOS)
+        // macOS: Metal (future)
+        fatalError("macOS support not yet implemented - Metal renderer coming soon")
+        
+        #else
+        fatalError("Unsupported platform: \(platformName)")
+        #endif
+    }
+    
+    static func createWindowManager() -> any WindowManager {
+        #if os(Linux)
+        return LinuxWindowManager()
+        
+        #elseif os(Windows)
+        return Win32WindowManager()
+        
+        #elseif os(macOS)
+        // return MacOSWindowManager()
+        fatalError("macOS support not yet implemented")
+        
+        #else
+        fatalError("Unsupported platform: \(platformName)")
+        #endif
+    }
+    
+    static func createInputHandler() -> any InputHandler {
+        #if os(Linux)
+        return LinuxInputHandler()
+        
+        #elseif os(Windows)
+        return Win32InputHandler()
+        
+        #elseif os(macOS)
+        // return MacOSInputHandler()
+        fatalError("macOS support not yet implemented")
+        
+        #else
+        fatalError("Unsupported platform: \(platformName)")
+        #endif
+    }
+    
+    static func createAudioEngine() -> any AudioEngine {
+        #if os(Linux)
+        return LinuxAudioEngine()
+        
+        #elseif os(Windows)
+        return Win32AudioEngine()
+        
+        #elseif os(macOS)
+        // return MacOSAudioEngine()
+        fatalError("macOS support not yet implemented")
+        
+        #else
+        fatalError("Unsupported platform: \(platformName)")
+        #endif
+    }
+}
+
+// MARK: - Application Configuration
+
+/// Parse command-line arguments for configuration
+func parseArguments() -> (rendererAPI: String?, windowTitle: String?, width: Int?, height: Int?) {
+    let args = CommandLine.arguments
+    
+    var rendererAPI: String?
+    var windowTitle: String?
+    var width: Int?
+    var height: Int?
+    
+    var i = 1
+    while i < args.count {
+        let arg = args[i]
+        
+        switch arg {
+        case "--renderer", "-r":
+            if i + 1 < args.count {
+                rendererAPI = args[i + 1]
+                i += 1
+            }
+        case "--title", "-t":
+            if i + 1 < args.count {
+                windowTitle = args[i + 1]
+                i += 1
+            }
+        case "--width", "-w":
+            if i + 1 < args.count {
+                width = Int(args[i + 1])
+                i += 1
+            }
+        case "--height", "-h":
+            if i + 1 < args.count {
+                height = Int(args[i + 1])
+                i += 1
+            }
+        case "--help":
+            printHelp()
+            exit(0)
+        default:
+            break
+        }
+        
+        i += 1
+    }
+    
+    return (rendererAPI, windowTitle, width, height)
+}
+
+func printHelp() {
+    print("""
+    Usage: SportsBallEngine [OPTIONS]
+    
+    Options:
+      --renderer, -r <api>     Renderer API (vulkan, dx12) [Windows only]
+      --title, -t <title>      Window title
+      --width, -w <pixels>     Window width (default: 1920)
+      --height, -h <pixels>    Window height (default: 1080)
+      --help                   Show this help message
+    
+    Examples:
+      SportsBallEngine --renderer vulkan --width 2560 --height 1440
+      SportsBallEngine --title "My Sports Game"
+    """)
+}
+
+// MARK: - Main Execution
+
+@main
+struct SportsBallEngineApp {
+    static func main() async {
+        do {
+            // Parse command-line arguments
+            let args = parseArguments()
+            
+            // Create platform-specific implementations
+            print("🔨 Creating platform abstractions...")
+            let renderer = PlatformFactory.createRenderer(preferredAPI: args.rendererAPI)
+            let windowManager = PlatformFactory.createWindowManager()
+            let inputHandler = PlatformFactory.createInputHandler()
+            let audioEngine = PlatformFactory.createAudioEngine()
+            print()
+            
+            // Create window
+            print("🪟 Creating window...")
+            let windowConfig = WindowConfig(
+                title: args.windowTitle ?? "SportsBallEngine - EA Sports-style Demo",
+                width: args.width ?? 1920,
+                height: args.height ?? 1080,
+                fullscreen: false,
+                resizable: true,
+                vsyncEnabled: true
+            )
+            try await windowManager.createWindow(config: windowConfig)
+            print()
+            
+            // Create engine configuration
+            let engineConfig = EngineConfig(
+                targetFrameRate: 60,
+                fixedTimeStep: 1.0 / 60.0,
+                maxFrameSkip: 5
+            )
+            
+            // Initialize the engine core with platform abstractions
+            print("⚙️  Initializing engine core...")
+            let engine = GameEngine(
+                renderer: renderer,
+                windowManager: windowManager,
+                inputHandler: inputHandler,
+                audioEngine: audioEngine,
+                config: engineConfig
+            )
+            print()
+            
+            // Start the engine (this runs the main loop)
+            print("=" * 60)
+            print("🎮 Starting game engine...")
+            print("=" * 60)
+            print()
+            print("Controls:")
+            print("  ESC - Exit application")
+            print()
+            
+            try await engine.start()
+            
+            // Engine has stopped
+            print()
+            print("=" * 60)
+            print("👋 Engine shutdown complete. Goodbye!")
+            print("=" * 60)
+            
+        } catch {
+            print()
+            print("=" * 60)
+            print("❌ Fatal Error: \(error)")
+            print("=" * 60)
+            exit(1)
+        }
+    }
+}
+
+// MARK: - String Multiplication Helper
+
+extension String {
+    static func * (string: String, count: Int) -> String {
+        return String(repeating: string, count: count)
+    }
+}
+
+/*
+ * ============================================================================
+ * ARCHITECTURE NOTES - Carmack-Style Separation
+ * ============================================================================
+ *
+ * This engine follows the id Software architectural pattern:
+ *
+ * 1. STRICT SEPARATION:
+ *    - EngineCore, PhysicsEngine, AssetLoader: NO platform imports
+ *    - PlatformLinux, PlatformWin32: Platform-specific code ONLY
+ *    - VulkanRenderer, DX12Renderer: Graphics API-specific code ONLY
+ *
+ * 2. PROTOCOL-ORIENTED DESIGN:
+ *    - All platform systems use protocols (Renderer, WindowManager, etc.)
+ *    - EngineCore only depends on protocols, never concrete types
+ *    - Platform layers are injected at startup via this main.swift
+ *
+ * 3. INITIALIZATION FLOW:
+ *    main.swift (this file)
+ *      → Detect platform
+ *      → Create platform-specific implementations
+ *      → Inject into EngineCore
+ *      → Start engine main loop
+ *
+ * 4. RENDER BACKENDS:
+ *    - Vulkan: Primary cross-platform (Linux + Windows)
+ *    - DirectX 12: Windows optimization
+ *    - Metal: Future macOS support
+ *
+ * 5. SPORTS GAME OPTIMIZATIONS:
+ *    - High-fidelity character rendering (skeletal animation)
+ *    - Fast ball/puck physics (custom collision detection)
+ *    - Large stadium rendering (LOD, culling)
+ *    - State machine-driven player movement
+ *    - Animation blending for smooth transitions
+ *
+ * ============================================================================
+ */
+

Sources/VulkanRenderer/VulkanRenderer.swift

@@ -0,0 +1,332 @@
+/// VulkanRenderer - Vulkan rendering backend implementation
+/// This is a PLATFORM-SPECIFIC module (Vulkan API)
+
+import Foundation
+import RendererAPI
+
+// Note: In a real implementation, this would import Vulkan C bindings
+// import CVulkan or similar Swift Vulkan wrapper
+
+/// Vulkan-based renderer implementation
+public final class VulkanRenderer: Renderer, @unchecked Sendable {
+    
+    private var config: RendererConfig?
+    private var isInitialized: Bool = false
+    
+    // Vulkan handles (placeholders - would be actual Vulkan types)
+    private var instance: UnsafeMutableRawPointer?
+    private var device: UnsafeMutableRawPointer?
+    private var physicalDevice: UnsafeMutableRawPointer?
+    private var surface: UnsafeMutableRawPointer?
+    private var swapchain: UnsafeMutableRawPointer?
+    private var commandPool: UnsafeMutableRawPointer?
+    private var graphicsQueue: UnsafeMutableRawPointer?
+    private var presentQueue: UnsafeMutableRawPointer?
+    
+    // Resource storage
+    private var meshes: [MeshHandle: VulkanMesh] = [:]
+    private var textures: [TextureHandle: VulkanTexture] = [:]
+    private var materials: [MaterialHandle: VulkanMaterial] = [:]
+    
+    private var currentFrameIndex: UInt32 = 0
+    private let maxFramesInFlight: UInt32 = 2
+    
+    public init() {
+        print("    🌋 VulkanRenderer created")
+    }
+    
+    // MARK: - Renderer Protocol Implementation
+    
+    public func initialize(config: RendererConfig) async throws {
+        print("    → Initializing Vulkan renderer...")
+        self.config = config
+        
+        // 1. Create Vulkan Instance
+        try createInstance()
+        
+        // 2. Create Surface (from window handle)
+        try createSurface(windowHandle: config.windowHandle)
+        
+        // 3. Pick Physical Device (GPU)
+        try pickPhysicalDevice()
+        
+        // 4. Create Logical Device
+        try createLogicalDevice()
+        
+        // 5. Create Swapchain
+        try createSwapchain(width: config.width, height: config.height, vsync: config.vsyncEnabled)
+        
+        // 6. Create Command Pools and Buffers
+        try createCommandResources()
+        
+        // 7. Create Render Pass
+        try createRenderPass()
+        
+        // 8. Create Framebuffers
+        try createFramebuffers()
+        
+        // 9. Create Graphics Pipeline
+        try createGraphicsPipeline()
+        
+        // 10. Create Descriptor Sets for materials
+        try createDescriptorResources()
+        
+        isInitialized = true
+        print("    ✓ Vulkan renderer initialized")
+    }
+    
+    public func beginFrame() throws {
+        guard isInitialized else { throw RendererError.notInitialized }
+        
+        // Wait for previous frame to finish
+        // Acquire next swapchain image
+        // Begin command buffer recording
+    }
+    
+    public func draw(scene: Scene) throws {
+        guard isInitialized else { throw RendererError.notInitialized }
+        
+        // Begin render pass
+        // Set viewport and scissor
+        // Bind pipeline
+        
+        // Draw each entity
+        for entity in scene.entities {
+            // Set up push constants / uniform buffers
+            // Bind vertex and index buffers
+            // Draw indexed
+            drawEntity(entity, camera: scene.camera)
+        }
+        
+        // End render pass
+    }
+    
+    public func endFrame() throws {
+        guard isInitialized else { throw RendererError.notInitialized }
+        
+        // End command buffer
+        // Submit to graphics queue
+        // Present to swapchain
+        
+        currentFrameIndex = (currentFrameIndex + 1) % maxFramesInFlight
+    }
+    
+    public func shutdown() async {
+        print("    → Shutting down Vulkan renderer...")
+        
+        // Wait for device idle
+        // Destroy all resources in reverse order
+        destroyDescriptorResources()
+        destroyGraphicsPipeline()
+        destroyFramebuffers()
+        destroyRenderPass()
+        destroyCommandResources()
+        destroySwapchain()
+        destroyLogicalDevice()
+        destroySurface()
+        destroyInstance()
+        
+        isInitialized = false
+        print("    ✓ Vulkan renderer shutdown complete")
+    }
+    
+    public func loadMesh(vertices: [Vertex], indices: [UInt32]) async throws -> MeshHandle {
+        let handle = MeshHandle()
+        
+        // Create Vulkan vertex buffer
+        // Create Vulkan index buffer
+        // Upload data to GPU
+        
+        let vulkanMesh = VulkanMesh(
+            vertexBuffer: nil,
+            indexBuffer: nil,
+            vertexCount: UInt32(vertices.count),
+            indexCount: UInt32(indices.count)
+        )
+        
+        meshes[handle] = vulkanMesh
+        return handle
+    }
+    
+    public func loadTexture(data: Data, width: Int, height: Int, format: TextureFormat) async throws -> TextureHandle {
+        let handle = TextureHandle()
+        
+        // Create Vulkan image
+        // Create Vulkan image view
+        // Create Vulkan sampler
+        // Upload texture data
+        
+        let vulkanTexture = VulkanTexture(
+            image: nil,
+            imageView: nil,
+            sampler: nil,
+            width: width,
+            height: height
+        )
+        
+        textures[handle] = vulkanTexture
+        return handle
+    }
+    
+    public func createMaterial(albedoTexture: TextureHandle?, normalTexture: TextureHandle?) async throws -> MaterialHandle {
+        let handle = MaterialHandle()
+        
+        // Create descriptor set for this material
+        // Bind textures to descriptor set
+        
+        let vulkanMaterial = VulkanMaterial(
+            descriptorSet: nil,
+            albedoTexture: albedoTexture,
+            normalTexture: normalTexture
+        )
+        
+        materials[handle] = vulkanMaterial
+        return handle
+    }
+    
+    public var info: RendererInfo {
+        return RendererInfo(
+            apiName: "Vulkan",
+            apiVersion: "1.3",
+            deviceName: "Vulkan Device (placeholder)",
+            maxTextureSize: 16384
+        )
+    }
+    
+    // MARK: - Vulkan-Specific Implementation
+    
+    private func createInstance() throws {
+        print("      • Creating Vulkan instance...")
+        // vkCreateInstance(...) with validation layers in debug
+    }
+    
+    private func createSurface(windowHandle: UnsafeMutableRawPointer?) throws {
+        print("      • Creating Vulkan surface...")
+        // Platform-specific surface creation:
+        // - Linux: vkCreateXlibSurfaceKHR or vkCreateWaylandSurfaceKHR
+        // - Windows: vkCreateWin32SurfaceKHR
+    }
+    
+    private func pickPhysicalDevice() throws {
+        print("      • Selecting physical device...")
+        // vkEnumeratePhysicalDevices
+        // Score devices and pick best one (dedicated GPU preferred)
+    }
+    
+    private func createLogicalDevice() throws {
+        print("      • Creating logical device...")
+        // vkCreateDevice with required extensions and features
+    }
+    
+    private func createSwapchain(width: Int, height: Int, vsync: Bool) throws {
+        print("      • Creating swapchain (\(width)x\(height))...")
+        // vkCreateSwapchainKHR with appropriate format and present mode
+    }
+    
+    private func createCommandResources() throws {
+        print("      • Creating command resources...")
+        // vkCreateCommandPool
+        // vkAllocateCommandBuffers
+    }
+    
+    private func createRenderPass() throws {
+        print("      • Creating render pass...")
+        // vkCreateRenderPass with color and depth attachments
+    }
+    
+    private func createFramebuffers() throws {
+        print("      • Creating framebuffers...")
+        // vkCreateFramebuffer for each swapchain image
+    }
+    
+    private func createGraphicsPipeline() throws {
+        print("      • Creating graphics pipeline...")
+        // Load shaders (SPIR-V)
+        // vkCreateGraphicsPipelines with all state
+    }
+    
+    private func createDescriptorResources() throws {
+        print("      • Creating descriptor resources...")
+        // vkCreateDescriptorSetLayout
+        // vkCreateDescriptorPool
+    }
+    
+    private func drawEntity(_ entity: Entity, camera: Camera) {
+        // Bind mesh
+        // Bind material
+        // Set push constants (MVP matrix)
+        // vkCmdDrawIndexed
+    }
+    
+    // MARK: - Cleanup
+    
+    private func destroyDescriptorResources() {
+        // vkDestroyDescriptorPool
+        // vkDestroyDescriptorSetLayout
+    }
+    
+    private func destroyGraphicsPipeline() {
+        // vkDestroyPipeline
+        // vkDestroyPipelineLayout
+    }
+    
+    private func destroyFramebuffers() {
+        // vkDestroyFramebuffer for each
+    }
+    
+    private func destroyRenderPass() {
+        // vkDestroyRenderPass
+    }
+    
+    private func destroyCommandResources() {
+        // vkFreeCommandBuffers
+        // vkDestroyCommandPool
+    }
+    
+    private func destroySwapchain() {
+        // vkDestroySwapchainKHR
+    }
+    
+    private func destroyLogicalDevice() {
+        // vkDestroyDevice
+    }
+    
+    private func destroySurface() {
+        // vkDestroySurfaceKHR
+    }
+    
+    private func destroyInstance() {
+        // vkDestroyInstance
+    }
+}
+
+// MARK: - Vulkan Resource Types
+
+private struct VulkanMesh {
+    var vertexBuffer: UnsafeMutableRawPointer?
+    var indexBuffer: UnsafeMutableRawPointer?
+    var vertexCount: UInt32
+    var indexCount: UInt32
+}
+
+private struct VulkanTexture {
+    var image: UnsafeMutableRawPointer?
+    var imageView: UnsafeMutableRawPointer?
+    var sampler: UnsafeMutableRawPointer?
+    var width: Int
+    var height: Int
+}
+
+private struct VulkanMaterial {
+    var descriptorSet: UnsafeMutableRawPointer?
+    var albedoTexture: TextureHandle?
+    var normalTexture: TextureHandle?
+}
+
+// MARK: - Errors
+
+private enum RendererError: Error {
+    case notInitialized
+    case vulkanError(String)
+}
+