Modding/Creating a Mod

This tutorial is to give the reader a general understanding of how to create a basic modification for ACS, following best practices. On the same topic, a link to iguana's Modding repository. The Readme\_EN.txt contains the following:

1. Create a new folder in the Mods folder
2. Create and complete Info.json
3. Start your Mod tour referring to the example

This is a bit more expanded version of the above list. Prerequisites:

* Amazing Cultivation Simulator
* A text editor

The tutorial is based on the Altar of Death (Wonder) Fix, mirrored on Nexus, and originally written by the author. [LINK]

## 1. Creating the Mod Folder

Navigate to the install directory for ACS, containing the executable and data files. For Steam Users, it's something similar to:

`SteamLibrary\steamapps\common\AmazingCultivationSimulator`

Navigate to the `Mods` folder. If the folder is missing for some reason, create it and navigate to it. Inside the Mods folder, create a new directory, and name it with the Internal ID of the mod you're creating.

### Mod Naming suggestions

* Keep it simple, but distinctive. If the mod is about changing a specific function, just use its name. For example, a mod fixing a particular building might have the name BuildingFix (WanGuXieFaTan\_WonderFix).
* Use prefixes to reduce conflicts. Add your name/group/initials to the internal ID. Like `iguana_WanGuXieFaTan_WonderFix`, as it not only reduces possibilities with conflicts, it also simplifies bug reporting and debugging.
* Those are for the internal designation, the Display Name has different considerations.

When the mod folder has been created and named, it's time to populate it with the required content.

## 2. Creating the Info.json and other filler

Inside the Mods\[ModID] folder, create a new text file, with the name of `Info.json`, or simply copy over an existing one. The Example Mod contains a decent example. Whether you created it from scratch or copied an existing one, ensure that the contents of the file are similar to the below example:

```
{

```

```
    "Name":"iguana_WanGuXieFaTan_WonderFix",

```

```
    "DisplayName":"Altar of Death Fix",

```

```
    "GameVersion":1.211,

```

```
    "Version":1.0,

```

```
    "Desc": "Fixes the Altar of Death ThingDef, enabling cultivation on it.",

```

```
    "Author":"iguana",

```

```
    "Tags":[

```

```
        "Function"

```

```
    ],

```

```
    "IncreasedDesc":"\n1.0: Initial Release"

```

```
}

```

A small explanation of the values within.

* Name - Internal ID of the Mod. Shown within logs, and used internally. An important value.
* DisplayName - The name displayed in-game, can be changed at will. Usage of prefixes are not needed.
* GameVersion - **Minimum** required ACS version. When the installed version is higher than the requirement, nothing happens. When it's **lower** than the requirement, the mod can't be activated.
* Version - Mod version, set by the author. Useful to update it as well, as prerequisite mods can require a certain version, which increases compatibility between mods.
* Desc - The full description of the Mod, shown in the Mod Manager.
* Author - Name of the author.
* Tags - Mod categories. This example has a single category, Function, corresponding to the Function category on the workshop.
* IncreasedDesc - Changelog, update it along with the Version.

The above is neither a minimal example (not everything is required), nor does it include every possible value. But it's short enough to give the reader another point of reference after the Readme\_EN.txt and Example Mod contents.

Apart from the Info.json, there's another file to add, the preview image. Not a requirement, but something easy to do that will make it more polished. At this point, the Mods\[ModID] should consist of the following:

* Info.json
* Preview.png

## 3. Modified content

After the structure and filler have been added, it's time to add the actual content of the mod. This is also the point where different tutorials often start at, as the previous doesn't change much.

For this example, the goal is changing an existing Buildings ThingDef. Readme\_EN.txt brings attension *[sic]* to the following:

1. Xml files can be added freely. The program will go through all the directories, including sub directories.
2. Def with same names will be overwritten according to loading order.

The Building in question, Altar of Death, can originally be found within `[ACS Install Directory]Settings\ThingDef\Buildings\Building_Ornament2.xml`, and its translation under `Settings\Language\OfficialEnglish\Settings\etc.` Taking those two points into considerations, changes can be made in two ways. The quick/dirty and the proper one. This example only goes over the proper method.

First, replicating the original file structure for the `ThingDef`.

Within `Mods\[ModID]`, create the following folder structure:

`[ModID]\Settings\ThingDef\Building`

Navigate to the Building directory and create an xml file within it. The name is irrelevant, the example uses `Building_Ornament2_FIX.xml`, or a full path of:

`iguana_WanGuXieFaTan_WonderFix\Settings\ThingDef\Building\Building_Ornament2_FIX.xml`

The file consists of ThingDefs, a single entry within the list, which is the offending ThingDef that needs to be overwritten. Compared to the vanilla version, the <Tags> are different. Full contents of that file can be seen below:

