Merge pull request #286 from satisfactorymodding/Dev

Update with changes from Dev

cspell.json

@@ -38,6 +38,7 @@
         "FACTORYGAME",
         "favorited",
         "Feyko",
+        "fgcheck",
         "fgrecipe",
         "FGUnlock",
         "ficsit",
@@ -130,6 +131,7 @@
         "hte",
         "reccomend",
         "outselves",
-        "favortied"
+        "favortied",
+        "destory"
     ]
 }

lychee.toml

@@ -24,8 +24,10 @@ exclude = [
     "https://www.audiokinetic.com/en/download/",
     # unable to get local issuer certificate
     "https://questions.satisfactorygame.com/",
-    # 403s despite being valid pages
-    "https://stackoverflow.com/questions/"
+    # 403s despite being valid page
+    "https://stackoverflow.com/questions/",
+    # 403s despite being valid page
+    "https://www.unrealengine.com/en-US/ue-on-github"
 ]
 
 # Exclude these filesystem paths from getting checked.

modules/ROOT/nav.adoc

@@ -41,6 +41,7 @@
 *** xref:Development/Cpp/setup.adoc[Setup]
 *** xref:Development/Cpp/debugging.adoc[Debugging]
 *** xref:Development/Cpp/hooking.adoc[Hooking]
+// TODO *** xref:Development/Cpp/GettingBpData.adoc[Working with Assets and Blueprint-Defined Data from {cpp}]
 *** xref:Development/Cpp/thirdparty.adoc[Third Party Libraries]
 
 ** xref:Development/Modeling/index.adoc[3D Modeling]

modules/ROOT/pages/CommunityResources/IconGenerator.adoc

@@ -17,7 +17,7 @@ https://github.com/DavidHGillen/Satisfactory_IconCapture[GitHub page].
 
 Kyrium's tool captures images using a render target, allowing capture of materials with opacity.
 
-You can learn more about how to download and use the plugin on its https://git.kyrium.space/sf-modding/publictools/kiconmaker[Gitlab page].
+You can learn more about how to download and use the plugin on its https://github.com/Satisfactory-KMods/KIconMaker[GitHub page].
 
 == Nog's Icon Generator
 

modules/ROOT/pages/Development/BeginnersGuide/CreateGitRepo.adoc

@@ -261,13 +261,16 @@ This section assumes that you already know about the repository creating, commit
 
 Use the git tool you are comfortable with.
 
-It is suggested that you not enable Unreal's version control integration because it works at the project level and not the plugin level.
-
-Be extra careful with merge conflicts and branches in the context of Unreal Engine.
-Most Unreal Engine asset files are raw binary files, which means git diffing them is difficult.
-Panakotta has directions on using UE as diff tool
-https://gist.github.com/Panakotta00/c90d1017b89b4853e8b97d13501b2e62[here],
-but it's best to totally avoid merge conflicts wherever possible.
+Be mindful of merge conflicts and branches in the context of Unreal Engine.
+Most Unreal Engine asset files are raw binary files, which means git diffing them must be done inside the editor.
+The editor has a pretty decent built-in merge resolver,
+but you must be able to open the editor to use it.
+You'll have to resolve conflicts and compile errors on the {cpp} side first
+to build a working Development Editor copy to open,
+and the editor could get confused if information from {cpp} parent classes change.
+
+Panakotta has directions on setting up UE to launch in diff mode as a git diff/merge tool
+https://gist.github.com/Panakotta00/c90d1017b89b4853e8b97d13501b2e62[here].
 
 ## UE4GitDiff
 

modules/ROOT/pages/Development/BeginnersGuide/SimpleMod/buildable.adoc

@@ -34,12 +34,14 @@ Later on, you can write your own to allow upgrading buildings or to have snappin
 You can learn more about how holograms work on the xref:Development/Satisfactory/BuildableHolograms.adoc[Buildable Holograms] page.
 ====
 
