Creating a new Mod

Folder structure

Overgrowth has a powerful and simple to use mod system that allow modders to both "overshadow" existing files, and create new ones.

Mods that are installed via the Steam workshop end up in ../Steam/steamapps/workshop/content/25000/. Each folder in there has a number assigned to it, so it can be hard to see which folder belongs to which mod. All other mods, such as manually installed ones, those from SUM Launcher and those you make yourself live in the ../Overgrowth/Data/Mods/ folder. There each mod folder has a readable name.

The folder for a mod contains at least a mod.xml file. But usually other data as well, such as scripts, shaders, models, textures or levels. All these folders are contained in a Data folder inside the mods folder, resulting in the following structure

   Overgrowth/Data/Mods/
   └── my_mod/
       ├── mod.xml
       └── Data/
           ├── Scripts/
           ├── Shaders/
           ├── Models/
           ├── Textures/
           └── Levels/

The folder called my_mod in the tree structure above is what is compressed into a zip file and distributed when a mod is released. You can also release the mod on Steam Workshop, which is a different process.

Steam Workshop

TODO: Write how to release a mod on Steam Workshop.

The mod.xml file

The mod.xml file contains the mods meta data. The game uses this file to understand how to use the mod with the game. Here is a complete example:

   <? xml version="1.0" ?>
   <Mod>
       <Id>unique-name</Id> 
       <Name>Human Readable Name</Name> 
       <Version>1.2.5</Version>
       <SupportedVersion>b4</SupportedVersion>
       <ModDependency>
           <Id>other-mod2</Id>
           <Version>1.0.0</Version> 
       </ModDependency>
   </Mod>

mod.xml tags

There are quite a few tags that can be used in the mod.xml file to set up your mod. Here we go through all of those tags.

Id

The unique ID for this mod that is not allowed to conflict with any other existing mod. One suggestion is to keep it the same as the folder name for the mod. The ID is not shown to the user, but it is used for instance when another mod wants to use this mod as a dependency.

Example: <Id>my-mod</Id>

Name

The name of the mod, shown in the mod menu.

Example: <Name>My Mod</Name>

Category

TODO: Write description

Example: <Category>Campaign</Category>

Author

Is shown in the user interface to tell the user who made the mod.

Example: <Author>John Doe</Author>

Description

Is shown in the user interface to tell the user what this mod does.

Example: <Description>This is my really cool mod that adds some excellent functionality</Description>

Version

The version of the mod. It is both shown in the user interface, and is used by other mods that depend on this mod to make sure that the user has the right version of your mod installed. Does not need to follow any specific pattern.

Example: <Version>1.0.0</Version>

Thumbnail

The path to an image to show in the user interface for your mod when the user is browsing their installed mods. Make sure you include the supplied image in the mod folder.

Example: <Thumbnail>Data/Images/my-mod/thumb.jpg</Thumbnail>

PreviewImage

This image is used in Steam Workshop to represent the mod in search results, when browsing mods and on the mod's page.

Example: <PreviewImage>Data/Images/my-mod/preview-image.jpg</PreviewImage>

Tag

Once the mod is uploaded to Steam Workshop, you can search for this tag to find the mod.

Example: <Tag>Campaign</Tag>

SupportedVersion

Which update of the game this mod can be used in. Can be something like b4, or * to indicate that it can be used with any version. Using * is useful for mods that don't rely on the game code as much, such as assets, levels and so on.

Example: <SupportedVersion>b4</SupportedVersion>

LevelHookFile

TODO: Write description

Example: <LevelHookFile>TODO: Write example</LevelHookFile>

MenuItem

TODO: Write description

title category thumbnail

Example: <MenuItem>TODO: Write example</MenuItem>

Campaign

Describes a set of levels that belong together.

Has a few attributes that describe the campaign:

Attribute	Purpose
title	The name of the campaign, shown in the menu.
type	TODO: Write description TODO: What can this be set to? A limited set? Whatever you want?
is_linear	Sets if you need to finish the first level to unlock access to the second and so on.
thumbnail	The path to the image to use for the campaign in the play menu.

Inside the campaign tag there are two or more "Level" tags in the desired order that make up the campaign. For more information about what is included in the "Level" tag, see the "Level" heading just below.

Example:

   <Campaign title="My Campaign"
             type="general"
             is_linear="true">
       <Level title="Intro" 
              thumbnail="Images/MyMod/intro_thumb.jpg">
              MyMod/intro.xml
       </Level>
       <Level title="Big Challenge" 
              thumbnail="Images/MyMod/challenge_thumb.jpg">
              MyMod/challenge.xml
       </Level>
       <Level title="Ending" 
              thumbnail="Images/MyMod/end_cutscene_thumb.jpg">
              MyMod/end_cutscene.xml
       </Level>
   </Campaign>

Level

Can be placed in the root "Mod" tag to make the specified levels show up under the play menu in the game. You can also place them in a "Campaign" tag to put them into a campaign, for more information on that, see the "Campaign" tag above.

Each level has two attributes, and between the start and end tags you write the path to the level. The root for the path is in the /Data/Levels/ folder, so leave everything up to the Levels folder out of the path, and make sure the level is stored inside the ../Overgrowth/Data/Mods/my_mod/Data/Levels/ folder.

Attributes:

Attribute	Purpose
title	The name of the level, shown in the menu.
thumbnail	The path to the image to use for the level in the play menu. This attribute is not required.

Example: <Level title="My Level" thumbnail="Images/MyMod/my_level_thumb.jpg">MyMod/my_level.xml</Level>

NeedsRestart

This tag is used to determine if the game should let the user know that they need to restart the game in order for the mod to function properly.

Can be true or false.

TODO: For what types of mods is this useful?

Example: <NeedsRestart>false</NeedsRestart>

ModDependency

Here is a list of other mods that this mod depends on to work. Has two tags for each mod:

Tag	Purpose
Id	The unique ID for the other mod.
Version	The version of the other mod that this mod requires. Set to * to accept any version of the other mod.

Example:

   <ModDependency>
       <Id>other-mod</Id>
       <Version>1.0.0</Version> 
   </ModDependency>

OverloadFile

TODO: Write description

Example: <OverloadFile>TODO: Write example</OverloadFile>

Item

Allows you to add entries to the "Load Item" list in the editor. This is useful if the mod adds weapons, characters, static objects, decals and similar things.

Has a few attributes for each entry:

Attribute	Purpose
category	Name of the sub-menu to add the item to. If the sub-menu does not exist it will automatically be created.
title	Name of the item to display in the list.
path	Path to the object file for this item.
thumbnail	Path to image to use as a preview image for this item.

Example:

   <Item category="My Mod"
         title="My item"
         path="Data/Items/MyItem.xml"
         thumbnail="Data/UI/spawner/MyItem.png" />