Plugins Documentation - (Really) Final Answer?

Development Pipeline & Plugins Plugins
,
1

Documentation for Plugin Samples to cover Plugin API.

Ok so far all I’ve read is:

“There isn’t one, just have a look at the examples provided”.

Well, that sounds like mega-poor for a platform like UE? One is forced to randomly walk into some random plugin and search for relatively similar functionality to copy and paste in your codebase?
Failing to do that spending 96 hours helplessly trying to stack-overflow it or using the UE forums which is always out of date with the most similar answer date somewhere mid-2016…

Really, how come there isn’t anything better than that?

I know most code is c++ so you can literally do whatever you want with it so there isn’t such a “plugin API” but things like: packages creation/save, big question mark unexplained in any documentation, widgets for plugins, maybe explained somewhere else but can’t really pinpoint where actually, nor what to actually look for…

Again instead of just try your luck copying an existing sample how come there isn’t a single sample of a basic plugin available in the official documentation?

Dado.

3

Yeah, there’s a disconnect between PR/Marketing and the actual developers, watching all the dev’s updates on YouTube really make you realise that. Leave a programmer to talk freely for few minutes and they’ll tell you exactly how the whole system is miraculously held together with duck-tape really.

Then there are the super false-fake PR announcements like “We are proud of blah blah blah, we strive to do better blah blah blah… Focus, emphasis, resources, targets, accomplishments, blah blah blah…”

Anyway, documentation is hard, real hard. I understand that. I just do not see any tangible results in “doubling the documentation team”, looks like patchwork to me.
Of course, there’s a lot more than that and situations are always a lot more complex than anyone might think, but at the end of the day you are judged on your results and on what people see, and in this case, is an absolute mess.

I personally think that API reference without linked samples is totally useless, it’s just a dump of doxygen (or whatever tool they are using) without any extra information, infact looking at the source code is most of the times more useful, which again, renders the documentation completely useless.

Take for example

UPackage::SavePackage

API Documentation is what? A dump of function definition, but if you do not have a sample of reference you’ll never know that you’ll need another 8 lines of code in order to make it work.
And not just that, you need to know the proper design pattern and best practice of how/when to use it.

When a 17years old youtuber explain the API better than your official documentation, and you are a multi-billion dollar platform, you have a problem IMO.

Dado.

4

I am using the engine for quite some time, but there was a time Epic was doing a lot of YouTube Live Training sections showing how to do stuff with the engine, mostly new features, and guess what? Plugins included!!

Here is a list of the videos I could compile in 15min of searching into the video list, thou I have found that some are missing:

Also, notice that following those videos will mostly require that you have installed the engine release they were using, so you won’t get caught on changes that will block you from following the lessons. Once, you have reproduced the lesson, you can install the next release and see if there was some sort of deprecation on the API that once you compile you will receive messages telling that in the next release a change on the source will be required. This way you will not only learn, but understand how to troubleshoot and understand why those changes (if any) took place.

GL there!

5

I think a lot of people are being quite disingenuous really. If you’re advanced enough to write complex plugins or have to do some custom functionality in UPackage::SavePackage then you’re ■■■■ well advanced enough to read and understand the engine source code, which is full of comments describing what certain bits and pieces do.

The QT documentation linked above and heralded as the “gold standard” is personally infuriating. I do not want my API docs cluttered by stupid bs like “what’s HSV color”. If you want to use HSV color there’s plenty of online resources to find out what HSV color is. But even if we disregard that, a detailed description of the “setBlue” function is really just clutter. It’s far more useful to have explanations of actual tricky functionality rather than go into silly details for obvious things just for the details’ sake.

6

That shows exactly my point :slight_smile: :grinning:

Out of those videos, the only one veguely referencing the plugin architecture is the one from 2015… And it won’t reference assets creation/saving, or is depreciated badly.
I’m not sure what the others 2 have to do with plugin documentation…

So yeah the answer for me can’t be: “Just search random video on YouTube”. It’s just not good enough, and as said, after watching 6 hours of content in the vain hope that that will matter to you, it wont…

Dado.

7

Asset Creation & Saving could be found at the Unreal Wiki, which is currently offline I guess. I remember someone posting an example of a Text asset which you can create, edit content, and reference while in editor and at runtime. Is this enough? If yes, I can try find the source material elsewhere.

I couldn’t agree more in respect of your concerns. Actually the current documentation lacks examples of API usage, and their descriptions are shallow. The only way I could improve my skills where to look at the engine source code and see how the devs are using them, some other time I check plugins made by Marketplace Creators and complement. It is by far the only way to get the job done in my case.

1 Like
8

Yes that’s exactly what I did, or what I do usually, I go straight to the source code but that will only get you up to a certain point. For example, scanning UPackage::SavePackage I couldn’t find the right pattern to use, I had found by luck some medium blog post by an excellent developer who explained that.

Looking at the source code won’t give you this: (This is my attempt, it’s working, I guess)

template <typename UA>
auto SaveAsset(UA* AssetObject, const FString& AssetName, const FString& AssetPath) -> bool
{
	auto bSaved = false;
	const auto AssetPathFull = AssetPath + AssetName;

	UPackage* Package = CreatePackage(ToCStr(AssetPathFull));
	Package->FullyLoad();

	auto* NewAnim = NewObject<UA>(Package, ToCStr(AssetName), RF_Public | RF_Standalone | RF_MarkAsRootSet,
	                              AssetObject);

	if (Package->MarkPackageDirty())
	{
		FAssetRegistryModule::AssetCreated(NewAnim);
		const FString PackageFileName = FPackageName::LongPackageNameToFilename(
			AssetPathFull, FPackageName::GetAssetPackageExtension());
		bSaved = UPackage::SavePackage(Package, NewAnim, EObjectFlags::RF_Public | EObjectFlags::RF_Standalone,
		                               *PackageFileName);
		// SNotification( FText::FromString(PackageFileName), 10.0f, SNotificationItem::CS_None);
		// SNotification( FText::FromString(bSaved ? TEXT("True") : TEXT("False")), 10.0f, SNotificationItem::CS_None);
	}
	return bSaved;
}

Now this is a super mega simple example, just saving an asset, imagine anything with a more elaborate dependency, either you are working on the engine, or you’ll have no chance.
And btw, it’s a super mega simple example but again, loads of unanswered questions:

  • What FullyLoad does ?!?
  • Do I need to MarkDirty or not?
  • What’s the correct path structure?
  • Why do I have to specify the package path twice?
  • What are InOuter packages it references to?

Of course, if I have all the time in the world I could just know the entirety of Unreal Engine and know all those answers, but I don’t unfortunately…

Dado.

9

Also, I don’t buy the “Read the source code” doctrine. I think it’s totally out of touch with reality.

A platform with billions of lines of code, with 20+ years of development of hundreds/thousands of people…

How can anyone in their right minds say: “Yeah, look at the source code, it’s there…”

Either it’s a shortcut to avoid documenting for the mere mortals, or not even John Carmack can do much with it… (I believe one of the reasons why Epic decided to make it open source-ish is that the code itself has got no value if you do not have the infrastructure behind to maintain, expand, understand, improve, etc…)

I know you won’t need to know it all but even pinpointing to the right place is a challenge, and as said, as soon as dependencies arise, you’re DOA!

Dado.

10

In the past I have explained a lot of these things in random forum posts here…

But good luck finding those posts, a lot of things were lost in the migration process lmao

1 Like