@beremaran/godot-agent-loop 1.0.1 → 1.1.0

package/build/scripts/mcp_interaction_server.gd

@@ -875,8 +875,8 @@ func _cmd_pause(params: Dictionary) -> void:
 # --- Get Performance ---
 func _cmd_get_performance(params: Dictionary) -> void:
 	var action: String = str(params.get("action", "sample"))
-	if not ["sample", "start", "stop", "report", "leaks"].has(action):
-		_send_response({"error": "action must be sample, start, stop, report, or leaks"})
+	if not ["sample", "start", "stop", "report", "stress", "leaks"].has(action):
+		_send_response({"error": "action must be sample, start, stop, report, stress, or leaks"})
 		return
 	if action == "start":
 		_profile_active = true
@@ -911,6 +911,16 @@ func _cmd_get_performance(params: Dictionary) -> void:
 	result["samples"] = samples
 	result["profiling"] = _profile_active
 	result["requested_sample_count"] = sample_count
+	result["timing_mode"] = OS.get_environment("GODOT_MCP_TIMING_MODE") if not OS.get_environment("GODOT_MCP_TIMING_MODE").is_empty() else "external"
+	result["distribution"] = _performance_distribution(samples)
+	result["metric_availability"] = {
+		"realtime_fps": {"available": true, "metric": "fps"},
+		"process_time": {"available": true, "metric": "process_time_ms"},
+		"rendering_time": {"available": true, "metric": "render_setup_cpu_ms", "scope": "CPU render setup only"},
+		"gpu_time": {"available": false, "reason": "Renderer/platform does not expose a stable GPU frame timer through the public runtime API"},
+	}
+	if action == "stress":
+		result["stress_window"] = _stress_comparison(samples)
 	if action == "leaks":
 		result["leak_diagnostics"] = {
 			"object_count": result.get("object_count", 0),
@@ -926,7 +936,11 @@ func _performance_snapshot() -> Dictionary:
 	return {
 		"fps": Performance.get_monitor(Performance.TIME_FPS),
 		"frame_time": Performance.get_monitor(Performance.TIME_PROCESS),
+		"process_time_ms": Performance.get_monitor(Performance.TIME_PROCESS) * 1000.0,
 		"physics_frame_time": Performance.get_monitor(Performance.TIME_PHYSICS_PROCESS),
+		"physics_process_time_ms": Performance.get_monitor(Performance.TIME_PHYSICS_PROCESS) * 1000.0,
+		"render_setup_cpu_ms": RenderingServer.get_frame_setup_time_cpu() * 1000.0,
+		"gpu_time_ms": null,
 		"memory_static": Performance.get_monitor(Performance.MEMORY_STATIC),
 		"memory_static_max": Performance.get_monitor(Performance.MEMORY_STATIC_MAX),
 		"object_count": Performance.get_monitor(Performance.OBJECT_COUNT),
@@ -954,15 +968,75 @@ func _profile_report() -> Dictionary:
 		"latest_object_count": latest.get("object_count", 0),
 		"latest_orphan_node_count": latest.get("object_orphan_node_count", 0),
 	}
+	report["distribution"] = _performance_distribution(_profile_samples)
+	report["metric_availability"] = {
+		"gpu_time": {"available": false, "reason": "Unavailable from the public runtime API on this renderer/platform"},
+		"render_setup_cpu": {"available": true},
+	}
 	return report
 
 
+func _performance_distribution(samples: Array[Dictionary]) -> Dictionary:
+	if samples.is_empty(): return {}
+	var fps_values: Array[float] = []
+	var frame_values: Array[float] = []
+	for sample: Dictionary in samples:
+		fps_values.append(_metric_float(sample.get("fps", 0.0)))
+		frame_values.append(_metric_float(sample.get("process_time_ms", 0.0)))
+	fps_values.sort()
+	frame_values.sort()
+	var percentile_index: int = mini(frame_values.size() - 1, floori(float(frame_values.size() - 1) * 0.95))
+	return {
+		"sample_count": samples.size(),
+		"fps_min": fps_values[0], "fps_max": fps_values[fps_values.size() - 1],
+		"fps_average": _array_average(fps_values),
+		"process_time_ms_min": frame_values[0], "process_time_ms_max": frame_values[frame_values.size() - 1],
+		"process_time_ms_average": _array_average(frame_values),
+		"process_time_ms_p95": frame_values[percentile_index],
+	}
+
+
+func _stress_comparison(samples: Array[Dictionary]) -> Dictionary:
+	if samples.size() < 3:
+		return {"available": false, "reason": "stress comparison requires at least 3 samples"}
+	var baseline: Dictionary = samples[0]
+	var recovery: Dictionary = samples[samples.size() - 1]
+	var peak_process_ms: float = 0.0
+	var peak_objects: int = 0
+	for sample: Dictionary in samples:
+		peak_process_ms = maxf(peak_process_ms, _metric_float(sample.get("process_time_ms", 0.0)))
+		peak_objects = maxi(peak_objects, _metric_int(sample.get("object_count", 0)))
+	return {
+		"available": true,
+		"baseline": baseline,
+		"peak": {"process_time_ms": peak_process_ms, "object_count": peak_objects},
+		"recovery": recovery,
+		"object_count_delta_recovery": _metric_int(recovery.get("object_count", 0)) - _metric_int(baseline.get("object_count", 0)),
+		"process_time_ms_delta_recovery": _metric_float(recovery.get("process_time_ms", 0.0)) - _metric_float(baseline.get("process_time_ms", 0.0)),
+	}
+
+
+func _array_average(values: Array[float]) -> float:
+	var total: float = 0.0
+	for value: float in values: total += value
+	return total / values.size()
+
+
 func _metric_float(value: Variant) -> float:
 	if value is int or value is float:
 		return value
 	return 0.0
 
 
+func _metric_int(value: Variant) -> int:
+	if value is int:
+		return value
+	if value is float:
+		var float_value: float = value
+		return roundi(float_value)
+	return 0
+
+
 # --- Wait N Frames ---
 func _cmd_wait(params: Dictionary) -> void:
 	var reader := CommandParams.new(params)

package/build/scripts/mcp_runtime/core_domain.gd

@@ -35,7 +35,8 @@ func _cmd_get_scene_tree(params: Dictionary) -> void:
 		return
 	var traversal: Dictionary = {"count": 0, "truncated": false, "max_nodes": max_nodes}
 	var tree: Dictionary = _build_tree_node(get_tree().root, traversal)
-	respond({"success": true, "tree": tree, "node_count": traversal["count"], "truncated": traversal["truncated"], "max_nodes": max_nodes})
+	respond({"success": true, "tree": tree, "node_count": traversal["count"], "truncated": traversal["truncated"], "max_nodes": max_nodes,
+		"current_scene": "" if get_tree().current_scene == null else get_tree().current_scene.scene_file_path})
 
 func _build_tree_node(node: Node, traversal: Dictionary) -> Dictionary:
 	var count_value: Variant = traversal.get("count", 0)

package/build/scripts/mcp_runtime/system_domain.gd

@@ -77,6 +77,8 @@ func _cmd_time_scale(params: Dictionary) -> void:
 		"success": true,
 		"time_scale": Engine.time_scale,
 		"fixed_fps": _configured_fixed_fps(),
+		"timing_mode": OS.get_environment("GODOT_MCP_TIMING_MODE") if not OS.get_environment("GODOT_MCP_TIMING_MODE").is_empty() else "external",
+		"display_pacing": OS.get_environment("GODOT_MCP_TIMING_MODE") == "realtime",
 		"ticks_msec": Time.get_ticks_msec(),
 		"fps": Engine.get_frames_per_second(),
 	})

