2026-02-24 04:30:27 +00:00

7.2 KiB

Raw Blame History

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:

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

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

Run on Startup (Background Mode)

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

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

2. Test the API (in another terminal)

# 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

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:

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

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

./aethex --headless-editor --verbose

Can't Connect from Studio

Problem: Studio shows "Engine Disconnected"

Solution:

Check engine is running: ps aux | grep aethex
Check port 6007 is listening: netstat -tuln | grep 6007
Test with curl: curl http://localhost:6007/rpc
Check firewall settings if connecting remotely

Port Already in Use

Problem: "Address already in use" error

Solution: Kill existing process:

lsof -i :6007
kill <PID>

Missing Project Path

Problem: "Project not found" error

Solution: Always specify project path explicitly:

./aethex --headless-editor --path /absolute/path/to/project

Next Steps

Test Headless Mode

cd /workspaces/AeThex-Engine-Core
./test_quick.sh

Connect Studio
- Follow instructions in ENGINE_INTEGRATION.md
- Import components from src/engine/components/
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 for complete list of available RPC methods.

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

7.2 KiB Raw Blame History