Difference between revisions of "Creating a new Mod"

From Wolfire Games Wiki
Jump to: navigation, search
(Created page with "== How to create a mod == Since alpha 210, a new mod system as been constructed to assist in making mods for Overgrowth. The mod system is mainly folder based and works by "Over...")
 
(Complete rewrite and adds maybe almost all information about mod.xml files.)
Line 1: Line 1:
−
== How to create a mod ==
+
== Folder structure ==
  
−
Since alpha 210, a new mod system as been constructed to assist in making mods for Overgrowth. The mod system is mainly folder based and works by "Overshadowing" and complementing
+
Overgrowth has a powerful and simple to use mod system that allow modders to both "overshadow" existing files, and create new ones.
−
the existing Data folder.
 
  
 +
Mods that are installed via the Steam workshop end up in <code>../Steam/steamapps/workshop/content/25000/</code>. 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 <code>../Overgrowth/Data/Mods/</code> folder. There each mod folder has a readable name.
  
−
Mods are usually installed in the game Data folder, in the Mods folder, it can look something like this
+
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/
+
    Overgrowth/Data/Mods/
 +
    └── my_mod/
 +
        ├── mod.xml
 +
        └── Data/
 +
            ├── Scripts/
 +
            ├── Shaders/
 +
            ├── Models/
 +
            ├── Textures/
 +
            └── Levels/
  
−
In the mods folder there is one folder for each mod.
+
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.
  
−
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 the Data folder, resulting in the following structure
+
== Steam Workshop ==
  
−
  Overgrowth/Data/Mods/
+
TODO: Write how to release a mod on Steam Workshop.
−
  - my_mod/
 
−
      - mod.xml
 
−
      - Data/
 
−
          - Scripts/
 
−
          - Shaders/
 
−
          - Models/
 
−
          - Textures/
 
−
          - Levels/
 
  
−
== The internal of the mod.xml - file ==
+
== The mod.xml file ==
  
−
The mod.xml file is the primary meta-file for a mod. It's the file that the game searches for and parses to understand how to integrate the mod into the game. Following is a complete example.
+
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" ?>
 
     <? xml version="1.0" ?>
Line 35: Line 35:
 
         <!-- Version number, can have any formatting you wish. -->
 
         <!-- Version number, can have any formatting you wish. -->
 
         <Version>1.2.5</Version>
 
         <Version>1.2.5</Version>
−
         <SupportedVersion>a210</SupportedVersion>
+
         <SupportedVersion>b4</SupportedVersion>
 
         <ModDependency>
 
         <ModDependency>
 
             <Id>other-mod2</Id>
 
             <Id>other-mod2</Id>
Line 41: Line 41:
 
         </ModDependency>
 
         </ModDependency>
 
     </Mod>
 
     </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:
 +
<code><Id>my-mod</Id></code>
 +
 +
=== Name ===
 +
 +
The name of the mod, shown in the mod menu.
 +
 +
Example:
 +
<code><Name>My Mod</Name></code>
 +
 +
=== Category ===
 +
 +
TODO: Write description
 +
 +
Example:
 +
<code><Category>Campaign</Category></code>
 +
 +
=== Author ===
 +
 +
Is shown in the user interface to tell the user who made the mod.
 +
 +
Example:
 +
<code><Author>John Doe</Author></code>
 +
 +
=== Description ===
 +
 +
Is shown in the user interface to tell the user what this mod does.
 +
 +
Example:
 +
<code><Description>This is my really cool mod that adds some excellent functionality</Description></code>
 +
 +
=== 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:
 +
<code><Version>1.0.0</Version></code>
 +
 +
=== 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:
 +
<code><Thumbnail>Data/Images/my-mod/thumb.jpg</Thumbnail></code>
 +
 +
=== PreviewImage ===
 +
 +
This tag is no longer used.
 +
 +
Maybe this entry should be removed as it doesn't do anything.
 +
 +
Example:
 +
<code><PreviewImage>Data/Images/my-mod/preview-image.jpg</PreviewImage></code>
 +
 +
=== Tag ===
 +
 +
Once the mod is uploaded to Steam Workshop, you can search for this tag to find the mod.
 +
 +
Example:
 +
<code><Tag>Campaign</Tag></code>
 +
 +
=== SupportedVersion ===
 +
 +
Which update of the game this mod can be used in. Can be something like <code>b4</code>, or <code>*</code> to indicate that it can be used with any version. Using <code>*</code> is useful for mods that don't rely on the game code as much, such as assets, levels and so on.
 +
 +
Example:
 +
<code><SupportedVersion>b4</SupportedVersion></code>
 +
 +
=== LevelHookFile ===
 +
 +
TODO: Write description
 +
 +
Example:
 +
<code><LevelHookFile>TODO: Write example</LevelHookFile></code>
 +
 +
=== MenuItem ===
 +
 +
TODO: Write description
 +
 +
title
 +
category
 +
thumbnail
 +
 +
Example:
 +
<code><MenuItem>TODO: Write example</MenuItem></code>
 +
 +
=== Campaign ===
 +
 +
Describes a set of levels that belong together.
 +
 +
Has a few attributes that describe the campaign:
 +
 +
{| class="wikitable"
 +
|-
 +
! 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 <code>../Overgrowth/Data/Mods/my_mod/Data/Levels/</code> folder.
 +
 +
Attributes:
 +
{| class="wikitable"
 +
|-
 +
! 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:
 +
<code><Level title="My Level" thumbnail="Images/MyMod/my_level_thumb.jpg">MyMod/my_level.xml</Level></code>
 +
 +
=== 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 <code>true</code> or <code>false</code>.
 +
 +
TODO: For what types of mods is this useful?
 +
 +
Example:
 +
<code><NeedsRestart>false</NeedsRestart></code>
 +
 +
=== ModDependency ===
 +
 +
Here is a list of other mods that this mod depends on to work. Has two tags for each mod:
 +
 +
{| class="wikitable"
 +
|-
 +
! Tag !! Purpose
 +
|-
 +
! Id
 +
| The unique ID for the other mod.
 +
|-
 +
! Version
 +
| The version of the other mod that this mod requires. Set to <code>*</code> 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:
 +
<code><OverloadFile>TODO: Write example</OverloadFile></code>
 +
 +
=== 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:
 +
 +
{| class="wikitable"
 +
|-
 +
! 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" />

Revision as of 18:27, 6 July 2017

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 tag is no longer used.

Maybe this entry should be removed as it doesn't do anything.

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" />
Retrieved from "https://wiki.wolfire.com/index.php?title=Creating_a_new_Mod&oldid=4621"