Editing Modding for fun and profit (section)

= Modding Guide for ''Ara: History Untold'' =

== Introduction ==
''Ara: History Untold'' is a new game, and modding possibilities are still evolving as the game stabilizes and expands. What can be modded today will grow in the future. This guide provides the basic structure for modding the game, along with examples to help modders get started.

== Chapter 0: ZNO, ZSchema, & ZData ==
''Ara: History Untold'' uses a unique data structure called ZNO, integrated into the Nitrous Engine that powers the game. Key components for modding include:

* '''ZSchema''' - Defines the fields and formatting rules for a data type.
* '''ZData''' - Used to implement new elements and content. Modders will work with .ZData files, similar to working with .JSON files.

=== Tools Required ===
Any text editor will work for editing .ZData files. Popular editors include Microsoft Visual Studio Code and Notepad++.

== Chapter 1: Data Modding ==

=== 1.1 Adding New Content ===
To add new content like items, resources, or units, create new .ZData files using existing .ZSchema templates.

'''Example: Adding a New Item (Pet Frog)'''

# Create a folder named '''PetFrogsMod'''.
# In your text editor, create a new .ZData file (e.g., '''PetFrogItems.zdata''').
# Reference the schema:

<syntaxhighlight lang="json"> schema Items; export ItemTemplate itm_petFrog = {
    .Name = "Pet Frog",
    .Description = "A happy, jumping boy that brings everyone joy.",
    .FlavorText = "He jumps, he brings joy",
    .RecipeID = "rcp_AIAssistants",
    .AtlasID = "AIAssistants",
    .uiRarity = RulesTypes.eRarity.Common,
    .uiType = RulesTypes.ItemType.Luxury,
    .uiHarvestType = RulesTypes.HarvestType.NoneOfTheAbove,
    .Flags = (Flags.HasActive | Flags.Resource | Flags.Consumable),
    .ActivateBuffs = {"buf_Item_Happiness_15", "", "", "", "", "", "", ""},
    .uiGiveConsumeItemsForNumTurns = 300u,
    .ActivateBuffsForImprovements = {"buf_Item_Happiness_15", "", "", "", "", "", "", ""}
}; </syntaxhighlight>

=== 1.2 Editing Existing Content ===
To modify existing data, create a new file that references the schema, and update the necessary elements.

'''Example: Updating Resources'''

# Create a new file (e.g., '''PetFrogResources.zdata''').
# Reference the existing schema and modify as needed:

<syntaxhighlight lang="json"> schema NaturalResources; export NaturalResourceTemplate nrc_Dyes = {
    .Name = "TXT_ITM_NATURAL_DYES",
    .Description = "TXT_ITM_DESC_NATURAL_DYES",
    .HarvestOptions = {
        {
            .Item = "itm_Dyes",
            .ProductionRequired = 150u,
            .HarvestCount = 1u
        },
        {
            .Item = "itm_petFrog",
            .ProductionRequired = 10u,
            .HarvestCount = 1u
        }
    }
}; </syntaxhighlight>

=== 1.3 ZData Cheat Sheet ===
An overview of the various schema files and what they control:

* '''Buffs.zschema''' - Defines buffs used by items and improvements.
* '''Governments.zschema''' - Controls government types and their impact on gameplay.
* '''Items.zschema''' - Defines items, from resources to amenities.
* '''Technologies.zschema''' - Defines technologies and research in the game.

== Chapter 2: Setting Up the Mod ==

=== 2.1 GameCoreData Setup ===
To properly load a mod, create a file called '''GameCoreData.zdata''' in your mod folder, and include references to the files in your mod.

<syntaxhighlight lang="json"> schema ZNODataLibrary; export Library Root = {
   .Groups = {
      .ItemTemplates = {
         .FromFiles = { "PetFrogItems.zdata" }
      },
      .NaturalResourceTemplates = {
         .FromFiles = { "NaturalResources0.zdata" }
      }
   }
}; </syntaxhighlight>

=== 2.2 Mod Folder Placement ===
Move the mod folder into the '''Mods''' folder at '''%LOCALAPPDATA%\Ara History Untold'''. If the Mods folder does not exist, create one.

=== 2.3 Updating Settings & Loading the Mod ===
Navigate to the '''Settings''' file under the '''Local App Data''' directory. Enable the mod by updating the following:

<syntaxhighlight> EnabledMods=1 GameCoreMod0Source=PetFrogsMod </syntaxhighlight>

== Chapter 3: Modding Technologies ==
Technologies in ''Ara'' are controlled by a single file, '''Technologies0.zdata'''.

'''Example: Increasing Research Costs'''

# Find the research cost entry for a technology (e.g., Archery) and increase the cost:

<syntaxhighlight lang="json"> export TechnologyTemplate tch_Archery = {
    .Name = "TXT_TCH_ARCHERY",
    .uiResearchCost = 100
}; </syntaxhighlight>

== Conclusion ==
Your mod should now be ready for testing! Place the files as directed, launch the game, and enjoy your custom modifications.