# Soul Cage Tiers

When a mob is killed in spirit and gone into a soul crystal, it is not functional in a soul cage until it has met the minimum requirements for one of the soul cage tiers that are specified. This page will show you how to define new types.

## Tier definition

Every soul cage tier must be defined in json in the **recipes** folder. **All** fields in the json (except for redstoneControlled, ignoreSpawnConditions, and the entity blacklist) are **required.** 

(the type field is the type for the recipe, do not change that)

```
{
    "type": "spirit:soul_cage_tier",
    "displayName": "spirit.soul_cage.tier_1",
    "requiredSouls": 64,
    "minSpawnDelay": 300,
    "maxSpawnDelay": 1000,
    "spawnCount": 3,
    "spawnRange": 5,
    "nearbyRange": 16,
    "redstoneControlled": false,
    "ignoreSpawnConditions": false,
    "blacklist": [
        "minecraft:iron_golem"
    ]
}
```

* `"displayName": string`

  Specifies the display name for the tier. This string is translatable.
* `"requiredSouls": string`\
  Specifies how many souls are required to achieve this tier. All tiers are ordered by this value
* `"minSpawnDelay": integer`\
  Specifies the minimum random delay before a mob can spawn
* `"maxSpawnDelay": integer`\
  Specifies the maximum random delay a mob should spawn before
* `"spawnCount": integer`\
  Specifies how many mobs spawn per spawn cycle
* `"spawnRange": integer`\
  Specifies how far away mobs can spawn from the soul cage
* `"nearbyRange": integer`\
  Specifies what the maximum distance a player can be from the spawner before it stops working. This value can be set to -1 to not require a player nearby
* `"redstoneControlled": boolean`\
  Specifies whether or not the soul cage can be disabled/enabled with redstone at this tier
* `"ignoreSpawnConditions": boolean`\
  Specifies whether or not spawn conditions are checked when a mob tries to spawn
* `"blacklist": list of strings`\
  Specifies which mobs are not usable in the soul cage at this tier of the soul cage


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://codexadrian.gitbook.io/spirit/developer/soul-cage-tiers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.