@createlex/createlexgenai 1.0.2 → 1.0.5

package/README.md

@@ -63,22 +63,22 @@ You need **at least one** of these enabled in your Unreal project. Both are buil
 
 1. Open your UE project
 2. Go to **Edit > Plugins**
-3. Search for **"Web Remote Control"** and enable it
+3. Enable **"Remote Control API"** and **"Remote Control Web Interface"**
 4. Restart the editor
 5. Go to **Edit > Project Settings > Plugins > Remote Control**
-6. Check **"Enable Remote Control Web Server"**
-7. Set port to **30010** (default)
-8. Ensure **"Enable HTTP Server"** is checked
+6. Under **Remote Control Web Server**, check **"Auto Start Web Server"**
+7. Set **"Remote Control HTTP Server Port"** to **30010** (default)
+8. Under **Remote Control > Security**, check **"Enable Remote Python Execution"**
 
 #### Option B: Python Remote Execution
 
 1. Open your UE project
 2. Go to **Edit > Plugins**
-3. Search for **"Python Editor Script Plugin"** and enable it
+3. Enable **"Python Editor Script Plugin"**
 4. Restart the editor
 5. Go to **Edit > Project Settings > Plugins > Python**
-6. Check **"Enable Remote Execution"**
-7. Multicast group: `239.0.0.1`, port: `6766` (defaults)
+6. Under **Python Remote Execution**, check **"Enable Remote Execution?"**
+7. Multicast Group Endpoint: `239.0.0.1:6766`, Multicast Bind Address: `127.0.0.1` (defaults)
 
 > **Tip:** Enable both for maximum reliability. If one backend is unavailable, the CLI automatically falls back to the other.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createlex/createlexgenai",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "CLI tool and MCP server for CreatelexGenAI — Unreal Engine AI integration",
   "bin": {
     "createlex": "./bin/createlex.js"

package/src/core/remote-execution.js

@@ -4,21 +4,58 @@ const dgram = require('dgram');
 const net = require('net');
 const crypto = require('crypto');
 
-// UE Python Remote Execution protocol constants
+// UE Python Remote Execution protocol constants (from remote_execution.py)
 const PROTOCOL_MAGIC = 'ue_py';
 const PROTOCOL_VERSION = 1;
 
 const MULTICAST_GROUP = '239.0.0.1';
 const MULTICAST_PORT = 6766;
-const COMMAND_PORT = 6776;
+const MULTICAST_BIND_ADDRESS = '127.0.0.1';
+const MULTICAST_TTL = 0;
+
+const DEFAULT_COMMAND_ENDPOINT = ['127.0.0.1', 6776];
+const DEFAULT_RECEIVE_BUFFER_SIZE = 8192;
 
 const DISCOVERY_TIMEOUT = 3000;
-const CONNECT_TIMEOUT = 10000;
 const COMMAND_TIMEOUT = 30000;
 
+/**
+ * Build a protocol message matching UE's _RemoteExecutionMessage.to_json() format.
+ */
+function buildMessage(type, source, dest, data) {
+  const msg = {
+    version: PROTOCOL_VERSION,
+    magic: PROTOCOL_MAGIC,
+    type: type,
+    source: source
+  };
+  if (dest) {
+    msg.dest = dest;
+  }
+  if (data) {
+    msg.data = data;
+  }
+  return JSON.stringify(msg);
+}
+
+/**
+ * Parse and validate a received protocol message.
+ */
+function parseMessage(buf) {
+  try {
+    const msg = JSON.parse(buf.toString('utf-8'));
+    if (msg.version !== PROTOCOL_VERSION) return null;
+    if (msg.magic !== PROTOCOL_MAGIC) return null;
+    if (!msg.type || !msg.source) return null;
+    return msg;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Discover running Unreal Engine instances via UDP multicast ping.
- * Returns an array of discovered nodes.
+ * Matches UE's _RemoteExecutionBroadcastConnection protocol exactly.
  */
 function discover(timeout = DISCOVERY_TIMEOUT) {
   return new Promise((resolve) => {
@@ -28,56 +65,62 @@ function discover(timeout = DISCOVERY_TIMEOUT) {
     const socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
 
     const timer = setTimeout(() => {
-      socket.close();
+      try { socket.close(); } catch {}
       resolve(nodes);
     }, timeout);
 
     socket.on('message', (msg) => {
-      try {
-        const data = JSON.parse(msg.toString());
-        if (data.magic === PROTOCOL_MAGIC && data.type === 'pong') {
-          // Avoid duplicates
-          if (!nodes.find(n => n.node_id === data.source)) {
-            nodes.push({
-              node_id: data.source,
-              engine_version: data.engine_version || 'unknown',
-              machine: data.machine || 'unknown',
-              user: data.user || 'unknown'
-            });
-          }
-        }
-      } catch {
-        // Ignore non-JSON or malformed messages
+      const message = parseMessage(msg);
+      if (!message) return;
+
+      // Filter: must not be from self, must be a pong
+      if (message.source === nodeId) return;
+      if (message.dest && message.dest !== nodeId) return;
+      if (message.type !== 'pong') return;
+
+      // Avoid duplicates
+      if (!nodes.find(n => n.node_id === message.source)) {
+        nodes.push({
+          node_id: message.source,
+          ...(message.data || {})
+        });
       }
     });
 
     socket.on('error', () => {
       clearTimeout(timer);
-      socket.close();
+      try { socket.close(); } catch {}
       resolve(nodes);
     });
 
-    socket.bind(0, '0.0.0.0', () => {
+    // Bind to the same port and address as UE expects
+    socket.bind(MULTICAST_PORT, MULTICAST_BIND_ADDRESS, () => {
       try {
-        socket.addMembership(MULTICAST_GROUP);
+        // Match UE's socket options
+        socket.setMulticastLoopback(true);
+        socket.setMulticastTTL(MULTICAST_TTL);
+        socket.setMulticastInterface(MULTICAST_BIND_ADDRESS);
+        socket.addMembership(MULTICAST_GROUP, MULTICAST_BIND_ADDRESS);
       } catch {
         // Multicast may not be available
       }
 
-      const ping = JSON.stringify({
-        magic: PROTOCOL_MAGIC,
-        version: PROTOCOL_VERSION,
-        type: 'ping',
-        source: nodeId
-      });
-
+      // Send ping (matches UE's _broadcast_ping)
+      const ping = buildMessage('ping', nodeId);
       socket.send(ping, 0, ping.length, MULTICAST_PORT, MULTICAST_GROUP, (err) => {
         if (err) {
           clearTimeout(timer);
-          socket.close();
+          try { socket.close(); } catch {}
           resolve(nodes);
         }
       });
+
+      // Send a second ping after 1 second (UE pings every _NODE_PING_SECONDS = 1)
+      setTimeout(() => {
+        try {
+          socket.send(ping, 0, ping.length, MULTICAST_PORT, MULTICAST_GROUP);
+        } catch {}
+      }, 1000);
     });
   });
 }
@@ -85,22 +128,18 @@ function discover(timeout = DISCOVERY_TIMEOUT) {
 /**
  * Execute a Python command on a discovered UE instance via the Remote Execution protocol.
  *
- * Steps:
- * 1. Send open_connection via UDP multicast targeting the node
- * 2. Listen on a TCP socket for the UE instance to connect back
- * 3. Send the command as JSON over TCP
- * 4. Receive the result
- *
- * @param {string} command - Python code to execute
- * @param {object} options
- * @param {string} options.nodeId - Target node ID from discovery (optional, broadcasts if omitted)
- * @param {string} options.execMode - 'ExecuteStatement', 'EvaluateStatement', or 'ExecuteFile'
- * @param {number} options.timeout - Command timeout in ms
+ * Matches UE's _RemoteExecutionCommandConnection flow:
+ * 1. Start TCP listen server on command_endpoint
+ * 2. Send open_connection via UDP multicast targeting the node
+ * 3. Accept TCP connection from UE
+ * 4. Send command message over TCP
+ * 5. Receive command_result over TCP
  */
 function executeCommand(command, options = {}) {
   const {
     nodeId = null,
-    execMode = 'ExecuteStatement',
+    execMode = 'ExecuteFile',
+    unattended = true,
     timeout = COMMAND_TIMEOUT
   } = options;
 
@@ -108,104 +147,162 @@ function executeCommand(command, options = {}) {
 
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
-      reject(new Error('Remote execution timed out. Ensure "Allow Python Remote Execution" is enabled in UE Project Settings > Python.'));
+      cleanup();
+      reject(new Error('Remote execution timed out. Ensure "Enable Remote Execution" is checked in UE Project Settings > Python.'));
     }, timeout);
 
-    // Step 1: Create TCP server to receive the connection from UE
-    const tcpServer = net.createServer((socket) => {
-      let responseBuffer = '';
+    let tcpServer = null;
+    let udpSocket = null;
 
+    function cleanup() {
+      clearTimeout(timer);
+      try { if (tcpServer) tcpServer.close(); } catch {}
+      try { if (udpSocket) udpSocket.close(); } catch {}
+    }
+
+    // Step 1: Create TCP server to accept connection from UE
+    tcpServer = net.createServer((socket) => {
+      socket.setNoDelay(true);
+      let responseBuffer = Buffer.alloc(0);
+
+      // Step 4: Send command once UE connects
+      const commandMsg = buildMessage('command', clientId, nodeId || '', {
+        command: command,
+        unattended: unattended,
+        exec_mode: execMode
+      });
+      socket.write(commandMsg, 'utf-8');
+
+      // Step 5: Receive command_result
       socket.on('data', (data) => {
-        responseBuffer += data.toString();
+        responseBuffer = Buffer.concat([responseBuffer, data]);
 
-        // Try to parse complete JSON
-        try {
-          const result = JSON.parse(responseBuffer);
-          clearTimeout(timer);
-          tcpServer.close();
+        const message = parseMessage(responseBuffer);
+        if (message && message.type === 'command_result') {
+          cleanup();
           socket.destroy();
-
-          if (result.type === 'command_result') {
-            resolve({
-              success: result.success !== false,
-              output: result.output || '',
-              result: result.result || null,
-              outputLog: result.output_log || []
-            });
-          } else {
-            resolve({ success: true, raw: result });
-          }
-        } catch {
-          // Keep buffering
+          resolve({
+            success: message.data ? message.data.success !== false : true,
+            output: message.data?.output || '',
+            result: message.data?.result || null,
+            outputLog: message.data?.output_log || []
+          });
         }
       });
 
       socket.on('error', (err) => {
-        clearTimeout(timer);
-        tcpServer.close();
-        reject(new Error(`TCP socket error: ${err.message}`));
+        cleanup();
+        reject(new Error(`TCP command socket error: ${err.message}`));
       });
-
-      // Step 3: Once UE connects, send the command
-      const commandMsg = JSON.stringify({
-        magic: PROTOCOL_MAGIC,
-        version: PROTOCOL_VERSION,
-        type: 'command',
-        source: clientId,
-        command: command,
-        unattended: false,
-        exec_mode: execMode
-      });
-
-      socket.write(commandMsg);
     });
 
     tcpServer.on('error', (err) => {
-      clearTimeout(timer);
+      cleanup();
       reject(new Error(`TCP server error: ${err.message}`));
     });
 
-    // Step 2: Start TCP server, then send open_connection via UDP
-    tcpServer.listen(0, '127.0.0.1', () => {
-      const tcpPort = tcpServer.address().port;
+    // Listen on the command endpoint
+    const commandPort = DEFAULT_COMMAND_ENDPOINT[1];
+    const commandHost = DEFAULT_COMMAND_ENDPOINT[0];
 
-      const udpSocket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
+    tcpServer.listen(commandPort, commandHost, () => {
+      // Step 2: Send open_connection via UDP multicast
+      udpSocket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
 
-      udpSocket.bind(0, '0.0.0.0', () => {
+      udpSocket.bind(0, MULTICAST_BIND_ADDRESS, () => {
         try {
-          udpSocket.addMembership(MULTICAST_GROUP);
-        } catch {
-          // OK if multicast not available
-        }
+          udpSocket.setMulticastLoopback(true);
+          udpSocket.setMulticastTTL(MULTICAST_TTL);
+          udpSocket.setMulticastInterface(MULTICAST_BIND_ADDRESS);
+          udpSocket.addMembership(MULTICAST_GROUP, MULTICAST_BIND_ADDRESS);
+        } catch {}
 
-        const openMsg = JSON.stringify({
-          magic: PROTOCOL_MAGIC,
-          version: PROTOCOL_VERSION,
-          type: 'open_connection',
-          source: clientId,
-          dest: nodeId || '',
-          command_ip: '127.0.0.1',
-          command_port: tcpPort
+        // Send open_connection (UE retries 6 times with 5s waits)
+        const openMsg = buildMessage('open_connection', clientId, nodeId || '', {
+          command_ip: commandHost,
+          command_port: commandPort
         });
 
         udpSocket.send(openMsg, 0, openMsg.length, MULTICAST_PORT, MULTICAST_GROUP, () => {
-          udpSocket.close();
+          try { udpSocket.close(); } catch {}
+          udpSocket = null;
         });
       });
     });
+
+    // If command port is in use, try a random port
+    tcpServer.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        tcpServer = net.createServer((socket) => {
+          socket.setNoDelay(true);
+          let responseBuffer = Buffer.alloc(0);
+
+          const commandMsg = buildMessage('command', clientId, nodeId || '', {
+            command: command,
+            unattended: unattended,
+            exec_mode: execMode
+          });
+          socket.write(commandMsg, 'utf-8');
+
+          socket.on('data', (data) => {
+            responseBuffer = Buffer.concat([responseBuffer, data]);
+            const message = parseMessage(responseBuffer);
+            if (message && message.type === 'command_result') {
+              cleanup();
+              socket.destroy();
+              resolve({
+                success: message.data ? message.data.success !== false : true,
+                output: message.data?.output || '',
+                result: message.data?.result || null,
+                outputLog: message.data?.output_log || []
+              });
+            }
+          });
+
+          socket.on('error', (err2) => {
+            cleanup();
+            reject(new Error(`TCP command socket error: ${err2.message}`));
+          });
+        });
+
+        tcpServer.listen(0, commandHost, () => {
+          const actualPort = tcpServer.address().port;
+          udpSocket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
+
+          udpSocket.bind(0, MULTICAST_BIND_ADDRESS, () => {
+            try {
+              udpSocket.setMulticastLoopback(true);
+              udpSocket.setMulticastTTL(MULTICAST_TTL);
+              udpSocket.setMulticastInterface(MULTICAST_BIND_ADDRESS);
+              udpSocket.addMembership(MULTICAST_GROUP, MULTICAST_BIND_ADDRESS);
+            } catch {}
+
+            const openMsg = buildMessage('open_connection', clientId, nodeId || '', {
+              command_ip: commandHost,
+              command_port: actualPort
+            });
+
+            udpSocket.send(openMsg, 0, openMsg.length, MULTICAST_PORT, MULTICAST_GROUP, () => {
+              try { udpSocket.close(); } catch {}
+              udpSocket = null;
+            });
+          });
+        });
+      }
+    });
   });
 }
 
 /**
- * Quick test: discover + execute a simple command.
+ * Quick test: discover remote nodes.
  */
 async function testConnection() {
   try {
-    const nodes = await discover(2000);
+    const nodes = await discover(3000);
     if (nodes.length === 0) {
       return {
         available: false,
-        error: 'No UE instances found via Remote Execution. Enable "Python Editor Script Plugin" and "Allow Python Remote Execution" in Project Settings.'
+        error: 'No UE instances found via Remote Execution. Enable "Python Editor Script Plugin" and check "Enable Remote Execution" in Project Settings > Python.'
       };
     }
     return {
@@ -223,6 +320,5 @@ module.exports = {
   executeCommand,
   testConnection,
   MULTICAST_GROUP,
-  MULTICAST_PORT,
-  COMMAND_PORT
+  MULTICAST_PORT
 };

package/src/core/web-remote-control.js

@@ -82,8 +82,8 @@ async function healthCheck(options = {}) {
       return { available: false, error: `Port ${port} not reachable` };
     }
 
-    // Full health check
-    const res = await request('GET', '/remote/api/v1/health', null, options);
+    // Full health check — UE uses /remote/info (not /remote/api/v1/health)
+    const res = await request('GET', '/remote/info', null, options);
     return {
       available: res.status === 200,
       status: res.status,