Skip to content

RandallLiuXin/GodotMaker / skills/core/gdtoolkit

gdtoolkit

Unverified

Lint and format GDScript files using gdtoolkit (gdlint + gdformat). Use after writing or modifying .gd files, when asked to check code style, fix lint errors, format code, or set up linting configuration. Also use when gdlint/gdformat errors appear in output and need diagnosis. Does NOT require Godot — runs as a standalone Python tool.

gdtoolkit — GDScript Lint & Format

Currently disabled (v0.3.4+). gm-verify no longer invokes gdlint / gdformat, and gm-build / gm-fixgap have removed this skill from their Available Skills tables. Reason: repeated gdtoolkit/linter/class_checks.py:144 NotImplementedError crashes on common ECS-style GDScript class shapes, plus low signal-to-noise vs the headless compile + reviewer pattern checks. Re-enabling tracked as ROADMAP R-112. The reference content below is preserved for ad-hoc use outside the pipeline and for the future re-enablement.

Wraps two CLI tools from the gdtoolkit Python package:

  • gdlint — static analysis and style checking
  • gdformat — deterministic auto-formatter

Prerequisites

pip install "gdtoolkit==4.*"    # Godot 4 projects
pip install "gdtoolkit==3.*"    # Godot 3 projects

Verify installation: gdlint --version && gdformat --version

If not installed, tell the user and offer to install. The version major must match the project's Godot major version (read from project.godot config/features).

Lint workflow

Run gdlint

gdlint path/to/file.gd          # single file
gdlint path/to/directory/       # all .gd files recursively

Interpret output

Each problem is one line on stderr:

path/to/file.gd:42: Error: Function name "MyFunc" is not valid (function-name)

Format: {file}:{line}: Error: {message} ({rule-id})

Exit codes:

  • 0 — no problems (stdout: Success: no problems found)
  • 1 — problems found (stderr: Failure: N problem(s) found)

Fix lint issues

For each reported issue, either:

  1. Fix the code — rename to match convention, remove unused arg, reorder members
  2. Suppress inline — when the violation is intentional:
    # gdlint:ignore = rule-id
    var _unusedButNeeded := 0   # this line + next line are suppressed
    
  3. Suppress region — for larger blocks:
    # gdlint: disable=function-name
    func ALLCAPS_required_by_engine():
        pass
    # gdlint: enable=function-name
    

When suppressing, always add a brief comment explaining why.

Format workflow

Run gdformat

gdformat path/to/file.gd        # format in-place
gdformat path/to/directory/      # format all .gd files
gdformat --check path/           # check only, don't modify (exit 1 if changes needed)
gdformat --diff path/            # show unified diff on stderr, don't modify

Exit codes:

  • 0 — already formatted / formatting succeeded
  • 1 — check mode found differences / parse error / safety check failed

Safety checks

gdformat runs three safety checks by default (disable with --fast):

  • TreeInvariantViolation — parse tree changed after formatting
  • FormattingStabilityViolation — formatting isn't idempotent
  • CommentPersistenceViolation — comments were lost

If a safety check fails, report the error to the user — do NOT use --fast to bypass it. This likely indicates a gdtoolkit bug; the file should be formatted manually or the problematic section excluded.

Rule reference

Naming rules (regex-configurable)

Rule IDDefault conventionExample
function-namesnake_case or _on_PascalCase_signalmove_player, _on_Button_pressed
class-namePascalCasePlayerController
sub-class-name_PascalCase (leading underscore)_InternalHelper
signal-namesnake_casehealth_changed
class-variable-namesnake_case or _privatespeed, _cache
function-variable-namesnake_caselocal_var
function-argument-namesnake_case or _unusedtarget_pos, _ignored
loop-variable-namesnake_case or _unuseditem, _i
constant-nameUPPER_SNAKE_CASEMAX_SPEED
enum-namePascalCaseDirection
enum-element-nameUPPER_SNAKE_CASENORTH, SOUTH_EAST

Code quality rules

Rule IDDefaultWhat it checks
max-returns6Too many return statements per function
max-public-methods20Too many public methods per class
function-arguments-number10Too many function arguments
max-file-lines1000File too long
max-line-length100Line too long

Style rules

Rule IDWhat it checks
unnecessary-passpass in non-empty body
duplicated-loadSame resource loaded twice
expression-not-assignedStandalone expression with no effect
unused-argumentArgument never used (fix: prefix with _)
comparison-with-itselfx == x
private-method-callCalling _private_method() from outside
class-definitions-orderMembers not in canonical order (see below)
trailing-whitespaceTrailing spaces
mixed-tabs-and-spacesMixed indentation
no-elif-returnUnnecessary elif after return
no-else-returnUnnecessary else after return

Class member order (class-definitions-order)

gdlint expects this top-to-bottom order:

  1. @tool
  2. class_name
  3. extends
  4. Docstring
  5. Signals
  6. Enums
  7. Constants
  8. Static variables
  9. @export variables
  10. Public variables
  11. Private variables (_prefixed)
  12. @onready public variables
  13. @onready private variables
  14. Remaining declarations

Configuration

gdlintrc

Create .gdlintrc (or gdlintrc) in the project root. YAML format. gdlint searches upward from CWD, uses the first file found.

Generate defaults: gdlint -d > .gdlintrc

Example with customizations:

# Relax line length to match gdformat default
max-line-length: 120

# Allow _on_NodeName_signal pattern (already default)
function-name: '(_on_[A-Z][a-z0-9]*(_[a-z0-9]+)*|[a-z][a-z0-9]*(_[a-z0-9]+)*)'

# Disable rules that conflict with project style
disable:
  - unnecessary-pass        # we use pass as explicit "intentionally empty"

# Exclude generated/vendored code
excluded_directories: !!set
  .git: null
  addons: null
  .godot: null

gdformatrc

Create gdformatrc in the project root. YAML format.

Generate defaults: gdformat --dump-default-config > gdformatrc

line_length: 120
# use_spaces: 4            # uncomment to use spaces instead of tabs
excluded_directories: !!set
  .git: null
  addons: null
  .godot: null

Important: no pyproject.toml support

gdtoolkit does NOT read from pyproject.toml. Only its own YAML config files work.

Recommended: align line lengths

Set max-line-length in .gdlintrc and line_length in gdformatrc to the same value. If they differ, gdformat may merge lines that then exceed gdlint's limit — a known source of false positives.

Quirks and limitations

  1. No # gdformat: off/on — there is no way to skip formatting for a code region. If gdformat mangles a specific construct, the only workaround is to restructure the code.

  2. gdlint checks unused arguments, not unused variables — var x = 1 with no further use of x will NOT be flagged. Only function arguments trigger unused-argument.

  3. excluded_directories only works when scanning directories — passing a file path directly (gdlint addons/plugin/main.gd) bypasses exclusion rules.

  4. gdformat safety check failures are real bugs — do not silence them with --fast. Report to the user and format that section manually.

  5. gdformat may cause data loss — always ensure the file is under version control before formatting. Run git diff after formatting to verify changes are correct.

  6. Version must match Godot version — gdtoolkit 4.x parses Godot 4 syntax, 3.x parses Godot 3. Mismatched versions cause parse errors on valid code.

Fallback: upstream documentation

If this skill's instructions don't resolve your issue — unexpected output, unfamiliar rule IDs, config syntax errors, or parse failures — consult the upstream repo directly:

Use the runtime's run_shell_command mapping with an available HTTPS client, such as curl --fail --location <url>, to read a wiki page or issue thread when you need details beyond what this skill covers. If no HTTPS client or outbound network access is available, stop and report that limitation instead of inventing upstream guidance.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall