Scenario Godot Performance Export

Godot performance and release

Target: Godot 4.7.2.stable, macOS Apple Silicon.

Expert level here means every claim about speed comes with a before and after number from the same harness, every build is verified as a file before anyone calls it shipped, and the agent knows which numbers Godot reports wrongly. The stance: measure, classify the bound, fix the biggest cost, re-measure, compare pictures, then ship builds you have opened, run and listed. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-godot-expert (channels, the review loop, toolkit, 4.7 traps).

Stance (the expert delta)

1. Classify before fixing. Frame time is the slower of CPU and GPU, so a fix on the other side gains nothing (general optimization doc). Live: cutting draw calls from 2,501 to 2 dropped CPU from 2.7 to 0.35 ms and left the GPU at 6.2 ms; only the shadow budget moved the GPU (to 1.7 ms). Run a half-resolution pass: when GPU time does not fall, resolution is not the problem [added]. First log RenderingServer.get_video_adapter_name(): a hybrid laptop may run on its integrated GPU; --gpu-index N picks another [added].
2. Nodes cost before pixels do. Per-node _process, thousands of nodes and redundant physics objects are the usual Godot CPU cost (Firebelley 1PnG3r1rKcs: 115 ms to about 8 ms with RenderingServer items; DwMoEdAhtYQ, O5a4AKemkiQ). Replace repeats with MultiMesh and a shader, and centralize ticking. Live: 2,000 MeshInstance3D created in 2.3 ms, 0.6 ms through RenderingServer.instance_create2.
3. Spread periodic work. Random phase per poller, force_raycast_update() on a disabled RayCast (Dan Does Dev, s2C2RO_WMh0 [00:05:34]). Live: 600 agents, worst tick 1.93 to 0.64 ms, spike frames 62 to 16.
4. Hand-sized occluders, judged by objects drawn. Box occluders per big wall beat a whole-scene bake (Zenva, VBiBZBVxu1s: about 300 to 80 FPS baked versus 350 with boxes). Occlusion is a CPU raster: judge by objects drawn from several camera spots.
5. Hitches are loading, pipelines and runtime bakes. Load AND instantiate off the main thread, ship a warm pipeline cache (Shader Baker export option, 4.5), and log the PIPELINE_COMPILATIONS_* deltas per frame so each hitch is classed as load or compile. Navmesh bakes and ReflectionProbes on Always at area boundaries are the other suspects [added]. Live worst frame: synchronous 453 ms cold, threaded load plus instantiate 230 ms cold, 9.6 ms warm.
6. Test on the real target, long enough. Export With Debug does not slow the game; throttling shows only on long runs (Ian Bolton, Arm, WrjaUNAXYqk [00:05:20, 00:09:35]). Soak a phone 30 minutes in the heaviest area and gate on minutes 20 to 30 [added duration]. Clean build for every perf report: a stale cache hid a perf bug for weeks (Claire Blackshaw, grdqHJOL5F4 [00:16:15]).
7. Exports fail on environment and credentials, not on Godot. Templates per exact version, JDK and SDK paths, ETC2/ASTC import, bundle ids, signing identities, server headers. Credentials go in GODOT_* env vars, never in export_presets.cfg (export docs; Nihamkin _n9l15CANag [00:25:38]).
8. Web is Compatibility only and single-threaded by default. Threads need COOP same-origin plus COEP require-corp over HTTPS (web doc). Live: the threaded build without headers does not start.
9. A written plan must run without this toolkit. Next to every gd_perf call, give the engine code or CLI it wraps: the logger below, godot --headless --export-release, the env vars, bundletool, xcodebuild. Round-1 blind grading docked plans a reader could not run.

Establish first

Workflow

