Profiling and builds: sources and measurements

The research behind the C# profiling and GC sections of the performance skill and behind the godot-export-release skill (versions, debug and release builds, reproducible exports, signing, store uploads), plus the kit changes made from it: export -GameVersion, the export check for missing C#, two doctor warnings and the import cache in the action. Gathered on 2026-10-21. Tests ran on Godot 4.7.2 mono and .NET 8.0.31 on Linux x86_64 (4 cores, headless), with dotnet-trace, dotnet-counters and dotnet-gcdump 10.0.750501 and dotnet-counters 8.0.547301. Marks: tested means run here, source means read in the code, doc means stated by the vendor, and unconfirmed means not verified. What the kit already had (bench, the GC-gen0 custom monitor, StringName caching, pipeline warm-up, export -Run, the release workflow, the Godot, template and NuGet caches) was not researched again.

Sources

Profiling C#

• The editor profiler (doc): "The profiler does not currently support C# scripts." It recommends Rider and dotTrace with the Godot plugin. It still shows engine time: "frame time, physics frame, idle time, and physics time", and "Frame Time includes rendering time". It runs over the debugger connection, so only in debug builds; --profiling turns it on from the command line (tested: listed in --help).
• The Visual Profiler (doc) "only measures CPU time taken for rendering tasks"; not on Compatibility on macOS; results depend on viewport size. --gpu-profile and Debug > Settings > stdout > Print GPU Profile print the same data without the editor but need a real renderer (unconfirmed: no GPU here). The ObjectDB Profiler (4.6+) snapshots and diffs every Object for leaks; "Native engine classes that are not exposed to the scripting API will not appear."
• --benchmark and --benchmark-file (tested) are editor-build only and time startup and shutdown phases ("[Startup] Main::Setup2": 0.246, "[Startup] Load Game": 0.101), no frames. --print-fps prints "Project FPS: 145 (6.89 mspf)" each second. --debug-stringnames prints every StringName allocated, at quit.
• Tracy, Perfetto and Instruments are scons options (profiler=tracy profiler_path=..., source). Tracy: "it's generally recommended to profile release templates" (doc). Perfetto: "Starting with Godot 4.7, Perfetto export templates are provided for every stable Godot release" (doc), but the 4.7.2 release assets hold Perfetto builds for Android only, no Tracy build, and native debug symbols for Android only (tested). These trace the engine; C# shows as time inside script calls.

Performance monitors in exports (tested)

TimeProcess and TimePhysicsProcess are in seconds. The class reference: some monitors "will always return 0 when used in a project exported in release mode"; custom monitors are readable "(debug and release mode)".

.NET diagnostics tools (tested)

Why the counters are empty (source): Godot hosts .NET as a component (hostfxr_initialize_for_runtime_config, hdt_load_assembly_and_get_function_pointer) and never runs a Main; the runtime calls RuntimeEventSource.Initialize() only from the startup path that runs Main. The reflection call reaches an internal type, so the skill keeps it under #if DEBUG. Without any tool, GC.GetTotalAllocatedBytes(true), GC.CollectionCount(n) and GC.GetTotalPauseDuration() as custom monitors work in release too.

GC and JIT settings (tested)

Where settings are read:

Which runtime: rollForward: LatestMajor makes an editor or --path run use the newest .NET runtime installed, not .NET 8. On GitHub's ubuntu-26.04 image 20261111 that is .NET 11, and there godottest under coverlet hit a CLR assert at shutdown (Attempt to reattach detached thread, ebr.cpp:144) after every test passed; with .NET 8 it did not (reproduced both ways, #264). So every Godot the kit starts gets DOTNET_ROLL_FORWARD=Major, which the .NET host applies over the runtimeconfig's setting: .NET 8 when it is installed, otherwise the lowest newer major. A value you set yourself is kept, and the kit's log names the one in force on its Godot: line. The editor you open by hand is not changed; set the variable in your environment to keep it on .NET 8 too.

<ServerGarbageCollector>true</ServerGarbageCollector> is not written to the runtimeconfig (Godot game projects are libraries with EnableDynamicLoading); <RuntimeHostConfigurationOption Include="System.GC.Server" Value="true" /> works.

Headless editor-binary runs, 3000 frames after 60 warm-up; "work" is the C# section of _Process, where GC pauses land. The workload keeps about 80 MB alive (300k int[64]) and allocates 2000 int[32] a frame, a quarter of them kept in a 200k ring so they get promoted (334 KB a frame):

