start_profiler
Begin recording a Godot runtime profiling capture that runs while scripts, input, and screenshots drive the game, then reports frame drops and timelines. Stops automatically after the set duration.
Instructions
Start a profiler capture and return at once, so simulate_input, run_script and screenshots drive the game while it records; timeline and track show where frames drop. Requires run_project with profiling: true. Stops itself after seconds (default 30, max 60); read it with stop_profiler. Unattended window: use profile_project. Returns: warnings if any, projectPath, active, visual, timeline, timelineMs, firstFrame, captureLimit, maxSeconds. Errors if a capture is running or profiling was off.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "start_profiler"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| track | No | Up to 4 NodePath:property values the game samples during the capture (every 250 ms, or half the interval when shorter), placed on the timeline by frame number, e.g. "/root/Main/Player:global_position" - where the player was when frames got slow. Implies timeline. Uses the bridge: drive the game between start_profiler and stop_profiler, not in parallel with profile_project. Collected only while the session that started the capture is current. | |
| visual | No | Also record the editor's Visual Profiler: CPU and GPU milliseconds per render stage (culling, shadows, opaque pass, canvas, ...) in `visual` (default: false). GPU times are null on GLES/web builds of the Compatibility renderer, which time no GPU work; `visual.gpuTimed` is false and a warning says so. A frame holds 256 render markers by default; a scene that needs more makes the engine log an error per lost marker, slowing the game, so the capture switches visual off and its warnings say how to raise the limit. | |
| seconds | No | Maximum capture duration before the automatic stop, greater than 0 and at most 60 (default: 30). | |
| timeline | No | Also record the capture over time in `timeline.buckets`: per interval the fps, frameMs avg/max, process/physics/script ms, slowFrames, draw calls, render CPU/GPU ms (with visual) and the heaviest functions, server calls or render stages (`top`, named once in `timeline.items`) - where and when frames got slow (default: false). timelineMs, timelineTop, timelineBuckets and track turn it on by themselves; false beside any is rejected. | |
| targetFps | No | Frame rate to hold the game to (default: 60). slowFrames counts frames whose frameMs exceeds 1000/targetFps, over the capture and per timeline interval. Under vsync every frame lasts the refresh interval: disable vsync, or set targetFps a few percent below the refresh rate. | |
| timelineMs | No | Timeline interval in milliseconds, 250..5000 (default: 500). Records at most about 60 intervals (60 s: 1000 ms) and the reply merges them down to timelineBuckets. Implies timeline. | |
| timelineTop | No | Heaviest functions, server calls or render stages listed per timeline interval, 0..10 (default: 3). 0 leaves `top` empty. Implies timeline. | |
| captureLimit | No | Rows the engine puts in each frame packet, 16..512 (default: 512). Godot selects them by inclusive time, so a lower limit hides cheap functions and sets limitReached. | |
| timelineBuckets | No | Most intervals the timeline reply holds, 4..60 (default: 20). A capture recorded in more is merged: adjacent intervals combine (counts and times add up, maxima stay) and `timeline.bucketMs` reports the width. Implies timeline. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| active | Yes | ||
| visual | Yes | ||
| timeline | Yes | ||
| warnings | No | ||
| firstFrame | Yes | ||
| maxSeconds | Yes | ||
| timelineMs | Yes | ||
| projectPath | Yes | ||
| captureLimit | Yes |