AeThex-Engine-Core/docs/CLOUD_SERVICES_ARCHITECTURE.md

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

# 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

# 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

# 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

# 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

# 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

# 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)

# 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.dev/v1

Request Format:

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "auth.login",
  "params": {
    "email": "user@example.com",
    "password": "hashed_password"
  }
}

Response Format:

{
  "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:

{
  "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.dev/v1/multiplayer

Authentication:

{
  "type": "auth",
  "token": "jwt-token-here"
}

Room Join:

{
  "type": "join_room",
  "room_id": "ABCD-1234",
  "player_data": {
    "username": "Player1",
    "character": "warrior",
    "level": 10
  }
}

State Update (Client → Server):

{
  "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):

{
  "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:

{
  "type": "rpc",
  "method": "take_damage",
  "target": "player_id_67890",
  "args": [25, "fire"]
}

---

Data Formats

Cloud Save Format

Metadata:

{
  "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):

{
  "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

{
  "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:

-- 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 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