diff options
Diffstat (limited to 'Docs.md')
| -rw-r--r-- | Docs.md | 83 |
1 files changed, 42 insertions, 41 deletions
@@ -1,20 +1,22 @@ +# 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 +### 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. -@TODO IMAGE + 2. Open the generated **Visual Studio solution**. 3. Verify that the build scripts are listed in the **Programs/Automation** directory -@TODO IMAGE + 4. **Build** the **AutomationTool** project. 5. **Build** and run **UGCExample**. @@ -22,15 +24,15 @@ Before opening the UGC Example project, follow these steps to ensure everything ### Project Overview The UGC Example project is pretty basic. It has two Levels, a handful of Blueprints, and an example mod menu UI. -@TODO IMAGE + 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**. -@TODO IMAGE + **ExampleMap** isn’t much more sophisticated, and only has two different spawned Actors invoked by the Level Blueprint. -@TODO IMAGE + 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 @@ -41,19 +43,19 @@ Clicking the toolbar button **Create UGC** will open a wizard that you can use t Give it a name, add your info, then click **Create Mod**. -@TODO Image + The Content Browser view of the new Mod plugin will open, and you can add your content. -@TODO Image + 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. -@TODO Image + -@TODO Image + 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. @@ -61,19 +63,19 @@ 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. -@TODO Image + From here, we can select **Open** for **MyNewLevel**, then play the new Level in the editor. -@TODO Image + 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. -@TODO Image + -@TODO Image + 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. @@ -81,44 +83,44 @@ Now we’ve managed to tell the game’s base class that it can be overridden by 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. -@TODO Image + 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. -@TODO Image + 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. -@TODO Image + If we click **Open Example Map** now, we’ll see that SilverBall has replaced SphereActor in the Level. -@TODO Image + 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. -@TODO Image + Afterwards, you’ll see a status indicator in the bottom right corner of the editor. -@TODO Image + -@TODO Image + Once complete, the cooked mod will be in a zipped folder where you saved to. -@TODO Image + ## 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. -@TODO Image + Run **UGCExample.exe**. @@ -126,11 +128,11 @@ 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: -@TODO Image + _UGCExample game folder—note the Mods directory._ -@TODO Image + _MyFirstMod folder and contents in the Mods folder._ @@ -140,29 +142,29 @@ Now, when you play the game, you should see the UGC package show up in the list, 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**. -@TODO Image + 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. -@TODO Image + 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**. -@TODO Image + 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. -@TODO Image + Copy the following directories from the UGC Example to the same locations in your project: **UGCExample/Plugins/SimpleUGC**: -@TODO Image + **UGCExample/Build/Scripts**: -@TODO Image + 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. @@ -181,17 +183,17 @@ For discovering mod packages and tracking overrides, we need a place to create a If you are not using a custom GameInstance, select **UGCBaseGameInstance** in the **Maps and Modes** section inside **Project Settings**. -@TODO Image + 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. -@TODO Image + 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. -@TODO Image + 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 @@ -199,7 +201,7 @@ Now that an Actor knows that it can be replaced by certain types of new Actors, 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. -@TODO Image + ### 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. @@ -208,7 +210,7 @@ We encourage you to replace any placed Actors with spawning logic for performanc ### 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: -@TODO Image + ### 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. @@ -235,11 +237,11 @@ When your game is packaged, you’re going to need a few files generated and sto The files you need are the **AssetRegistry.bin** and the **Metadata** folder found in **Saved/Cooked/WindowsNoEditor/<ProjectName>** -@TODO Image + 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. -@TODO Image + 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 @@ -255,13 +257,12 @@ Now that you’re up and running, let’s take a look at a few things you might #### 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. -@TODO Image + #### 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. -@TODO Image + #### 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. - |