GDShrapt is a set of C# libraries for working with GDScript code — the scripting language of Godot Engine. Whether you need to parse, analyze, transform, validate, lint, or format GDScript source code, GDShrapt provides the building blocks to do it programmatically.
The libraries are designed to be used together or independently: from a lightweight parser for simple code inspection to a full-featured toolkit for building IDE plugins, CLI tools, or custom language integrations.
-
One-pass parsing — High-performance character-by-character parsing with no backtracking. The parser processes input in a single pass, making it predictable and fast.
-
Format preservation — Comments, whitespace, and formatting are preserved in the AST. Round-trip your code through parse → modify → generate without losing structure.
-
Modular architecture — Use only what you need. The core parser has zero dependencies; validation, linting, and formatting are separate packages.
-
Full GDScript 4.x — Complete support for modern GDScript: lambdas, await, typed arrays/dictionaries, pattern matching, all annotations.
- IDE/Editor plugins — Build language support, code completion, refactoring tools
- CLI tools — Create linters, formatters, code generators for CI/CD pipelines
- Language embedding — Integrate GDScript parsing into other technologies
- Code analysis — Static analysis, metrics, documentation generation
| Package | Description | NuGet |
|---|---|---|
| GDShrapt.Reader | Core parser and AST | |
| GDShrapt.Builder | Fluent API for code generation |  |
| GDShrapt.Validator | AST validation with diagnostics |  |
| GDShrapt.Linter | Style checking and naming conventions |  |
| GDShrapt.Formatter | Code formatting with type inference |  |
dotnet add package GDShrapt.ReaderAdd optional packages as needed:
dotnet add package GDShrapt.Builder
dotnet add package GDShrapt.Validator
dotnet add package GDShrapt.Linter
dotnet add package GDShrapt.Formatterusing GDShrapt.Reader;
var reader = new GDScriptReader();
var tree = reader.ParseFileContent(@"
extends Node2D
@export var health: int = 100
func _ready():
print(""Hello, Godot 4!"")
");
Console.WriteLine(tree.Extends?.Type); // "Node2D"
Console.WriteLine(tree.Variables.First().Identifier); // "health"var classDecl = GD.Declaration.Class(
GD.Atribute.Extends("Node2D"),
GD.Declaration.Variable("speed", "float", GD.Expression.Number(100.0))
);
classDecl.UpdateIntendation();
Console.WriteLine(classDecl.ToString());var validator = new GDValidator();
var result = validator.Validate(tree);
foreach (var error in result.Errors)
Console.WriteLine(error); // "error GD5001: 'break' can only be used inside a loop (3:4)"var linter = new GDLinter();
var result = linter.LintCode(code);
foreach (var issue in result.Issues)
Console.WriteLine(issue); // "warning GDL101: Variable 'MyVar' should use snake_case (2:4)"var formatter = new GDFormatter();
var formatted = formatter.FormatCode(code);
// Applies consistent spacing, indentation, and line endingsEach package has detailed documentation in its README:
- GDShrapt.Reader — Parsing API, helper classes, error recovery
- GDShrapt.Builder — Building styles, factory methods, examples
- GDShrapt.Validator — Diagnostic codes, runtime providers, type inference
- GDShrapt.Linter — Lint rules, naming conventions, suppression comments
- GDShrapt.Formatter — Format rules, LSP options, style extraction
For examples, see the test projects in src/.
See CHANGELOG.md for version history.
Contributions are welcome! Please feel free to submit issues and pull requests.
If GDShrapt helps your project, consider supporting its development:
Your support helps maintain these tools and build new features for the Godot community.
Related projects:
| Project | Description |
|---|---|
| GDShrapt.TypesMap | Runtime type provider for Godot classes and global functions |
This project is licensed under the MIT License — see the LICENSE file for details.
- Godot Engine team for the amazing game engine
- All contributors who have helped improve this project
