AeThex-Engine-Core/HEADLESS_MODE.md

# AeThex Engine - Headless Editor Mode

## Overview

Headless editor mode allows the AeThex Engine to run **without the AeThex Editor UI**, serving only as a backend for the AeThex Studio web-based interface. This enables a true Studio-first workflow where all editing happens in the TypeScript/React interface while the C++ engine handles scene management, rendering, and game logic.

## Why Headless Mode?

- **Studio-First Workflow**: Edit your game entirely through the modern AeThex Studio web interface
- **Resource Efficiency**: No need to load the heavy traditional Editor UI when using Studio
- **Cloud Deployments**: Run the engine on a server without requiring a display
- **Multiple Connections**: Multiple Studio instances can connect to the same engine backend
- **Development Flexibility**: Run engine on one machine, Studio on another (same network)

## Usage

### Basic Usage

Start the engine in headless editor mode:

```bash
./bin/aethex.linuxbsd.editor.x86_64 --headless-editor --path /path/to/your/project
```

You should see:
```
AeThex Engine running in headless editor mode.
StudioBridge available on localhost:6007
Connect from AeThex Studio to edit the project.
```

### With Specific Project

```bash
cd engine/bin
./aethex.linuxbsd.editor.x86_64 --headless-editor --path ../../my_game_project
```

### Run on Startup (Background Mode)

```bash
nohup ./bin/aethex.linuxbsd.editor.x86_64 --headless-editor --path /path/to/project > engine.log 2>&1 &
```

## What Gets Loaded in Headless Mode?

### ✅ Loaded/Active:
- Core AeThex systems (scenes, nodes, resources)
- StudioBridge HTTP server (localhost:6007)
- All module systems (GDScript, physics, rendering backend)
- Project resources and scene trees
- Editor-level APIs (you can still use EditorInterface-like features via bridge)

### ❌ NOT Loaded:
- AeThex Editor UI (EditorNode, inspector panels, scene tree panel)
- Editor window and display
- Editor-specific GUI components
- Editor addons/plugins that rely on EditorNode

## Architecture

```
┌─────────────────────────────┐
│   AeThex Studio (Web UI)    │  Port 3000 (dev server)
│   TypeScript/React          │
└──────────────┬──────────────┘
               │ HTTP Requests
               │ POST /rpc
               ▼
┌─────────────────────────────┐
│  StudioBridge (HTTP Server) │  localhost:6007
│  C++ JSON-RPC API (26 methods)
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│   AeThex Engine Core        │  Headless Mode
│   Scene Tree, Resources     │  --headless-editor
│   Rendering, Physics, etc.  │
└─────────────────────────────┘
```

## Testing Headless Mode

### 1. Start Engine in Headless Mode

```bash
cd /workspaces/AeThex-Engine-Core/engine
./bin/aethex.linuxbsd.editor.x86_64 --headless-editor
```

### 2. Test the API (in another terminal)

```bash
# Get all available node types
curl -X POST http://localhost:6007/rpc \
  -H "Content-Type: application/json" \
  -d '{"method":"getAllNodeTypes","params":{}}'

# Get current scene tree
curl -X POST http://localhost:6007/rpc \
  -H "Content-Type: application/json" \
  -d '{"method":"getSceneTree","params":{}}'

# Create a new node
curl -X POST http://localhost:6007/rpc \
  -H "Content-Type: application/json" \
  -d '{"method":"createNode","params":{"type":"Node2D","name":"MyNode","parent":""}}'
```

### 3. Connect from Studio

```bash
cd /workspaces/aethex-studio
npm run dev
# Open browser to localhost:3000
# Studio will auto-connect to engine on localhost:6007
```

## Use Cases

### Local Development
Run engine and Studio on same machine:
- **Engine**: `./aethex --headless-editor`
- **Studio**: `npm run dev` (connects to localhost:6007)

### Remote Development
Run engine on powerful desktop, Studio on laptop:
- **Desktop**: `./aethex --headless-editor` (expose port 6007)
- **Laptop**: Configure Studio to connect to desktop IP
- Edit from anywhere on your network

### Cloud IDE / Codespaces
Perfect for browser-based development:
- Engine runs in container with headless mode
- Studio UI accessed via web browser
- Full game development from iPad, Chromebook, etc.

### CI/CD Pipeline
Automate game builds and tests:
```bash
./aethex --headless-editor --path $PROJECT_PATH &
ENGINE_PID=$!
sleep 5  # Wait for engine to start
# Run automated tests via HTTP API
curl -X POST http://localhost:6007/rpc -d '{"method":"runGame","params":{}}'
# ... perform tests ...
kill $ENGINE_PID
```

## Command Line Options

### Headless Editor Mode
```
--headless-editor
```
Runs the engine with StudioBridge but without traditional Editor UI.

### Combined with Other Options

```bash
# Specify project path
./aethex --headless-editor --path /path/to/project

# Custom viewport size (for rendering)
./aethex --headless-editor --resolution 1920x1080

# Verbose logging
./aethex --headless-editor --verbose

# Custom log file
./aethex --headless-editor --log-file engine.log
```

## Comparison: Regular vs Headless Mode

| Feature | Regular Editor Mode | Headless Editor Mode |
|---------|-------------------|----------------------|
| Traditional Editor UI | ✅ Yes | ❌ No |
| StudioBridge API | ✅ Yes | ✅ Yes |
| Memory Usage | ~500MB+ | ~200MB |
| Startup Time | 5-10 seconds | 2-3 seconds |
| Display Required | Yes | No |
| Multiple Studios | Limited | ✅ Yes |
| Cloud Deployment | Difficult | ✅ Easy |

## Troubleshooting

### Engine Won't Start

**Problem**: Engine exits immediately

**Solution**: Make sure you're in editor mode (--headless-editor sets this automatically):
```bash
./aethex --headless-editor --verbose
```

### Can't Connect from Studio

**Problem**: Studio shows "Engine Disconnected"

**Solution**: 
1. Check engine is running: `ps aux | grep aethex`
2. Check port 6007 is listening: `netstat -tuln | grep 6007`
3. Test with curl: `curl http://localhost:6007/rpc`
4. Check firewall settings if connecting remotely

### Port Already in Use

**Problem**: "Address already in use" error

**Solution**: Kill existing process:
```bash
lsof -i :6007
kill <PID>
```

### Missing Project Path

**Problem**: "Project not found" error

**Solution**: Always specify project path explicitly:
```bash
./aethex --headless-editor --path /absolute/path/to/project
```

## Next Steps

1. **Test Headless Mode**
   ```bash
   cd /workspaces/AeThex-Engine-Core
   ./test_quick.sh
   ```

2. **Connect Studio**
   - Follow instructions in [ENGINE_INTEGRATION.md](../aethex-studio/ENGINE_INTEGRATION.md)
   - Import components from `src/engine/components/`

3. **Build Standalone Package**
   - Bundle engine binary + Studio web build
   - Create Electron app for desktop distribution
   - See packaging documentation (coming soon)

## API Reference

See [StudioBridge API Documentation](../aethex-studio/ENGINE_INTEGRATION.md#api-reference) for complete list of available RPC methods.

---

**Ready to test?** Run `./test_quick.sh` to verify everything works!