```
<ThingDefs><List>

```

```
<ThingDef Type="Building" Name="Building_WanGuXieFaTan" Parent="MiracleBase">

```

```
    <TexPath>res\Sprs\building_zhengfatianxia\building_wanguxiefatan01</TexPath>

```

```
    <TexScale>1</TexScale>

```

```
    <Tags>

```

```
        <Tag Name="_WONDER" Level="1"/>

```

```
        <Tag Name="Sitable" Level="1"/>

```

```
        <Tag Name="Practice" Level="20"/>

```

```
    </Tags>

```

```
    <TonglingHair>hairbaiman</TonglingHair>

```

```
    <ThingName>万骨邪法坛</ThingName>

```

```
    <Desc>百蛮山镇派奇观，传说其中蕴含有时空尽衰之道的奥秘。</Desc>

```

```
    <ElementKind>Mu</ElementKind>

```

```
    <ShadowSize>

```

```
        <x>1</x>

```

```
        <y>1.2</y>

```

```
    </ShadowSize>

```

```
    <ColliderKind>NoPass</ColliderKind>

```

```
    <Collider>

```

```

```

```
        <Data>

```

```
        [1,1,5,1,1,1],

```

```
        [1,1,1,1,1,1],

```

```
        [1,1,3,1,1,1],

```

```
        [1,1,1,1,1,1],

```

```
        </Data>

```

```
        <WorkOffset>

```

```
            <li Index="0"  X="0.5" Y="0.5" Z="-3" Ang="181"/>

```

```
        </WorkOffset>

```

```
        <OffsetGroup>

```

```
            <li><x>0</x><y>0</y></li>

```

```
            <li><x>0</x><y>0</y></li>

```

```
            <li><x>0.5</x><y>1.4</y></li>

```

```
            <li><x>0</x><y>0</y></li>

```

```
        </OffsetGroup>

```

```
    </Collider>

```

```
    <Building>

```

```
        <OwnerCount>1</OwnerCount>

```

```
        <PracticeEffectiveness>2</PracticeEffectiveness>

```

```
        <SnowRenderData>

```

```
            <x>3.3</x>

```

```
            <y>3.95</y>

```

```
            <z>1</z>

```

```
        </SnowRenderData>

```

```
    </Building>

```

```
    <Element>

```

```
        <Kind>Mu</Kind>

```

```
    </Element>

```

```
    <Ling>

```

```
        <AddionLing>1200</AddionLing>

```

```
        <AddionRadius>3</AddionRadius>

```

```
        <AddionFailing>1</AddionFailing>

```

```
        <AddionFailRadius>1</AddionFailRadius>

```

```

```

```
        <Attenuation>0</Attenuation>

```

```
        <Absorption>0</Absorption>

```

```
        <Accommodate>0</Accommodate>

```

```
    </Ling>

```

```
    </ThingDef>

```

```
</List></ThingDefs>

```

The offending Building is now fixed, but when testing it out, it will be obvious that something is missing. It's now in Chinese. That can be solved by adding the OfficialEnglish translations to the Mod. And with that, there are also two ways. The simple version for vanilla content, and the intended alternative for custom content. Since it's about vanilla content, the former can be used.

### Translation

Similarly to how a single ThingDef can be easily overwritten, a similar logic can be applied to translations. An important difference between vanilla and modded content, the directory is **different**. As an example for this building:

* Vanilla translations are located under [InstallDirectory]\Settings\Language\OfficialEnglish\Settings\ThingDef\Building
* Mod translations are located under [ModID]\Language\OfficialEnglish\Settings\ThingDef\Building

With that in mind, within `Mods\[ModID]`, create the following folder structure:

`[ModID]\Language\OfficialEnglish\Settings\ThingDef\Building`

Similarly to the previous, create an xml file within it. An identical name is not a hard requirement, but it does make it cleaner for further development as well as anyone looking at it afterwards. The full path for that:

`iguana_WanGuXieFaTan_WonderFix\Language\OfficialEnglish\Settings\ThingDef\Building\Building_Ornament2_FIX.xml`

While the previous file contained ThingDefs, translations contain Texts. Full contents of that file can be seen below:

```
<Texts Type="Thing">

```

```
  <List>

```

```
    <Text Name="Building_WanGuXieFaTan" sParam="Building">

```

```
      <ThingName>Altar of Death</ThingName>

```

```
      <Desc>Iconic scenery of Mt. Hundred Insects, it is said to have embodied secrets regarding the nullification of time and space.</Desc>

```

```
    </Text>

```

```
  </List>

```

```
</Texts>

```

And that's it. A folder, an Info.json, preview image, and two xml files located at the proper paths, nothing else needed.

Test it out in-game, you will see that it works the way as described.