Modding Guide - Getting Started

How to get started creating mods for Mercury Fallen.

What Are Mods?

Mods are a way of adding or changing game data. This includes overriding existing data and adding new data to change various aspects of the game such as a new language translation. Mercury Fallen data is defined using XML files.

Tutorial Files

Download the tutorial .zip file below which contains examples of adding and overriding data in Mercury Fallen. The tutorial mod also shows the expected file structure for your custom mod.

Included Examples

• Overriding the Power Generator to increase power output and material requirements
  
• Creating a new piece of colonist equipment
  
• Creating a language file to add name/description data for added equipment

Tutorial Mod Download[nitrousbutterfly.com]

User Mods Location

When creating your own mod, or using a mod not on the Steam Workshop, the mod folder must be placed inside the Mercury Fallen UserMods folder. Placing mod folders in the UserMods folder will ensure that the mod can be enabled in the Mod Manager in game.

Windows Location
<Documents>/Mercury Fallen/UserMods/

Mac Location
/Users/<yourusername>/Mercury Fallen/UserMods

Mod File Structure

A mod must be contained in it’s own folder. In the root of this folder resides the modinfo.xml file and preview.jpg. Xml files that modify or add game data must be in a sub-folder.



Sub folders containing your mod data files do not require any specific naming convention. When a mod is enabled the game will search all sub folders inside a mods main folder for xml data.

The mod preview image is required if submitting your mod to the Steam Workshop. 512×512 pixel size is recommended.

Mod Info File

A modinfo.xml file must be in the root of your mod folder. This defines your mod and is required for your mod to function. The mod info file must contain the following XML content. You can use a text editor such as WordPad or Notepad++ to create and edit XML files. Change the values accordingly for your mod.

<ModInfo> 
    <Name>Generator Mod</Name>
    <Author>So &amp; So</Author>
    <URL>http://wwww.website.com</URL>
    <Version>1.0</Version>
    <Summary>Increases Output of Coal Generator</Summary>
</ModInfo>

Name
This is the display name that will appear in the mod manager list inside the game

Author
This is you. Add your name or call sign here. This is visible in the mod manager.

URL
A link to your website or page regarding this mod or your mods.

Version
A description of your mods version. Version info is up to you, but should reflect the current state of the mod and be changed as you update your mod.

Summary
A description of what your mod does.

Note:
If you upload your mod to the Workshop the Name, Author and Summary fields will use the values from the Steam Workshop when viewed in the Mod Manager. This allows you to modify your Title and Description on the Workshop without having these values overridden when you update your mod later.

Core Game Content

When creating a mod you will often be overriding XML data defined by the core content of the game. Follow the instructions below to reach the location of the core game files.

• Right click Mercury Fallen in your Steam Library and click Properties
  
• Click the Local Files tab
  
• Click the Browse Local Files… button. This will open the local game folder for Mercury Fallen.
  
• The core game files are located under MercuryFallen_Data/Mods/Core

The game data files are organized into sub-folders. This is a good place to get started as this will show you how the various data is defined in the game.

Enabling Mod

Once your mod has been setup it will need to be enabled in game. On the Main Menu click on Mods to open the Mod Manager. The mod should appear in the mod list. Click the toggle next to the mod to enable it and click the close button. The mod is now enabled and loaded.


If your mod doesn't appear in the Mod Manager double check that your mod folder is in the correct location and that your modinfo.xml is setup correctly as shown above.

Upload To Workshop

Be sure to play test your mod before uploading it to the Steam Workshop. Any mod that you upload must either be of your own creation or you have proper permission to upload it as your own.

You can easily upload your mod to the Steam Workshop from the Mod Manager. Select your mod in the Mod Manager and click the Upload To Workshop button. Once the upload is complete your mod should now be in the Steam Workshop. This is also how you can update your mod if you need to upload changes.

Workshop items are hidden by default, so be sure to set your mod to visible in the properties page of your mod on the workshop.

Creating & Overriding Data

Overview

This section will cover xml structure and usage.

Object data is stored in xml files. You can use a text editor such as Notepad++ to create and edit your xml files. All xml data files should have the .xml extension. For reference on how existing objects in the game are defined please check the Core Game Content section.

Xml Structure

The xml data structure for Mercury Fallen is as follows:

<GEInfos>
   <GEInfo name="" class="">
      <components>
         <comp class="">
            ...
         </comp>
         <comp class="">
            ...
         </comp>
      </components>
   </GEInfo>

   <GEInfo name="" class="">
      ...
   </GEInfo>
</GEInfos>

Each xml file is expected to contain one <GEInfos> or <GDInfos> tag. Contained inside these tags can be one or more <GEInfo> or <GDInfo> tags respectively. <GEInfo> is used to represent Game Entities that have visual elements in world such as floors, walls, machines. <GDInfo> is used to represent GameData such as items, research, discoveries etc..

Override Existing Xml Definitions

Core game content can be overridden to add or change existing properties or behavior. As mods are loaded, any mod data with a matching GEInfo or GDInfo name attribute value will replace any currently loaded data by the same name in the core data or a previously loaded mod based on mod load order.

• Find the GEInfo or GDInfo data you want to override in the core game files
  
• Copy the GEInfo or GDInfo data to an xml file in your mod
  
• Do not change the name value of the GEInfo or GDInfo data as this is how it knows what it will override
  
• Modify the data in your mods xml file

New Object Xml Example

The example below uses custom content generated using the Mod Tools. Please refer to the Custom Artwork guide for more information on setting up custom artwork.

https://steamcommunity.com/sharedfiles/filedetails/?id=2436191603

The example below is an xml file for a mod that adds a custom lamp object.

<GEInfos>
   <GEInfo name="mf_mod_tut_lamp" class="EStructure">
        <components>
            <comp class="CGraphicModel">
                <resource_path>Assets/Export Content/Meshes/Sample Lamp/ModTutorialObjectPrefab.prefab</resource_path>
                <connect_type>Single</connect_type>
            </comp>
            <comp class="CProperties">	
                <tags>tg_ge_lightsource</tags>
                <rotatable>false</rotatable>
                <size type="IntVec2">1,1</size>               
                <destroyable>true</destroyable>
                <walkable>true</walkable>                
                <ui_struct_cat>uisc_furniture</ui_struct_cat>
                <ui_icon>Assets/Export Content/Icons/tutmod_icons/icon_ModTutorialObjectPrefab.png</ui_icon>
                <collider>true</collider>
                <durability>10</durability>
                <footprint>
                    A
                </footprint>
            </comp>
            <comp class="CLightSource">
                <range>4</range>
                <intensity>1.2</intensity>
                <color>#FFFFFF</color>
                <offset_y>0.73</offset_y>
                <reqire_power>true</reqire_power>
                <allow_color_change>true</allow_color_change>
            </comp>            
            <comp class="CElectricConsumer">  
                <consumption_amt>5</consumption_amt>
            </comp>
            <comp class="CDecorProvider">
                <amount>0.1</amount>
                <range>2</range>
            </comp>
            <comp class="CBuildable">
                <work_amt>5</work_amt>
                <resources>
                    <item name="res_structresin">5</item>
                    <item name="res_copper">1</item>
                </resources>
            </comp>		
            <comp class="CEquipment">
                <max_allowed>1</max_allowed>
            </comp>
        </components>
    </GEInfo>
</GEInfos>

The <GEInfo> tag contains a list of components that add various properties and functionality to the object. There are too many options to cover here and it is recommended to review the core game files for examples of how various data is setup for Mercury Fallen.

There are a couple of important elements to note though.

GEInfo Name Attribute

The name attribute of the <GEInfo> tag must be a unique name if creating a new piece of content. This name must not match any existing name used in the core game files or in another mod. It is recommended to use your mod name in front of the unique object name to ensure there are no conflicts.

<GEInfo name="MYMOD_MY_UNIQUE_NAME" class="EStructure">

Resource Path

The <resource_path> tag is the path to your custom model inside the asset bundle generated for your mod. A manifest file is generated for each asset bundle generated when using the Mod Tool. This manifest contains a list of asset paths that can be used inside the <resource_path> tag to reference your model prefab.

<comp class="CGraphicModel">
                <resource_path>Assets/Export Content/Meshes/Sample Lamp/ModTutorialObjectPrefab.prefab</resource_path>
                <connect_type>Single</connect_type>
</comp>

UI Icon

The <ui_icon> tag is the path to the sprite asset used as an icon for your object. A manifest file is generated for each asset bundle generated when using the Mod Tool. This manifest contains a list of asset paths that can be used inside the <ui_icon> tag to reference your icon sprite.

 <ui_icon>Assets/Export Content/Icons/tutmod_icons/icon_ModTutorialObjectPrefab.png</ui_icon>

[Aidylheid]

Thanks for the info. Is there an example for making new objects? I used to make mods for Space Engineers and would love to start making models and other objects for this game. An example of that would be great. Haven't played with Blender for a while and really want to get back into that.