Modding Guide

What Are Mods?

Modding allows you to create custom content for the game such as language translations, tweaks and new objects and functionality.

Recommended Knowledge/Tools

Xml

Xml is used to define game data for Mercury Fallen. This game data describes most of the content in the game such as languages, objects, items, attributes and a whole lot more.

3D Modelling Software

3D Modelling software, such as Blender, is needed if creating custom 3D objects.

Unity Game Engine

The Unity game engine is used to create Mercury Fallen. Unity is used to import your custom 3D models and export them into asset bundles that can be used in your mod.

Getting Started

User Mods Location

When creating your own mod, or using a mod not on the Steam Workshop, your mods 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

Folder 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 subfolders inside a mods main folder for game data.

Preview Image

A mod preview image is required if submitting your mod to the Steam Workshop. This file should be named preview.jpg and 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 or referencing XML data defined by the core content of the game. Follow the instructions below to find 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.

Running Your Mod In Game

Once your mod has been set up it will need to be enabled in game. On the Main Menu click the Mods button 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 set up 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.

Language Translation Mods

Overview

This section will cover how to create a new language translation for Mercury Fallen. This is done in the following steps.

Create and setup your mods folder
Copy the core English language files that will be translated
Setup and translate language files
Upload To Steam Workshop

Setup Your Mod Folder

You will first need to set up your mod folder in the UserMods folder as covered in the Getting Started section of this guide.

Once your mod folder has been set up and you have a Data folder you will need to copy over the source language files to your mod folder.

Copy Core Language Files

Follow the below instructions to locate the core language 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 language files are located under MercuryFallen_Data/Mods/Core/Language

Copy the files inside of the Language folder to your Mods Data folder.

Modify & Translate Language Files

At the top of each language file inside your mod folder you’ll need to change the name and display_name properties. Be sure all of your modified language files use the same values.

<GDInfo name="YOUR_LANGUAGE_NAME" class="GDGameLanguage">
        <components>
            <comp class="CProperties">
                <display_name>YOUR_DISPLAY_NAME</display_name>
                <language_code>en-US</language_code>  
            </comp>
        </components>

name
This is the unique identifier for your language mod. This must be different from the core language file. All of the translated language files must use this same name.

display_name
This is how your language will appear in the Language setting drop down in game.

Translation

After setting up your mod and copying the language files you can translate the game. Open the language files in your mod folder in a text editor like WordPad or Notepad++. All language strings for Mercury Fallen use the ‘gstr’ tag. Translate the values between the opening and closing gstr tags.

Do not change the name attribute value. Do not change/remove any special characters including curly brackets. Doing so may cause unexpected behavior when running your mod.

You can enable your mod using the Mod Manager from the main menu.

Be sure to change the selected language under settings after enabling your mod.

Custom Models

Overview

Mercury Fallen supports custom 2D & 3D artwork. You will need 3D modelling software to create your content. This section will cover how to import your content into Unity and export it so that it can be used in your mod.

Unity Installation

Mercury Fallen uses Unity Engine version 2018.4.32. Download Unity using the following link:

https://unity3d.com/get-unity/download/archive

Unity Hub Recommended

Unity Setup

You will need to install the Mercury Fallen Mod Tools package available in your Steam game library under tools.

Launch the Mercury Fallen – Mod Tools from Steam. This will open a folder containing a Unity project folder and mod example files. The “Mercury Fallen – Mod Tools” folder will need to be opened in Unity.

Open Unity HUB and click the Add button. Browse to the Mercury Fallen – Mod Tools folder located in the mod tools folder opened from Steam. Click Select Folder to add the project to Unity.

Click the Mercury Fallen – Mod Tools in the list to open the project. You will be prompted to install the correct Unity version if it’s not already installed.

Model & Texture Info

Model Details

Be sure to keep your objects low poly. Especially given that objects are not seen close up.

Scale

Models are designed to fit onto the floor grid. Each floor tile is 1×1 meter in size.

Model Pivot

The models pivot should be at world center (0, 0, 0). The pivot represents the center of the objects footprint. So a 3×2 tile object will still have it’s pivot at world center but the object mesh may be offset from center depending on how it should appear within it’s footprint area.

Format

Export to FBX format from your 3D modelling software

Texture Size

This depends on the detail/size of the object. This can range from 128×128 for smaller objects up to 512×512 for larger objects. Often 256×256 is a good texture size for most objects.

Material Textures

Mercury Fallen uses a custom Physically Based Rendering material. PBR materials require color, metallic and roughness maps. The custom Mercury Fallen standard shader used for Unity materials is broken down as follows.

Main Texture

This is the main color texture

Normal Map

While recommended, a normal map is not required

MREM

The MREM texture uses the texture color channels for following properties.

Red Channel = Grayscale metallic values

Blue Channel = Grayscale roughness values

Green Channel = Optional grayscale emission mask

Importing Your Assets

It is recommended to import your content to the Export Content folder in the Project panel.

Select the Export Content folder in the Project panel.

Drag and Drop your model and textures to the Project panel

Model Preparation

Prefab

Once your mesh is imported, drag it from the Project panel to the Hierarchy panel. Your model will appear in the scene. Simply drag it back to the to Project panel from the hierarchy panel to create a prefab instance.

You can now double click the prefab instance in the Project panel to open the prefab editor. Inside the prefab editor you can now assign your materials and setup custom colliders as shown below.

Materials

Right click inside the Project window, inside your models folder, and select Create->Material. Be sure to name your material something unique.

Select the material and in the inspector set the Shader to Mercury Fallen->MF_Standard. Drag and drop your Main Color texture, BumpMap and MREM to the correct slots on the material.

Any other texture slots/values can remain with their default values.

Colliders

Colliders are generated automatically for your model, but in some instances this may not be desired or function as expected. Colliders can be created manually.

Double click your prefab to open the prefab editor.

Right click the top level of your object in the hierarchy panel and select Create Empty.

Rename the new gameobject “Collider”

Select the Collider gameobject and in the inspector click the Add Component button and choose Box Collider

Click the Edit Collider Button and adjust your collider to fit your model

Creating An Object Icon

Included with the Mod Tool is the Prefab Icon Maker. This utility can be used to generate icon sprites for your custom objects.

Open the Prefab Icon Maker under the Mercury Fallen menu.

Object Prefab

Drag and drop your model prefab from the Project panel to the Object Prefab field

Packing Tag

The packing tag is used to generate a folder to store your icons as well as the sprites packing tag for use in a sprite atlas. It is recommended that all of the icon for your mod should use the same packing tag.

Camera Preset

The camera preset drop down has a collection of default camera values used when capturing your icon.

Object/Camera Values

These sliders are used to position the object and camera when previewing/saving your icon.

Preview

Clicking the preview button will display a sample of the generated icon below the button. Be sure to adjust the Object/Camera values until the icon looks good.

Save Icon

After previewing your icon and making sure that it looks just right, click the Save Icon button to save your icon. Saved icons will be stored in the Icons/[packing tag] folder under Assets.

Assign Asset Bundle

All of the assets included in your mod will need to be assigned an asset bundle tag. This includes all models, prefabs, textures and icons. Any assets not assigned an asset bundle tag will not be exported.

Select one or more assets in the Project panel.

At the bottom of the Inspector panel select None and then New…

Enter a name for your asset bundle.

If adding new assets to an asset bundle tag you already created, then select your asset bundle tag in the list.

Exporting Your Assets

Open the Mod Tool by selecting Mercury Fallen->Mod Tool from the top menu.

You can either load an existing mod folder or create a new mod.

Load Mod
Choose an existing mod to load from the mod folder located in the UserMods folder. Select a mods folder to load.

Create Mod
This will open a prompt to create a new mod folder. Once created it will setup the mod folder in the UserMods folder. It will also setup a default modinfo.xml file and data folder for your content.

Once your mod is loaded or created you can export your content. You can also edit the mod info from here and any changes.

Click the Export Assets to export your model content.

Your exported content will be stored in the Data folder inside your mod folder. Clicking “Open Mod Folder” button will open a file browser to your mods folder.

The *.asset files should be included with your mod. *.manifest files are also generated which do not need to be included in your final mod upload. The manifest files can be opened in a text editor and contain a list of the assets that are included in your asset bundle. The listed asset paths can be used in your mod for referencing the prefab and or any sprite files.

Xml 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 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>

Modding Guide

What Are Mods?

Recommended Knowledge/Tools

Xml

3D Modelling Software

Unity Game Engine

Getting Started

User Mods Location

Folder Structure

Preview Image

Mod Info File

Core Game Content

Running Your Mod In Game

Upload To Workshop

Language Translation Mods

Overview

Setup Your Mod Folder

Copy Core Language Files

Modify & Translate Language Files

Translation

Custom Models

Overview

Unity Installation

Unity Setup

Model & Texture Info

Model Details

Material Textures

Importing Your Assets

Model Preparation

Prefab

Materials

Colliders

Creating An Object Icon

Assign Asset Bundle

Exporting Your Assets

Xml Data

Overview

Xml Structure

Override Existing Xml Definitions

New Object Xml Example

Contents