AeThex-Engine-Core/docs/LAUNCHER_INTEGRATION_PLAN.md

# AeThex Studio Integration Plan

## Overview

This document outlines the strategy to merge the **AeThex Launcher** (Tauri/React app) with the **AeThex Engine** (Godot 4.7 fork) into a unified **AeThex Studio** experience.

---

## Current State Analysis

### AeThex Launcher Features (60+ components)

| Category | Features |
|----------|----------|
| **Core** | Game Library, Store, Download Manager, Auto-Update |
| **Social** | Friends, Activity Feed, AeThex Connect (messaging), Streaming, Replays |
| **Developer** | Gameforge, My Projects, AeThex Lang, Bot Dev IDE, Warden Security |
| **Community** | Forum, News Hub, Socials, Roadmap |
| **Economy** | Dev Exchange, Rewards Center, Gift System |
| **Account** | Auth (OAuth), Profile Hub, Cloud Saves, Achievements |
| **Settings** | Theme Engine, Sound System, Keyboard Shortcuts, Controller Mode |
| **Family** | Family Sharing, Parental Controls |
| **Testing** | Beta Testing Hub, Version Channels, Labs, Preview |
| **Modes** | Player, Creator, Corp, Foundation (different home screens) |

### AeThex Engine (Current)

- Godot 4.7 fork with custom modules
- Project Manager with new tabs (Terminal, Community, Cloud, Launcher)
- Custom modules: `aethex_cloud`, `aethex_telemetry`, `discord_rpc`

---

## Integration Options

### Option A: Embedded WebView (Recommended - Phase 1)

**Concept**: Embed the React launcher UI inside the engine using a WebView/HTML component.

**Pros**:
- Fastest to implement (weeks, not months)
- Reuses 100% of existing launcher code
- Unified window experience
- Backend/API code unchanged

**Cons**:
- Requires bundling Chromium or using system WebView
- Adds ~50MB to engine size
- Two rendering systems (Godot + Web)

**Implementation**:
```
┌─────────────────────────────────────────────────────────────┐
│                    AeThex Studio Window                      │
├──────────────┬──────────────────────────────────────────────┤
│              │                                               │
│   Sidebar    │     Tab: Launcher (WebView)                   │
│   (Native)   │     ├── React App renders here                │
│              │     └── Full launcher functionality           │
│  - Editor    │                                               │
│  - Projects  │     Tab: Editor (Native Godot)                │
│  - Launcher  │     ├── Scene editor                          │
│  - Settings  │     └── Script editor                         │
│              │                                               │
└──────────────┴──────────────────────────────────────────────┘
```

### Option B: Full Native Port (Phase 2+)

**Concept**: Rewrite all launcher features as native C++ Godot editor plugins.

**Pros**:
- Fully native, consistent UI
- No web dependencies
- Better performance
- Offline-first

**Cons**:
- 6-12 months development time
- 60+ React components → C++ translation
- Ongoing maintenance burden

**Priority Order for Native Port**:
1. Auth System (critical)
2. Game Library 
3. Cloud Saves
4. Download Manager
5. Store
6. Social/Friends
7. Everything else

### Option C: Hybrid Progressive (Recommended Long-term)

**Concept**: Start with WebView, progressively replace critical features with native.

**Phase 1** (1-2 weeks): WebView integration
**Phase 2** (1 month): Native auth + game library
**Phase 3** (2 months): Native store + downloads
**Phase 4** (ongoing): Port remaining features as needed

---

## Recommended Architecture

```
AeThex Studio
├── engine/                    # Godot 4.7 fork (C++)
│   ├── editor/
│   │   ├── project_manager/   # Enhanced project manager
│   │   └── launcher/          # NEW: Native launcher module
│   │       ├── auth_ui.cpp         # Native auth screens
│   │       ├── game_library.cpp    # Native game browser
│   │       ├── webview_panel.cpp   # WebView for web features
│   │       └── launcher_api.cpp    # Communication layer
│   └── modules/
│       ├── aethex_cloud/      # Cloud saves, sync
│       ├── aethex_auth/       # NEW: Native auth (Supabase)
│       └── aethex_store/      # NEW: Store API client
│
├── launcher-web/              # Embedded React app
│   ├── dist/                  # Built React app
│   └── src/                   # Source (from current launcher)
│
└── platform/
    └── windows/
        └── webview/           # Platform-specific WebView
```

---

## Phase 1 Implementation Plan (WebView)

### Step 1: Add WebView Support to Engine

```cpp
// modules/webview/webview_panel.h
class WebViewPanel : public Control {
    GDCLASS(WebViewPanel, Control);
    
    void navigate(const String &url);
    void load_html(const String &html);
    void execute_javascript(const String &script);
    void set_communication_callback(Callable callback);
};
```

### Step 2: Create Launcher Tab in Project Manager

The launcher tab will host a WebView that loads the React app:

```cpp
// In ProjectManager
void _create_launcher_tab() {
    WebViewPanel *webview = memnew(WebViewPanel);
    webview->navigate("file:///launcher/index.html");
    // or
    webview->navigate("https://launcher.aethex.dev");
}
```

### Step 3: Bridge Communication

JavaScript ↔ C++ communication for:
- Launching games (JS calls C++ to spawn processes)
- File system access (downloads, installations)
- Native OS features (notifications, file dialogs)

```cpp
// launcher_bridge.cpp
void LauncherBridge::handle_message(const String &message) {
    Dictionary data = JSON::parse_string(message);
    String action = data.get("action", "");
    
    if (action == "launch_game") {
        String exe_path = data.get("path", "");
        OS::get_singleton()->execute(exe_path, args);
    }
    else if (action == "open_editor") {
        EditorNode::get_singleton()->open_request(data.get("project_path", ""));
    }
}
```

