# AeThex Engine - Cloud Services Architecture ## Vision Cloud-first game engine infrastructure providing authentication, multiplayer backend, cloud saves, analytics, and asset delivery - making online games trivial to build. --- ## Core Services ### 1. Authentication & User Management - Email/password, OAuth (Google, GitHub, Discord) - User profiles and preferences - Team/organization management - Permission systems ### 2. Cloud Saves & Sync - Automatic save game cloud sync - Cross-platform save compatibility - Conflict resolution - Version history ### 3. Multiplayer Backend - Matchmaking service - Real-time relay servers - P2P connection facilitation - Voice/text chat infrastructure ### 4. Analytics & Telemetry - Player behavior tracking - Performance metrics - Crash reporting - A/B testing framework ### 5. Asset Delivery Network (CDN) - DLC/update distribution - Asset streaming - Version management - Bandwidth optimization ### 6. Leaderboards & Achievements - Global/friend leaderboards - Achievement system - Player statistics - Social features --- ## System Architecture ### High-Level Overview ``` ┌─────────────────────────────────────────────────────┐ │ AeThex Game (Client) │ │ ┌──────────────────────────────────────────────┐ │ │ │ AeThex Cloud SDK (GDScript/C++) │ │ │ │ • Auth • Saves • Multiplayer • Analytics │ │ │ └──────────────────────────────────────────────┘ │ │ ↓ HTTPS/WebSocket ↓ │ └─────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────┐ │ API Gateway (Load Balancer) │ │ • Rate Limiting • Authentication │ │ • Request Routing • SSL Termination │ └─────────────────────────────────────────────────────┘ ↓ ┌──────────────┬──────────────┬──────────────┬─────────┐ │ Auth │ Saves │ Multiplayer │Analytics│ │ Service │ Service │ Service │ Service │ │ │ │ │ │ │ Node.js │ Go/Rust │ C++/Rust │ Python │ │ PostgreSQL │ S3/Object │ WebSocket │ ClickH.│ └──────────────┴──────────────┴──────────────┴─────────┘ ``` --- ## Module Structure (Engine Side) ``` engine/modules/aethex_cloud/ ├── SCsub ├── config.py ├── register_types.h/cpp ├── aethex_cloud.h/cpp # Main singleton ├── auth/ │ ├── auth_manager.h/cpp # Authentication │ ├── user_profile.h/cpp # User data │ └── session_manager.h/cpp # Session handling ├── saves/ │ ├── cloud_save_manager.h/cpp # Save sync │ ├── save_conflict_resolver.h/cpp │ └── save_metadata.h/cpp ├── multiplayer/ │ ├── matchmaking.h/cpp # Matchmaking │ ├── relay_client.h/cpp # Relay connection │ ├── voice_chat.h/cpp # Voice integration │ └── room_manager.h/cpp # Room/lobby system ├── analytics/ │ ├── analytics_manager.h/cpp # Event tracking │ ├── crash_reporter.h/cpp # Crash reports │ └── performance_tracker.h/cpp # Performance ├── cdn/ │ ├── asset_downloader.h/cpp # Asset loading │ ├── dlc_manager.h/cpp # DLC handling │ └── update_checker.h/cpp # Updates ├── social/ │ ├── leaderboard.h/cpp # Leaderboards │ ├── achievements.h/cpp # Achievements │ └── friends_list.h/cpp # Social features ├── api/ │ ├── http_client.h/cpp # HTTP requests │ ├── websocket_client.h/cpp # WebSocket │ └── api_request.h/cpp # Request builder └── ui/ ├── auth_dialog.h/cpp # Login UI ├── cloud_panel.h/cpp # Cloud dashboard └── analytics_viewer.h/cpp # Analytics view ``` --- ## Backend Services ### Tech Stack Recommendation #### Authentication Service **Technology:** Node.js + Express + PostgreSQL **Responsibilities:** - User registration/login - JWT token generation - OAuth integration - Password reset - Email verification **API Endpoints:** ``` POST /api/v1/auth/register POST /api/v1/auth/login POST /api/v1/auth/refresh POST /api/v1/auth/logout GET /api/v1/auth/profile PUT /api/v1/auth/profile POST /api/v1/auth/oauth/google ``` #### Cloud Save Service **Technology:** Go/Rust + S3/MinIO **Responsibilities:** - Store save game data - Version management - Conflict resolution - Compression **API Endpoints:** ``` GET /api/v1/saves/:user_id POST /api/v1/saves/:user_id GET /api/v1/saves/:user_id/:save_id DELETE /api/v1/saves/:user_id/:save_id GET /api/v1/saves/:user_id/history ``` #### Multiplayer Service **Technology:** C++/Rust + WebSocket/UDP **Responsibilities:** - Real-time relay - Matchmaking - Room management - Voice chat (WebRTC) **WebSocket Events:** ``` // Client → Server join_room leave_room send_message player_state_update // Server → Client room_joined room_left player_joined player_left state_update ``` #### Analytics Service **Technology:** Python/Go + ClickHouse/TimescaleDB **Responsibilities:** - Event ingestion - Real-time analytics - Crash report storage - Query API --- ## Client SDK (GDScript API) ### Authentication ```gdscript # Singleton: AeThexCloud # Login var result = await AeThexCloud.auth.login_email("user@example.com", "password") if result.success: print("Logged in as: ", result.user.username) # OAuth Login AeThexCloud.auth.login_oauth("google") # Get current user var user = AeThexCloud.auth.get_current_user() print(user.email, user.username, user.avatar_url) # Logout AeThexCloud.auth.logout() ``` ### Cloud Saves ```gdscript # Save game to cloud var save_data = { "level": 5, "health": 100, "inventory": ["sword", "shield"], "position": Vector3(10, 0, 20) } var result = await AeThexCloud.saves.save("slot1", save_data) if result.success: print("Game saved to cloud") # Load from cloud var loaded = await AeThexCloud.saves.load("slot1") if loaded.success: var data = loaded.data player.level = data.level player.health = data.health # List all saves var saves_list = await AeThexCloud.saves.list() for save in saves_list: print(save.name, save.timestamp, save.size) # Auto-sync (background) AeThexCloud.saves.enable_auto_sync(true) ``` ### Multiplayer ```gdscript # Join matchmaking AeThexCloud.multiplayer.matchmaking.join_queue({ "mode": "deathmatch", "region": "us-east", "skill_range": [1000, 1500] }) # Handle match found AeThexCloud.multiplayer.matchmaking.match_found.connect(func(match_info): print("Match found! Joining room: ", match_info.room_id) AeThexCloud.multiplayer.join_room(match_info.room_id) ) # Send player state AeThexCloud.multiplayer.send_state({ "position": player.position, "rotation": player.rotation, "health": player.health }) # Receive other players' state AeThexCloud.multiplayer.player_state_received.connect(func(player_id, state): var other_player = get_node("Player_" + str(player_id)) other_player.position = state.position other_player.rotation = state.rotation ) # Voice chat AeThexCloud.multiplayer.voice.enable(true) AeThexCloud.multiplayer.voice.mute_player(player_id, true) ``` ### Analytics ```gdscript # Track events AeThexCloud.analytics.track_event("level_completed", { "level": 5, "time": 120.5, "deaths": 3 }) # Track custom metrics AeThexCloud.analytics.track_metric("fps", Engine.get_frames_per_second()) # Track screen view AeThexCloud.analytics.track_screen("main_menu") # User properties AeThexCloud.analytics.set_user_property("vip_status", true) # Crash reporting (automatic) AeThexCloud.analytics.enable_crash_reporting(true) ``` ### Leaderboards ```gdscript # Submit score AeThexCloud.social.leaderboards.submit_score("high_scores", 1000) # Get leaderboard var leaderboard = await AeThexCloud.social.leaderboards.get("high_scores", { "range": "global", # or "friends" "limit": 10 }) for entry in leaderboard: print(entry.rank, entry.username, entry.score) ``` ### Achievements ```gdscript # Unlock achievement AeThexCloud.social.achievements.unlock("first_kill") # Track progress AeThexCloud.social.achievements.set_progress("kill_100_enemies", 45) # Get all achievements var achievements = await AeThexCloud.social.achievements.get_all() for ach in achievements: print(ach.name, ach.unlocked, ach.progress) ``` --- ## Security & Privacy ### Authentication - JWT tokens with short expiry (15 min) - Refresh tokens (30 days) - Secure password hashing (bcrypt/argon2) - Rate limiting on auth endpoints - CAPTCHA for registration ### Data Encryption - TLS 1.3 for all communications - At-rest encryption for save data - End-to-end encryption for voice chat - Encrypted credentials storage ### Privacy - GDPR compliant - COPPA compliant (for kids' games) - Opt-in analytics only - Data deletion on request - Privacy policy integration --- ## Pricing Model ### Free Tier - 5,000 monthly active users - 1 GB cloud saves per user - 100 GB CDN bandwidth - Basic analytics - Community support ### Pro Tier ($99/month) - 50,000 MAU - 5 GB cloud saves per user - 1 TB CDN bandwidth - Advanced analytics - Priority support - Custom branding ### Enterprise (Custom) - Unlimited MAU - Custom storage - Dedicated servers - 24/7 support - SLA guarantees - White-label options --- ## Implementation Phases ### Phase 1: Foundation (Month 1-2) - [ ] Basic auth service - [ ] Simple cloud saves - [ ] API client in engine - [ ] UI dialogs ### Phase 2: Multiplayer (Month 3-4) - [ ] Matchmaking service - [ ] Relay servers - [ ] Room management - [ ] Basic voice chat ### Phase 3: Analytics (Month 5-6) - [ ] Event tracking - [ ] Crash reporting - [ ] Dashboard UI - [ ] Query system ### Phase 4: Social (Month 7-8) - [ ] Leaderboards - [ ] Achievements - [ ] Friends system - [ ] Social sharing ### Phase 5: CDN & DLC (Month 9-12) - [ ] Asset delivery - [ ] DLC management - [ ] Update system - [ ] Version control --- ## Deployment ### Infrastructure (Kubernetes) ```yaml # Simplified deployment structure apiVersion: apps/v1 kind: Deployment metadata: name: aethex-auth-service spec: replicas: 3 selector: matchLabels: app: aethex-auth template: metadata: labels: app: aethex-auth spec: containers: - name: auth image: aethex/auth-service:latest ports: - containerPort: 8080 env: - name: DATABASE_URL valueFrom: secretKeyRef: name: db-credentials key: url ``` ### Monitoring - Prometheus + Grafana - Error tracking (Sentry) - Log aggregation (ELK/Loki) - Uptime monitoring - Cost tracking --- ## Migration Path ### For Developers 1. Install AeThex Cloud module 2. Sign up for cloud account 3. Get API keys 4. Add cloud SDK to project 5. Implement auth/saves/multiplayer 6. Test thoroughly 7. Deploy games with cloud features ### For Players 1. Create AeThex account (optional) 2. Cloud saves work automatically 3. Multiplayer just works 4. Cross-platform progress --- ## Competitive Advantages **vs. Custom Backend:** - Zero infrastructure management - Built-in best practices - Automatic scaling - Cost-effective **vs. PlayFab/GameSparks:** - Engine-integrated (not third-party) - Open-source friendly - More affordable - Better DX for AeThex users **vs. Epic Online Services:** - Language-agnostic - No platform lock-in - More flexible pricing - Indie-friendly --- **Next Steps:** Build auth service MVP + basic cloud saves --- ## API Protocol Specifications ### REST API Standards **Base URL:** `https://api.aethex.io/v1` **Request Format:** ```json { "jsonrpc": "2.0", "id": "unique-request-id", "method": "auth.login", "params": { "email": "user@example.com", "password": "hashed_password" } } ``` **Response Format:** ```json { "jsonrpc": "2.0", "id": "unique-request-id", "result": { "success": true, "data": { "user_id": "12345", "token": "jwt-token-here", "refresh_token": "refresh-token-here" } } } ``` **Error Format:** ```json { "jsonrpc": "2.0", "id": "unique-request-id", "error": { "code": -32600, "message": "Invalid credentials", "data": { "field": "password", "reason": "Password incorrect" } } } ``` ### WebSocket Protocol **Connection URL:** `wss://ws.aethex.io/v1/multiplayer` **Authentication:** ```json { "type": "auth", "token": "jwt-token-here" } ``` **Room Join:** ```json { "type": "join_room", "room_id": "ABCD-1234", "player_data": { "username": "Player1", "character": "warrior", "level": 10 } } ``` **State Update (Client → Server):** ```json { "type": "state_update", "timestamp": 1234567890, "data": { "position": {"x": 100, "y": 200, "z": 50}, "rotation": {"x": 0, "y": 45, "z": 0}, "health": 80, "custom": {} } } ``` **State Broadcast (Server → Clients):** ```json { "type": "player_state", "player_id": "67890", "timestamp": 1234567890, "data": { "position": {"x": 150, "y": 220, "z": 55}, "rotation": {"x": 0, "y": 90, "z": 0}, "health": 75 } } ``` **RPC Call:** ```json { "type": "rpc", "method": "take_damage", "target": "player_id_67890", "args": [25, "fire"] } ``` --- ## Data Formats ### Cloud Save Format **Metadata:** ```json { "save_id": "uuid-here", "user_id": "12345", "game_id": "my-awesome-game", "slot_name": "slot1", "version": "1.2.3", "timestamp": "2024-01-01T12:00:00Z", "size_bytes": 1024, "checksum": "sha256-hash", "compressed": true, "engine_version": "4.3.0" } ``` **Save Data (JSON):** ```json { "player": { "name": "Hero", "level": 15, "xp": 4500, "position": {"x": 100.5, "y": 0, "z": 200.3}, "rotation": {"x": 0, "y": 180, "z": 0} }, "inventory": [ {"id": "sword_legendary", "quantity": 1, "durability": 85}, {"id": "potion_health", "quantity": 5} ], "quests": { "completed": ["quest_1", "quest_2"], "active": ["quest_3"], "progress": {"quest_3": 2} }, "settings": { "volume": 0.8, "difficulty": "hard" } } ``` ### Analytics Event Format ```json { "event_id": "uuid", "user_id": "12345", "game_id": "my-game", "event_type": "level_completed", "timestamp": "2024-01-01T12:00:00Z", "session_id": "session-uuid", "properties": { "level": 5, "time_seconds": 120.5, "deaths": 3, "score": 1000, "difficulty": "hard" }, "device": { "os": "Windows", "os_version": "10.0.19041", "engine_version": "4.3.0", "game_version": "1.2.3" } } ``` --- ## Database Schema **services/database/schema.sql:** ```sql -- Users table CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email VARCHAR(255) UNIQUE NOT NULL, username VARCHAR(50) UNIQUE NOT NULL, password VARCHAR(255) NOT NULL, avatar_url VARCHAR(500), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, last_login TIMESTAMP, is_active BOOLEAN DEFAULT true, is_verified BOOLEAN DEFAULT false ); CREATE INDEX idx_users_email ON users(email); CREATE INDEX idx_users_username ON users(username); -- OAuth providers CREATE TABLE oauth_connections ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID REFERENCES users(id) ON DELETE CASCADE, provider VARCHAR(50) NOT NULL, provider_user_id VARCHAR(255) NOT NULL, access_token TEXT, refresh_token TEXT, expires_at TIMESTAMP, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, UNIQUE(provider, provider_user_id) ); -- Sessions CREATE TABLE sessions ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID REFERENCES users(id) ON DELETE CASCADE, token TEXT NOT NULL, refresh_token TEXT NOT NULL, expires_at TIMESTAMP NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, ip_address INET, user_agent TEXT ); -- Cloud saves CREATE TABLE cloud_saves ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID REFERENCES users(id) ON DELETE CASCADE, game_id VARCHAR(100) NOT NULL, slot_name VARCHAR(50) NOT NULL, data JSONB NOT NULL, metadata JSONB, version INTEGER DEFAULT 1, checksum VARCHAR(64), size_bytes INTEGER, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, UNIQUE(user_id, game_id, slot_name, version) ); CREATE INDEX idx_saves_user_game ON cloud_saves(user_id, game_id); -- Analytics events CREATE TABLE analytics_events ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID REFERENCES users(id) ON DELETE CASCADE, game_id VARCHAR(100) NOT NULL, event_type VARCHAR(100) NOT NULL, properties JSONB, session_id UUID, timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP, device_info JSONB ); CREATE INDEX idx_analytics_game ON analytics_events(game_id); CREATE INDEX idx_analytics_event ON analytics_events(event_type); ``` --- ## Performance & Monitoring ### Optimization Strategies **Caching (Redis):** - User sessions (15 min TTL) - User profiles (5 min TTL) - Leaderboards (1 min TTL) - Save metadata (10 min TTL) **Database:** - Connection pooling - Prepared statements - Batch inserts for analytics - Cursor-based pagination **WebSocket:** - Message batching (60 FPS → 20 FPS) - Delta compression - Binary protocol option - Automatic reconnection ### Metrics to Track **System:** - Request latency (p50, p95, p99) - Error rates by endpoint - Active connections - Cache hit rate **Business:** - Daily/Monthly Active Users - New registrations - Average session length - Cloud save frequency --- ## Implementation Guide See [API Reference](API_REFERENCE.md) for GDScript usage examples. **Development Phases:** 1. **Phase 1 (MVP):** Auth service + Cloud saves 2. **Phase 2:** Multiplayer relay + Matchmaking 3. **Phase 3:** Analytics + Crash reporting 4. **Phase 4:** Leaderboards + Achievements 5. **Phase 5:** CDN + DLC system