Modding Guide

What a mod can add

Four kinds of content, all of them made in the Unreal Editor, none of them needing a line of C++.

Everything your mod contains lives under its own name, so two mods can both have a creature called Wolf without ever colliding. Your assets are mounted at /YourModName/.

Before you start

Three things, and the third one is the part most people miss.

Unzip it anywhere and open HolyShroomModSDK.uproject. The plugins come compiled, so you do not need Visual Studio and there is nothing to build.

A mod is a content-only Unreal plugin that sits in the Mods folder of the SDK project:

1Create the mod

One menu entry. It writes the descriptor, the folder and the manifest for you.

1. Open the Mod SDK project in Unreal Editor 5.8.
2. Go to Tools → Ultimate Mod Kit → New Mod…
3. Type a name, your author name and one sentence about what the mod does.

The Content Browser now shows /MyCoolMod/ and you can start dropping assets in. You never need the Python console for any of this: the same menu packages the mod and publishes it.

The whole menu

If you would rather script it, the same four things are on unreal.GrzybiarzModTools in the Python console — but nothing in this guide requires it.

2Fill in the manifest

The manifest is the game asking: so what exactly did you bring?

Open /MyCoolMod/ModManifest. Every field is a list you add to.

Characters: body and animations

A character here is not a pawn class - it is a row of data (body, stat bars, voice) that the shared player body uses. Two fields decide how it moves:

Mechanics: where your component goes

A mechanic is a Blueprint deriving from Grzybiarz Mod Mechanic Component, listed under Mechanics with your blueprint in ComponentClass. Target picks who gets it:

Tables: changing the rules, not just adding to them

Make a Data Table with the same row type as ours, and list it under Tables with the name of the table it joins:

Two rules decide everything:

• a row whose key the game does not have is added: a new species, item or contract,
• a row whose key the game does have replaces ours: that is how you double what a bolete sells for.

Set bMayOverrideBaseRows to false if your mod should only ever add things; the game then leaves its own rows alone and tells you in the log when your table collides with one. Changing prices makes your mod gameplay-affecting, so everyone in a co-op session needs it. That happens by itself.

3Example: a creature in ten minutes

The shortest useful mod there is. One data asset, and the game gives it a working brain: idle, wander, chase, attack, flee, die.

Right click in your mod folder and create a Grzybiarz Mod Creature Profile, or make it from the console:

unreal.GrzybiarzModTools.create_mod_data_asset(
    "MyCoolMod", "DA_MyCreature", unreal.GrzybiarzModCreatureProfile)

Then fill it in. These are the numbers from Rotcap, the first published mod, so you can copy them and change one thing at a time:

Want more than the built-in brain?

• Level 2: set ControllerClass to your own AIController. The game still spawns it, counts it, handles damage, death and networking. You only decide how it behaves.
• Level 3: set PawnClass to your own Character class. The game only spawns it and counts it. Everything else is yours.

Last step: add the profile to Creatures in the manifest. A creature nobody lists is a creature nobody sees.

4Test it in the editor

Two tests, and they answer different questions. The SDK has no game in it, so the game itself is where a mod is finally proven.

In the SDK: does the game accept the mod at all

1. Mount the mod (see step 1).
2. Watch the Output Log, category LogGrzybiarzMods. Mounting the mod and loading its manifest both report there, and so does every table it changes: doklada do tabeli 'Mushrooms': 20 wierszy.
3. If the manifest has a mistake, it is named here: a table entry without an id, a creature profile that would not load, a table the game does not know.

In the game: does it actually do something

1. Package the mod (step 5).
2. Copy the packaged mod folder into Mods next to the installed game, so that you end up with HolyShroom/Mods/YourMod/YourMod.uplugin and HolyShroom/Mods/YourMod/Content/Paks/Windows/.
3. Start the game, open MODS, tick your mod, press APPLY.
4. The row tells you what the game took from it, for example 2 tables or 1 creature. If it says Assets only., your manifest declared nothing.

