auto-godot: A Headless CLI Tool for Godot Engine Targeting Agent Workflows

auto-godot is a Godot 4.6+ command-line tool designed specifically for AI agents. By directly manipulating Godot's text-format files (.tscn, .tres, project.godot), it enables features like sprite import, tileset automation, and scene management without the need for the editor GUI, filling the gap in headless workflow automation within the Godot ecosystem. It is particularly suitable for AI agent workflows and CI/CD automation scenarios.

As an open-source game development platform, the Godot engine has tools like version managers, GDScript syntax checkers, and CI Docker images, but it lacks a CLI tool that can bridge Aseprite exports to SpriteFrames and automate TileSet terrain configuration in headless mode. Existing MCP servers require running an editor instance, while many automation tasks should be executed headlessly in CI/CD pipelines—auto-godot was created for this purpose.

Sprite Workflow Automation

Supports Aseprite and TexturePacker workflows, converting sprite sheets into SpriteFrames .tres resources, handling animation directions, variable frame duration FPS, sprite cropping, and also supports sprite sheet splitting and atlas creation.

Tileset Automation

Automatically generates TileSet terrain configurations (47-tile blob, 16-tile minimal, RPG Maker A2 layout), supports creating tilesets from sprite sheets, batch assigning collision shape rules, and Tiled map import.

Scene Management

The scene list command displays project scenes and node trees; scene create creates scenes via JSON definitions and supports property passing for any node type.

GDScript Tools

Generates GDScript files, adds methods/signals/exports, parses Godot4 documentation comments to output documents in Markdown/JSON format.

Project Export and Management

Supports headless export, automatic retry for missing import caches, preset management and validation (checking duplicate names, missing paths, etc.).

Technical Features

Developed with Python 3.12+, uv package management is recommended; follows agent-native principles, output is suitable for AI parsing; optional image dependency handles image processing functions.

Application Scenarios

AI-assisted game development workflows (agents directly manipulate files), CI/CD pipeline automation, batch processing of sprites/tilesets, automated document generation for game projects.

auto-godot is unique in the Godot tool ecosystem: compared to MCP servers that require an editor instance, it provides truly headless file operations; compared to GDQuest docs-maker, which only supports Godot 3 and is no longer maintained, it supports Godot 4 document generation; it is the only independent tool that can import Aseprite/TexturePacker into SpriteFrames and automate TileSet terrain parity.

auto-godot achieves headless automation by directly manipulating Godot text files, enabling AI agents to seamlessly integrate into game development workflows. As AI-assisted development becomes more widespread, such agent-native tools will play an increasingly important role in various fields.