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/
Note that your mod can be set up and kept in either YourPC/Documents/Wolfire/Overgrowth/Data/Mods, or in the actual program files, in YourPC/(C:)/Program Files(x86)/Steam/steamapps/common/Overgrowth/Data/Mods - both of these "Mods" folder locations will work. 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
Deprecated, no longer works.
Adds a campaign button to the Play menu which runs a script. The script type is a Scriptable Menu.
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 | Deprecated, has no effect. |
| 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.
You need to manually test for if your mod works properly without a game restart, and then put true or false depending on the outcome.
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" />
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
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?