package/build/server-instructions.js

@@ -2,10 +2,10 @@
  * Initialization guidance is paid for in every MCP session. Keep this to the
  * durable operating method; detailed procedures belong in plugin skills.
  */
-export const SERVER_INSTRUCTIONS = `Build and verify Godot changes with an author → run → observe → assert loop.
+export const SERVER_INSTRUCTIONS = `Use an author → run → observe → assert loop.
 
-1. Author scenes, scripts, resources, and project settings with project tools.
-2. Run with run_project, then observe through game_get_scene_tree, game_get_ui, game_screenshot, and get_debug_output.
-3. Assert outcomes with verify_project or run_project_tests instead of assembling fragile manual checks. Stop the project when finished.
+For watched work, call editor_session ensure and prefer editor_transaction or editor-routed tools. Report fallbacks and conflicts. Persist structure in scenes/resources and behavior in scripts; justify procedural construction.
 
-Prefer compound tools when they cover the task. Runtime bridge injection and cleanup are automatic; do not add MCP autoloads or addon files to the project. Reflection, code execution, and network tools are denied by default. For trusted local work, enable only required groups with GODOT_MCP_PRIVILEGED_GROUPS (reflection, code-execution, network), or explicitly enable all with GODOT_MCP_ALLOW_PRIVILEGED_COMMANDS=true.`;
+Use realtime run_project when watched. Observe with scene/UI queries, screenshots, and logs. Assert with deterministic verify_project, game_wait_until, game_scenario, or run_project_tests. Stop and report diagnostics, unsupported metrics, and cleanup.
+
+Prefer compound tools. Runtime injection and cleanup are automatic; never add MCP files. Reflection, code execution, and network are denied by default. Enable only needed GODOT_MCP_PRIVILEGED_GROUPS, or explicitly allow all with GODOT_MCP_ALLOW_PRIVILEGED_COMMANDS=true.`;

