Creating a new Mod

Folder structure

Overgrowth has a powerful and simple system to allow the creation of mods by both "overshadowing" existing files, and by creating new files.

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 must contain at least a mod.xml file. Other data may be present as well, such as scripts, shaders, models, textures or levels. All these folders are contained in a Data folder inside the mod's 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 that you can read about a bit further down.

The mod.xml file

The mod.xml file contains the mod's meta data. The game uses this file to understand how to use the mod with the game. XML files can be written and modified using programs like Notepad++ and Sublime Text. 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>

You can find all available tags and their uses under the mod.xml_tags heading below.

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. ID tag text must consist of letters and dashes only, with no uppercase.

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

Name

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

Example: <Name>My Mod</Name>

Category

TODO: Verify that this is correct.

Required for a valid mod, but does not seem to have any effect.

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 the tags to find the mod. You can have as many tags as you want.

Example:

<Tag>Campaign</Tag>
<Tag>Parkour</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.

TODO: How can you find out which is the current version?

Example: <SupportedVersion>b4</SupportedVersion>

LevelHookFile

Specifies a path to a script file. Functions in this script are run for every level in the game when the mod is active. Every mod can add their own level hook script. Read this for more information.

Example: <LevelHookFile>Scripts/my_mod/level_script.as</LevelHookFile>

MenuItem

Adds a campaign button to the Play menu which runs a script. The script type is a Scriptable Menu.

TODO: The current example does not work. Is this feature functional?

Example: <MenuItem title="My Menu" category="My Category" thumbnail="Data/Images/my_mod/my_item.png" path="Data/Scripts/my_menu_script.as"/>

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

This 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" />

Advanced mod menu

The advanced mod menu

To help modders validate their mods and upload them to the Steam Workshop there is a tool called the "Advanced mod menu". Access it by going to the main menu, then in the top menu bar, click Windows -> Mods. This brings up a simpler version of the mod menu. To activate the advanced mod menu, click Menu -> Advanced. Make sure to increase the size of the window to see all the new information in the window.

This shows all the available information for the selected mod.

Steam Workshop

The Steamworks New Upload menu

To release a mod on Steam Workshop, first create your mod and make sure it works as intended. Then open up the advanced mod menu, make sure the "Valid" item says "Yes", press "Upload To Steamworks..." and follow the instructions at the bottom.

If it says something about needing to accept an agreement when you've uploaded a mod, go to http://steamcommunity.com/sharedfiles/workshoplegalagreement, log in, read through and accept the agreement if you do.

Any mod that has just been uploaded will be private. And before you make it public you should brush up the mod's page a bit. It's a good idea to add a video, some screenshots, a description that tells the user what makes the mod interesting, how to use it and so on.

If the mod requires some other mod to work, make sure to specify that using the "Add/Remove Required Items" in the "Owner Controls".

Updating a Mod on Steam Workshop

TODO: What is the process for updating an already uploaded mod on Steam Workshop?