Skip to main content

Mod Loading QuickStart

Introduction​

mod.io provides studios and publishers with suggested tools to enable official mod support in their games. In addition to tools, our goal is to share best practices for developers exploring how to ready their game for mods and provide the best opportunity for a successful long-tail provided by official mod support. This guide features a starting point specific to Unreal Engine games and includes:

  • Mod Content Types
  • Packaging and cooking
  • Mod Loading
  • Mod Creation Tools
  • Cross-platform Compliance

Mod Content Types​

Generic Data Types​

Unreal Engine supports loading non-Unreal specific data formats (i.e., non-uassets) at runtime, such as JSON, PNG, CSV, etc. Unreal also has various “Interchange” modules that can process more complex source assets at runtime (such as FBX, UDatasmith, etc). If your game is suitable for using this sort of data for mod creation—for instance, describing behavior or level layouts via JSON blobs or replacing textures or icons from PNG files—then you can go this route instead of having to worry about Unreal-specific PAK files and managing the cooking and packaging process.

PAK Files​

PAK files are an engine-standard way of packaging and distributing all of Unreal's specific functionality and content. This means that you can load any sort of UAsset type (Blueprints, StaticMeshes, AnimationSequences, etc.) that the engine supports at runtime.

In order for your game to support this, you should keep the following in mind when structuring your content:

  • Avoid hard references
  • Make use of primary asset types
  • Resolve content references from the asset registry

For example, when spawning a component within an Actor in C++, rather than referencing a StaticClass directly, it is preferable to use a blueprint-exposed TSubclassOf so that modders can change the asset that is spawned.

Mod Packaging​

Generic Data Types​

If you are using generic data types for your mods, then no additional work is needed to package and distribute this content.

When you use the mod.io Plugin or tools to submit mods, the folder containing all of the content is zipped for you and extracted once the file is downloaded. We recommend using a manifest file to structure the content references. One of the major benefits of this approach is that it is not necessary to cook the mod prior to distribution.

PAK Files​

PAK files can be thought of as UE-specific archive files or, in other words, a packaged collection of UAssets. They are generated by UnrealPak.exe located in ...\UE_version\Engine\Binaries\Win64. Generally speaking, it’s not necessary to run this directly, as the editor provides a few ways to generate them through a wizard that will invoke UnrealPak for you.

See below an example command to extract a pak file:

"C:\Program Files\Epic Games\UE_5.1\Engine\Binaries\Win64\UnrealPak.exe" "C:\Game\MyPakFile.pak" -Extract "C:\Users\My_Username\Desktop\Unpack"

The easiest way to package/cook a mod into a pak file is to create a plugin that contains all the mod’s data. Then it is possible to invoke UnrealPak using the DLC cooker, such as via the Project Launcher that comes with every modern vanilla UE. Note that the mod would need to be cooked for every platform intended for release, unlike the Generic Data Type approach.

Mod Loading​

Generic Data Types​

This kind of mod can be loaded in through UE’s built-in file IO layer to directly load and access the data required. In cases of raw assets, UE exposes most editor tools for asset importing, which allows runtime importing of supported asset types. This includes textures, FBX, and datasmith, all of which can be imported at runtime using Interchange, though there are other modules available to achieve this as well.

PAK Files​

PAK files can be loaded by mounting them at runtime, either statically in cases of standalone base game content/DLC, or dynamically in the case of mods.

In a packaged build, you can only mount pak files that contain cooked content. Just using UnrealPak to put a bunch of .uasset files in a pak file won’t work unless the content was cooked by the Editor for the platform being used.

The PAK file in question can be loaded based on its creation method. If it was created through DLC cooking and each asset has a matching entry in the AssetRegistry.bin within the PAK archive, then typically you can include it dynamically into your game by mounting the pak file and registering a mount point.

Once you mount pak files, they can be referenced as normal paths like any other content. In order to load them, you could query the asset registry, look up replacement actor references as part of your Spawn method, or use any other custom logic to load the content.

Modding Tools​

In-Game Modding​

Limited to generic data types as UnrealPak is not available in packaged games, nor is it redistributable under the standard UE license. This sort of approach would be common for things such as placing meshes or actors in a level and then exporting them as a JSON file. Your mod loading implementation would then read this JSON file and spawn all of these actors.

Standalone Vanilla UE Editor​

This is the minimal effort mod tooling solution while providing reasonable flexibility. To interface with base game content, some form of reparenting/remapping would be necessary. A potential solution to avoid that would be using gameplay tags to interface over a global message bus (see UGameplayMessageSubsystem in the GameplayMessageRouter plugin from the Lyra sample game).

Vanilla Editor with Mod Tool Kit​

The addition of a mod tool kit/plugin allows improved interfacing with the base game content over a vanilla editor without any supplementary content.

Example UE5 game: Torque Drift 2 (Greasemonkey Games) modding is created using the UE5 vanilla editor and supplementary tools and files provided by the developer. Their focus is on track creation and sharing. Submission from the UE5 editor with mod tool kit is direct to mod.io. Supplementary mod kit is authored by the studio for use by the modding community.

Example UE4 game: Ready or Not (VOID Interactive) modding is documented in a series of guides created by modders and shared with the studio for feedback and input. The mod kit and process are owned and driven by the modding community.

Dedicated Editor Unreal​

This option allows the maximum interfacing with the base game content and requires a cooked DDC. Based on the type of game, a creative way to strip back specific content must be devised to make the game unplayable within the mod editor while still allowing modders to mod the game as much as possible.

Example game: Homeworld 3 (Black Bird Interactive/Gearbox) modding is created via a studio-authored and released version of their dev tools. Releasing a public editor tool requires approval from Epic Games and is published in Addons (Epic Game Store).

Cross-Platform Compliance​

PAK Files​

Each PAK file should correspond to its respective platform, so if you intend to support multiple platforms, you must cook and package the plugin's content for each target platform.

‘Dos and Don’ts’​

  • Do: Utilize mod.io functionality that allows the game to sync mod collections on a subscribe function, checking the player’s collection and providing the means to enable and disable mods for a play session.

  • Don’t: Rely on exiting and restarting the application to enable mods subscribed to by a player

  • Do: Load content dynamically using the built-in QueryUserInstallations method to get the paths for each piece of content the user has installed

  • Don’t: Rely on the engine's auto-loading behavior or leveraging the Mods directory to load content, as these directories are not accessible on consoles and present additional challenges around file locking for uninstalling and updating content

Contacts​

For any further enquiries, please contact developers@mod.io.