diff options
| author | ivey <[email protected]> | 2020-06-15 15:58:35 -0400 |
|---|---|---|
| committer | ivey <[email protected]> | 2020-06-15 15:58:35 -0400 |
| commit | 38195462a26532c91efb21a8d2fa9525375d4c04 (patch) | |
| tree | 0c1aae5e9ff42a864117628e90b3254d620ecb9e /Documentation | |
| parent | Initial commit of the UGCExample Project (diff) | |
| download | ugcexample-38195462a26532c91efb21a8d2fa9525375d4c04.tar.xz ugcexample-38195462a26532c91efb21a8d2fa9525375d4c04.zip | |
Moved Docs into Documentation folder
Diffstat (limited to 'Documentation')
41 files changed, 268 insertions, 0 deletions
diff --git a/Documentation/Images/.DS_Store b/Documentation/Images/.DS_Store Binary files differnew file mode 100644 index 0000000..2e9ddc7 --- /dev/null +++ b/Documentation/Images/.DS_Store diff --git a/Documentation/Images/image1.png b/Documentation/Images/image1.png Binary files differnew file mode 100644 index 0000000..e31e1c4 --- /dev/null +++ b/Documentation/Images/image1.png diff --git a/Documentation/Images/image10.png b/Documentation/Images/image10.png Binary files differnew file mode 100644 index 0000000..ef62ea7 --- /dev/null +++ b/Documentation/Images/image10.png diff --git a/Documentation/Images/image11.png b/Documentation/Images/image11.png Binary files differnew file mode 100644 index 0000000..f0b558e --- /dev/null +++ b/Documentation/Images/image11.png diff --git a/Documentation/Images/image12.png b/Documentation/Images/image12.png Binary files differnew file mode 100644 index 0000000..c8f8469 --- /dev/null +++ b/Documentation/Images/image12.png diff --git a/Documentation/Images/image13.png b/Documentation/Images/image13.png Binary files differnew file mode 100644 index 0000000..13e6173 --- /dev/null +++ b/Documentation/Images/image13.png diff --git a/Documentation/Images/image14.png b/Documentation/Images/image14.png Binary files differnew file mode 100644 index 0000000..f501e41 --- /dev/null +++ b/Documentation/Images/image14.png diff --git a/Documentation/Images/image15.png b/Documentation/Images/image15.png Binary files differnew file mode 100644 index 0000000..cdd1296 --- /dev/null +++ b/Documentation/Images/image15.png diff --git a/Documentation/Images/image16.png b/Documentation/Images/image16.png Binary files differnew file mode 100644 index 0000000..0d7f17e --- /dev/null +++ b/Documentation/Images/image16.png diff --git a/Documentation/Images/image17.png b/Documentation/Images/image17.png Binary files differnew file mode 100644 index 0000000..0bade5c --- /dev/null +++ b/Documentation/Images/image17.png diff --git a/Documentation/Images/image18.png b/Documentation/Images/image18.png Binary files differnew file mode 100644 index 0000000..8c81387 --- /dev/null +++ b/Documentation/Images/image18.png diff --git a/Documentation/Images/image19.png b/Documentation/Images/image19.png Binary files differnew file mode 100644 index 0000000..4408036 --- /dev/null +++ b/Documentation/Images/image19.png diff --git a/Documentation/Images/image2.png b/Documentation/Images/image2.png Binary files differnew file mode 100644 index 0000000..23c65ed --- /dev/null +++ b/Documentation/Images/image2.png diff --git a/Documentation/Images/image20.png b/Documentation/Images/image20.png Binary files differnew file mode 100644 index 0000000..e462d77 --- /dev/null +++ b/Documentation/Images/image20.png diff --git a/Documentation/Images/image21.png b/Documentation/Images/image21.png Binary files differnew file mode 100644 index 0000000..e68f106 --- /dev/null +++ b/Documentation/Images/image21.png diff --git a/Documentation/Images/image22.png b/Documentation/Images/image22.png Binary files differnew file mode 100644 index 0000000..4cb053d --- /dev/null +++ b/Documentation/Images/image22.png diff --git a/Documentation/Images/image23.png b/Documentation/Images/image23.png Binary files differnew file mode 100644 index 0000000..1d60442 --- /dev/null +++ b/Documentation/Images/image23.png diff --git a/Documentation/Images/image24.png b/Documentation/Images/image24.png Binary files differnew file mode 100644 index 0000000..da94b00 --- /dev/null +++ b/Documentation/Images/image24.png diff --git a/Documentation/Images/image25.png b/Documentation/Images/image25.png Binary files differnew file mode 100644 index 0000000..49ce996 --- /dev/null +++ b/Documentation/Images/image25.png diff --git a/Documentation/Images/image26.png b/Documentation/Images/image26.png Binary files differnew file mode 100644 index 0000000..3f03c30 --- /dev/null +++ b/Documentation/Images/image26.png diff --git a/Documentation/Images/image27.png b/Documentation/Images/image27.png Binary files differnew file mode 100644 index 0000000..5f480f3 --- /dev/null +++ b/Documentation/Images/image27.png diff --git a/Documentation/Images/image28.png b/Documentation/Images/image28.png Binary files differnew file mode 100644 index 0000000..79a29dd --- /dev/null +++ b/Documentation/Images/image28.png diff --git a/Documentation/Images/image29.png b/Documentation/Images/image29.png Binary files differnew file mode 100644 index 0000000..d5522ad --- /dev/null +++ b/Documentation/Images/image29.png diff --git a/Documentation/Images/image3.png b/Documentation/Images/image3.png Binary files differnew file mode 100644 index 0000000..f0b1c88 --- /dev/null +++ b/Documentation/Images/image3.png diff --git a/Documentation/Images/image30.png b/Documentation/Images/image30.png Binary files differnew file mode 100644 index 0000000..6c1d446 --- /dev/null +++ b/Documentation/Images/image30.png diff --git a/Documentation/Images/image31.png b/Documentation/Images/image31.png Binary files differnew file mode 100644 index 0000000..4443fbb --- /dev/null +++ b/Documentation/Images/image31.png diff --git a/Documentation/Images/image32.png b/Documentation/Images/image32.png Binary files differnew file mode 100644 index 0000000..ea85fc2 --- /dev/null +++ b/Documentation/Images/image32.png diff --git a/Documentation/Images/image33.png b/Documentation/Images/image33.png Binary files differnew file mode 100644 index 0000000..a616b07 --- /dev/null +++ b/Documentation/Images/image33.png diff --git a/Documentation/Images/image34.png b/Documentation/Images/image34.png Binary files differnew file mode 100644 index 0000000..26cb9ad --- /dev/null +++ b/Documentation/Images/image34.png diff --git a/Documentation/Images/image35.png b/Documentation/Images/image35.png Binary files differnew file mode 100644 index 0000000..1bdf572 --- /dev/null +++ b/Documentation/Images/image35.png diff --git a/Documentation/Images/image36.png b/Documentation/Images/image36.png Binary files differnew file mode 100644 index 0000000..7ea8ba6 --- /dev/null +++ b/Documentation/Images/image36.png diff --git a/Documentation/Images/image37.png b/Documentation/Images/image37.png Binary files differnew file mode 100644 index 0000000..f050181 --- /dev/null +++ b/Documentation/Images/image37.png diff --git a/Documentation/Images/image38.png b/Documentation/Images/image38.png Binary files differnew file mode 100644 index 0000000..acd5d0c --- /dev/null +++ b/Documentation/Images/image38.png diff --git a/Documentation/Images/image39.png b/Documentation/Images/image39.png Binary files differnew file mode 100644 index 0000000..ac52d2e --- /dev/null +++ b/Documentation/Images/image39.png diff --git a/Documentation/Images/image4.png b/Documentation/Images/image4.png Binary files differnew file mode 100644 index 0000000..5bcf94d --- /dev/null +++ b/Documentation/Images/image4.png diff --git a/Documentation/Images/image5.png b/Documentation/Images/image5.png Binary files differnew file mode 100644 index 0000000..1f1bda1 --- /dev/null +++ b/Documentation/Images/image5.png diff --git a/Documentation/Images/image6.png b/Documentation/Images/image6.png Binary files differnew file mode 100644 index 0000000..2d98f13 --- /dev/null +++ b/Documentation/Images/image6.png diff --git a/Documentation/Images/image7.png b/Documentation/Images/image7.png Binary files differnew file mode 100644 index 0000000..d4cf195 --- /dev/null +++ b/Documentation/Images/image7.png diff --git a/Documentation/Images/image8.png b/Documentation/Images/image8.png Binary files differnew file mode 100644 index 0000000..79aca50 --- /dev/null +++ b/Documentation/Images/image8.png diff --git a/Documentation/Images/image9.png b/Documentation/Images/image9.png Binary files differnew file mode 100644 index 0000000..7775934 --- /dev/null +++ b/Documentation/Images/image9.png diff --git a/Documentation/QuickStart.md b/Documentation/QuickStart.md new file mode 100644 index 0000000..55f647e --- /dev/null +++ b/Documentation/QuickStart.md @@ -0,0 +1,268 @@ +# UGC Example Quick Start +## Prerequisites +To follow along with this overview, you’ll need the following installed on your machine: +- A source build of Unreal Engine 4.25.1 or higher (to recompile the Automation Tool project) +- Visual Studio 2019 Community or higher +- This project (UGCExample) + +*If you’re comfortable in Visual Studio and want to skip looking at the example project, head straight to the Adding Mod Support to Your Project section below.* +### Building the UGC Example Project +Before opening the UGC Example project, follow these steps to ensure everything is generated and built for the project: + +1. Right click the **UGCExample uproject** file, then select **Generate Visual Studio Project Files**. Make sure that the project is associated with your source build of Unreal Engine. + + + +2. Open the generated **Visual Studio solution**. +3. Verify that the build scripts are listed in the **Programs/Automation** directory + + + +4. **Build** the **AutomationTool** project. +5. **Build** and run **UGCExample**. +## UGC Example Project +### Project Overview +The UGC Example project is pretty basic. It has two Levels, a handful of Blueprints, and an example mod menu UI. + + + +If we use play-in-editor (PIE), we will go to the **MainMenuLevel** that shows the available UGC packages (none as yet), and allows us to open **ExampleMap**. + + + +**ExampleMap** isn’t much more sophisticated, and only has two different spawned Actors invoked by the Level Blueprint. + + + +On the toolbar, you’ll see the two new buttons mentioned above—**Create UGC** and **Package UGC**. Let’s see how they work. +## Making a New Mod +### Creating a New Mod Plugin +Clicking the toolbar button **Create UGC** will open a wizard that you can use to generate a new UGC package. It generates a new content-only plugin, and places it in your **Mods** directory. + +**NOTE**: In 4.25.0, mods are placed in the **Plugins** directory instead. Either upgrade to 4.25.1, or move the newly-created folder from Plugins to Mods in order for this to properly work! + +Give it a name, add your info, then click **Create Mod**. + + + +The Content Browser view of the new Mod plugin will open, and you can add your content. + + + +I’ve added a simple Level based on the **StarterContent** Level, a Blueprint Actor called **SilverBall**, and a Material, **SilverBallMat**, for our new object. + +SilverBall is an Actor with a scaled Sphere Component that has **Simulate Physics** checked and the SilverBallMat applied to the mesh. I’ve placed one in the Level, so when it is run, I can see it fall to the ground. + + + + + +This is pretty basic, but we are now able to find this UGC package and play this new Level that uses the new Actor and Material in editor via the **UGCRegistry** functions. + +Let’s see how to test it in the main game using PIE. +### Testing the New Mod +When we start a PIE session, our new UGC shows up in the list of **UGC Packages**. That’s because the list is populated by plugins classified as **Mods** and located in the Mods project directory. + + + +From here, we can select **Open** for **MyNewLevel**, then play the new Level in the editor. + + + +We’ve now shown a basic way to load a new Level (and the content associated with it) using PIE and some menu helpers. But what if we wanted the SilverBall Actor to be available for use inside the main game in traditional mod style? +### Overriding the Base Game +The Simple UGC module has two Components that make in-game object replacement pretty straightforward. If you take a look at the Sphere Actor, you’ll see a **MakeReplaceableActorComponent** on it. + + + + + +This explicitly makes the SphereActor replaceable by user-generated content. In the Details panel, you’ll see a field for Compatible Replacement. This defines what type of Actor can replace it, as there may be compatibility concerns when swapping one Actor for another, and this must be set if you intend to make a Class overridable. For Robo Recall’s guns, for instance, this would be OdinGun, as most of the game called and reacted to functions or properties on OdinGun. For demonstration purposes, SphereActor just uses Actor as our Compatible Replacement base. + +Now we’ve managed to tell the game’s base class that it can be overridden by a mod, let’s make the SilverBall an override for that class. + +In the same vein as adding a **MakeReplaceableActorComponent** to the original Class, let’s add a **ReplacementActorComponent** to the Class we expect to replace it when the mod is active. + + + +Here, you’ll see that we have an **Actor Classes To Replace** array in the Details panel. This is where we define what this class is supposed to replace in the main game. I’ve added SphereActor to the list so that SilverBall knows to register itself as a replacement for SphereActor when our new mod is active. +### Testing the Override Mod +If we PIE now, we can see ActorReplacements in the list and our SilverBall_C Blueprint class in the list. + + + +Clicking **Apply** or **Apply All** on the Class or on the Actor Replacements header will register the override, which is reflected in the **Registered Overrides** list. + + + +If we click **Open Example Map** now, we’ll see that SilverBall has replaced SphereActor in the Level. + + + +This is an example of how to test Actor replacement in the editor before the mod is ready to ship. When everything is as desired, we can package the UGC using the second new toolbar button, **Package UGC**. +### Packaging Your New Mod +Packaging is a one-touch operation using the Package UGC option in the toolbar. If we click the button and select our mod from the list, a directory dialog opens for choosing where to save our UGC. + + + +Afterwards, you’ll see a status indicator in the bottom right corner of the editor. + + + + + +Once complete, the cooked mod will be in a zipped folder where you saved to. + + + +## Playing Your New Mod +Now you can test your UGC in the actual game. We have included a zip of the packaged game for this purpose. +### Running the Game +Head over to **UGCExample/Release/UGCExampleGame_v1** and copy **PackagedExe.zip** to somewhere convenient. Unzip the PackagedExe.zip and you can run the (thrilling) game from the UGC Example project. + + + +Run **UGCExample.exe**. + +As expected, there are no UGC Packages found. Let’s add the new mod. +### Adding Your Packaged UGC to the Base Game +Extract your packaged mod to somewhere convenient. Copy the folder containing Content and the .plugin file into a new Mods directory in the **UGCExample** game folder that you just extracted. Here’s what mine looks like: + + + +_UGCExample game folder—note the Mods directory._ + + + +_MyFirstMod folder and contents in the Mods folder._ + +Now, when you play the game, you should see the UGC package show up in the list, with the content now made available the same way it was in the editor! +## Adding Mod Support to Your Project +### Project and Environment Setup +Now that you’ve seen how everything works together, let’s take a look at the pieces you need to add the same type of mod support to your games. +The majority of the heavy lifting takes place in the **SimpleUGC** plugin (found in **UGCExample/Plugins**.) This plugin contains two modules: **SimpleUGC** and **SimpleUGCEditor**. + + + +SimpleUGC is a runtime module that includes Classes, Components, and functions that make it easy to find and use new content found in mods in your base game. Detailed information about these Classes can be found later on in this document. + + + +The SimpleUGCEditor Editor module adds two toolbar and File menu dropdown buttons that automate the creation and packaging of mods, as well as a templates folder for populating the **New Mod Creation Wizard**. + + + +The other important piece of the puzzle is the custom automation tool project found in the project, **SimpleUGC.Automation**. The important file here is **PackageSimpleUGCPlugin.cs**, which contains the UAT command required to package our mods. + + + +Copy the following directories from the UGC Example to the same locations in your project: + +**UGCExample/Plugins/SimpleUGC**: + + + +**UGCExample/Build/Scripts**: + + + +If you went through the example above, you may need to use **Clean the Automation Tool** project after you generate project files to ensure that the build scripts get added and built after generating project files for your project. + +Alternatively, you can refactor the names in these build scripts to match your project as you’re likely going to make a number of project-specific changes by the time you ship your mod kit. + +Take these steps for your project (just like above): + +1. Right-click your uproject file and select **Generate Project Files**. Ensure that your project is associated with a source build of Unreal Engine. +2. Open your **Visual Studio** solution. +3. Verify that the build scripts are part of the **/Automation** directory. +4. **Build** the **Automation Tool**. +5. **Build** and run your project. + +### Custom Game Instance +For discovering mod packages and tracking overrides, we need a place to create and store the UGCRegistry Class. We do this in a custom **GameInstance** Class, as GameInstance gets created early enough that mod packages can become available before the first UE4 Level is on the screen, but late enough that all content plugin packages have been mounted and are ready for use. + +If you are not using a custom GameInstance, select **UGCBaseGameInstance** in the **Maps and Modes** section inside **Project Settings**. + + + +If you are using a custom GameInstance, reparent it to UGCBaseGameInstance in order for the UGCRegistry to be created and made available for use in your game. +### Making Actors Replaceable +For Actors in your game that you want to make replaceable by UGC, you’ll need to add a MakeReplaceableActor Component to the Actor. + + + +In the Details panel, you’ll see a field for **Compatible Replacement**. This defines what types of Actors are able to replace this Class when they’re registered as mod overrides. This should be a common base Class shared by the Actor you want to be replaced by a mod Class and the mod Class trying to replace it. + + + +For instance, in Robo Recall, we knew that OdinGun was the super Class that all guns derived from. When we would call events to fire, reload, drop, or throw guns, we called that functionality on OdinGun. If we were to add this Component to any original guns in the game, we would add OdinGun as the Compatible Replacement to ensure that new guns that replace original guns remain compatible with the assumptions that the game code makes. +### Handling Class Swapping +Now that an Actor knows that it can be replaced by certain types of new Actors, we need to ensure that we handle the replacement logic whenever the Actor is supposed to spawn. + +Where you spawn Actors that can be overridden instead of passing the Class straight into **SpawnActorFromClass**, call **GetOverrideForActorClass** on the UGCRegistry and pass the Class type in as the ActorClass parameter. This will return the original class if no valid overrides are registered, or the replacement class if an override has been registered. + + + +### Avoiding Placed Actors +In the effort to keep this plugin simple and avoid any low-level engine changes, it does not support replacement of Actors placed in Levels. That action would be better handled in the Level loading code instead, as it can be very expensive to tear down a bunch of instantiated Actors with Components just to recreate them in a timely manner before the player spawns into the Level. + +We encourage you to replace any placed Actors with spawning logic for performance reasons. In situations where you absolutely cannot spawn an Actor and it must be placed, you can do the UGCRegistry check in the Level Blueprint and handle the replacement if necessary. We had to do this for the Robo Recall boss due to an issue with loading order for cinematics. +### Special Case for Player Pawn +Since player Pawn spawning is handled by the GameMode class, we can employ the same method for Actor replacement in our GameMode Class. Overriding GetDefaultPawnClassForController allows us to manage the class replacement logic like so: + + + +### Add Methods to Find and Consume UGC +You will need to add mechanisms to discover and use UGC in your game. This could appear in many forms, such as a mods menu as in Robo Recall, or systems that crawl new packages looking for new Assets of a certain type to use in existing systems. + +In general, it’s important to remember that mods are just big lumps of extra content, and it is up to you, the game’s creator, to decide how it best fits into your world. + +The UGC Example project has some examples of use in a mod menu, but here are some UGCRegistry properties and functions that will help you along the way: + +| Name | Description | +| ----------- | ----------- | +| UGCPackages | Array of found UGC Packages. This is populated when UGCBaseGameInstance is initialized. | +| GetAllClassesInPackage | Returns all new classes in the UGC Package provided. This includes Classes with and without ReplacementActor Components for overrides. | +| GetMapsInPackage | Returns all Maps (Levels) found in a package. NOTE: This will even return Levels that you only intend to use as sublevels, so you should add special filtering on your map names if you want modders to make only certain Levels available. | +| GetActorClassesWithReplacementActorComponentsInPackage | Only returns Actor Classes that have ReplacementActorComponents on them, meaning they are meant to override the original game. | +| ApplyAllOverridesInPackage | Registers overrides for all Classes with ReplacementActorComponents in the UGC Package provided. | +| ApplyOverridesForActorClass | Like ApplyOverridesForActorClass, but just registers Overrides for the Actor Class passed in. | +| ClearOverrideForClass | Removes the override that is registered for the origin Class passed in. | +### Packaging UGC Setup +Now that your game supports newly discovered packaged mods, you’ll need to prepare the editor environment for mods to be appropriately created, packaged and distributed. There are a few things needed to make this work. +#### Asset Registry from Packaged Game +Mods for packaged games require a packaged game, right? + +When your game is packaged, you’re going to need a few files generated and stored in the project **Saved** directory. This is needed in the UGC packaging step so it’s generating the appropriate data for the appropriately supported release of the game. + +The files you need are the **AssetRegistry.bin** and the **Metadata** folder found in **Saved/Cooked/WindowsNoEditor/<ProjectName>** + + + +You will need to move these to a folder in a newly created **Releases** directory in your project. The name of the folder is important, as it is referenced by the packaging script. For the UGC Example project, I just named it **UGCExample_v1** to keep things simple. + + + +Best practice is to have this accounted for in your build system so that it would generate this folder and copy these over for you. It is currently hardcoded in our example as we anticipate that everyone is going to have slightly different needs and tools for this sort of thing. +#### Updating Packaging Scripts +This folder name is referenced in two areas in code: +- ReleaseVersion in **SimpleUGCPackager.cpp** +- ReleaseVersion in **PackageSimpleUGCPlugin.cs** + +These strings must match the name of the supported release folder for packaging to work, as the files in the directory are required for packaging the UGC. Any changes to these will require you to rebuild either project in VS. As mentioned above, ideally, these are read from an area that is generated by your build system, such as an .ini file whenever you are preparing your editor for release. We left this hardcoded here so as to not be presumptive of your setup. + +At this point, you have everything moved over and you can test. Remember to add the ReplaceableActorComponents to new Actors you want to override original content with, and set the properties as mentioned above! +### Further Customization +Now that you’re up and running, let’s take a look at a few things you might want to customize for your game. +#### Templates +The New Mod Wizard pulls from a Templates folder in the SimpleUGC plugin. We’ve included an empty, content-only plugin as a starting point. If you look over at the source for Robo Recall, you’ll see that we have a bunch of starting templates that have jumping-off points for creating new types of mods. You will want to account for these in the custom **IPluginWizardDefinition** in the SimpleUGCEditor module so they properly populate in the list of templates. See the Robo Recall source for a good reference on how that can be handled. + + + +#### Icons +Toss our basic icons out and add your own to flavor up your mod editor! These are found in the Resources folder in the SimpleUGC plugin. + + + +#### Other Asset Types +All Assets inside each UGC package get added into the mod .pak file when we package. These are available for use as soon as the game runs, though the current UGCRegistry Class has helper functions for handling Class and Level discovery. If you want to provide easier access to other Asset types such as materials, textures, and sounds, **UUGCRegistry::GetMapsInPackage** is a good reference for how you can crawl package paths for specific Asset types. Instead of adding **UWorld::StaticClass()->GetFName()** to the **ARFilter.ClassNames**, add the type that you’d like to filter for. |
