AeThex-Labs/AeThex-Engine-Core
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
AeThex-Engine-Core/UNIFIED_STUDIO_GUIDE.md

14 KiB
Raw Blame History

Unified Studio - Complete Integration Guide

Overview

The Unified Studio merges the script-focused IDE (AethexStudio) with the engine editor (EngineEditorLayout) into one comprehensive game development environment.

Architecture

Components Merged

From AethexStudio:

  • ✅ Code editor with syntax highlighting
  • ✅ AI assistant integration
  • ✅ Multi-file tab management
  • ✅ Platform templates (Roblox, UEFN, Spatial, Web)

From EngineEditorLayout:

  • ✅ Scene tree (node hierarchy)
  • ✅ 3D Viewport with Canvas rendering
  • ✅ Inspector panel (node properties)
  • ✅ Asset browser (file management)
  • ✅ WebSocket connection to engine
  • ✅ Real-time console output

New Integration Features

Script Attachment:

  • Select a node in the scene tree
  • Click "Attach Script" button
  • Automatically creates GDScript file
  • Opens in code editor for immediate editing
  • Script linked to node visually

Unified File System:

  • Assets and scripts in same browser
  • Open scripts from asset browser
  • Edit scripts from inspector
  • Save syncs with engine backend

AI-Powered Development:

  • AI assistant available while coding
  • Get suggestions for AeThex/Godot patterns
  • Ask questions about scene structure
  • Generate code snippets

Layout Structure

┌─────────────────────────────────────────────────────────┐
│ ⚡ AeThex Studio  [▶ Run] [⏹ Stop] [💾 Save] [🤖

 AI]   │
├──────────┬───────────────────────────┬──────────────────┤
│ Left     │ Center                    │ Right            │
│          │                           │                  │
│ 🌲 Scene │ 🎮 3D Viewport            │ 🔍 Inspector     │
│ Tree     │                           │                  │
│          │ [FPS: 60]                 │ Properties       │
│ OR       │ [Resolution: 1920x1080]   │                  │
│          │                           │ [Attach Script]  │
│ 📁 Assets│ [Wireframe] [Grid]        │                  │
│ Browser  │ [Camera] [Fullscreen]     │                  │
│          │                           │                  │
├──────────┴───────────────────────────┴──────────────────┤
│ Bottom Panel (Tabs)                                     │
│                                                          │
│ 📋 Console | 💻 Code Editor                            │
│                                                          │
│ [23:15:45] Game started successfully                    │
│ [23:15:46] Scene loaded                                 │
│                                                          │
│ -- OR --                                                │
│                                                          │
│ [player.gd] [enemy.gd] [game_controller.gd]            │
│                                                          │
│ 1 | extends Node                                        │
│ 2 | # Script content here                              │
│ 3 | func _ready():                                      │
│                                                          │
└─────────────────────────────────────────────────────────┘
│ 🤖 AI Assistant (Right Side Panel)                      │
│                                                          │
│ Ask me anything...                                      │
│                                                          │
└─────────────────────────────────────────────────────────┘

Key Features

1. Scene Management

  • Location: Left panel → Scene Tree tab
  • Features:
    • View node hierarchy
    • Select nodes (highlights in inspector)
    • Add/remove nodes via engine API
    • Real-time updates via WebSocket

2. 3D Viewport

  • Location: Center panel
  • Features:
    • Canvas-based rendering
    • FPS counter + resolution display
    • Control buttons: Wireframe, Grid, Camera, Fullscreen
    • Connected to engine for texture streaming

3. Inspector

  • Location: Right panel
  • Features:
    • Shows properties of selected node
    • Edit values (position, rotation, scale)
    • "Attach Script" button for selected node
    • Type-specific property editors

4. Asset Browser

  • Location: Left panel → Assets tab
  • Features:
    • Grid/List view modes
    • Breadcrumb navigation
    • Search functionality
    • File preview panel
    • Multi-select support (Ctrl+Click)
    • File icons by type (.gd, .png, .tscn, etc.)

5. Code Editor

  • Location: Bottom panel → Code Editor tab
  • Features:
    • Multi-file tab management
    • Line numbers + syntax highlighting
    • File close buttons on tabs
    • Auto-saves to engine
    • Supports GDScript, C#, C++

