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:

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:

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

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

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

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

# custom.py
headless_editor = "yes"  # Remove Godot editor UI
embed_studio = "yes"      # Bundle Studio files
studio_port = 6007        # RPC server port

Build command:

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

# 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

# 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? 🚀