With short-lived garbage only (448 KB a frame, small heap): 78 gen0 collections and 31 to 33 ms of pauses in 3000 frames, p99 0.88 ms, against 0 collections and p99 0.49 ms pooled. TieredCompilation=0, TieredPGO=0, TC_QuickJitForLoops=0 and ReadyToRun=0 made no measurable change (p99 0.80 to 1.30 ms, noise). Settings trade many medium pauses for fewer large ones; server GC also keeps a heap per core and uses more memory. Pooling removes the hitches, and GC.GetTotalPauseDuration() is the number to put on a monitor.

Builds

Configurations (source)

Godot.NET.Sdk 4.7.2 has Debug;ExportDebug;ExportRelease. Editor runs use Debug (DEBUG;TOOLS), debug exports ExportDebug (DEBUG, Optimize=false), release exports ExportRelease (Optimize=true, no DEBUG). Always defined: GODOT, a platform symbol (GODOT_WINDOWS;GODOT_PC, GODOT_LINUXBSD, GODOT_MACOS, GODOT_ANDROID;GODOT_MOBILE, GODOT_IOS, GODOT_WEB; from the RuntimeIdentifier at export, the host OS in the editor) and version symbols (GODOT4_7, GODOT4_7_2, GODOT4_7_OR_GREATER). The SDK sets the Debug constants "to ensure that the user cannot override" them. What reaches each build was checked in the DLLs: see debug-tools.md.

An export that exits 0 without C# (tested)

--export-release on a C# project with no .sln logged ERROR: ... no solution file was found and "completed with warnings", exited 0, and produced a game with no data_* folder: no C# at all.

Versions (tested)

application/config/version becomes the Windows FileVersion and ProductVersion, the macOS short_version and version, and the Android version/name when the preset fields are empty (doc). Android version/code must be raised by hand for every Play upload.

Reproducible exports (tested)

Inside git, ContinuousIntegrationBuild maps paths through SourceRoot, but the commit sha in InformationalVersion differs per commit, as expected. dotnet/include_debug_symbols=true in the preset ships a portable <Name>.pdb next to the DLL, which gives line numbers in C# stack traces; butler --ignore '*.pdb' leaves it out of a store upload while it goes to the crash service (sentry-cli debug-files upload -o <org> -p <project> [--include-sources] [--wait] <paths>, doc). Official desktop templates have no engine symbols.

Import cache (tested)

A project copied with cp -r (a new path and new file times) re-ran --import with no import lines; a cold run of examples/csharp logged 59. So .godot/imported, .godot/uid_cache.bin and .godot/editor/filesystem_cache* can be restored from a cache; .godot/mono holds build output and stale DLLs and stays out. On this small project no time was saved, since startup dominates.

Signing (doc)

• Windows: Godot signs on export with SignTool (on Windows) or osslsigncode (any OS); preset codesign/enable, codesign/identity, codesign/timestamp_server_url; environment GODOT_WINDOWS_CODESIGN_IDENTITY, GODOT_WINDOWS_CODESIGN_IDENTITY_TYPE, GODOT_WINDOWS_CODESIGN_PASSWORD, and GODOT_SCRIPT_ENCRYPTION_KEY.
• Azure Trusted Signing is now Artifact Signing: signtool.exe sign ... /dlib Azure.CodeSigning.Dlib.dll /dmdf metadata.json, SignTool 10.0.2261.755 or later. "Artifact Signing certificates have a three-day validity, so time stamping is critical". azure/artifact-signing-action@v2: "This Action can only be executed on Windows runners"; OIDC (id-token: write, azure/login@v3) recommended.
• macOS: Xcode codesign and notarytool, or rcodesign from any OS with a PKCS#12 certificate and an App Store Connect API key; staple afterwards. Environment GODOT_MACOS_CODESIGN_CERTIFICATE_FILE, ..._CERTIFICATE_PASSWORD, ..._PROVISIONING_PROFILE, GODOT_MACOS_NOTARIZATION_API_KEY, ..._API_KEY_ID, ..._API_UUID. Mono exports always get the JIT, unsigned-memory and DYLD entitlements.
• Android: C# export "is experimental and some limitations apply"; new Play apps need an AAB (Gradle build); "the keystore password and the key password currently have to be the same"; GODOT_ANDROID_KEYSTORE_RELEASE_PATH, _USER, _PASSWORD.
• iOS: C# experimental; export on macOS with Xcode; GODOT_IOS_PROVISIONING_PROFILE_UUID_RELEASE and _DEBUG.

