Godot Mobile Perf Doctor

Static mobile performance diagnostics for Godot 4 projects, with optional parsing of captured adb summary text.

The first release deliberately starts with static checks so it works in CI without an Android device.

Use it before device testing to catch obvious mobile risks: desktop renderer settings, missing or risky stretch configuration, oversized textures, missing safe-area evidence, and suspicious viewport settings.

Install

python -m pip install -e .

From PyPI:

python -m pip install godot-mobile-perf-doctor

Quick Start

godot-mobile-perf-doctor C:\Projects\MyGame --static
godot-mobile-perf-doctor . --profile portrait-2d --format json --output perf-report.json
godot-mobile-perf-doctor . --adb-summary adb-summary.txt --format markdown --output mobile-perf-report.md
godot-mobile-perf-doctor . --mobile-ui-metadata reports\mobile-ui.json --format markdown --output mobile-perf-report.md

List the built-in mobile profiles:

godot-mobile-perf-doctor --list-profiles

Config File

Create .godot-mobile-perf-doctor.toml in the project root:

profile = "portrait-2d"
format = "markdown"
fail_on = "warning"
output = "reports/mobile-perf.md"
max_texture_dimension = 2048
max_viewport_pixels = 2073600
mobile_ui_metadata = "reports/mobile-ui.json"

Profiles provide default texture and viewport budgets. CLI flags override config values, and config values override profile defaults:

godot-mobile-perf-doctor . --static --max-viewport-pixels 921600 --format json

Built-in profiles:

Real Workflow: Prepare An Android Test Build

Run a static mobile scan before sending a build to a phone:

godot-mobile-perf-doctor . --static --profile portrait-2d --fail-on warning --format markdown --output reports\mobile-perf.md

Use the report to check:

• whether the renderer choice is suitable for mobile;
• whether viewport and stretch settings are explicit and not likely to distort phone layouts;
• whether expected mobile UI metadata exists for safe-area and touch-layout review;
• which PNG textures carry the largest estimated RGBA memory cost;
• whether a recent adb summary shows janky frames that need follow-up.

If you already captured a short device run, attach the summary:

godot-mobile-perf-doctor . --adb-summary reports\adb-summary.txt --format json --output reports\mobile-perf.json

What It Checks

• Renderer setting and mobile risk.
• Base viewport size against the selected mobile profile.
• Stretch mode presence and stretch/aspect="ignore" risks.
• Optional mobile UI metadata path for safe-area evidence handoff.
• PNG texture dimensions and estimated RGBA memory.
• Optional adb summary text for device model and janky frame counts.

JSON reports include report metadata, active budget limits, and a rules object with plain-language explanations. Text, Markdown, and SARIF output use the same rule titles so local and CI reports are easier to compare.

Documentation

• Static checks
• Configuration
• Renderer guidance
• Texture guidance
• ADB summaries
• Rule reference
• CI usage

CI Example

- run: python -m pip install godot-mobile-perf-doctor
- run: godot-mobile-perf-doctor . --static --profile portrait-2d --format markdown --output reports/mobile-perf.md

Development

python -m pip install -e .
python -m unittest discover -s tests -v
godot-mobile-perf-doctor examples\tiny-godot-project --static --fail-on none

Examples are generic and safe to publish.