Modding allows you to create custom content for the game such as language translations, tweaks and new objects and functionality.
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, such as Blender, is needed if creating custom 3D objects.
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.
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
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.
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.
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 & 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.
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.
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.
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.
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.
This section will cover how to create a new language translation for Mercury Fallen. This is done in the following steps.
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.
Follow the below instructions to locate the core language files.
Copy the files inside of the Language folder to your Mods Data folder.
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.
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.
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.
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
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.
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.
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
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
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.
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 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
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.
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.
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.
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.
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..
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.
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>