MCA Village Ranks replaces MCA's standard rank progression with an ordered list of stages. It is designed to encourage you to grow your village from a small settlement to a huge city.

For server owners, datapack creators and modpack builders, this mod gives you the ability to create new and replace existing stages using datapacks/config. A progression can contain as many stages as desired, rather than being limited to MCA's six built-in rank values.

Each custom stage has its own MCA rank mapping and list of tasks. Tasks use MCA's existing task definitions and completion checks, which maintains maximum compatibility with the base mod and addons.

Configuration

This mod can be played without any configuration needed, however it also has the capability for you to modify village ranks.

To disable the default ranks shipped by this mod, search for the configuration file in "config/mca_rank_customiser.json" and change "enableDefaultRanks" to false.

This will not disable external datapacks, only the default village ranks created by this mod.

Custom Datapacks

External rank definitions are read from the mca_custom_ranks data directory. You must put your rank definitions in a JSON file here in your datapack. The datapack can use any namespace. For example:

my_village_progression/
├── pack.mcmeta
└── data/
    └── example/
        └── mca_custom_ranks/
            ├── settlement.json
            ├── hamlet.json
            ├── village.json
            └── town.json

Rank JSON Format

A rank definition contains these fields:

Example, settlement.json:

{
  "order": 0,
  "mca_rank": "PEASANT",
  "tasks": [
    {
      "type": "population",
      "population": 5
    },
    {
      "type": "building",
      "building": "house"
    }
  ]
}

Task JSON is defined by MCA. Objects inside tasks must follow the JSON format expected by the task type registered by MCA, you can find the most up to date information on this in the MCA source code for the version you are using.

Task Types

Population: A population task is completed when the village population reaches or exceeds the configured threshold.

{
  "type": "population",
  "population": 10
}

Building: A building task is completed when the village has the named building. Example:

{
  "type": "building",
  "building": "inn"
}

Reputation: A reputation task is completed when the player reaches or exceeds the configured threshold. Example:

{
  "type": "reputation",
  "reputation": 400
}

Advancement: An advancement task is completed when the player unlocks the configured advancement. Example:

{
  "type": "advancement",
  "id": "mca:adventure/kill_grim_reaper"
}

Translation

MCA uses translation keys. This mod follows the same practice.

Custom rank names use translation keys in this format:

rank.<namespace>.<path>

Important Datapack Rules

• Order: Use increasing order values to define the intended progression. Lower values are earlier stages.
• Non-negative values: Negative order values are invalid.
• MCA mapping: The mca_rank string must identify an MCA enum value, ignoring letter case. Valid values are OUTLAW, PEASANT, MERCHANT, NOBLE, MAYOR, and MONARCH.
• Empty task lists: A rank with no tasks may load, but the loader reports a warning. Since there are no required tasks to block completion, such a stage can be immediately complete.
• Duplicate order values: The loader reports duplicate order values. Give each stage a distinct order to make the progression easier to understand and maintain.
• Mapping regressions: A stage that maps to an MCA rank lower than the previously accepted stage is skipped by progression validation. Keep MCA mappings level or increasing as the custom progression advances.
• Invalid entries: Invalid rank files are logged and skipped rather than preventing all valid rank files from loading. Check the server log after startup or datapack reload if a rank does not appear.
• Validation: This mod has built in validation. If something is not working, look through your latest.log file.

Something is broken!

A rank does not appear
Confirm the file is under data/<namespace>/mca_custom_ranks/.
Confirm the file has a .json extension and valid JSON syntax.
Check that order is a non-negative integer.
Check that mca_rank is one of the six supported MCA enum values.
Check the log for a decode error, duplicate task ID, or progression validation warning.
Ensure the datapack is enabled and has been loaded by the world.

The bundled progression is missing
Check config/mca_rank_customiser.json and make sure enableDefaultRanks is set to true. External datapack ranks can still load when this option is false.

The blueprint still shows the normal MCA progression
The custom blueprint integration is only used when at least one valid custom rank is loaded. Run /mca-admin villageRanks to verify that the server has loaded the intended stages.

A custom rank name appears as a translation key
Add the appropriate rank.<namespace>.<path> entry to your language resource file, using the rank's namespace and path.

A stage is completed immediately
Review its task list. An empty task list has no required conditions to satisfy. Also verify that the task definitions use the intended thresholds and identifiers.