1. Baseline on a clean project copy. Clone with gd_env.base_project, gd_perf.install(P), rename application/config/name (Base3D clones otherwise share one user:// and shader cache). Read project.godot back: Jolt for 3D, the renderer you mean. gd_perf.scene_audit on the heavy scene. GATE: audit JSON saved, physics engine and renderer confirmed.
2. Measure windowed, per variable. gd_perf.profile_variant(P, scene, size=(1280, 720), driver="vulkan"): per-frame CSV, visible and shadow draw calls, scene _process time from sentinel nodes; it compares settings, toggles or rendering_method variants after gd_perf.install(P), while a single verdict on an unchanged scene needs only the lead's gd_run.profile_scene(driver="vulkan"). Never use Performance.TIME_PROCESS per frame: it holds one value for about a second. Metal reports GPU 0 on macOS; use Vulkan. Windowed frame time is capped at the refresh; judge gpu_ms and cpu_ms. Deeper: --gpu-profile, the Visual Profiler, the script Profiler (read Self, not Inclusive; it does not cover C#), RenderDoc or the vendor tool for one frame. GATE: two runs within 10 % [added].
3. Classify. gd_perf.classify(full, half_res). GATE: a written verdict (CPU scripts, CPU render, GPU fill, GPU geometry or shadows) backed by numbers.
4. Fix one thing, re-measure, look. gd_perf.apply_fix(P, scene, out, fix) writes a new scene: share_materials, multimesh, shadow_budget, box_occluders, visibility_range, strip_process (lab only: drops _process scripts once a shader does their work). gd_perf.compare(before, after) applies a 5 % and 0.1 ms noise floor. Capture before and after, contact sheet, open it. Resolution scale below an agreed floor (0.67) needs sign-off [added]. GATE: metric improved beyond noise, nothing regressed, mean luma difference under 0.02 or the change approved.
5. Hitch pass. perf_bench.gd:hitch with a fresh private HOME for a cold shader cache. GATE: worst frame under 2x the budget on warm cache, pipeline compilations off gameplay frames.
6. Ship builds. Presets through gd_run.ensure_preset plus gd_perf.preset_fields; exports under gd_perf.export_env(HOME=private_home). Plain CLI: godot --headless --path . --export-release "<preset>" <out>. Verify each artifact: verify_macos, verify_apk, verify_xcode_project, pck_listing, size_report, web_smoke. GATE: per platform below.
7. Run what you exported. gd_perf.run_exported(exe, ["--headless", "--", "--perf-log", "--perf-quit"]) with perf_logger.gd; web through headless Chrome. GATE: SHIP_BOOT shows the expected tags and renderer, PERF_SUMMARY p95 within budget, no errors.
8. Release audit and handover. gd_perf.release_audit(P); write signing, notarization and upload steps for the human holding the accounts (notarize_plan, steam_vdf). GATE: no high flag; account steps listed as "not run" with the reason.

Phones. Mobile renderer, or Compatibility for the widest low-end reach (Ray Hayes, KWhVVMpihsc [00:06:03]); fallback_to_opengl3 is on by default and changes the look, so capture the fallback too [00:05:12]. Low tier: scaling_3d_scale 0.67 to 0.8, Engine.max_fps = 30, physics tick 30 with interpolation on (O5a4AKemkiQ [00:03:43]). Apply the safe area on Android too: 4.7.2 APKs target SDK 36 (measured), so Android 15+ draws edge to edge [added]. Android build: --install-android-build-template only together with an export command (with --quit it installs nothing, measured), keystore in GODOT_ANDROID_KEYSTORE_RELEASE_{PATH,USER,PASSWORD}, size with bundletool build-apks --connected-device then get-size total [not run]. Thermal soak: log adb shell dumpsys thermalservice every 10 s; Streamline region markers and Performance Advisor in CI (WrjaUNAXYqk [00:14:43]); Performance.add_custom_monitor for on-device game metrics. Wire a crash reporter and test the next OS beta before launch (8zqjiRuhQLE [00:03:40, 00:09:11]). iOS: export writes an Xcode project, then xcodebuild archive and -exportArchive; create the App Store Connect record before the first upload, raise the build number each time, no simulator for Vulkan renderers, sudo xcode-select -s /Applications/Xcode.app/Contents/Developer when export says "xcodebuild requires Xcode" (x_ZFAV2id3I [00:14:41, 00:17:04, 00:40:34]). IAP: store plugins and accounts, never faked.

Web. Single-threaded unless threads were measured to matter. itch.io serves files as uploaded (no on-the-fly compression), so budget the bytes it sends. Background tabs pause _process and drop networked games; HTTPRequest has no chunked responses and one progress step per frame; a stale service worker can show another project (web doc). Once isolated, cross-origin fetches need CORS or CORP [added]. C# projects cannot export to web (version deltas 16). Leaderboard read-only in the browser.