This second test is the one that matters. A mod can look perfect in the editor, where its assets are loose files on disk, and still arrive empty in a packaged game, where everything lives inside an archive. Do not skip it, and do not announce a mod you have only seen in the editor.

5Package it

In the editor, raw asset files work. In the real game they do not, and this is where most first mods die.

The packaged game reads cooked content, a .pak inside your mod's Content/Paks/<Platform>, for example Content/Paks/Windows. You never build that by hand:

Tools → Ultimate Mod Kit → Package Mod → your mod. Package Mod and Upload are submenus: they list every mod the kit can see, and you pick yours.

Your mod is cooked on top of a snapshot of the shipped game. Anything you re-use from the base game, a mesh, an animation blueprint, a sound, stays out of your .pak and costs you nothing. That is why a good creature mod can weigh a few kilobytes.

6Upload to the Steam Workshop

Tools → Ultimate Mod Kit → Upload Mod To Steam Workshop → your mod

What ends up on your Workshop page is taken from files you already have:

Make the preview a square, somewhere around 512 by 512, and keep it under 1 MB: that is Steam's limit for a Workshop preview image. A 4K screenshot dropped in as preview.png is the most common reason an upload comes back with an error that explains nothing.

The first time you upload anything to a Workshop, Steam asks you to accept the Steam Workshop Terms of Service. Until you do, uploads from any tool fail.

Bump VersionName on every release. Players paste their mod list into bug reports, and the version is what tells you which build they were on.

7Your item page on Steam

Most of your item page is written by your mod, not by you clicking around on Steam.

The title, the description and the tags come from your .uplugin (FriendlyName, Description, UMKTags) and are sent again on every upload. Fix a typo in the descriptor, upload, and the page follows. The flip side: if you rewrite that text by hand on Steam, your next upload overwrites it. To keep the page yours, put "SyncDescription": false into the mod's workshop.json and the uploader stops touching it.

Visibility is also set by the upload, so a new item does not sit there private waiting for you to find the switch. It comes from "Visibility" in workshop.json, and when that field is absent, from the game's own default, which is public:

{
    "ItemId": "3826200138",
    "Mod": "RotcapMod",
    "Visibility": "public"
}

public is listed and searchable, unlisted works by direct link and can still be subscribed to, friends is your Steam friends only, and private is you alone. Set it here rather than on the Steam page: a change made on the page is undone by your next upload.

What is still yours to do on Steam:

1. Open Workshop → Your Files → Your Workshop Files, or go straight to the item by its id, the number the kit writes into workshop.json.
2. Add screenshots. Three or four from inside the game, showing the thing your mod adds. The uploader does not send these, and they are what decides whether anyone subscribes.

Check it like a player would

1. Subscribe to your own item.
2. Start Holy Shroom!
3. Open MODS. Your mod is in the list, with the name and description from the .uplugin.
4. Tick it, press APPLY, play.

8Updating your mod

Same two clicks, one number.

1. Change whatever you are changing in the editor.
2. Bump VersionName in the .uplugin.
3. Package Mod again.
4. Upload Mod To Steam Workshop again. Thanks to workshop.json this updates your existing item instead of making a second one.
5. On the item page, write a short change note. Subscribers get your update automatically and a note is the only way they learn what moved.

When something breaks

The mod list in the game says all of this out loud. Here is what each line means.

Co-op rules

Holy Shroom! is played together, and that puts three rules on your mod.

• The server owns the run. Anything that changes the world runs on the server. Calling a server action from a client writes a loud warning into the log instead of quietly doing nothing.
• Gameplay mods must match. The game builds a fingerprint from the enabled gameplay mods and their versions. Cosmetic mods do not have to match; set bForceGameplayAffecting if the game guesses wrong.
• Never move something under a player's feet every frame. It looks fine for the host and tears apart for everyone who joined.

Money and progress live in the profile of the machine you are on, not in the world: in co-op everybody has their own wallet.