-As you can see in the `Components` pane in the top left, the actor already contains a few components. But not any visuals, so, now add a new static mesh component in the center of the viewport. The build gun uses the origin when targeting the mesh to be built or snapped.
+As you can see in the `Components` pane in the top left, the actor already contains a few components.
+But not any visuals, so, now add a new instanced static mesh component in the center of the viewport.
+The build gun uses the origin when targeting the mesh to be built or snapped.
 You can use link:{attachmentsdir}/BeginnersGuide/simpleMod/Mesh_DocBuild.fbx[this example Mesh], the Plantpot of Knowledge, for your buildable.
 
 This Actor is also where you can define the snapping area and the clearance area, but we won't do that for now. Look to other machines and examples for inspiration as there are several relevant settings to make those behaviors work correctly.
 
-== Make it paintable
+== Make it Paintable
 
 We want to make our buildable xref:Development/Satisfactory/Paintable.adoc[paintable], meaning, able to be painted it with the paint gun. Because the `FGBuildable`-class already provides a basic implementation for that, we just need our buildable's mesh to use the `MI_Factory_Base_01` material. The provided example mesh already provides a proper UV map for said material, so you will not need to edit the UVs of the provided mesh. You will need to do so for your own models. More info on the materials already in the game can be found at xref:Development/Modeling/MainMaterials.adoc[Main Materials] documentation page. 
 
@@ -76,6 +78,8 @@ then add Ingredients entries to define the cost of constructing the building.
 The Product field should contain exactly one entry -
 the FGBuildingDescriptor asset you just created for your buildable.
 
+Don't forget to list your newly created recipe in the unlocks of a Schematic otherwise it won't be registered.
+
 That's it! You don't need to register anything else. When the recipe gets loaded, everything else also gets loaded and the buildable in the save file has soft references to the classes, and if they get loaded also the classes like our newly created buildable get loaded.
 
 == Trying it Out

modules/ROOT/pages/Development/BeginnersGuide/SimpleMod/recipe.adoc

@@ -98,7 +98,7 @@ M Overridden Category::
   Categories control what subsection a recipe appears under in the recipe list.
   By default, recipes take on the category of their first product item.
   {blank} +
-  We'll leave this at `None` so that it sticks with the default category of the Leaves item.
+  We'll leave this at `None` so that it sticks with the default category of the Wood item.
 * {blank}
 +
 M Manufacturing Menu Priority::

modules/ROOT/pages/Development/BeginnersGuide/dependencies.adoc

@@ -138,14 +138,6 @@ as well as making sure you're logged into your linked GitHub account when you fo
 [id="UnrealLinker"]
 === Link Your GitHub Account to Our Repository
 
-[WARNING]
-====
-**Update 8/SML3.5 Special Note**:
-If you have trouble getting the linker to work,
-please contact us on the Discord.
-It's a very recent addition to the setup process and we're still ironing out the bugs.
-====
-
 In addition to the changes Coffee Stain has made to Unreal Engine,
 the modding community has also applied some engine changes of our own.
 
@@ -335,10 +327,7 @@ This is the *latest* version of the docs.
 
 Early Access and Experimental are currently both the same version - Update 8.
 