6. Console

  • Location: Bottom panel → Console tab
  • Features:
    • Real-time engine output
    • Color-coded messages (info/success/warning/error)
    • Timestamps on all messages
    • Auto-scrolls to latest
    • Filters via WebSocket events

7. AI Assistant

  • Location: Right sidebar (toggleable)
  • Features:
    • Chat interface for code help
    • Godot-specific suggestions
    • Code generation
    • Template access
    • Context-aware responses

Usage Workflows

Creating a New Game Object

  1. Add Node → Click in scene tree, add Node2D/Node3D
  2. Attach Script → Select node, click "Attach Script"
  3. Write Code → Script opens in editor, write logic
  4. Save → Click "Save File" in toolbar
  5. Test → Click "Run" to test in viewport
  6. Debug → Check console for output

Editing Existing Scripts

  1. Find Script → Switch to Assets tab
  2. Open File → Click .gd file
  3. Edit → Modify in code editor
  4. Save → Ctrl+S or Save button
  5. Reload → Engine auto-reloads changes

Using AI Assistant

  1. Open AI → Click 🤖 in toolbar
  2. Ask Question → Type in chat
  3. Get Code → AI generates AeThex/Godot-compatible code
  4. Copy → Insert into script
  5. Test → Run to verify

Multi-Node Workflow

  1. Select Node A → Inspector shows properties
  2. Attach Script → Creates node_a.gd
  3. Select Node B → Inspector updates
  4. Attach Script → Creates node_b.gd
  5. Switch Tabs → Edit both scripts
  6. Cross-Reference → AI helps with node communication

Keyboard Shortcuts

  • Ctrl+S - Save current file
  • Ctrl+R - Run game
  • Ctrl+Q - Stop game
  • Ctrl+/ - Toggle AI assistant
  • Ctrl+B - Toggle asset browser
  • Ctrl+J - Toggle console
  • Tab - Indent in code editor
  • Esc - Close panels

API Integration

Bridge Methods Used

// Scene operations
bridge.getSceneTree()
bridge.getNodeInfo(nodePath)
bridge.setNodeProperty(nodePath, property, value)

// File operations
bridge.listDirectory(path)
bridge.readFile(path)
bridge.writeFile(path, content)

// Game control
bridge.runGame()
bridge.stopGame()
bridge.saveScene(path)

// WebSocket events
bridge.connectEvents({
  onConsoleOutput: (msg, type) => {...},
  onSceneChanged: () => {...},
  onNodeSelected: (node) => {...}
})

WebSocket Events

// Incoming from engine
scene_changed      // Scene structure updated
node_selected      // Node clicked in viewport
property_changed   // Node property modified
console_output     // Print/debug messages

// Outgoing to engine
run_game          // Start game loop
stop_game         // Stop execution
save_scene        // Write scene to disk

Files Structure

/workspaces/aethex-studio/src/
├── components/aethex/
│   ├── unified-studio.tsx       # Main component (400+ lines)
│   ├── unified-studio.css       # Complete styling (560+ lines)
│   ├── code-editor.tsx          # Multi-file editor
│   ├── ai-assistant.tsx         # AI chat interface
│   └── aethex-studio.tsx        # Old IDE (kept as backup)
├── engine/
│   ├── bridge.ts                # WebSocket + HTTP client
│   ├── hooks.ts                 # React state hooks
│   └── components/
│       ├── SceneTreePanel.tsx   # Node hierarchy
│       ├── InspectorPanel.tsx   # Property editor
│       ├── ViewportPanel.tsx    # 3D canvas
│       ├── AssetBrowser.tsx     # File browser
│       └── EngineConnectionStatus.tsx
└── app/
    ├── ide/page.tsx             # Route → UnifiedStudio
    └── engine-test/page.tsx     # Route → Old EngineEditorLayout (backup)

Backend Requirements

No Engine Changes Needed! ✅

The unified studio works with the existing StudioBridge API:

  • Same 26 RPC methods
  • Same WebSocket port (6007)
  • Same HTTP endpoints
  • Zero C++ code changes
  • No recompilation required

Engine Must Be Running

# Check engine status
ps aux | grep aethex

# Should show:
./bin/aethex.linuxbsd.editor.x86_64 --headless-editor

