Godot editor plugin

The agh plugin for Godot 4.3 and later shows each file's agh record in the editor, edits its tags, files requests for new assets without leaving Godot, and finds the assets your game no longer uses.

Install

Copy engines/godot/addons/agh from the agh repository into your project's addons/ folder, then turn on Asset Goes Here in Project > Project Settings > Plugins. An agh dock appears on the right.

In Project Settings > General > agh (the basic settings):

• Server: the agh address, such as https://app.assetgoeshere.com, or http://localhost:7414 for agh serve.
• Project: the agh project id, such as my-game.
• Repository Folder: where the Godot project sits in the repository, such as game, when it isn't at the root. Left empty, the plugin finds it from the .git folder. agh paths are relative to the repository root, so game/art/hero.png in agh is res://art/hero.png in Godot.

These go into project.godot, so everyone on the team shares them.

Sign in

The plugin signs in the way the agh CLI does, and they share a sign-in:

• If you've run agh login for this server, the editor is already signed in.
• Otherwise press Sign in in the dock. Your browser opens agh's sign-in page and returns to the editor; the CLI is signed in afterwards too.
• To sign in as a tool instead of a person, set agh/tool_client_id and agh/tool_client_secret in Editor > Editor Settings (or AGH_CLIENT_ID and AGH_CLIENT_SECRET in the environment).
• A local agh serve needs no sign-in. Set agh/local_user in Editor Settings (or AGH_USER) to name yourself.

Editor settings stay on your machine and never go into the project.

See a file's record

Select a file in the FileSystem dock. The Asset tab shows its agh record: id, kind and status, the brief, the provenance and who made it, the file waiting for review if there is one, the pull request it waits in, an open question and the last review note. The same record appears at the top of the inspector for a resource you open.

A file agh doesn't track says so. If the repository's .agh/provenance.yaml lists it, the plugin shows what that file says, and it does the same when the server can't be reached.

From the record you can:

• Edit tags. Type to pick a tag other assets in the project already use, as in the Gallery, or write a new one as key=value. Save tags needs the developer or admin role.
• Ask for a new version of a delivered, accepted or published asset, with a note, as agh revise does.
• Follow Used by links to the scenes and resources that use the file, after a scan.

See the files a node uses

Select a node in the Scene dock and the inspector's Asset Goes Here section lists the files it uses: its textures, sounds, fonts, materials and the like, including script variables that hold a resource or a res:// path. Each row names the property, such as texture or click_sound, and shows the file's agh id, status and provenance. Files with a delivery waiting for review or an open question come first. Open a row for its record, with Show in FileSystem, Open in agh dock and Ask for a new version…. A file agh doesn't track offers Request with agh… and Adopt…, which tracks it as it is, as agh adopt does, once it's pushed.

It works for the running game too. Run the game, open the Game tab, choose 2D (or 3D) and Select, and click something: Godot selects that node in the Scene dock's Remote tree, and the section shows its files. While the game runs with Input chosen, clicks go to the game instead.

The agh dock's Asset tab follows along: it lists Files this node uses above the record, and picking one shows its record and selects it in the FileSystem dock. Selecting a file in the FileSystem dock goes back to that one file.

Request an asset

Right-click a folder in the FileSystem dock and choose Request with agh… (Godot 4.4 and later), or select a folder and use the Asset tab's button, or open the Request tab. Give the path the game expects the file at, write the brief, and pick the kind, tags and spec. The id is suggested from the path, as agh adopt makes them.

Add to my draft puts the request in your draft batch, as agh request does. Reference the path in your scene or code straight away; agh publishes the file there once someone makes it and you accept it. When the feature's requests are in, write a message and Submit for approval. Developers and admins can tick Approve it too to send the batch straight to the queue.

Find unused assets

The Unused tab's Scan project reads every scene, resource, script, shader and project setting for the files they use, and lists the agh assets in two groups:

• Nothing uses these: no file in the project refers to them.
• Only files the game never reaches use these: a scene or resource uses them, but nothing leads to that scene from what the game starts from. The game starts from the main scene, autoloads, the icon and the other paths in project.godot and export_presets.cfg.

Scripts that name an asset's path without res://, such as load("res://" + "art/hero.png"), count as using it. A path a script builds from pieces is read as a pattern: "res://art/level_%d.png" % n matches art/level_1.png, "res://cards/" + id + ".png" matches every PNG in cards/, and "icons/{0}.png".format(...) works too. Assets a pattern matches go in a third group, Code may build these paths from pieces, whose tooltip names the script and the pattern; they aren't tagged usage=unused. A pattern needs some fixed folder or name to go on, so "%s.png" % name alone matches nothing. Paths built any other way, such as from a list in a data file, can't be seen, so check before you remove anything. Assets for the store page or marketing, and files outside the Godot project, are left out.

Double-click a row to select the file. Tag in agh tags every asset found usage=unused, and takes the tag off assets in use again, so agh list --tag usage=unused and the Gallery find them.

For agents: this page as Markdown is at /docs/godot.md, and the CLI prints it with agh guide godot.