first commit

2025-11-24 23:10:55 -06:00
commit 8315fa51c9
279 changed files with 74600 additions and 0 deletions
--- a/godot_client/docs/EXPORT.md
+++ b/godot_client/docs/EXPORT.md
@@ -0,0 +1,413 @@
+# Export Configuration Guide
+
+## Overview
+
+Code of Conquest targets multiple platforms:
+- Desktop: Windows, macOS, Linux
+- Mobile: Android, iOS
+- Web: HTML5/WebAssembly
+
+Each platform requires specific configuration in Godot's export system.
+
+## Prerequisites
+
+### 1. Install Export Templates
+
+In Godot Editor:
+1. Editor → Manage Export Templates
+2. Click "Download and Install"
+3. Wait for templates to download (~300-500 MB)
+
+Alternatively, download manually from [Godot downloads](https://godotengine.org/download).
+
+### 2. Platform-Specific Requirements
+
+#### Windows
+- **Template**: Included by default
+- **Optional**: Custom icon (.ico file)
+- **Optional**: Code signing certificate for production
+
+#### macOS
+- **Template**: Included by default
+- **Requirements** (for distribution):
+  - macOS machine for final build
+  - Apple Developer account ($99/year)
+  - Code signing certificate
+  - Notarization for Gatekeeper
+
+#### Linux
+- **Template**: Included by default
+- **Note**: Export on Linux for best results
+- **Distribution**: AppImage, Flatpak, or raw binary
+
+#### Android
+- **Android SDK**: API level 33+ (Android 13)
+  - Download via Android Studio or command-line tools
+  - Set path in Godot: Editor → Editor Settings → Export → Android → SDK Path
+
+- **Java JDK**: Version 17 or later
+
+- **Keystore for Signing**:
+  ```bash
+  keytool -genkey -v -keystore code_of_conquest.keystore \
+    -alias coc_key -keyalg RSA -keysize 2048 -validity 10000
+  ```
+
+- **Package Name**: `com.codeofconquest.game`
+
+#### iOS
+- **Requirements**:
+  - macOS with Xcode installed
+  - Apple Developer account ($99/year)
+  - Provisioning profile
+  - Code signing certificate
+
+- **Bundle ID**: `com.codeofconquest.game`
+
+- **Export Process**:
+  1. Export Xcode project from Godot
+  2. Open in Xcode
+  3. Configure signing
+  4. Build for device or App Store
+
+#### Web (HTML5)
+- **Template**: Included by default
+- **Server Requirements**:
+  - HTTPS (for SharedArrayBuffer support)
+  - CORS headers for cross-origin resources
+  - Proper MIME types for .wasm files
+
+- **PWA Configuration** (optional):
+  - Manifest file for installability
+  - Service worker for offline support
+  - Icons in multiple sizes
+
+## Configuration Steps
+
+### Step 1: Open Export Window
+
+In Godot:
+1. Project → Export
+2. Click "Add..." to add a new preset
+
+### Step 2: Configure Each Platform
+
+#### Windows Export
+
+1. Add → Windows Desktop
+2. Configure:
+   - **Executable Name**: `CodeOfConquest.exe`
+   - **Export Path**: `builds/windows/CodeOfConquest.exe`
+   - **Icon**: `assets/ui/icon.ico` (optional)
+   - **Embed PCK**: `true` (for single-file distribution)
+
+3. Features:
+   - 64-bit: Recommended for modern systems
+   - 32-bit: Optional for older systems
+
+#### Linux Export
+
+1. Add → Linux/X11
+2. Configure:
+   - **Executable Name**: `CodeOfConquest.x86_64`
+   - **Export Path**: `builds/linux/CodeOfConquest.x86_64`
+   - **Embed PCK**: `true`
+
+3. After export, set executable permissions:
+   ```bash
+   chmod +x CodeOfConquest.x86_64
+   ```
+
+#### macOS Export
+
+1. Add → macOS
+2. Configure:
+   - **App Name**: `Code of Conquest`
+   - **Bundle ID**: `com.codeofconquest.game`
+   - **Export Path**: `builds/macos/CodeOfConquest.dmg`
+   - **Icon**: `assets/ui/icon.icns` (optional)
+
+3. For distribution:
+   - Set code signing identity
+   - Enable hardened runtime
+   - Enable notarization
+
+#### Android Export
+
+1. Add → Android
+2. Configure:
+   - **Package Name**: `com.codeofconquest.game`
+   - **Version Code**: `1` (increment for each release)
+   - **Version Name**: `0.1.0`
+   - **Min SDK**: `21` (Android 5.0)
+   - **Target SDK**: `33` (Android 13)
+
+3. Keystore:
+   - **Debug Keystore**: Auto-generated (for testing)
+   - **Release Keystore**: Path to your `.keystore` file
+   - **Release User**: Keystore alias (e.g., `coc_key`)
+   - **Release Password**: Your keystore password
+
+4. Permissions (add in export preset):
+   - `INTERNET` - Required for API calls
+   - `ACCESS_NETWORK_STATE` - Check connectivity
+
+5. Screen Orientation:
+   - Landscape or Portrait (choose based on game design)
+
+6. Graphics:
+   - Renderer: GL Compatibility (best mobile support)
+
+7. Export:
+   - **APK**: For direct installation/testing
+   - **AAB** (Android App Bundle): For Google Play Store
+
+#### iOS Export
+
+1. Add → iOS
+2. Configure:
+   - **Bundle ID**: `com.codeofconquest.game`
+   - **Version**: `0.1.0`
+   - **Icon**: Multiple sizes required (see Xcode)
+   - **Orientation**: Landscape or Portrait
+
+3. Provisioning:
+   - **Team ID**: From Apple Developer account
+   - **Provisioning Profile**: Development or Distribution
+
+4. Export:
+   - Export as Xcode project
+   - Open in Xcode for final build
+
+5. Capabilities (configure in Xcode):
+   - Network requests
+   - Push notifications (if needed later)
+
+#### Web Export
+
+1. Add → HTML5
+2. Configure:
+   - **Export Path**: `builds/web/index.html`
+   - **Export Type**: Regular or PWA
+   - **Head Include**: Custom HTML header (optional)
+
+3. Features:
+   - **Thread Support**: Enable for better performance (requires COOP/COEP headers)
+   - **SharedArrayBuffer**: Requires HTTPS + specific headers
+
+4. Server Configuration:
+   - Must serve with proper MIME types:
+     - `.wasm`: `application/wasm`
+     - `.pck`: `application/octet-stream`
+
+5. CORS Headers (for threaded builds):
+   ```
+   Cross-Origin-Opener-Policy: same-origin
+   Cross-Origin-Embedder-Policy: require-corp
+   ```
+
+6. PWA Manifest (optional):
+   ```json
+   {
+     "name": "Code of Conquest",
+     "short_name": "CoC",
+     "start_url": ".",
+     "display": "standalone",
+     "background_color": "#1a1a2e",
+     "theme_color": "#d4af37",
+     "icons": [...]
+   }
+   ```
+
+## Testing Exports
+
+### Desktop Testing
+
+1. Export to local directory
+2. Run executable directly
+3. Test with backend running on localhost
+4. Verify:
+   - Window sizing and fullscreen
+   - Keyboard/mouse input
+   - API connectivity
+   - Save/load functionality
+
+### Mobile Testing
+
+#### Android
+1. Enable USB debugging on device
+2. Connect via USB
+3. Use `adb install` to install APK:
+   ```bash
+   adb install builds/android/CodeOfConquest.apk
+   ```
+4. Or export to device directly from Godot (Debug → Deploy)
+
+5. Verify:
+   - Touch input responsiveness
+   - Screen orientation
+   - Battery usage
+   - Network connectivity
+   - Permissions granted
+
+#### iOS
+1. Configure development provisioning
+2. Export Xcode project
+3. Open in Xcode
+4. Build to connected device
+5. Verify same as Android
+
+### Web Testing
+
+1. Export to directory
+2. Serve locally:
+   ```bash
+   python3 -m http.server 8000
+   ```
+3. Open `http://localhost:8000` in browser
+4. Verify:
+   - Loading performance
+   - Browser compatibility (Chrome, Firefox, Safari)
+   - WebGL rendering
+   - Network requests
+   - Mobile browser (responsive)
+
+## Distribution
+
+### Desktop
+
+**Windows**:
+- Distribute .exe directly
+- Or create installer (e.g., Inno Setup, NSIS)
+- Upload to Steam, itch.io, etc.
+
+**macOS**:
+- Create .dmg for distribution
+- Notarize for Gatekeeper
+- Upload to Mac App Store or direct download
+
+**Linux**:
+- Raw binary
+- AppImage (self-contained)
+- Flatpak (Flathub distribution)
+- Snap package
+
+### Mobile
+
+**Android**:
+- Google Play Store (requires AAB)
+- Amazon Appstore
+- F-Droid (open source)
+- Direct APK download (sideloading)
+
+**iOS**:
+- App Store (requires App Store Connect)
+- TestFlight (beta testing)
+- Enterprise distribution (if applicable)
+
+### Web
+
+**Hosting Options**:
+- Static hosting: Netlify, Vercel, GitHub Pages
+- CDN: Cloudflare, AWS S3 + CloudFront
+- Game platforms: itch.io (supports HTML5)
+
+**Deployment**:
+1. Export web build
+2. Upload all files (index.html, .wasm, .pck, etc.)
+3. Configure COOP/COEP headers if using threads
+4. Test on production URL
+
+## Performance Optimization
+
+### General
+- Use compressed textures (ETC2 for mobile, S3TC for desktop)
+- Minimize draw calls
+- Use LOD (Level of Detail) for 3D
+- Profile with Godot profiler
+
+### Mobile Specific
+- Reduce resolution for lower-end devices
+- Limit particle effects
+- Use simpler shaders
+- Test on low-end devices
+- Monitor battery usage
+
+### Web Specific
+- Optimize asset sizes (compress images, audio)
+- Use progressive loading for large assets
+- Minimize WASM binary size
+- Cache assets with service worker
+
+## Platform-Specific Considerations
+
+### Windows
+- Antivirus may flag unsigned executables
+- Consider code signing for production
+- Test on Windows 10 and 11
+
+### macOS
+- Gatekeeper will block unsigned apps
+- Notarization required for distribution
+- Test on both Intel and Apple Silicon (M1/M2)
+
+### Linux
+- Provide both 32-bit and 64-bit builds
+- Test on multiple distros (Ubuntu, Fedora, Arch)
+- Include library dependencies or use static linking
+
+### Android
+- Target latest API level for Play Store
+- Test on multiple screen sizes and densities
+- Handle back button properly
+- Support safe areas (notches, rounded corners)
+
+### iOS
+- Follow Apple Human Interface Guidelines
+- Support safe areas
+- Handle app lifecycle (background/foreground)
+- Test on multiple devices (iPhone, iPad)
+
+### Web
+- Fallback for browsers without WebGL
+- Loading screen for asset downloads
+- Handle browser resize events
+- Support both desktop and mobile browsers
+
+## Troubleshooting
+
+### "Missing export template"
+→ Download templates via Editor → Manage Export Templates
+
+### "Android SDK not found"
+→ Set SDK path in Editor Settings → Export → Android
+
+### "Code signing failed" (macOS/iOS)
+→ Verify certificate and provisioning profile
+
+### "Web build won't load"
+→ Check browser console, verify MIME types, check CORS
+
+### "App crashes on mobile"
+→ Check device logs (adb logcat for Android, Xcode console for iOS)
+
+## Resources
+
+- [Godot Export Documentation](https://docs.godotengine.org/en/stable/tutorials/export/)
+- [Android Publishing Guide](https://developer.android.com/studio/publish)
+- [iOS App Distribution](https://developer.apple.com/documentation/xcode/distributing-your-app-for-beta-testing-and-releases)
+- [PWA Documentation](https://web.dev/progressive-web-apps/)
+
+## Automation (Future)
+
+Consider automating builds with CI/CD:
+- GitHub Actions
+- GitLab CI
+- Jenkins
+
+Example workflow:
+1. Commit to `main` branch
+2. Trigger automated export for all platforms
+3. Run automated tests
+4. Upload builds to distribution channels
+5. Tag release with version number