package/build/session-timing.js

@@ -2,6 +2,7 @@
 export const GODOT_SESSION_FIXED_FPS = 60;
 export const GODOT_SESSION_INITIAL_TIME_SCALE = 1;
 export const GODOT_SESSION_FIXED_FPS_ENV = 'GODOT_MCP_FIXED_FPS';
+export const GODOT_SESSION_TIMING_MODE_ENV = 'GODOT_MCP_TIMING_MODE';
 /**
  * Fixed FPS makes each rendered frame advance the same simulation delta.
  * max-fps retains a wall-clock cap so an idle persistent session does not spin
@@ -16,5 +17,20 @@ export function deterministicSessionArguments() {
 }
 /** Metadata mirrored into the child because Godot strips recognized CLI flags from script-visible args. */
 export function deterministicSessionEnvironment() {
-    return { [GODOT_SESSION_FIXED_FPS_ENV]: String(GODOT_SESSION_FIXED_FPS) };
+    return {
+        [GODOT_SESSION_FIXED_FPS_ENV]: String(GODOT_SESSION_FIXED_FPS),
+        [GODOT_SESSION_TIMING_MODE_ENV]: 'deterministic',
+    };
+}
+/** Watched runs retain normal display/VSync pacing and do not force fixed simulation deltas. */
+export function realtimeSessionArguments() {
+    return ['--time-scale', String(GODOT_SESSION_INITIAL_TIME_SCALE)];
+}
+export function realtimeSessionEnvironment() {
+    return { [GODOT_SESSION_FIXED_FPS_ENV]: '', [GODOT_SESSION_TIMING_MODE_ENV]: 'realtime' };
+}
+export function timingPolicy(mode) {
+    return mode === 'deterministic'
+        ? { mode, fixed_fps: GODOT_SESSION_FIXED_FPS, max_fps: GODOT_SESSION_FIXED_FPS, time_scale: 1, display_pacing: false }
+        : { mode, fixed_fps: null, max_fps: null, time_scale: 1, display_pacing: true };
 }

