How the ReligionManager Handles Religious Beliefs in Unciv

The ReligionManager class in Unciv governs the entire lifecycle of religious beliefs, from tracking faith accumulation and pantheon creation to founding full religions and enhancing them through Great Prophet actions.

The ReligionManager serves as the central authority for religious mechanics in the open-source Civilization V clone, managing how civilizations accumulate faith, select beliefs, and progress through distinct religious states. Located in core/src/com/unciv/logic/civilization/managers/ReligionManager.kt, this class coordinates interactions between the player's faith economy, the belief selection UI, and the global religion registry. Understanding how the ReligionManager handles religious beliefs is essential for modding the game or implementing custom religious mechanics.

Core Responsibilities of the ReligionManager

The ReligionManager maintains the religious state for each civilization through several key fields and methods that handle belief economics and selection.

Tracking Faith and Religion State

The manager tracks religious progression through transient references and accumulated resources. The var religion: Religion? property holds a transient reference to the civilization's current major religion (or pantheon), which restores from the global GameInfo.religions map when the game loads. Faith generation accumulates in storedFaith, which the manager spends to found pantheons, create religions, and generate Great Prophets.

Managing Free Belief Slots

Before the player can select beliefs, the manager calculates available slots using a Counter<String> named freeBeliefs. This counter records how many free belief slots of each BeliefType the civilization can choose for the current turn. The helper function freeBeliefsAsEnums() converts this string-based counter into a Counter<BeliefType> for type-safe processing within the Kotlin codebase.

How Belief Selection Works

The ReligionManager determines valid belief choices through a private calculation method and exposes specific entry points for founding and enhancing actions.

Calculating Available Belief Slots

The private method getBeliefsToChooseAtProphetUse(enhancingReligion: Boolean) builds a Counter<BeliefType> that reflects available options by combining:

• The number of belief types remaining in the ruleset (numberOfBeliefsAvailable)
• Extra slots granted by civilization-specific uniques (FreeExtraBeliefs, FreeExtraAnyBeliefs)
• Existing free belief slots from freeBeliefsAsEnums()

This internal logic exposes through getBeliefsToChooseAtFounding() and getBeliefsToChooseAtEnhancing(), which the UI calls to populate belief picker screens.

The chooseBeliefs Method

When the player finalizes their selection, the UI invokes chooseBeliefs(beliefs: List<Belief>, useFreeBeliefs: Boolean = false). This method:

1. Clears the freeBeliefs counter
2. Creates a pantheon if the civilization remains at ReligionState.None
3. Adds selected beliefs to the current Religion object
4. Updates religionState (progressing from Pantheon → Religion → EnhancedReligion)
5. Fires triggered uniques such as TriggerUponFoundingReligion

Founding and Enhancing Religions

State transitions follow strict validation rules to ensure religious progression occurs only under valid game conditions.

Pre-conditions for Founding

The manager guards religious founding through mayFoundReligionAtAll() and mayFoundReligionHere(tile). These methods verify that religion is enabled game-wide, the civilization is a major civ, sufficient belief slots remain globally, and the prophet stands on valid terrain. Only after these checks pass can foundReligion(prophet) execute, marking the state as FoundingReligion and storing the holy city location.

State Transitions: Pantheon to Enhanced Religion

Religious progression follows a strict enum sequence defined in ReligionState. When enhancing an existing religion, useProphetForEnhancingReligion(prophet) sets the state to EnhancingReligion and notifies other civilizations through diplomatic channels. After the player selects enhancement beliefs via chooseBeliefs, the state advances to EnhancedReligion, unlocking additional belief effects.

Spreading Religion and City Management

Beyond belief selection, the manager provides validation helpers for religious units and queries city-level religious statistics.

Validation Helpers for Religious Units

The ReligionManager contains maySpreadReligionAtAll(missionary) and maySpreadReligionNow(missionary) methods that verify:

• City ownership status
• The missionary's assigned religion
• Presence of protective Inquisitors blocking conversion

These checks prevent invalid spread actions and ensure religious combat follows game rules.

Holy City and Majority Calculations

Helper methods query the global city list to provide statistics for UI screens and diplomatic modifiers. getHolyCity() returns the founding city, getMajorityReligion() identifies the dominant faith across the empire, and numberOfCitiesFollowingThisReligion() calculates religious influence for victory conditions and AI decision-making.

Code Examples: Working with ReligionManager

The following Kotlin patterns demonstrate how to interact with the ReligionManager for common religious operations:

// Check whether a civilization can found a religion
if (civ.religionManager.mayFoundReligionAtAll()) {
    // Retrieve available belief slots for founding
    val beliefChoices = civ.religionManager.getBeliefsToChooseAtFounding()
    // Present beliefChoices to the player via UI...
}

// Process player-selected beliefs from a picker screen
val selectedBeliefs: List<Belief> = // obtained from ReligiousBeliefsPickerScreen
civ.religionManager.chooseBeliefs(selectedBeliefs, useFreeBeliefs = true)

// Enhance an existing religion with a Great Prophet
if (civ.religionManager.mayEnhanceReligionAtAll()) {
    val enhanceChoices = civ.religionManager.getBeliefsToChooseAtEnhancing()
    // UI displays enhanceChoices
    civ.religionManager.chooseBeliefs(chosenEnhancementBeliefs)
}

Summary

• The ReligionManager in ReligionManager.kt controls belief selection, faith economics, and religious state transitions for each civilization.
• Free belief slots tracked via freeBeliefs and freeBeliefsAsEnums() determine what beliefs players can choose when founding or enhancing religions.
• State transitions progress from None → Pantheon → Religion → EnhancedReligion through guarded methods like foundReligion() and useProphetForEnhancingReligion().
• Validation methods such as mayFoundReligionAtAll() and maySpreadReligionNow() ensure religious actions comply with game rules and diplomatic boundaries.
• City-level queries including getHolyCity() and getMajorityReligion() integrate the manager with the global city system for UI and AI calculations.

Frequently Asked Questions

How does the ReligionManager track which beliefs a civilization can select?

The manager calculates available beliefs through getBeliefsToChooseAtProphetUse(), which combines ruleset-defined belief counts, civilization-specific uniques granting extra slots, and the freeBeliefs counter. This method exposes through getBeliefsToChooseAtFounding() and getBeliefsToChooseAtEnhancing() to provide the UI with valid belief options based on the current game state and BeliefType availability.

What happens to free belief slots after the player chooses beliefs?

When chooseBeliefs() executes with useFreeBeliefs = true, the method immediately clears the freeBeliefs counter after applying the selected beliefs to the religion. This prevents duplicate selection and ensures extra slots from uniques or game effects consume properly during the founding or enhancement process.

How does the ReligionManager validate Great Prophet actions?

The manager implements specific validation gates: mayFoundReligionAtAll() checks global religion slots and civilization eligibility, while mayFoundReligionHere(tile) validates the prophet's tile location. For enhancements, useProphetForEnhancingReligion() verifies the civilization has an existing religion not yet enhanced, then transitions the religionState to EnhancingReligion pending belief selection.

Where does the ReligionManager interact with the game's UI?

The primary UI integration occurs in ReligiousBeliefsPickerScreen.kt, which calls getBeliefsToChooseAtFounding() and getBeliefsToChooseAtEnhancing() to populate belief selection interfaces. Unit actions in UnitActionsReligion.kt invoke the manager's validation methods before executing religious spreads, while NextTurnAction.kt triggers religion founding prompts when conditions are met.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}