Vav Labs
Back to current work

Tool / Godot 4 / Free · MIT

Godot Project Doctor Mini — project hygiene linter for Godot 4

A small Godot 4 editor plugin that scans a project for the problems that accumulate quietly — broken references, oversized textures, heavy scenes, export gaps — and writes Markdown and JSON reports. It runs in the editor dock and, using the same scanner, in CI.

Get it on the Asset LibraryView source on GitHub

v0.2.8 · MIT licensed · Godot 4.6+ · GDScript

The Project Doctor dock open in the Godot editor, showing Scan Project and Open Reports Folder buttons, a severity summary of 0 errors and 1 warning, and severity filters.
The Project Doctor dock running inside the Godot editor.

What it does

Make project rot visible before it ships.

Godot projects collect broken scene references, stale assets, oversized textures, and export-readiness gaps without announcing it. Project Doctor Mini makes those issues visible early — inside the editor and in pull requests — with conservative checks that aim to be useful rather than to impersonate a full dependency-graph analyzer.

  • One-click project scan from a Godot editor dock named Project Doctor.
  • Markdown and JSON reports from one shared schema, so the dock, files, CI summary, and PR comments never disagree.
  • Headless scan script for repeatable local checks and CI, not just the interactive dock.
  • Severity summary and filters for error, warning, and info findings.
  • Compact settings panel: thresholds, ignore patterns, baseline path, and experimental checks.
  • Baseline and ignore controls so existing projects start quiet instead of drowning in known findings.

Checks

What it looks for.

CheckSeverityPurpose
Missing scriptsErrorScene/resource references to scripts that no longer exist.
Broken resource pathsErrorReferenced res:// paths that cannot be found.
Large texturesWarningTextures above the configured size threshold.
Heavy scenesWarningScenes with many nodes that may need review or splitting.
Export preset readinessWarningMissing presets, or gaps such as missing platform, name, or export path.
Import settings issuesWarningUnreadable .import files, missing sources/targets, raw-mode large textures.
_process() usageInfoScripts doing per-frame work, marked for manual review.
Empty foldersInfoKeeps the project tree tidy.
Possibly unused filesInfoExperimental, off by default: files not referenced by scanned resources.

Continuous integration

The same scanner, as a reusable GitHub Action.

Project Doctor ships a reusable workflow (workflow_call), so a project can run the scan on every pull request without copying scripts around. Pick a mode —report-only, warn, or fail-on-errors — optionally let it post one compact PR comment, and read findings back as workflow outputs (errors, warnings, info, scan_duration_ms).

jobs:
  project-doctor:
    uses: Vav-Labs/godot-project-doctor-mini/.github/workflows/project-doctor.yml@v0.2.8
    with:
      godot-version: 4.6.2
      mode: warn            # report-only | warn | fail-on-errors
      comment-on-pr: true   # posts/updates one compact PR comment

Pin to a tag so CI behavior does not change underneath you.

Reports

Human-readable Markdown, machine-readable JSON.

Every scan writes both reports/project-doctor-report.md andreports/project-doctor-report.json from one schema. The Markdown is grouped into collapsible severity sections for GitHub; the JSON carries the same findings for automation. A sample Markdown report:

## Summary

| Severity | Count |
| --- | ---: |
| Error   | 2 |
| Warning | 1 |
| Info    | 0 |

### Error: Broken Resource Path in Example Texture
- Path: res://assets/textures/example.png
- Check: broken_resource_path
- Message: Referenced resource path does not exist.
- Recommendation: Update the reference or restore the missing resource.

Versioning & changelog

Current release: v0.2.8

The plugin follows simple semantic versioning while it evolves toward broader public use. Recent changes:

  • v0.2.8Synced every version reference across plugin metadata, docs, and example reports.
  • v0.2.6Dropped SVG from texture source extensions (it logged a warning each scan); tighter source-archive export rules.
  • v0.2.5Removed a leftover dotnet section from project.godot — the plugin is pure GDScript.
  • v0.2.4Asset Library submission release; stabilized the PR comment marker.
Full changelog