-You should download a zip either of the **`dev` branch`**,
-which will have the latest changes and fixes,
-or the **`master` branch** .
-
+You should download a zip either of the **`dev` branch** or the **`master` branch**.
 Of those two, you probably want whichever branch was pushed to most recently, which you can see
 https://github.com/satisfactorymodding/SatisfactoryModLoader/branches[on the GitHub repository].
 

modules/ROOT/pages/Development/BeginnersGuide/project_setup.adoc

@@ -64,20 +64,18 @@ or you will have to repeat some of the setup process again.
 ====
 This is the *latest* version of the docs.
 
-If you want to develop mods for Update 8,
-you should clone either the **`dev` branch**,
-which will have the latest changes and fixes,
-or the **`master` branch** .
+Early Access and Experimental are currently both the same version - Update 8.
 
+You should clone either the **`dev` branch** or the **`master` branch**.
 Of those two, you probably want whichever branch was pushed to most recently, which you can see
 https://github.com/satisfactorymodding/SatisfactoryModLoader/branches[on the GitHub repository].
-====
 
-If you're still uncertain which to download, ask us on the Discord.
+If you're still uncertain which to clone, ask us on the Discord.
+====
 
 https://github.com/satisfactorymodding/SatisfactoryModLoader/[Here] is a link to the repository to clone.
 Again, make sure to clone the correct branch - it will probably start you on the `master` branch by default
-and you may have to switch branches to the correct one.
+and you may have to switch branches to the branch you actually intend to clone.
 
 The directory is ready for use as soon as the clone is complete.
 Move on to the link:#_setting_up_wwise[next heading].
@@ -348,7 +346,7 @@ you need to go back and re-do the link:#_setting_up_wwise[Wwise integration step
 Make sure that your project folder is not stored in a folder path that contains unicode characters.
 Review the directions in the link:#_starter_project[Starter Project] section.
 
-===== Entire computer locks up while compiling
+==== Entire computer locks up while compiling
 
 The fix for this rare but troublesome issue seems to vary for each person that encounters it.
 Try the following:

modules/ROOT/pages/Development/Cpp/GettingBpData.adoc

@@ -0,0 +1,117 @@
+= Working with Assets and Blueprint-Defined Data from {cpp}
+
+[NOTE]
+====
+You have found a hidden docs page!
+
+This page is still a work in progress.
+
+If you have any feedback, please let us know in the Discord.
+====
+
+When working with {cpp} code and hybrid mods, you may encounter situations where you need to reference and operate on assets.
+This poses a complication, as assets and their fields don't 'exist' yet when writing {cpp} code, only in the blueprint code.
+
+Generally, if you need to access a class/field in {cpp},
+have the parent class defined on the {cpp} side that define the fields you want to work with in {cpp},
+then populate them in a blueprint child version of the class.
+TODO example, TODO move this to a section?
+
+There are many solutions to this problem, each with their own tradeoffs.
+We have listed them in order of what we suggest below:
+
+[id="HybridMod"]
+== Approach 0: Hybrid Mod
+
+Does the operation you're performing need to happen on the {cpp} side?
+If you can work with the data on the blueprint code side instead,
+you can avoid this problem.
+
+Consider if the performance gains from doing the operation in {cpp} are worth the added complexity of this problem.
+
+TODO example
+
+[id="DataAsset"]
+== Approach 1: Data Asset
+
+Create a subclass of `UDataAsset` on the cpp side
+
+Define fields for values you want to pass across to the {cpp} side.
+Add `UPROPERTY(EditAnywhere, BlueprintReadWrite)` or BlueprintReadOnly to the properties you want to access
+
+Create a field on your Game Instance Module that holds a reference to your Data Asset
+Create the data asset on the BP side + populate its fields there + populate the field in your game instance module with it
+
+To access the data, get your instance module, get data class, get field.
+
+TODO mircea mentioned static getter?
+
+TODO example
+
+[source,h]
+----
+#pragma once
+#include "CoreMinimal.h"
+#include "Resources/FGItemDescriptor.h"
+#include "Buildables/FGBuildablePowerStorage.h"
+#include "ApBlueprintDataBridge.generated.h"
+
+/**
+ * Data asset definition to allow passing assets from blueprint to the C++ side without having to LoadObject hard code them
+ */
+UCLASS(NotBlueprintable, BlueprintType)
+class UApBlueprintDataBridge : public UDataAsset {
+	GENERATED_BODY()
+public:
+
+	// Power Storage building asset for UI modifications
+	UPROPERTY(EditAnywhere, BlueprintReadWrite)
+		TSubclassOf<AFGBuildablePowerStorage> PowerStorageBuilding;
+
+	// Item to use as the Archipelago Blocker
+	UPROPERTY(EditAnywhere, BlueprintReadWrite)
+		TSubclassOf<UFGItemDescriptor> BlockerItem;
+
+	// Item to use as the replacement for Somersloops
+	UPROPERTY(EditAnywhere, BlueprintReadWrite)
+		TSubclassOf<UFGItemDescriptor> ExplorationPickupItem_Somersloop;
+
+	// Item to use as the replacement for Mercer Spheres
+	UPROPERTY(EditAnywhere, BlueprintReadWrite)
+		TSubclassOf<UFGItemDescriptor> ExplorationPickupItem_Mercer;
+};
+----
+
+[id="GameInstanceField"]
+== Approach 2: Field on Game Instance Module
+
+Similar to Approach 1, putting
+
+This can get messy pretty fast because you're adding a lot of fields to your game instance module.
+
+It also causes stuff to preload sooner than it probably needs to -> hitches?
+
+TODO example
+
+[id="FindObject"]
+== Approach 3: Find Object and Load Object
+
+Generally don't use this with hardcoded strings because it's very brittle,
+if you move the asset it will no longer point to something and Unreal can't notice to auto-fix it up for you.
+
+The only approach that can find assets with a location determined at runtime.
+
+Okayish for base-game stuff that Should™ never move.
+
+Example from ContentLib:
+
+[source,h]
+----
+UClass* Class = FindObject<UClass>(FindPackage(nullptr, TEXT("/Game/")), TEXT("BP_UnlockInfoOnly_C"), false);
+if (!Class) {
+	Class = LoadObject<UClass>(nullptr, TEXT("/Game/FactoryGame/Unlocks/BP_UnlockInfoOnly.BP_UnlockInfoOnly_C"));
+	if (!Class) {
+		UE_LOG(LogContentLib, Fatal, TEXT("CL: Couldn't find BP_UnlockInfoOnly_C wanting to Add to %s"), *Schematic->GetName())
+	}
+}
+----

modules/ROOT/pages/Development/Cpp/debugging.adoc

@@ -80,9 +80,11 @@ When used correctly, they can help catch bugs early and make debugging easier
 by pinpointing the exact location where an assumption was violated.
 
 You can read more about these utilities (and see usage examples) on the relevant
-https://docs.unrealengine.com/4.26/en-US/ProgrammingAndScripting/ProgrammingWithCPP/Assertions/[Unreal Engine documentation page].
+https://dev.epicgames.com/documentation/en-us/unreal-engine/asserts-in-unreal-engine?application_version=5.2[Unreal Engine documentation page].
 
 Note that Assert and Check statements will crash the game if their conditions are not met, however, Ensure statements will allow the game to keep running.
 
+You should generally use `fgcheck()`, a custom assert implemented by Coffee Stain, instead of Unreal's standard `check()` because fgcheck is enabled in Shipping builds.
+
 When SML is installed and a debugger is attached, Checks and Ensures will be caught by the debugger.
 This is not normally the case in Shipping builds of Unreal Engine games; this behavior is enabled by SML.

modules/ROOT/pages/Development/ModLoader/AccessTransformers.adoc

@@ -49,16 +49,15 @@ Creates the public methods `FORCEINLINE PropertyType GetSomeProperty() { return
 
 This is beneficial when you are trying to access a field and you are not in a class to use Friend for. Below is an example from PowerSuit for the FEquipmentStats struct.
 
+// cspell:ignore Getm
 [source,cpp]
 ----
 // Instead of this ...
 SuitCostToUse = Parent->EquipmentParent->mCostToUse;
 // ... use this
-SuitCostToUse = Parent->EquipmentParent.GetCostToUse();
+SuitCostToUse = Parent->EquipmentParent.GetmCostToUse();
 ----
 
-Note that the generated methods lack the `m` from the original property name.
-
 === BlueprintReadWrite
 
 Adds `BlueprintReadWrite` to the specified UPROPERTY, allowing you to access that property from blueprints (it cannot be added to a non-UPROPERTY field). It also bypasses the private BPRW conflict check (which is compile time only, it does not affect the editor, or the game), so that no changes to the game headers are required.

modules/ROOT/pages/Development/Modeling/index.adoc

@@ -28,7 +28,7 @@ PBR Materials::
 +
 Texture Atlases::
   Helps understand the painting system (which allows you to change factory colours) and allows you to use decals on your models.
-  https://blog.immersed.team/texture-atlasing-an-inside-look-at-optimizing-3d-worlds-8a07145856d7[Tutorial Article]
+  https://web.archive.org/web/20200101133356/https://blog.immersed.team/texture-atlasing-an-inside-look-at-optimizing-3d-worlds-8a07145856d7?gi=9b479f256ecc[Tutorial Article]
 * {blank}
 +
 Normal Map Decals::

modules/ROOT/pages/Development/Satisfactory/AbstractInstance.adoc

@@ -42,3 +42,72 @@ You may also find the following properties useful:
 * Use Relative Transform to apply a transform this specific mesh relative to the overall building.
 * If the building has no components set `mContainsComponents` on the buildable to false
 * The "apply random offset" properties can be used to mitigate z-fighting issues when multiple copies of the building overlap.
+
+[id="Examples"]
+== Examples for Custom Implementations
+
+You may find the below examples useful
+if you're planning to implement Abstract Instances on things that don't inherit from `AFGBuildable`.
+
+=== Storing Instance Handles
+
+Custom implementations should define a field to hold instance handles.
+Consider `TArray< struct FInstanceHandle* > mInstanceHandles` used by `AFGBuildable`.
+
+=== Resolve Hits on Abstract Instances
+
+[NOTE]
+====
+Hits in Holograms are already resolved and don't need this implementation.
+====
+
+To resolve the hit, we have two options:
+
+- Hit result `bool ResolveHit( const FHitResult& Result, FInstanceHandle& OutHandle )`
+- Overlap Result `bool ResolveOverlap( const FOverlapResult& Result, FInstanceHandle& OutHandle )`
+
+```cpp
+AMyModActor::ResolveHitResult(const FHitResult& Hit) {
+    AAbstractInstanceManager* Manager = AAbstractInstanceManager::Get(GetWorld());
+    fgcheck(Manager);
+
+    FInstanceHandle OutHandle;
+    if(Manager->ResolveHit(Hit, OutHandle)) {
+        // We hit a abstract instance, so we can get information, like the owner, from that handle
+        OutHandle.GetOwner() // AActor* who owns the Instance
+    }
+    // We don't hit a abstract instance so we can continue with the Hit
+}
+```
+
+=== Create Abstract Instances at Runtime
+
+```cpp
+static void SetInstanceFromDataStatic( AActor* OwnerActor, const FTransform& ActorTransform, const FInstanceData& InstanceData, FInstanceHandle* &OutHandle, bool bInitializeHidden = false );
+
+AMyModActor::CreateInstanceFromMesh(UStaticMesh* Mesh) {
+    // Prepare the InstanceData with a given Mesh at the relative Transform 0.
+    FInstanceData InstanceData;
+    InstanceData.StaticMesh = Mesh;
+    InstanceData.Mobility = EComponentMobility::Static;
+    InstanceData.RelativeTransform = FTransform();
+    InstanceData.NumCustomDataFloats= 20;
+
+    FInstanceHandle* Handle;
+    AAbstractInstanceManager::SetInstanceFromDataStatic(this, GetActorTransform(), InstanceData, Handle);
+
+    // You should add this Handle to the array so we can destroy them if the actor is destroyed (for example, dismantled).
+    mInstanceHandles.Add(Handle);
+}
+```
+
+=== Destroy Abstract Instances at Runtime
+
+```cpp
+static void RemoveInstances( UObject* WorldContext, TArray<FInstanceHandle*>& Handles, bool bEmptyHandleArray = true );
+
+AMyModActor::ClearInstances(UStaticMesh* Mesh) {
+    // Will remove/destroy all instances and empty mInstanceHandles.
+    AAbstractInstanceManager::RemoveInstances( GetWorld( ), mInstanceHandles );
+}
+```