### Step 4: Bundle React App

Build the React launcher and include it in the engine distribution:

```
aethex-studio/
├── bin/
│   └── aethex.windows.editor.x86_64.exe
└── launcher/
    ├── index.html
    ├── assets/
    └── *.js
```

---

## Phase 2 Implementation Plan (Native Critical Features)

### Native Auth Module

```cpp
// modules/aethex_auth/aethex_auth.h
class AeThexAuth : public Object {
    GDCLASS(AeThexAuth, Object);
    
    static AeThexAuth *singleton;
    
    String supabase_url;
    String supabase_anon_key;
    String current_token;
    Dictionary user_profile;
    
public:
    Error sign_in_with_email(const String &email, const String &password);
    Error sign_in_with_oauth(const String &provider); // google, discord, github
    Error sign_out();
    Error refresh_token();
    
    bool is_authenticated() const;
    Dictionary get_user() const;
    Dictionary get_launcher_profile() const;
    
    Signal user_signed_in;
    Signal user_signed_out;
    Signal profile_updated;
};
```

### Native Game Library

```cpp
// modules/aethex_launcher/game_library.h
class GameLibrary : public Control {
    GDCLASS(GameLibrary, Control);
    
    struct GameEntry {
        String id;
        String title;
        String cover_image;
        String install_path;
        String status; // installed, downloading, available
        float download_progress;
        String version;
    };
    
    Vector<GameEntry> games;
    
    void refresh_library();
    void launch_game(const String &game_id);
    void install_game(const String &game_id);
    void uninstall_game(const String &game_id);
    void update_game(const String &game_id);
};
```

---

## Backend Integration

The launcher uses Supabase for:

| Service | Purpose |
|---------|---------|
| **Auth** | User authentication, OAuth providers |
| **Database** | Profiles, games, achievements, friends |
| **Storage** | Avatars, cloud saves, game assets |
| **Realtime** | Friend status, notifications |
| **Edge Functions** | Store transactions, webhooks |

The engine will need HTTP clients to call these APIs:

```cpp
// Example: Fetch user profile
HTTPRequest *http = memnew(HTTPRequest);
http->connect("request_completed", callable_mp(this, &AeThexAuth::_on_profile_fetched));
http->request(
    supabase_url + "/rest/v1/launcher_profiles?user_id=eq." + user_id,
    PackedStringArray({"apikey: " + anon_key, "Authorization: Bearer " + token})
);
```

---

## File Structure After Integration

```
AeThex-Engine-Core/
├── engine/
│   ├── editor/
│   │   ├── project_manager/
│   │   │   ├── project_manager.cpp     # Has launcher tab with WebView
│   │   │   └── project_manager.h
│   │   └── launcher/                   # NEW directory
│   │       ├── launcher_bridge.cpp     # JS ↔ C++ bridge
│   │       ├── launcher_bridge.h
│   │       ├── native_auth_panel.cpp   # Native auth UI
│   │       ├── native_auth_panel.h
│   │       └── SCsub
│   ├── modules/
│   │   ├── aethex_auth/                # NEW module
│   │   │   ├── aethex_auth.cpp
│   │   │   ├── aethex_auth.h
│   │   │   ├── config.py
│   │   │   ├── register_types.cpp
│   │   │   ├── register_types.h
│   │   │   └── SCsub
│   │   ├── aethex_cloud/               # Existing (enhanced)
│   │   ├── webview/                    # NEW module
│   │   │   ├── webview_panel.cpp
│   │   │   ├── webview_panel.h
│   │   │   └── platform/
│   │   │       ├── webview_windows.cpp # WebView2 on Windows
│   │   │       ├── webview_macos.mm    # WKWebView on macOS
│   │   │       └── webview_linux.cpp   # WebKitGTK on Linux
│   │   └── ...
│   └── platform/
└── launcher-web/                       # Bundled React app
    ├── build.sh
    ├── package.json
    └── dist/                           # Built output
```

---

## Timeline Estimate

| Phase | Duration | Deliverable |
|-------|----------|-------------|
| **Phase 1a** | 1 week | WebView module for Windows (WebView2) |
| **Phase 1b** | 1 week | Launcher tab integration + JS bridge |
| **Phase 1c** | 3 days | Bundle React app + build pipeline |
| **Phase 2a** | 2 weeks | Native auth module |
| **Phase 2b** | 2 weeks | Native game library |
| **Phase 2c** | 1 week | Native download manager |
| **Phase 3+** | Ongoing | Port remaining features as needed |

---

## Decision Points

### Question 1: WebView Library
- **Windows**: WebView2 (Edge/Chromium) - recommended
- **Alternative**: CEF (Chromium Embedded Framework) - more control, larger size

### Question 2: Initial Distribution
- **Option A**: Ship with embedded web app (offline-capable)
- **Option B**: Load from `https://launcher.aethex.dev` (always latest)
- **Recommended**: Option A with update check

### Question 3: Auth Flow
- **Option A**: WebView handles auth entirely
- **Option B**: Native OAuth browser popup → callback to engine
- **Recommended**: Option A for Phase 1, Option B for Phase 2

---

## Next Steps

1. **Decide on approach** (WebView vs Native-first)
2. **Set up WebView2 in engine** (if WebView approach)
3. **Build React launcher** for embedding
4. **Create JS↔C++ bridge** for native features
5. **Test end-to-end flow**

---

## Notes

- The current launcher at `A:\AeThex Launcher\AeThex-Landing-Page` has 40+ pages and 60+ components
- Full native port would be ~10,000+ lines of C++ code
- WebView approach allows immediate integration with gradual native migration
- Consider keeping WebView for "web-heavy" features (forum, store, socials) even after native port