# Log location
tail -f /tmp/engine.log

Testing Checklist

  • Studio loads at http://localhost:9002/ide
  • Engine connection shows "Connected" (green dot)
  • Scene tree loads node hierarchy
  • Viewport shows grid placeholder
  • Inspector shows properties when node selected
  • "Attach Script" creates new .gd file
  • Code editor opens with script content
  • Saving file shows success message in console
  • Run button starts game (console output)
  • Stop button stops execution
  • AI assistant responds to questions
  • Asset browser shows files
  • Console displays timestamped messages
  • WebSocket reconnects after disconnect

Troubleshooting

Studio Not Loading

# Check Next.js server
ps aux | grep "next dev"

# Restart if needed
cd /workspaces/aethex-studio
npm run dev

Engine Not Connected

# Check engine process
ps aux | grep aethex

# Check port binding
netstat -tlnp | grep 6007

# Restart engine
pkill -f godot
cd /workspaces/AeThex-Engine-Core/engine
./bin/aethex.linuxbsd.editor.x86_64 --headless-editor > /tmp/engine.log 2>&1 &

WebSocket Not Connecting

  1. Open browser console (F12)
  2. Check for WebSocket errors
  3. Verify ws://localhost:6007 is accessible
  4. Check engine log: tail -f /tmp/engine.log

Scripts Not Saving

  1. Check console for error messages
  2. Verify write permissions in project
  3. Test with bridge.writeFile() directly
  4. Check engine log for file operations

AI Assistant Not Responding

  1. Check network tab for API calls
  2. Verify AI service is configured
  3. Check aethex-studio .env.local
  4. Restart Studio server

Performance Tips

  • Close Unused Files: Keep 3-5 tabs max in editor
  • Disable AI When Not Needed: Toggle off to save resources
  • Use Console Filtering: Only show relevant messages
  • Grid View for Assets: Faster than list view for many files
  • Collapse Inspector Sections: When not editing properties

Future Enhancements

Phase 1 (Current) ✅

  • Unified layout with all panels
  • Script attachment to nodes
  • Real-time console output
  • AI assistant integration

Phase 2 (Planned)

  • Monaco editor integration (advanced syntax)
  • Debugger panel (breakpoints, watch)
  • Git integration (version control)
  • Collaborative editing (multiplayer)

Phase 3 (Future)

  • Visual scripting (node-based)
  • Performance profiler
  • Asset pipeline (import/export)
  • Plugin marketplace

Comparison: Old vs New

Old System (Disconnected)

Route: /ide

  • Script editing only
  • No scene access
  • No engine connection
  • Platform templates
  • AI assistant

Route: /engine-test

  • Scene editing only
  • No code editing
  • Engine connected
  • 3D viewport
  • Inspector panel

New System (Unified)

Route: /ide ← Updated to UnifiedStudio

  • ✅ Script editing
  • ✅ Scene access
  • ✅ Engine connection
  • ✅ Platform templates
  • ✅ AI assistant
  • ✅ 3D viewport
  • ✅ Inspector panel
  • ✅ Asset browser
  • ✅ Console output
  • ✅ Script attachment

Route: /engine-test ← Kept as backup

  • Original EngineEditorLayout preserved
  • Available for testing/comparison

URLs

Command Reference

# Start engine
cd /workspaces/AeThex-Engine-Core/engine
./bin/aethex.linuxbsd.editor.x86_64 --headless-editor > /tmp/engine.log 2>&1 &

# Start Studio
cd /workspaces/aethex-studio
npm run dev > /tmp/studio.log 2>&1 &

# Check status
ps aux | grep aethex
ps aux | grep "next dev"
netstat -tlnp | grep -E "(6007|9002)"

# View logs
tail -f /tmp/engine.log   # Engine output
tail -f /tmp/studio.log   # Studio output

# Stop all
pkill -f godot
pkill -f "next dev"

Success Metrics

✅ Integration Complete: All components merged into one interface
✅ Zero Backend Changes: Same API endpoints, no engine modification
✅ Feature Parity: All old features preserved + new integration features
✅ Performance: No degradation, same WebSocket connection
✅ UX Improvement: Single unified workflow instead of switching between 2 IDEs

Last Updated: February 23, 2026
Version: 1.0.0
Status: ✅ Production Ready