Arcbound Data Modding Spec (EA v1)

This spec covers JSON data modding via ModManager (Add, Override, Patch).

1. Mod Package Model

Folder Layout

Mods/
  <modId>/
    mod.json
    *.json (operation files, any name)
    subfolders/*.json
    Scripts/init.lua (optional, see Lua API doc)

All *.json files under a mod folder are scanned recursively, except mod.json.

Manifest (`mod.json`)

{
  "modId": "author.my-mod",
  "version": "1.0.0",
  "displayName": "My Mod",
  "dependencies": ["core.required.mod"],
  "loadAfter": ["another.mod"]
}

Fields:

modId required and unique.
dependencies hard requirements.
loadAfter soft ordering preference.

Load Order

Base game defs load first.
Enabled mods are dependency-checked.
Missing dependency => mod is disabled with warning.
Remaining mods are topologically sorted (dependencies + loadAfter edges).
Operations apply in sorted order.
Last writer wins for same <defType>/<stableId>.

If dependency cycles exist, a warning is emitted and load order may be reduced.

Runtime Policy

Mods apply at boot/main menu only.
No runtime hot reload during active gameplay.
Toggling mods sets RestartRequired.

2. Operation File Schema

Each operation file is:

{
  "operations": [
    {
      "defType": "resources",
      "action": "Patch",
      "stableId": "alloys",
      "fields": [
        { "field": "displayName", "value": "Alloys+" }
      ]
    }
  ]
}

Operation Fields

defType: target family key (case-insensitive).
action: Add, Override, or Patch (case-insensitive).
stableId: target identity key.
fields: list of field writes.
- field: public field path.
- value: string value converted to target type.

Action Semantics

Add
- Fails (warning) if stableId already exists.
- Creates a new def instance, sets stable id, applies fields.
Override
- Requires target exists.
- Applies provided fields onto existing def.
Patch
- Requires target exists.
- Applies provided fields onto existing def.

Current implementation treats Override and Patch identically (partial field updates).

3. Supported `defType` Families

Use these keys consistently:

buildables
crops
research
recipes
doctrines
events
resources
missions

These map to runtime registries and save validation.

4. Stable ID Contract

Gameplay/save logic must key defs by stableId (or canonical legacy alias fallback during migration), never by Unity asset object name for new content.

Recommended stable id format:

lowercase
a-z0-9._-
immutable once shipped

Example: build.storage.demo_crate.

5. Field Path Rules

Field writes use reflection on public instance fields.

Path syntax

Simple: displayName
Nested object: requirements.minEngineering
Indexed list/array: focusOptions[0]
Nested indexed: variants[0].messageOverride

Invalid path segments produce warnings and are skipped.

List behavior

Writing list[index] auto-expands list with default values up to index.
Negative indices are invalid.

6. Value Conversion Rules

All input values are strings; conversion is type-based.

Supported target types:

string
int
float (invariant culture)
bool (true/false, also 1/0)
enum (case-insensitive parse)
Vector2 as "x,y"
Vector3 as "x,y,z"
Vector2Int as "x,y"
Vector3Int as "x,y,z"
Color as HTML color string (e.g. #FFAA00)
UnityEngine.Object refs:
- null or empty => null
- res:Path/To/Asset or plain Path/To/Asset
- resolved with Resources.Load(path, targetType)

Unsupported type conversion => warning and field not applied.

7. Conflict Diagnostics

Conflicts are tracked by <defType>/<stableId> as:

<defType>/<stableId>: <previousModId> -> <newModId>

This indicates last-writer override order.

8. Error and Warning Model

Non-fatal by design:

malformed operation file
unknown action
missing target for Override/Patch
duplicate Add
invalid path/value conversion

Errors produce warnings; game continues loading.

9. Save/Load Expectations

Save references

Defs should be saved using stable ids, not list indices.

Missing mod set handling

On load, saved enabled mod ids are compared to current enabled mods:

missing mods are tracked and surfaced as warnings/UI prompts.

Provenance

sourceModId tracking is available for mod-applied defs by <defType>/<stableId> lookup.

Missing def fallback

Missing defs should degrade gracefully where possible (warning + placeholder behavior), not hard-crash saves.

10. Authoring Examples

Example A: Add a new buildable

{
  "operations": [
    {
      "defType": "buildables",
      "action": "Add",
      "stableId": "build.storage.demo_crate",
      "fields": [
        { "field": "displayName", "value": "Demo Crate" },
        { "field": "category", "value": "StorageAndLogistics" },
        { "field": "storageStackSlots", "value": "4" }
      ]
    }
  ]
}

Example B: Patch a resource display name

{
  "operations": [
    {
      "defType": "resources",
      "action": "Patch",
      "stableId": "alloys",
      "fields": [
        { "field": "displayName", "value": "Alloys (Refined)" }
      ]
    }
  ]
}

Example C: Patch event variant text

{
  "operations": [
    {
      "defType": "events",
      "action": "Patch",
      "stableId": "phase2_event_derelict_arcship",
      "fields": [
        { "field": "variants[0].messageOverride", "value": "The derelict emits a faint civil distress loop." }
      ]
    }
  ]
}

11. Best Practices

Keep stableId immutable after public release.
Prefer Patch for compatibility.
Use loadAfter only when needed; prefer explicit dependencies for hard requirements.
Validate mods after edits and check warnings list in mod manager.
For asset refs, prefer Resources paths that exist in both Editor and builds.
Use starter files under Docs/examples/mods/example.mod/ as copy/paste templates.

See also: Docs/modding_lua_api.md for scripting hooks and runtime API.

12. Per-SO Mod Schema (Exact Field Catalog)

This section is the exact modding field surface for supported defType families.

Conventions:

fields[].field can target any public instance field listed below.
Enum fields accept enum-name strings (case-insensitive).
UnityEngine.Object references use res:Path/Inside/Resources.

12.1 `buildables` (`BuildItemSO`)

Identity/UI:

stableId
displayName
icon
category (BuildCategory)
requiredResearchId
phase2Only

Placement/shape:

placementKind (BuildPlacementKind: Tile, Object, Tool)
requiresFloorSupport
taskType (TaskType)
rotatable
rotations (Rotations4SO)
size (Vector2Int)
pivot (Vector2Int)

Tile/object visuals:

placeCellType (CellType)
tile (TileBase)
placeObjectType (ObjectType)
objectTile (TileBase)
wallVisuals (WallVisualSetSO)
doorVisuals (DoorVisualSetSO)
airTightDoor
blocksWalkability
isVerticalConnector
verticalConnectorStep
toggledOffObjectTile (TileBase)
emitsLight
lightRadius
lightOnObjectTile (TileBase)
lightRequiresPower
isOxygenVent
isFireSuppressor
fireSuppressionRadius

Costs/work/stats:

costAlloys
costElectronics
costSubstrate
costFuel
buildWorkSeconds
deconstructWorkSeconds
requiredConstructionSkill
powerDelta
tag

Durability/maintenance/comfort:

maxDurability
armorPct
requiresMaintenance
maintenanceDurabilityLossPerDay
taskMustWorkOnCell
providesMaintenanceAnchor
maintenanceAnchorRadius
maintenanceWorkSpeedBonusPct
maintenanceResourceEfficiencyPct
roomMoralePerDay

Utility topology:

isUtility
utilityType (UtilityType)
isConduit
isDevice
isPowerSwitch
capacity
throughput
conduitVisuals (ConduitVisualSetSO)
waterPorts (DirMask4)
wastePorts (DirMask4)
powerPorts (DirMask4)

Per-day utility IO:

powerUsePerDay
allowUnpoweredOperation
unpoweredOperationWorkSpeedMultiplier
powerGenPerDay
waterUsePerDay
waterGenPerDay
wasteGenPerDay
wasteUsePerDay
oxygenUsePerDay
oxygenGenPerDay

Per-use utility IO:

usePerUseUtilityIo
powerUsePerUse
waterUsePerUse
wasteGenPerUse

Storage/crafting:

storageStackSlots
craftRecipeIds (List<string>)

Civilian systems:

isCivilianHabitat
civilianHabitatCapacity
civilianComfortContribution
isCivilianSupplyIntake
civilianSupplyFoodCapacity
civilianSanitationContribution
civilianCommonsContribution
civilianComfortAuraRadius
civilianFoodEfficiencyBonusPct
civilianSecurityContribution
civilianSecuritySuppressionBonusPct
civilianEnablesLockdown

Civilian security supplies:

isCivilianSecurityCheckpoint
securityBatonCapacity
riotShieldCapacity
stunSidearmCapacity
securityEnergyCellCapacity
securityBatonCoveragePerUnit
securityBatonSuppressionPerUnit
securityBatonUnrestDecayPerUnit
riotShieldCoveragePerUnit
riotShieldSuppressionPerUnit
riotShieldUnrestDecayPerUnit
poweredStunSidearmCoveragePerUnit
poweredStunSidearmSuppressionPerUnit
poweredStunSidearmUnrestDecayPerUnit

Civilian recovery/production:

civilianHealthLossReductionPct
civilianCrisisMortalityReductionPct
crewInjuryRecoveryBoostPct
civilianCrewCandidateQualityBonusPct
civilianFabricationAlloysPerDay
civilianFabricationElectronicsPerDay
civilianFabricationSubstratePerDay
civilianHydroYieldBonusPct
civilianResearchPointsPerDay

Fuel/resource IO:

fuelUsePerDay
resourceCapacity
fuelCapacity
alloysUsePerDay
electronicsUsePerDay
substrateUsePerDay
alloysGenPerDay
electronicsGenPerDay
substrateGenPerDay
fuelGenPerDay

12.2 `crops` (`CropDefSO`)

Identity/visuals:

stableId
cropId
displayName
icon
plantedSprite

Growth/harvest:

stages (StageDef[])
- stages[i].stage (GrowthStage)
- stages[i].durationDays
- stages[i].o2PerTick
- stages[i].maintenanceIntervalDays
- stages[i].yieldAmount
harvestMode (HarvestMode: None, AutoAtBestStage, ManualAnytime)
bestHarvestStage (GrowthStage)
harvestEndsPlant
yieldType (ResourceType)
baseYieldAmount

12.3 `research` (`ResearchDefSO`)

Identity/core:

stableId
id
displayName
description
category (ResearchCategory: Engineering, Society, Archives, Signal)
phase2Only
tier
costPoints
icon
prerequisiteIds (List<string>)

Requirements:

requirements.requiredBuildings (List<ResearchBuildingRequirement>)
- requirements.requiredBuildings[i].buildItemId
- requirements.requiredBuildings[i].objectType (ObjectType)
- requirements.requiredBuildings[i].count
requirements.minEngineering
requirements.minSocial
requirements.requiresPoweredDesk
requirements.minCivilianPopulation
requirements.minContinuumInstability
requirements.requiredArchiveFragments
requirements.requiredSignalFragments
requirements.consumeRequiredFragmentsOnStart
requirements.requiresWaterNetwork
requirements.requiredZoneType (ZoneType)
requirements.minRequiredZoneCells

Effects:

effects.unlockBuildItemIds (List<string>)
effects.researchSpeedBonusPct
effects.hydroYieldBonusPct
effects.batteryCapacityBonusPct
effects.maintenanceFrequencyReductionPct
effects.waterRecyclingEfficiencyBonusPct
effects.missionConsequenceSeverityReductionPct
effects.reactorFuelUseReductionPct
effects.engineFuelUseReductionPct
effects.collapsePressureDeltaReductionFlat
effects.collapseEventFrequencyReductionPct
effects.civilianFoodEfficiencyBonusPct
effects.civilianDeliveryWasteReductionPct
effects.civilianHygieneDecayReductionPct
effects.civilianUnrestGrowthReductionPct
effects.civilianComfortFlatBonus
effects.civilianSecuritySuppressionBonusPct
effects.civilianDoctrineStabilityBonusPct
effects.civilianUnrestSpikeReductionPct
effects.enablesCivilianPromotion
effects.highMoraleCiGrowthReductionPct
effects.unlocksAnomalySocietyEvents
effects.roomBonusMultiplierPct
effects.stablePopulationShipStrainReductionPerDay
effects.recipeOutputBonuses (List<RecipeOutputBonus>)
- effects.recipeOutputBonuses[i].recipeId
- effects.recipeOutputBonuses[i].bonusPct
effects.mealQualityMoraleBonusPerDay
effects.hygieneNegativeStatusDurationReductionPct
effects.missionFoodConsumptionReductionPct
effects.unlocksMissionEventChains
effects.enablesEssenceMissionRewards
effects.relationshipGrowthRateBonusPct
effects.psychologicalBreakChanceReductionPct
effects.moraleRecoveryBonusPct
effects.doctrineAlignmentDecayReductionPct
effects.culturalInstabilityGrowthReductionPct
effects.civilianResearchPointsPerDay
effects.promotionStartingSkillBonusPct
effects.promotionStartingDoctrineAlignmentBonusPct
effects.crisisRecoverySpeedBonusPct
effects.doctrineStrengthBonusPct
effects.relationshipDamageReductionPct
effects.culturalTransitionDurationReductionPct
effects.stableShipMoralePerDay
effects.stressAccumulationReductionPct
effects.unlocksArchiveEvents
effects.unlocksPeacefulResolutionEvents
effects.crewDeathMoralePenaltyReductionPct
effects.unlocksTransitSignalMissions
effects.improvesMissionRewardPreviews
effects.signalEventFrequencyBonusPct
effects.enablesHiddenMissionOffers
effects.anomalyBadOutcomeReductionPct
effects.archiveResearchSpeedBonusPct
effects.signalResearchSpeedBonusPct
effects.unlocksDerelictArcshipEncounters
effects.continuumInstabilityGrowthReductionPct
effects.unlocksHighRiskSignalMissions
effects.anomalyPositiveOutcomeBonusPct
effects.shipStrainGrowthReductionPct
effects.majorDisasterFrequencyReductionPct
effects.unlocksLateGameContactEvents

12.4 `recipes` (`CraftRecipeSO`)

Identity/unlock:

stableId
id
displayName
description
requiredResearchId
requiredBenchTag

Crafting:

workSeconds
primarySkill (SkillType)
baseFailChance
inputs (List<ResourceAmount>)
- inputs[i].type (ResourceType)
- inputs[i].amount
outputs (List<ResourceAmount>)
- outputs[i].type (ResourceType)
- outputs[i].amount
powerUsePerCraft
waterUsePerCraft
wasteGenPerCraft

12.5 `doctrines` (`DoctrineDefinitionSO`)

Identity/copy:

stableId
doctrineId
displayName
shortDescription
cardIcon
bonusesSummary
weaknessSummary

Modifiers:

moraleRecoveryMultiplier
relationshipGainMultiplier
relationshipLossMultiplier
breakDurationMultiplier
breakRiskMultiplier
comfortMoraleMultiplier
missionRewardMultiplier
missionConsequenceSeverityMultiplier
collapsePressureMultiplier
engineeringXpMultiplier
hydroEfficiencyMultiplier
waterEfficiencyMultiplier
constructionSpeedMultiplier
maintenanceSpeedMultiplier
researchSpeedMultiplier
archiveDiscoveryMultiplier
breakdownChanceMultiplier
instabilitySensitivityMultiplier
startingMoraleOffset
personnelExtractionSeverityMultiplier
crewDeathMoraleLossMultiplier
foodSecurityExpectationMultiplier
missionTurnaroundMultiplier
fuelRaidRewardMultiplier
fuelRaidCollapsePressureMultiplier
socialRecoveryBonusMultiplier
conflictMoraleCollapseMultiplier

12.6 `events` (`Phase2TransitEventDefinitionSO`)

Identity/director:

stableId
eventId
displayName
defaultMessage
category (Phase2EventCategory: ShipSystem, Social, CivilianSociety, TransitExternal, ContinuumAnomaly)
baseWeight
cooldownDays
minDay
maxDay
minPressure01
maxPressure01
minEventBudget01
maxEventBudget01
earlyTransitWeight
midTransitWeight
lateTransitWeight
preferLeastRecentlySeen

Conditions/execution:

requiresCivilianPopulation
requiresUnrest
requiresContinuumResearchUnlock
minCivilianUnrest
maxCivilianUnrest
minShipStrain
maxShipStrain
minContinuumInstability
maxContinuumInstability
minFoodDays
minWaterDays
requiredContextTags (List<string>)
blockedContextTags (List<string>)
actionType (Phase2EventActionType: LegacyOperationalIncident, LegacyCivilianUnrest, LegacyCivilianIdeology, LegacyContinuumIncident, NarrativeAlert)
triggerChance
severityMin01
severityMax01
consumeCategoryBudget

Variants/chains:

variants (List<Phase2TransitEventVariant>)
- variants[i].variantId
- variants[i].weightMultiplier
- variants[i].messageOverride
- variants[i].requiredContextTags
- variants[i].blockedContextTags
- variants[i].followupEventIds
followupMinDelayDays
followupMaxDelayDays

12.7 `resources` (`ResourceDefSO`)

stableId
id
displayName
icon
resourceType (ResourceType)
stackable
stackLimit
tint (Color)

12.8 `missions` (`MissionSiteDefinition`)