package/build/tool-definitions.js

@@ -17,7 +17,7 @@ export const toolDefinitions = [
     },
     {
         name: 'launch_editor',
-        description: 'Launch Godot editor for a specific project',
+        description: 'Attach to an existing matching editor or launch one when needed',
         inputSchema: {
             type: 'object',
             properties: {
@@ -29,6 +29,20 @@ export const toolDefinitions = [
             required: ['projectPath'],
         },
     },
+    {
+        name: 'editor_session',
+        description: 'Discover, attach, inspect, or disconnect a per-project Godot editor session',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectPath: { type: 'string', description: 'Godot project path' },
+                action: { type: 'string', enum: ['ensure', 'status', 'disconnect'], description: 'Session action' },
+                launchIfNeeded: { type: 'boolean', description: 'For ensure, launch an editor only after discovery finds none. Default: false' },
+                timeoutSeconds: { type: 'number', minimum: 0, maximum: 30, description: 'Bounded discovery/attach wait. Default: 2' },
+            },
+            required: ['projectPath', 'action'],
+        },
+    },
     {
         name: 'editor_control',
         description: 'Inspect and edit open scenes through an authenticated editor bridge',
@@ -47,6 +61,37 @@ export const toolDefinitions = [
             required: ['projectPath', 'action'],
         },
     },
+    {
+        name: 'editor_transaction',
+        description: 'Apply one validated compound scene edit as one editor undo step',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectPath: { type: 'string', description: 'Godot project path whose editor is attached' },
+                scenePath: { type: 'string', description: 'Project-relative or res:// scene path' },
+                name: { type: 'string', minLength: 1, maxLength: 128, description: 'Human-readable undo action name' },
+                rootType: { type: 'string', maxLength: 128, description: 'Root node type when creating a missing scene' },
+                operations: {
+                    type: 'array', minItems: 1, maxItems: 256, description: 'Ordered editor-native scene operations',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            op: { type: 'string', enum: ['add_node', 'remove_node', 'rename_node', 'duplicate_node', 'reparent_node', 'set_properties', 'instantiate_scene', 'attach_script', 'assign_resource', 'save'] },
+                            nodePath: { type: 'string' }, parentPath: { type: 'string' }, newParentPath: { type: 'string' },
+                            nodeType: { type: 'string' }, nodeName: { type: 'string' }, name: { type: 'string' },
+                            properties: { type: 'object' }, property: { type: 'string' }, value: {},
+                            scenePath: { type: 'string' }, scriptPath: { type: 'string' }, resourcePath: { type: 'string' },
+                            keepGlobalTransform: { type: 'boolean' },
+                        },
+                        required: ['op'],
+                    },
+                },
+                focusPath: { type: 'string', description: 'Node to reveal after commit' },
+                save: { type: 'boolean', description: 'Save and independently reopen/read the scene. Default: true' },
+            },
+            required: ['projectPath', 'scenePath', 'name', 'operations'],
+        },
+    },
     {
         name: 'run_project',
         description: 'Run the Godot project and capture output',
@@ -61,6 +106,10 @@ export const toolDefinitions = [
                     type: 'string',
                     description: 'Optional: Specific scene to run',
                 },
+                timingMode: {
+                    type: 'string', enum: ['realtime', 'deterministic'],
+                    description: 'realtime follows display/VSync; deterministic uses fixed 60 FPS. Default: realtime',
+                },
             },
             required: ['projectPath'],
         },
@@ -143,6 +192,7 @@ export const toolDefinitions = [
                 sourcePath: { type: 'string', description: 'Existing project-relative path for rename preview' },
                 destinationPath: { type: 'string', description: 'Proposed project-relative rename destination' },
                 maxFiles: { type: 'integer', minimum: 1, maximum: 50000, description: 'Resource scan limit. Default: 10000' },
+                allowProceduralMainScene: { type: 'boolean', description: 'Suppress the trivial-main-scene warning when procedural construction is an explicit design requirement. Default: false' },
             },
             required: ['projectPath', 'action'],
         },
