diff options
Diffstat (limited to 'Documentation/QuickStart.md')
| -rw-r--r-- | Documentation/QuickStart.md | 55 |
1 files changed, 31 insertions, 24 deletions
diff --git a/Documentation/QuickStart.md b/Documentation/QuickStart.md index a119039..9f0964e 100644 --- a/Documentation/QuickStart.md +++ b/Documentation/QuickStart.md @@ -20,24 +20,25 @@ Before opening the UGC Example project, follow these steps to ensure everything 2. Run **GenerateProjectFiles.bat** in your UE4 root directory. 3. Open **UE4.sln**. -4. Verify that the build scripts are listed in the **Programs/Automation** directory +4. If you haven't yet, build the **UE4** and **UnrealPak** projects. +5. Verify that the build scripts are listed in the **Programs/Automation** directory  -5. Open **Properties** for **SimpleUGC.Automation** and choose the **Build** tab on the left. Set the **Output Path** to your source build's **Engine\Binaries\DotNET\AutomationScripts\\** directory for **both Development and Debug Configurations**. The "Browse..." button makes this easy. +6. Open **Properties** for **SimpleUGC.Automation** and choose the **Build** tab on the left. Set the **Output Path** to your source build's **Engine\Binaries\DotNET\AutomationScripts\\** directory for **both Development and Debug Configurations**. The "Browse..." button makes this easy.  -6. **Build** the **AutomationTool** project. -7. **Build** the **UGCExample** project in the **Development** configuration. -8. **Build and run** the **UGCExample** project in the **Development Editor** configuration. +7. **Build** the **AutomationTool** project. +8. **Build** the **UGCExample** project in the **Development** configuration. +9. **Build and run** the **UGCExample** project in the **Development Editor** configuration. ## 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**. +If we use play-in-editor (PIE), we will go to the **MainMenu** Level that shows the available UGC packages (none as yet), and allows us to open **ExampleMap**.  @@ -60,7 +61,7 @@ The Content Browser view of the new Mod plugin will open, and you can add your c  -I’ve added a simple Level based on the **StarterContent** Level, a Blueprint Actor called **SilverBall**, and a Material, **SilverBallMat**, for our new object. +I’ve added a simple Level based on the StarterContent Level **Minimal_Default**, 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. @@ -72,17 +73,17 @@ This is pretty basic, but we are now able to find this UGC package and play this Let’s see how to test it in the main game using PIE. ### Testing the New Mod -Open **MainMenuLevel** if it's not already open. 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. +Open the **MainMenu** Level if it's not already open. 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. +From here, we can select **Open** for your newly created level (mine was called NewTestLevel), 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. +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 **MakeReplaceableActor** Component on it.  @@ -92,7 +93,7 @@ This explicitly makes the SphereActor replaceable by user-generated content. In Now that 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. +In the same vein as adding a **MakeReplaceableActor** Component to the original Class, let’s add a **ReplacementActor** Component to the Class we expect to replace it (the SilverBall) when the mod is active.  @@ -129,7 +130,7 @@ 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. +Head over to **UGCExample/Releases/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.  @@ -150,7 +151,8 @@ _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. +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. **Note**: In order for the build scripts to be added to the AutomationTool, your project needs to be a code project. If it's currently a Blueprint only project, you can convert it by adding a new C++ class in the Content Browser. + The majority of the heavy lifting takes place in the **SimpleUGC** plugin (found in **UGCExample/Plugins**.) This plugin contains two modules: **SimpleUGC** and **SimpleUGCEditor**.  @@ -189,11 +191,12 @@ Take these steps for your project (just like above, see images for references): 2. Run **GenerateProjectFiles.bat** in your UE4 root directory. 3. Open the **Visual Studio solution**. -4. Verify that the build scripts are listed in the **Programs/Automation** directory -5. Open **Properties** for **SimpleUGC.Automation** and choose the **Build** tab on the left. Set the **Output Path** to your source build's **Engine\Binaries\DotNET\AutomationScripts\\** directory for **both Development and Debug Configurations**. The "Browse..." button makes this easy. -6. **Build** the **AutomationTool** project. -7. **Build your project** in the **Development** configuration. -8. **Build and run your project** in the **Development Editor** configuration. +4. If you haven't yet, build the **UE4** and **UnrealPak** projects. +5. Verify that the build scripts are listed in the **Programs/Automation** directory +6. Open **Properties** for **SimpleUGC.Automation** and choose the **Build** tab on the left. Set the **Output Path** to your source build's **Engine\Binaries\DotNET\AutomationScripts\\** directory for **both Development and Debug Configurations**. The "Browse..." button makes this easy. +7. **Build** the **AutomationTool** project. +8. **Build your project** in the **Development** configuration. +9. **Build and run your project** in the **Development Editor** configuration. ### 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. @@ -236,7 +239,7 @@ In general, it’s important to remember that mods are just big lumps of extra c 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 | +| 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. | @@ -256,17 +259,21 @@ The files you need are the **AssetRegistry.bin** and the **Metadata** folder fou  -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. +Make a new **Releases** directory in your project root. Inside it, add another folder for your supported release. The name of this folder is important, as this directory will be referenced by your packaging script. For the UGC Example project, I just named it **UGCExample_v1** to keep things simple. Inside that folder, add a **WindowsNoEditor** folder and put the AssetRegistry.bin and the Metadata folder copied from the Saved/Cooked directory inside.  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 process. #### Updating Packaging Scripts -This folder name is referenced in two areas in code: -- ReleaseVersion in **SimpleUGCPackager.cpp** -- ReleaseVersion in **PackageSimpleUGCPlugin.cs** +For the sake of simplicity, for the UGCExample project, we hardcoded the project's release folder name. If you copied the SimpleUGC plugin and SimpleUGC automation scripts into your own project then you'll need to change a couple places in code. + +The hardcoded "UGCExampleGame_v1" folder name is referenced in by two variables in code: +- ReleaseVersion in **SimpleUGCPackager.cpp** (line 109) +- ReleaseVersion in **PackageSimpleUGCPlugin.cs** (line 38) + +These strings must match the name of the Releases sub-folder that you created in the previous step. If you change these strings, make sure rebuild your projects in Visual Studio -- both **AutomationTool** and **your project**. -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 Visual Studio. 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. +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 **ReplaceableActorComponents** to new Actors you want to override original content with, and set the properties as mentioned above! ### Further Customization |