From 09389f12db3754719faec2268bb5614cfd3940cf Mon Sep 17 00:00:00 2001 From: Rob B Date: Wed, 19 Jun 2024 22:37:18 -0400 Subject: [PATCH] WIP page for ExtendedAttributeProvider/Gameplay Tags --- modules/ROOT/nav.adoc | 2 + .../ModLoader/ExtendedAttributeProvider.adoc | 88 +++++++++++++++++++ .../pages/Development/UpdatingFromSml37.adoc | 4 +- 3 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 modules/ROOT/pages/Development/ModLoader/ExtendedAttributeProvider.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 505ade78..de0feba6 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -80,6 +80,7 @@ *** xref:Development/Satisfactory/ShoppingList.adoc[To-Do/Shopping List] *** xref:Development/Satisfactory/ConveyorRendering.adoc[Conveyor Rendering (Outdated)] // TODO ADA *** xref:Development/Satisfactory/AdaMessages.adoc[ADA Messages] + ** xref:Development/ModLoader/index.adoc[Mod Loader] *** xref:Development/ModLoader/ModModules.adoc[Mod Modules] *** xref:Development/ModLoader/Logging.adoc[Logging] @@ -93,6 +94,7 @@ *** xref:Development/ModLoader/ChatCommands.adoc[Chat Commands] *** xref:Development/ModLoader/Registry.adoc[Registry] *** xref:Development/ModLoader/GameMapRegistry.adoc[Game Map Registry] +// TODO *** xref:Development/ModLoader/ExtendedAttributeProvider.adoc[Extended Attribute Provider] *** xref:SMLConfiguration.adoc[SML Configuration] *** Legacy diff --git a/modules/ROOT/pages/Development/ModLoader/ExtendedAttributeProvider.adoc b/modules/ROOT/pages/Development/ModLoader/ExtendedAttributeProvider.adoc new file mode 100644 index 00000000..64b423d1 --- /dev/null +++ b/modules/ROOT/pages/Development/ModLoader/ExtendedAttributeProvider.adoc @@ -0,0 +1,88 @@ += Extended Attribute Provider + +Introduced in SML3.8, ISMLExtendedAttributeProvider is an interface that allows any modded asset to offer +https://dev.epicgames.com/documentation/en-us/unreal-engine/using-gameplay-tags-in-unreal-engine?application_version=5.2[Gameplay Tags] +to be utilized by mod systems. + +Gameplay Tags are essentially a structured hierarchical system of FName tags that Unreal has built further libraries and optimizations around. +Since the tags are text-based, using this system makes implementing cross-mod interactions with no hard dependencies easier. + +Learn more about practical use cases for Gameplay Tags in +https://www.tomlooman.com/unreal-engine-gameplaytags-data-driven-design/[this blog post]. + +TODO verify: +Epic's existing `IGameplayTagAssetInterface` is not useful for modding because it must be implemented in {cpp} +and we often want to apply tags to assets we don't have control over the parent class structure of, like FGItemDescriptors. + +Satisfactory Mod Loader adds mod config folders to Unreal Engine's search path as a gameplay tag source, +allowing each mod to define its own set of tags. + +== Usage Example: SML Special Item Descriptor Tag + +By adding the `SML.Registry.Item.SpecialItemDescriptor` tag to an item descriptor, the +GetObtainableItemDescriptors and IsDescriptorFilteredOut utilities in UModContentRegistry will consider it a Special item descriptor, +meaning it will be filtered according to usage of the `EGetObtainableItemDescriptorsFlags::IncludeSpecial` flag. + +[id="TagNameConventions"] +== Tag Naming Conventions + +TODO ue docs talking about the hierarchical nature of tags + +Tags should always start with your mod reference for clarity of who created them + +== Using Tags + +[id="CheckTags_Blueprint"] +=== In Blueprint + +TODO UE docs + +[id="CheckTags_Cpp"] +=== In C++ + +TODO Check implementation of `UModContentRegistry::IsDescriptorFilteredOut` in SML source code and UE docs + +=== Using Tags from Other Mods + +TODO pretty sure you can just create a tag with the exact same name in your mod and it will Just Work even in the case of 2 mods offering the same tag + + +== Defining New Tags + +[id="DefineTags_Editor"] +=== In the Editor + +Use the in-editor gameplay tag editor to define new tags and tag sources. + +You can find this manager in any editor field that uses gameplay tags, or by going to +Edit > Project Settings... > (Project heading) GameplayTags > Gameplay Tag List. + +TODO screenshot + +To define new tags, you must first add a tag file to your mod. +To do this, open the `Add New Tag Source` section of the manager. +Use `YourModReferenceGameplayTags.ini` as the Name, select your mod in the Config Path dropdown, then press `Add New Source`. + +It's possible to have more than one source in a mod + +Once you have a tag source, open the `Add New Gameplay Tag` section to define new tags. + +Make sure to follow the link:#TagNameConventions[Tag Naming Conventions] when defining new tags. +Leave a comment explaining the purpose of the tag, which will appear in editor hover tooltips. +Finally, pick your mod's ini as the Source and press `Add New Tag`. + +[id="DefineTags_Blueprint"] +=== From Blueprint + +TODO do we even want to mention runtime created tags in BP as an option? + +Would the data table route even be supported since we are using the config approach? +https://dev.epicgames.com/documentation/en-us/unreal-engine/using-gameplay-tags-in-unreal-engine?application_version=5.2 + + +[id="DefineTags_Cpp"] +=== From C++ + +TODO + +Mircea says you can just use regular c++ calls so probably link people to UE docs diff --git a/modules/ROOT/pages/Development/UpdatingFromSml37.adoc b/modules/ROOT/pages/Development/UpdatingFromSml37.adoc index 2505f93a..97a51239 100644 --- a/modules/ROOT/pages/Development/UpdatingFromSml37.adoc +++ b/modules/ROOT/pages/Development/UpdatingFromSml37.adoc @@ -118,4 +118,6 @@ and clicking on this warning will automatically update it for you. You might not be affected by these changes, but we'd like to draw extra attention to them. -=== TODO Additional Changes \ No newline at end of file +=== Gameplay Tags and ISMLExtendedAttributeProvider + +TODO xref:Development/ModLoader/ExtendedAttributeProvider.adoc[Extended Attribute Provider]