gdharness 1.2.6 → 1.2.8

package/build/cli.js

@@ -42623,7 +42623,8 @@ function profiledFunctions(totals, limit, sourceOf = () => null) {
     counted: rows.length,
     superCallers: rows.filter((row) => row.selfIncludesSuper === true).length,
     perCallUs,
-    overheadDominated: rows.filter((row) => row.overheadMs !== undefined).length
+    overheadDominated: rows.filter((row) => row.overheadMs !== undefined).length,
+    overheadNamed: rows.filter((row) => row.overheadMs !== undefined).map((row) => row.function)
   };
 }
 function isCalibration(signature) {
@@ -42721,7 +42722,7 @@ function callersOf(totals, name, scripts) {
   sites.sort((a, b) => (b.withinTotalMs ?? -1) - (a.withinTotalMs ?? -1) || a.script.localeCompare(b.script) || a.line - b.line);
   return { target, sites: sites.slice(0, CALL_SITES), omitted: Math.max(0, sites.length - CALL_SITES) };
 }
-var QUEUE_SETTING = "limits/debugger/max_queued_messages", QUEUE_DEFAULT = 2048, QUEUE_HEADROOM = 512, UNNAMED_PREFIX = "#", ms = (seconds) => Math.round(seconds * 1e6) / 1000, RUNTIME_SCRIPT = "gdharness_runtime/runtime_autoload.gd", PROFILER_PROBE = "_profiler_probe", PROFILER_CALIBRATOR = "_calibrate_the_profiler", CALL_SITES = 40;
+var QUEUE_SETTING = "limits/debugger/max_queued_messages", QUEUE_DEFAULT = 2048, QUEUE_HEADROOM = 512, UNNAMED_PREFIX = "#", PROFILE_FROM_START = "GDHARNESS_PROFILE_FROM_START", ms = (seconds) => Math.round(seconds * 1e6) / 1000, RUNTIME_SCRIPT = "gdharness_runtime/runtime_autoload.gd", PROFILER_PROBE = "_profiler_probe", PROFILER_CALIBRATOR = "_calibrate_the_profiler", CALL_SITES = 40;
 var init_script_profile = __esm(() => {
   init_gdscript_source();
   init_godot_variant();
@@ -43542,7 +43543,7 @@ function profileAnswer(reading, limit) {
     notes.push(`${table.superCallers === 1 ? "One function calls" : `${table.superCallers} functions call`} through super, marked selfIncludesSuper: the engine takes every other call out of the caller's self time, and not a super call, so ${table.superCallers === 1 ? "its" : "their"} selfMs holds the overridden function's time, which that function's own row counts again. Self time therefore cannot be added along an override chain, and scriptMs counts the time under a super call once more for each level above it.`);
   }
   if (table.overheadDominated > 0 && table.perCallUs !== null) {
-    notes.push(`The profiler costs about ${table.perCallUs}µs a call in this run, measured on an empty function the runtime addon calls as it goes on, and that time lands in the self time of the function called. ${table.overheadDominated === 1 ? "One function has" : `${table.overheadDominated} functions have`} at least half ${table.overheadDominated === 1 ? "its" : "their"} selfMs in it, under overheadMs: that much of its time is the profiler's and goes once the profiler is off, whether the function is inlined or not. What inlining saves is the call itself, which costs something without the profiler too, not the work inside it.`);
+    notes.push(`The profiler costs about ${table.perCallUs}µs a call in this run, measured on an empty function the runtime addon calls as it goes on, and that time lands in the self time of the function called. ${table.overheadDominated === 1 ? "One function has" : `${table.overheadDominated} functions have`} at least half ${table.overheadDominated === 1 ? "its" : "their"} selfMs in it, under overheadMs: ${namedFew(table.overheadNamed)}. That much of ${table.overheadDominated === 1 ? "its" : "their"} time is the profiler's and goes once the profiler is off, whether the function is inlined or not. What inlining saves is the call itself, which costs something without the profiler too, not the work inside it.`);
   }
   notes.push(...cappedNotes(totals));
   if (totals.unreadable > 0) {
@@ -43564,12 +43565,21 @@ function profileAnswer(reading, limit) {
     note: notes.length > 0 ? notes.join(" ") : undefined
   };
 }
+function namedFew(names) {
+  const shown = names.slice(0, 5);
+  const more = names.length - shown.length;
+  if (more > 0) {
+    return `${shown.join(", ")} and ${more} more`;
+  }
+  return shown.length > 1 ? `${shown.slice(0, -1).join(", ")} and ${shown.at(-1) ?? ""}` : shown[0] ?? "";
+}
 function cappedNotes(totals) {
   const notes = [];
   const most = totals.frameFunctions;
   const why = `${most} is kept below the game's debugger queue (network/limits/debugger/max_queued_messages), which drops the message naming a function when one frame names more than it holds, and a function whose name is dropped is never named afterwards.`;
   if (most !== undefined && totals.complete && totals.totalCapped === true) {
-    notes.push(`The engine's totals carried the most functions the profiler asks for, ${most}, so the functions with the least time are not in them: ${why}`);
+    const leastKept = Math.min(...Object.values(totals.functions).map((one) => one.totalSeconds));
+    notes.push(leastKept > 0 ? `The engine's totals carried the most functions the profiler asks for, ${most}, so the functions with the least time are not in them: ${why}` : `The engine's totals carried the most functions the profiler asks for, ${most}, and the last of them took no measurable time, so neither did any left out: the time is all here, and only a function too quick for the clock can be missing, with its calls. The engine lists every function it has compiled, run or not, and sends them busiest first. ${why}`);
   } else if (most !== undefined && !totals.complete && (totals.cappedFrames ?? 0) > 0) {
     const capped = totals.cappedFrames ?? 0;
     notes.push(`${capped === totals.frames ? capped === 1 ? "The one frame" : `All ${capped} frames` : `${capped} of the ${totals.frames} frames`} carried the most functions the profiler asks for in one, ${most}, so the functions with the least time in ${capped === 1 ? "it" : "them"} are not counted there: ${why}`);
@@ -46929,10 +46939,11 @@ class GodotServer {
     const startedAt = Date.now();
     const transcript = openTranscript(startedAt);
     closeSync2(transcript.fd);
+    const gameEnv = profiled ? { ...env ?? process.env, [PROFILE_FROM_START]: "1" } : env;
     const launched = await launchOutsideTheTree({
       command: godotPath,
       args: cmdArgs,
-      ...env === undefined ? {} : { env },
+      ...gameEnv === undefined ? {} : { env: gameEnv },
       run: {
         transcript: transcript.path,
         startedAt,

package/build/godot/addons/gdharness_editor/tools/profile_tools.gd

@@ -22,6 +22,9 @@ const DEBUGGER_CLASS: String = "ScriptEditorDebugger"
 const PROFILE_CAPTURE: String = "gdharness"
 const PROFILE_SENT: String = "gdharness:profile_sent"
 const PROFILE_RECEIVED: String = "gdharness:profile_received"
+## Set in the environment a played game inherits, when the play is to be profiled from its start.
+## Kept in step with the runtime addon's runtime_autoload.gd.
+const PROFILE_FROM_START: String = "GDHARNESS_PROFILE_FROM_START"
 
 
 ## The editor's debugger sessions, numbered as the editor numbers its debugger tabs.
@@ -106,6 +109,10 @@ func profile_start(args: Dictionary) -> Dictionary:
 	_frame_functions = asked if asked > 0 else FRAME_FUNCTIONS
 	if Read.as_bool(args.get("arm", false)):
 		_armed = true
+		# The game the editor starts next inherits the editor's environment, and this tells its
+		# runtime addon to hold its start until the profiler is on, which the session's start
+		# switches on with a message the game reads only on a later poll.
+		OS.set_environment(PROFILE_FROM_START, "1")
 		return {"ok": true, "started": false, "armed": true, "session": -1}
 	var active: int = _active_session()
 	if active < 0:
@@ -137,6 +144,7 @@ func profile_read(_args: Dictionary) -> Dictionary:
 
 func _reset() -> void:
 	_armed = false
+	OS.unset_environment(PROFILE_FROM_START)
 	_session = -1
 	_frames = 0
 	_complete = false
@@ -172,6 +180,8 @@ func _on_session_started(session_id: int) -> void:
 		_reset()
 		return
 	_armed = false
+	# The game has started with it by now, and a later play must not.
+	OS.unset_environment(PROFILE_FROM_START)
 	if _hook() > 0:
 		_switch_on(session_id)
 

package/build/godot/addons/gdharness_runtime/runtime_autoload.gd

@@ -47,6 +47,13 @@ const PROFILER_PROBE_CALLS: int = 10000
 ## on every 2048th call and only counts the others.
 const POLLS_PER_READ: int = 2048
 
+## Set in a game's environment by whatever starts it to be profiled from its start: the server for
+## a run it spawns, the editor for a play. Kept in step with `PROFILE_FROM_START` in the server.
+const PROFILE_FROM_START: String = "GDHARNESS_PROFILE_FROM_START"
+
+## How long such a game waits for its debugger to switch the profiler on before carrying on.
+const PROFILER_WAIT_MS: int = 5000
+
 ## How the engine is told to run a script instead of the game: `godot -s thing.gd`.
 const SCRIPT_FLAGS: PackedStringArray = ["-s", "--script"]
 
@@ -134,6 +141,37 @@ func _init() -> void:
 		"wait_signal": _waits.wait_signal,
 		"wait_until": _waits.wait_until,
 	}
+	_wait_for_the_profiler()
+
+
+## Holds the game's start until the profiler is on, when whatever started the game asked for a
+## profile from its start. The debugger switches the profiler on with a message the game reads only
+## on a poll, which comes every [constant POLLS_PER_READ] lines of script, so the main scene's _ready
+## could run first: a game played on a macOS runner counted 25 calls of a function called 26 times,
+## the first of them from _ready. Run at the autoload's construction, before the main scene loads.
+func _wait_for_the_profiler() -> void:
+	if OS.get_environment(PROFILE_FROM_START).is_empty():
+		return
+	# Read once: a process this game starts inherits its environment and must not wait as well.
+	OS.unset_environment(PROFILE_FROM_START)
+	if not EngineDebugger.is_active():
+		return
+	var deadline: int = Time.get_ticks_msec() + PROFILER_WAIT_MS
+	while not EngineDebugger.is_profiling("servers"):
+		if Time.get_ticks_msec() >= deadline:
+			push_warning(
+				(
+					(
+						"gdharness: this game was started to be profiled from its start, and the profiler"
+						+ " was not on %d ms later, so what ran before it is not counted"
+					)
+					% PROFILER_WAIT_MS
+				)
+			)
+			return
+		for _poll: int in POLLS_PER_READ:
+			EngineDebugger.line_poll()
+		OS.delay_msec(1)
 
 
 func _ready() -> void:

package/build/index.js

@@ -33393,6 +33393,7 @@ function queuedMessagesOf(projectGodot) {
   return typeof set === "number" && Number.isInteger(set) && set > 0 ? set : QUEUE_DEFAULT;
 }
 var UNNAMED_PREFIX = "#";
+var PROFILE_FROM_START = "GDHARNESS_PROFILE_FROM_START";
 function signatureParts(signature) {
   const parts = signature.split("::");
   if (parts.length < 3) {
@@ -33414,7 +33415,8 @@ function profiledFunctions(totals, limit, sourceOf = () => null) {
     counted: rows.length,
     superCallers: rows.filter((row) => row.selfIncludesSuper === true).length,
     perCallUs,
-    overheadDominated: rows.filter((row) => row.overheadMs !== undefined).length
+    overheadDominated: rows.filter((row) => row.overheadMs !== undefined).length,
+    overheadNamed: rows.filter((row) => row.overheadMs !== undefined).map((row) => row.function)
   };
 }
 var RUNTIME_SCRIPT = "gdharness_runtime/runtime_autoload.gd";
@@ -36036,7 +36038,7 @@ function profileAnswer(reading, limit) {
     notes.push(`${table.superCallers === 1 ? "One function calls" : `${table.superCallers} functions call`} through super, marked selfIncludesSuper: the engine takes every other call out of the caller's self time, and not a super call, so ${table.superCallers === 1 ? "its" : "their"} selfMs holds the overridden function's time, which that function's own row counts again. Self time therefore cannot be added along an override chain, and scriptMs counts the time under a super call once more for each level above it.`);
   }
   if (table.overheadDominated > 0 && table.perCallUs !== null) {
-    notes.push(`The profiler costs about ${table.perCallUs}µs a call in this run, measured on an empty function the runtime addon calls as it goes on, and that time lands in the self time of the function called. ${table.overheadDominated === 1 ? "One function has" : `${table.overheadDominated} functions have`} at least half ${table.overheadDominated === 1 ? "its" : "their"} selfMs in it, under overheadMs: that much of its time is the profiler's and goes once the profiler is off, whether the function is inlined or not. What inlining saves is the call itself, which costs something without the profiler too, not the work inside it.`);
+    notes.push(`The profiler costs about ${table.perCallUs}µs a call in this run, measured on an empty function the runtime addon calls as it goes on, and that time lands in the self time of the function called. ${table.overheadDominated === 1 ? "One function has" : `${table.overheadDominated} functions have`} at least half ${table.overheadDominated === 1 ? "its" : "their"} selfMs in it, under overheadMs: ${namedFew(table.overheadNamed)}. That much of ${table.overheadDominated === 1 ? "its" : "their"} time is the profiler's and goes once the profiler is off, whether the function is inlined or not. What inlining saves is the call itself, which costs something without the profiler too, not the work inside it.`);
   }
   notes.push(...cappedNotes(totals));
   if (totals.unreadable > 0) {
@@ -36058,12 +36060,21 @@ function profileAnswer(reading, limit) {
     note: notes.length > 0 ? notes.join(" ") : undefined
   };
 }
+function namedFew(names) {
+  const shown = names.slice(0, 5);
+  const more = names.length - shown.length;
+  if (more > 0) {
+    return `${shown.join(", ")} and ${more} more`;
+  }
+  return shown.length > 1 ? `${shown.slice(0, -1).join(", ")} and ${shown.at(-1) ?? ""}` : shown[0] ?? "";
+}
 function cappedNotes(totals) {
   const notes = [];
   const most = totals.frameFunctions;
   const why = `${most} is kept below the game's debugger queue (network/limits/debugger/max_queued_messages), which drops the message naming a function when one frame names more than it holds, and a function whose name is dropped is never named afterwards.`;
   if (most !== undefined && totals.complete && totals.totalCapped === true) {
-    notes.push(`The engine's totals carried the most functions the profiler asks for, ${most}, so the functions with the least time are not in them: ${why}`);
+    const leastKept = Math.min(...Object.values(totals.functions).map((one) => one.totalSeconds));
+    notes.push(leastKept > 0 ? `The engine's totals carried the most functions the profiler asks for, ${most}, so the functions with the least time are not in them: ${why}` : `The engine's totals carried the most functions the profiler asks for, ${most}, and the last of them took no measurable time, so neither did any left out: the time is all here, and only a function too quick for the clock can be missing, with its calls. The engine lists every function it has compiled, run or not, and sends them busiest first. ${why}`);
   } else if (most !== undefined && !totals.complete && (totals.cappedFrames ?? 0) > 0) {
     const capped = totals.cappedFrames ?? 0;
     notes.push(`${capped === totals.frames ? capped === 1 ? "The one frame" : `All ${capped} frames` : `${capped} of the ${totals.frames} frames`} carried the most functions the profiler asks for in one, ${most}, so the functions with the least time in ${capped === 1 ? "it" : "them"} are not counted there: ${why}`);
@@ -39426,10 +39437,11 @@ class GodotServer {
     const startedAt = Date.now();
     const transcript = openTranscript(startedAt);
     closeSync2(transcript.fd);
+    const gameEnv = profiled ? { ...env ?? process.env, [PROFILE_FROM_START]: "1" } : env;
     const launched = await launchOutsideTheTree({
       command: godotPath,
       args: cmdArgs,
-      ...env === undefined ? {} : { env },
+      ...gameEnv === undefined ? {} : { env: gameEnv },
       run: {
         transcript: transcript.path,
         startedAt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "mcpName": "io.github.Aureliolo/gdharness",
   "description": "A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.",
   "type": "module",