Meta-Thread: Enhancing Plugin/AddOn Documentation

[betalars]

This is a thread I create to gather issues with the documentation around Creating more Complex Editor Plugins, as a lot of it is really hidden and obscure knowledge and/or really counter-intuitive.

I will do my best to not try and tackle anything that is just about @tools in general to limit the scope.

This thread is intended for me to keep track of what are available resources both inside and outside the official documentation, what are known issues that involve documentation and editors so I can brainstorm ideas for fixes.

If you want to contribute to this, feel free to drop in comments following my examples.

The permanent links:
The branch I will be working from
Query of all issues in this repo about plugins
Query of all issues in the godot repo around documentation and plugins/extensions

Root of the current Plugin Documentation

This is the place where text drafts will be edited (a markdown instance hosted by a friend)

No, I don't want to nessecarily solve all the issues at once, but I just want a good overview of what could use enhancement and what not.

[betalars]

TranslationServer is unavailable in editor

[betalars]

My Captions Addon that needs a tons of these workarounds

[betalars]

This being required to create a plugin that allows you to both add new Objects and some UI for those:

if Engine.is_editor_hint():
	caption_inspector_plugin = (CaptionInspectorPlugin as Variant).new()

TODO: find an issue that mentions this

[betalars]

How to properly create and load custom user settings.

Creating and Reading User Settings for AddOns right now is kind of counter-intuitive, as they need to be created when the AddOn is activated, but also each time the game is loaded due to godot not saving settings that still have their default value.

This is an issue I raised because of that
A godot forum user asked about that

I did not find anything in the official documentation about it.

[betalars]

Passing a selected resource to a panel (similar to how selecting an AnimationPlayer will make the Animation Panel usable)

TODO: find an issue that mentions this

[betalars]

Confusion around when and why plugin functions are being alled

[betalars]

Will go trough all the issues not from other users next, but soon ™

[betalars]

Referencing from within the Plugin Base Script can be quite cumbersome, as some keywords are loaded after the AddOn has initialized but will prevent the AddOn from initializing because they cause errors in the parser before the AddOn is loaded.

TODO: find an issue that mentions this

[betalars]

Tiny confusion in the inspector plugin page about naming the base script: #9430

Resolution: replace plugin.gd with my_inspector_plugin.gd

[betalars]

I've just realized that due to scope I really do not want to tackle things revolving around just the @tool scripts that are not specific to Plugins/AddOns to limit the scope.
So I will not be enhancing Issues like #9784 right now.

[betalars]

Disambiguation:
What is a / when to use an AddOns, Plugins, gdextensions, modulse, tool and so on.

ALSO, and most critically: what is the difference between a plugin and an addon and what is the reasons all plugins reside in the addon folder?

A big question for it would be: where to best put it? My gut feeling would say it may need it's own section under Manual. This would then 100% be a seperate issue, that I am gooing to open for discussion.

Would address:

• Add clear instructions on how an end user can use a pre-compiled GDExtension in their project #9277

[betalars]

I've just realized that due to scope I really do not want to tackle things revolving around just the @tool scripts that are not specific to Plugins/AddOns to limit the scope.

Okay, I may make exceptions for really small tool-specific changes like this one:

• Document @tool gotchas #7184

[tetrapod00]

Just a general comment, if you have multiple small self-contained PRs it's usually preferred to send them in separately. But if you are writing a new page or large section that closes multiple issues, one large PR is also fine.

Multiple smaller PRs maximizes the chances that each one gets through without getting stuck in review.