Store uploads (doc; nothing was run)

A release job runs on push: tags or workflow_dispatch behind a protected environment, never on fork pull requests (pull_request_target would expose secrets to fork code); it writes certificates and keystores from base64 secrets to a temporary file deleted in an always() step, and passes no secret as a logged argument.

Kit changes

• bench places each frame by camera position and reports the slowest places (hotspots), and the skill budgets per area; from a Halo 4 talk, see gdc/halo-4-content-performance.md.
• export -GameVersion (Invoke-Export in ci/godot/hyperdot.ps1) takes a tag such as v1.2.3-rc.1; anything not starting with up to four dot-separated numbers fails with invalid-arguments. It writes the numbers (1.2.3) to config/version in project.godot for the export, sets Version and InformationalVersion (1.2.3-rc.1) in the environment, adds gameVersion to the JSON, and restores project.godot and the environment afterwards. The action's game-version input passes it, and .github/workflows/godot.yml sets it to the tag name on tag runs. Tested on examples/csharp with -GameVersion v1.2.3-rc.1: Example.dll FileVersion 1.2.3.0 and ProductVersion 1.2.3-rc.1+<commit sha>; with the preset's application/modify_resources=true the Windows exe's FileVersion and ProductVersion became 1.2.3.0, with false they stayed Godot's 4.7.2; project.godot was restored.
• Invoke-ExportPresets fails a C# export for Windows or Linux with export-failed when no data_* folder holds a .dll, which catches the exit-0 export above.
• doctor (ci/godot/lib/Doctor.ps1) warns when application/config/version is not numbers and dots, and when a preset has application/modify_resources=false.
• doctor warns about asset files (images, sounds, models, fonts, shaders) with the same content, each copy imported and exported on its own: compared by size, then SHA-256, outside addons/ (an add-on keeps its own icons), .godot/ and folders with a .gdignore; empty files are skipped.
• doctor warns when a scene or script adds an OccluderInstance3D and rendering/occlusion_culling/use_occlusion_culling is off (4.7.2's default, read with ProjectSettings.get_setting): the occluders cull nothing.
• doctor warns when physics interpolation is off (physics/common/physics_interpolation, 4.7.2's default) and a script on a CharacterBody2D/3D or RigidBody2D/3D moves it in _physics_process / _PhysicsProcess (move_and_slide, move_and_collide, forces and impulses, translate, or setting the position or linear velocity), so it moves at the tick rate (60 by default) and judders on a faster screen. It stays quiet when the frame rate is capped at the tick rate (application/run/max_fps, or Engine.max_fps / Engine.MaxFps set in code to that number or to anything that is not a plain number), and skips test folders. A script that extends the body through a class of its own is not followed.
• export -Json breaks each build's size down (exports[].size, ci/godot/lib/BuildSize.ps1): the output folder item by item, and Godot's pack by folder and by kind of source file. The pack format was read from 4.7.2's exports (format 4: "GDPC", version, engine version, flags, file base, directory offset; an embedded pack ends the executable with its size and "GDPC"), and an imported file's bytes count under its source through the .import and .remap files in the pack. Tested on Linux exports of a copy of examples/gdscript, separate and embedded (tests/Test-BuildSize.ps1); format 2 (Godot 4.0 to 4.3, directory right after the header) is read from memory of the source, not tested.
• .github/actions/godot/action.yml caches .godot/imported, .godot/uid_cache.bin and .godot/editor/filesystem_cache* under godot-import-<os>-<godot version>-<hash of *.import and project.godot>, with the prefix without the hash as a restore key.

Not confirmed

• --gpu-profile and Print GPU Profile output (no GPU here); whether C# methods are named in Perfetto's godot_scripting category (no custom build was made).
• How much time the import cache saves on a project with many assets.
• Who can use Artifact Signing (individuals, regions); whether the C# DLLs in data_* need signing as well as the exe.
• With Play App Signing, the exported keystore being only the upload key (Play documentation not fetched).
• GOG's documentation (HTTP 500); branch selection for build-game.
• No store upload, signing step or macOS, Android or iOS export was run.
• Whether DOTNET_EnableDiagnostics=0 should be set in shipped games so tools cannot attach (an opinion, not a finding).