Skip to content

Your first mod

This guide makes Low Gravity, a mod that adds a new round to a game. The game never names it: the mod finds its own place in the game's list of rounds. The example project's Mods/LowGravity is this mod, finished, and Mods/README.md beside it goes into more detail.

A mod is made in the game's own project (or a copy of it handed to modders), so it can use the game's content, and cooked against a released build, so it ships only its own.

1. The game takes mods

The game sets this up once (Mods has the details):

  1. Project Settings > Plugins > Gantry Experience: add Mods to Mod Directories, and turn on Mount Mods At Startup.
  2. Install Gantry's game feature policy, so mods made for another build are refused.
  3. Package a release that mods are built against, with -createreleaseversion=1.0 on BuildCookRun. This writes the release's details to Releases/1.0/<Platform>/.

2. The mod's folder

Create Mods/LowGravity/ next to the game's .uproject, with a LowGravity.uplugin in it. It is a game feature plugin: copy an example mod's .uplugin and change the names, or check that it has:

  • "ExplicitlyLoaded": true, "EnabledByDefault": false;
  • "BuiltInInitialFeatureState": "Registered": Gantry activates it when its experience runs;
  • "CanContainContent": true;
  • Gantry in Plugins, plus any game feature plugin of the game's it builds on.

Declare the mod's own gameplay tags in Config/Tags/LowGravity.ini inside the folder, such as Experience.Yard.LowGravity. They are read when the mod is registered.

3. Mount it in the editor

  1. In the console, run Gantry.Mods.Mount. The first time, the mod has no game feature data yet, so Gantry opens its content folder and says so.
  2. In that folder, Add > Gantry > Game Feature Data, named LowGravity, at the folder's root.
  3. Run Gantry.Mods.Mount again. The mod is registered, and its content works like the game's own.

4. The round

  1. In the mod's content folder, Add > Gantry > Experience, using the game's own experience class if it has one, and name it EXP_LowGravity.
  2. Set Experience Tag to Experience.Yard.LowGravity.
  3. Set Attach To to the experience the game's rounds sit under. In the example game, that is Experience.Yard, so the round joins the lobby's vote.
  4. In Stages, add Activate Game Features with LowGravity in Game Feature Plugin Names, plus any of the game's plugins the round reuses.
  5. Put the round's content in the mod's plugin: in the example, a game feature action that makes every character floaty.

Play in the editor: the round appears wherever the game lists rounds. Gantry.Mods.Report shows the mod, and anything it clashes with.

To change an existing round instead of adding one, set Extends to that round's tag and Attach To to the base experience's: the example's Mods/ShinyCrates does this.

5. Cook it

Cook the mod as DLC against the release from step 1:

RunUAT BuildCookRun -project=<game>.uproject -platform=<Platform> -cook -stage -pak
  -dlcname=<path to>/Mods/LowGravity/LowGravity.uplugin -basedonreleaseversion=1.0

Add -server -noclient or -client for dedicated server or client builds. Gantry mounts the mod inside the cook so the cooker can find it, and the cook refuses anything the mod uses that is neither its own nor in the release.

Then copy the staged .pak, .utoc and .ucas files from the mod's Saved/StagedBuilds into Mods/LowGravity/Content/Paks/<Platform>/.

6. Ship it

Copy the mod's folder (LowGravity.uplugin, Config/, Content/Paks/) into the packaged game's Mods/ folder. Or pack it into one file for players, stored, not compressed:

cd Mods/LowGravity && zip -0 -r ../LowGravity.gantry LowGravity.uplugin Config Content/Paks/<Platform>

Start the game: Gantry mounts the mod, and the round is offered with the game's own. If the game has a Mod Rescan Interval, a mod copied in while it runs is mounted within a moment.

When it is refused

The log, and Gantry.Mods.Report, say why. The usual reasons: the .uplugin is not Explicitly Loaded, the mod was cooked against another build, or its Metadata > Required Game Version does not include this one. Mods lists every check.