AeThex-Engine-Core/docs/STUDIO_INTEGRATION.md

# AeThex Engine - Studio Integration Plan

## Overview
Replace Godot's C++ editor with AeThex Studio's web UI while keeping the powerful C++ runtime.

## Architecture

### What We Keep (C++ Engine Runtime)
- ✅ Scene system & nodes
- ✅ GDScript VM
- ✅ Physics (2D/3D)
- ✅ Rendering (Vulkan/OpenGL)
- ✅ Audio engine
- ✅ Asset pipeline
- ✅ Export system
- ✅ Networking

### What We Replace (Editor UI)
- ❌ Godot's C++ editor UI
- ❌ Built-in script editor
- ❌ Scene tree inspector
- ❌ Resource dock
- ❌ FileSystem dock

### What We Add (Studio UI)
- ✅ AeThex Studio (Next.js web app)
- ✅ Monaco editor (VS Code engine)
- ✅ AI assistant panel
- ✅ Modern UI/UX
- ✅ Web-based 3D viewport
- ✅ Cross-platform consistency

## Implementation Phases

### Phase 1: Headless Engine Mode (Week 1)
**Goal:** Strip out Godot editor, keep runtime

**Changes:**
1. Add `--headless-editor` flag to engine
2. Remove editor UI initialization
3. Keep scene/resource system accessible via API
4. Add JSON-RPC server for Studio communication

**Files to modify:**
```
engine/main/main.cpp - Add headless mode
engine/editor/editor_node.cpp - Conditional compilation
engine/core/api/ - Add JSON-RPC server
```

**Build command:**
```bash
scons platform=windows target=editor headless_editor=yes
```

### Phase 2: JSON-RPC Bridge (Week 2)
**Goal:** Communication between Studio (web) and Engine (C++)

**API Endpoints:**
```javascript
// Studio calls Engine
engine.loadScene(path)      // Load .tscn file
engine.saveScene(path)      // Save scene
engine.createNode(type)     // Spawn node
engine.setProperty(node, property, value)
engine.runGame()           // Start game
engine.stopGame()          // Stop game
engine.exportProject()     // Build game

// Engine notifies Studio
on_scene_changed()         // Scene modified
on_node_selected()         // Node clicked in viewport
on_property_changed()      // Inspector update needed
on_console_output()        // Debug messages
```

**Implementation:**
```cpp
// engine/editor/studio_bridge.h
class StudioBridge : public Object {
    GDCLASS(StudioBridge, Object);
    
private:
    HTTPServer *rpc_server;
    WebSocketServer *ws_server;
    
public:
    void start_server(int port);
    void handle_rpc_call(const String &method, const Dictionary &params);
    void send_event(const String &event, const Dictionary &data);
};
```

**Communication:**
```
Studio (localhost:3000) ←→ WebSocket ←→ Engine (localhost:6007)
```

### Phase 3: Studio UI Adaptation (Week 3)
**Goal:** Modify Studio to control the engine

**New Studio Components:**
```typescript
// studio/src/engine/
├── bridge.ts           // WebSocket to engine
├── scene-tree.tsx      // Scene hierarchy from engine
├── inspector.tsx       // Node properties from engine
├── viewport.tsx        // 3D preview (Three.js mirroring engine)
├── console.tsx         // Engine output
└── game-runner.tsx     // Play mode control
```

**Example:**
```typescript
// studio/src/engine/bridge.ts
class EngineBridge {
  private ws: WebSocket;
  
  async loadScene(path: string) {
    return await this.call('load_scene', { path });
  }
  
  async createNode(type: string) {
    return await this.call('create_node', { type });
  }
  
  onNodeSelected(callback: (node) => void) {
    this.on('node_selected', callback);
  }
}
```

### Phase 4: 3D Viewport Integration (Week 4)
**Goal:** Studio displays engine's 3D viewport

**Two approaches:**

**Approach A: Screen Sharing**
- Engine renders to texture
- Sends pixels via WebRTC/WebSocket
- Studio displays in canvas