@@ -426,10 +476,12 @@ export const toolDefinitions = [
     },
     {
         name: 'game_screenshot',
-        description: 'Screenshot the running game (returns base64 PNG)',
+        description: 'Capture a PNG preview with dimensions, digest, and optional temp artifact',
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                retainArtifact: { type: 'boolean', description: 'Retain a PNG in the system temp artifact directory. Default: false' },
+            },
             required: [],
         },
     },
@@ -704,7 +756,7 @@ export const toolDefinitions = [
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['sample', 'start', 'stop', 'report', 'leaks'], description: 'Profiler action. Default: sample' },
+                action: { type: 'string', enum: ['sample', 'start', 'stop', 'report', 'stress', 'leaks'], description: 'Profiler action. Default: sample' },
                 sampleCount: { type: 'integer', minimum: 1, maximum: 120, description: 'Number of samples for a bounded session. Default: 1' },
             },
             required: [],
@@ -729,6 +781,47 @@ export const toolDefinitions = [
             required: [],
         },
     },
+    {
+        name: 'game_wait_until',
+        description: 'Wait once for a bounded runtime condition and return the last observation',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectPath: { type: 'string', description: 'Godot project path for trace correlation' },
+                condition: { type: 'string', enum: ['connection', 'node', 'property', 'signal', 'log', 'scene'], description: 'Condition kind' },
+                nodePath: { type: 'string' }, property: { type: 'string' }, value: {}, signal: { type: 'string' },
+                text: { type: 'string', maxLength: 1000 }, scenePath: { type: 'string' },
+                timeoutSeconds: { type: 'number', minimum: 0.05, maximum: 60, description: 'Maximum wait. Default: 10' },
+                pollIntervalMs: { type: 'integer', minimum: 20, maximum: 1000, description: 'Internal poll interval. Default: 100' },
+            },
+            required: ['condition'],
+        },
+    },
+    {
+        name: 'game_scenario',
+        description: 'Run bounded input, wait, assertion, screenshot, and performance steps',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectPath: { type: 'string', description: 'Godot project path for trace correlation' },
+                name: { type: 'string', minLength: 1, maxLength: 128 },
+                timeoutSeconds: { type: 'number', minimum: 0.1, maximum: 120, description: 'Whole scenario timeout. Default: 60' },
+                steps: {
+                    type: 'array', minItems: 1, maxItems: 100,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            type: { type: 'string', enum: ['input', 'wait', 'observe', 'assert', 'screenshot', 'performance'] },
+                            tool: { type: 'string' }, arguments: { type: 'object' }, condition: { type: 'object' },
+                            label: { type: 'string', maxLength: 200 },
+                        },
+                        required: ['type'],
+                    },
+                },
+            },
+            required: ['name', 'steps'],
+        },
+    },
     {
         name: 'read_scene',
         description: 'Read scene file as JSON node tree (headless)',
@@ -2704,7 +2797,7 @@ export const toolDefinitions = [
                 projectPath: { type: 'string', description: 'Absolute path to Godot project' },
                 action: { type: 'string', enum: ['create', 'read'], description: 'Action: create or read' },
                 platforms: { type: 'array', description: 'Target platforms: windows, linux, macos, web', items: { type: 'string', enum: ['windows', 'linux', 'macos', 'web'] } },
-                godotVersion: { type: 'string', pattern: '^4\\.\\d+(?:\\.\\d+)?(?:-stable)?$', description: 'Godot 4 version (e.g. 4.3-stable)' },
+                godotVersion: { type: 'string', pattern: '^4\\.(?:[7-9]|\\d{2,})(?:\\.\\d+)?(?:-stable)?$', description: 'Supported Godot 4.7+ version (e.g. 4.7-stable)' },
             },
             required: ['projectPath', 'action'],
         },
