# How the ReligionManager Handles Religious Beliefs in Unciv

> Explore how Uncivs ReligionManager class manages religious beliefs, from tracking faith accumulation and pantheon creation to founding religions and enhancing them with Great Prophets.

- Repository: [Yair Morgenstern/Unciv](https://github.com/yairm210/Unciv)
- Tags: internals
- Published: 2026-06-18

---

**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`](https://github.com/yairm210/Unciv/blob/main/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:

```kotlin
// 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`](https://github.com/yairm210/Unciv/blob/main/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`](https://github.com/yairm210/Unciv/blob/main/ReligiousBeliefsPickerScreen.kt), which calls `getBeliefsToChooseAtFounding()` and `getBeliefsToChooseAtEnhancing()` to populate belief selection interfaces. Unit actions in [`UnitActionsReligion.kt`](https://github.com/yairm210/Unciv/blob/main/UnitActionsReligion.kt) invoke the manager's validation methods before executing religious spreads, while [`NextTurnAction.kt`](https://github.com/yairm210/Unciv/blob/main/NextTurnAction.kt) triggers religion founding prompts when conditions are met.