**Approach B: Native Window**
- Engine creates separate window
- Studio embeds window handle
- Lower latency, better performance

**Recommended:** Approach B (native embedding)

### Phase 5: Packaging (Week 5)
**Goal:** Distribute as single application

**Option 1: Electron Wrapper**
```
AeThex.exe
├── electron.exe (Studio UI)
└── aethex_runtime.exe (Engine)
```

**Option 2: CEF Embedded**
```
AeThex.exe (Single binary)
├── Chromium Embedded Framework
│   └── Studio UI (embedded web)
└── Engine Runtime (C++)
```

**Recommended:** Electron (faster development)

## Technical Details

### Build System Changes

**New SCons options:**
```python
# custom.py
headless_editor = "yes"  # Remove Godot editor UI
embed_studio = "yes"      # Bundle Studio files
studio_port = 6007        # RPC server port
```

**Build command:**
```bash
scons platform=windows target=editor \
  headless_editor=yes \
  embed_studio=yes \
  -j4
```

### File Structure
```
AeThex-Engine-Core/
├── engine/              # C++ runtime
│   ├── core/
│   ├── scene/
│   ├── servers/
│   └── studio_bridge/   # NEW: Studio↔Engine API
├── studio/              # Web UI (Next.js)
│   ├── src/
│   │   ├── components/
│   │   └── engine/      # NEW: Engine integration
│   └── out/            # Build output (static files)
└── packaging/
    └── electron/        # Electron wrapper
```

### Distribution Package
```
AeThex-Engine-v1.0-windows.zip
├── AeThex.exe           # Electron app
├── resources/
│   ├── aethex_runtime.exe  # C++ engine
│   ├── studio/          # Web UI files
│   └── templates/       # Project templates
└── README.txt
```

## Development Workflow

### Local Development
```bash
# Terminal 1: Run Engine
cd engine
./bin/aethex.linuxbsd.editor.x86_64 --studio-mode --port 6007

# Terminal 2: Run Studio UI
cd studio
npm run dev

# Studio connects to localhost:6007
# Changes hot-reload automatically
```

### Production Build
```bash
# 1. Build Engine
cd engine
scons platform=windows target=editor headless_editor=yes

# 2. Build Studio
cd studio
npm run build

# 3. Package with Electron
cd packaging/electron
npm run package
```

## Testing Strategy

### Unit Tests
- Engine RPC endpoints
- Studio API client
- Scene serialization/deserialization

### Integration Tests
- Studio creates node → Engine spawns it
- Studio modifies property → Engine updates
- Engine emits event → Studio receives

### E2E Tests
- Create new project
- Add 3D scene
- Write script
- Run game
- Export project

## Performance Targets

| Metric | Target |
|--------|--------|
| Studio → Engine latency | <16ms |
| Scene load time | <2s |
| Property update | <5ms |
| Viewport FPS | 60fps |
| Memory overhead | <100MB |

## Rollout Plan

### Alpha (Internal)
- Basic scene editing
- Node creation/deletion
- Property inspector
- Script editor

### Beta (Early Users)
- 3D viewport
- Game runner
- Asset pipeline
- Export system

### V1.0 (Public)
- AI assistant
- Cross-platform export
- Template library
- Full documentation

## Timeline

| Phase | Duration | Deliverable |
|-------|----------|-------------|
| 1 | 1 week | Headless engine |
| 2 | 1 week | RPC bridge |
| 3 | 1 week | Studio UI integration |
| 4 | 1 week | 3D viewport |
| 5 | 1 week | Electron packaging |
| **Total** | **5 weeks** | **Alpha Release** |

## Next Steps

1. ✅ Create headless engine branch
2. ⬜ Implement JSON-RPC server
3. ⬜ Modify Studio for engine control
4. ⬜ Test scene editing workflow
5. ⬜ Package as Electron app

---

**Ready to start implementation?** 🚀