Latest revision as of 00:49, 18 February 2025

Ara Modding Setup Guide[edit | edit source]

This document will show you how to get started with modding and playing with mods in Ara: History Untold.

As of the 1.2 Modder's Paradise update, you can enable mods easily in the main menu -- simply navigate to Mods and click either the button labeled "Enabled Modding" or click the checkbox in the corner of the main modding window. Within this menu, you can also use the Mod Browse and access the mods hosted on the official mod.io repository. You can also download these mods as reference for your own modding ideas!

To get started with modding, you'll want to get the Example Mod -- in the "Installed" tab of the modding window, there should be a button labeled "Setup Example Mod". This will copy a folder full of base game files and give a lot of helpful reference material for the syntax and structure of mod files. It should copy over to your Mods folder, which is located at Documents\My Games\Ara History Untold\Mods\.

The Example Mod (or DefaultMod as it appears in the Mods directory) is a copy of one of the game's source folders, located at assets\SourceMods\ from the game's installation folder. These SourceMods files update with each game update, so you may want to delete the Example Mod as the game updates.

Modding Basics[edit | edit source]

Every mod requires a file named GameCoreData.zdata. The file tells Ara which files it should import into the game, and what part of the game should be updated or added to. For example, from a published developer mod:

schema ZNODataLibrary;

export Library Root =
{
    .Groups =
    {
        
        .Technologies =
        {
            .FromFiles = { "files/Tech_Axe.zdata" },
        },

        .Improvements = 
        {
            .FromFiles = { "files/Improvement_Axe.zdata" },
        }, 
        
    }
};

When you're at a loss as to how you should import your files, you should refer to the Example Mod's own GameCoreData.zdata file. For art assets, documentation is lacking, but it starts with an AssetData.zdata file, not named within GameCoreData.zdata. Here is an example snippet from the same developer mod:

schema ModAssets;

export AssetList Root =
{
    .IconAtlases =
    {
    
        .Items_160 = 
        {
            .Textures =
            {
                ."item_axe" = "files/item_axe.png",
                ."item_axeman" ="files/project_Axeman.png",
            },
        },

          .Improvements_256 = 
        {
            .Textures =
            {
                ."AxeImp" = "files/WoodCutter.png",
            },
        },
        
    },
};

The left side of the Textures data (e.g. item_axe, AxeImp) seems to be used for the AtlasID attribute on improvements, items, etc. It's worth noting that the Atlas group Improvements_256 does not add the yellow icon border -- you will have to add the border yourself if you wish to copy the style of the game's icon assets. A copy of the Axe Man mod is recommended for study to add art assets, at least until more official documentation is provided.

If you work within the modding folder of the game, be sure that the GameCoreData.zdata file is available inside your mod folder at the same level viewed when opening the folder. To test your mod changes, make sure the mod is 'checked' and active, and either click New Game or click the "Reload mod configuration" button in the modding window to reload your changes.

At the moment, a new game is required for all mod testing and changes made to the mod.

Attributes & Modifiers[edit | edit source]

Buffs have the "Attributes" attribute in their definition that defines a condition for the buff to apply, for example:

.Attributes = @"ATTR(AtrCityStatCheck(ReligionImprovementCount, '>=', 1.0))ATTR"

The above code would allow the buff to trigger (based on the TargetType and Scope values) only when the City has at least one Religion Improvement. For multiple conditions, see this example from one of the Republic Government Policies:

.Attributes = @"ATTR(AtrImprovementDomainCheck(Culture) or AtrImprovementDomainCheck(Government) or AtrImprovementDomainCheck(Science))ATTR"

This buff checks for improvements of Culture, Government, or Science domains. This particular buff (at time of writing) has a TargetType of BuffTargetType.Improvement and a Scope of BuffScope.All, targeting all Improvements you have or are building. For the actual effect, we look at the Modifiers attribute. For example:

.Modifiers = @"MODS(ModMul(Strength, 0.25))MODS"

This modifier will add a 25% multiplier to unit strength. Multipliers are additive, so this is adding 25% to the total bonus multiplier, not directly multiplying by 25%, which would be a reduction in strength instead. Negative values are allowed where you'd expect them. (You probably can't reduce the turn count...)

An aside: This syntax is also similar to that used for the Condition attribute on events, e.g. .Condition = "AtrActGoalWonCheck(goal_SpecificTriumphLibraryofCelsus)".

The table below lists all currently possible variables for use in conditions or modifiers, provided by one of the developers, with Description and Notes for wiki users to add:


Name	Description	Notes
Invalid
Act		Spotted in Adviser Wisdom like so: AtrNationStatCheck(Act, '<', 2.0)
Era		Spotted in NarrativeEvents like so: AtrNationStatCheck(Era, '=', 5.0)
Population	Growth
PopulationTier		Spotted in Buffs0 like so: AtrCityStatCheck(PopulationTier, '<=', 4.0)
PopulationTierCap	Housing
BonusPrestigeOnComplete		e.g. Museum
PrestigeOnKill
TotalIncomingMoney
Item
Happiness
Education
Health
Prosperity
Wealth
Aesthetics	Security
MinHappiness
MinEducation
MinHealth
MinProsperity
MinWealth
MinAesthetics	Security
ParagonSpawnChance
ArtistPickChance
EngineerPickChance
StrategistPickChance
BusinessmanPickChance		Entrepeneur?
MusicianPickChance
ProphetPickChance
ActivistPickChance
ScientistPickChance
WriterPickChance
ExplorerPickChance
BuildRate
HarvestRate
CraftRate
MasterpieceCreateRate
Production
Maintenance
TaxIncome
IncomeRate
GoldenAgeProgress
GoldenAgeDuration
GoldenAgeBonusPrestigeRate
RegionCount
CityCount
ReligionFollowerCount
ReligionSpreadStrength
ReligionSpreadDistance
ForeignReligionInfluence
ResearchAgreementResearch
ResearchCost
PopulationTierResearch
TotalIncomingResearch
MerchantCount
TradeAgreementCount
AllianceCount
ParagonCount
IsFortified		Condition is checked as = 1.0
TradeMoney
Relationship
BaseRelationship
TribeRelationship
BaseTribeRelationship
BaseTribeNotHostileFlag		Add +1.0 to make tribes non hostile
ArmyCapLand
ArmyCapAir
ArmyCapSea
CityCap
BonusExpOnTrained
BonusExpOnCombat
LevelUpStrength
Level
FormationBonus
Strength
TerrainStrengthMod	Modifier to Strength based on terrain
SiegeDamage	Damage to Cities
PillageDamage	Damage to improvements
Defense
Speed	Movement points
HomeCity
WorkerGain
BonusWorkersOnFoundCity
CannotCounterFlag
MaintenanceFlag
SightRange
ActionRange
WarWeariness
InflictWarWeariness
InflictWarWearinessOnKill
RecoverWarWearinessOnKill
BonusExpOnKill
PreventPillageFlag
BirthRate
DeathRate
ImmigrationRate
EmmigrationRate
HealRate
StartBonusHealth
SiegeDefense
FoodFertility
WoodFertility
StoneFertility
CoinFertility
Pollution
WarDeclarePrestigeCost
EventsGiven
ExtraLocalFood
IsOpenTerrainFlag
IsRoughTerrainFlag
RoadType
MilitaryImprovementCount
CommerceImprovementCount
GovernmentImprovementCount
ReligionImprovementCount
CultureImprovementCount
ScienceImprovementCount
IndustryImprovementCount
DistinctMilitaryImprovementCount
DistinctCommerceImprovementCount
DistinctGovernmentImprovementCount
DistinctReligionImprovementCount
DistinctCultureImprovementCount
DistinctScienceImprovementCount
DistinctIndustryImprovementCount
ArtistParagonCount
EngineerParagonCount
StrategistParagonCount
BusinessmanParagonCount
MusicianParagonCount
ProphetParagonCount
ActivistParagonCount
ScientistParagonCount
WriterParagonCount
ExplorerParagonCount
CityCountDiff
TurnsSinceLastParagonCompletedEvent
TurnsSinceLastMasterpieceCompletedEvent
TurnsSinceWarEvent
TurnsSinceSkirmishWarEvent
TurnsSinceRetaliationWarEvent
TurnsSinceDefenderWarEvent
TurnsSinceAttackerWarEvent
TurnsSinceLastWarVictoryEvent
TurnsSinceLastWarEndedEvent
TurnsSinceLastCombatEvent
TurnsSinceEnteredAllianceEvent
TurnsSinceEnteredResearchAgreementEvent
TurnsSinceTechnologyUnlockedEvent
InWarFlag
InAttackerWarFlag
InDefenderWarFlag
InRetaliationWarFlag
InSkirmishFlag
InWarWithAnyoneFlag
RegionDistanceToFriendlyArmy
CoastalRegionCount
GoldenAgeRemainingTurns
PositiveModifiers
NegativeModifiers
IsCapitalFlag
IsCityCenterFlag
IsOwnedFlag
TriumphFlag
AdjacentToImpassibleFlag
AdjacentToRiverFlag
CoastalLandFlag
HasRiverFlag
ReligionDominantFlag
ReligionFoundedFlag
CurrentTurn
PrestigeTier
UnlockedGovernmentCount
UnassignedExpertCount
OpenExpertSlotCount
UnassignedParagonCount
OpenParagonSlotCount
IsAtPopulationTierCapFlag
IsGrowthStagnantFlag
IsStarvingFlag
HasOpenBordersFlag
HasTradeAgreementFlag
HasResearchAgreementFlag
HasAllianceFlag
WarlikeScore
PeacefulScore
IsAtMaxCityCapFlag
IsCityCenterDefendedFlag
UnitsInReserveCount
LandArmyCount
SeaArmyCount
AirArmyCount
HasMetFlag
UnassignedMerchantCount
MilitaryStrength
MilitaryRatio
UnslottedMasterpieceCount
ReligionFollowersConvertedThisTurnCount
PercentForcesHealth
IdleCraftersCount
AvailableFlag

Guides[edit | edit source]

Modding for fun and profit
Modding Ara: History Untold by Brad Wardell