@@ -2717,7 +2810,7 @@ export const toolDefinitions = [
             properties: {
                 projectPath: { type: 'string', description: 'Absolute path to Godot project' },
                 action: { type: 'string', enum: ['create', 'read'], description: 'Action: create or read' },
-                godotVersion: { type: 'string', pattern: '^4\\.\\d+(?:\\.\\d+)?(?:-stable)?$', description: 'Godot 4 version (e.g. 4.3-stable)' },
+                godotVersion: { type: 'string', pattern: '^4\\.(?:[7-9]|\\d{2,})(?:\\.\\d+)?(?:-stable)?$', description: 'Supported Godot 4.7+ version (e.g. 4.7-stable)' },
                 exportPreset: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9 _./-]{0,127}$', description: 'Export preset name (letters, digits, spaces, _, ., /, and -)' },
                 baseImage: { type: 'string', enum: ['ubuntu:22.04', 'ubuntu:24.04'], description: 'Supported base Docker image (default: ubuntu:22.04)' },
             },

package/build/tool-handlers/game-tool-handlers.js

@@ -1,5 +1,9 @@
 import { createErrorResponse, errorMessage, normalizeParameters } from '../utils.js';
 import { VisualRegressionService } from './visual-regression-service.js';
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 /**
  * ParticleProcessMaterial fields the runtime reads, keyed by the camelCase name
  * the MCP surface uses. `processMaterial` is a free-form object, so its keys are
@@ -44,7 +48,7 @@ export class GameToolHandlers {
         };
         this.visualRegression = new VisualRegressionService(context.commands);
     }
-    async handleGameScreenshot() {
+    async handleGameScreenshot(args = {}) {
         if (!this.context.commands.hasActiveProcess()) {
             return createErrorResponse('No active Godot process. Use run_project first.');
         }
@@ -57,6 +61,15 @@ export class GameToolHandlers {
                 return createErrorResponse(`Screenshot failed: ${response.error.message}`);
             }
             const result = response.result;
+            const bytes = Buffer.from(result.data ?? '', 'base64');
+            const digest = createHash('sha256').update(bytes).digest('hex');
+            let artifactPath = null;
+            if (args.retainArtifact === true && bytes.length > 0) {
+                const artifactDirectory = join(tmpdir(), 'godot-agent-loop-artifacts');
+                mkdirSync(artifactDirectory, { recursive: true });
+                artifactPath = join(artifactDirectory, `${digest}.png`);
+                writeFileSync(artifactPath, bytes);
+            }
             return {
                 content: [
                     {
@@ -66,7 +79,11 @@ export class GameToolHandlers {
                     },
                     {
                         type: 'text',
-                        text: `Screenshot captured: ${result.width}x${result.height}`,
+                        text: JSON.stringify({
+                            captured: bytes.length > 0, width: result.width, height: result.height,
+                            bytes: bytes.length, sha256: digest, artifact_path: artifactPath,
+                            project_artifact: false, visual_regression_metadata: null,
+                        }, null, 2),
                     },
                 ],
             };
@@ -174,8 +191,8 @@ export class GameToolHandlers {
     async handleGamePerformance(args = {}) {
         args = normalizeParameters(args || {});
         const action = args.action ?? 'sample';
-        if (!['sample', 'start', 'stop', 'report', 'leaks'].includes(action)) {
-            return createErrorResponse('action must be sample, start, stop, report, or leaks.');
+        if (!['sample', 'start', 'stop', 'report', 'stress', 'leaks'].includes(action)) {
+            return createErrorResponse('action must be sample, start, stop, report, stress, or leaks.');
         }
         return this.context.gameCommand('get_performance', args, a => ({
             action: a.action ?? 'sample', sample_count: a.sampleCount ?? a.sample_count ?? 1, sampleCount: a.sampleCount ?? a.sample_count ?? 1,