Defining Entity Overrides

Catharsis allows you to override entity models and textures using Bedrock entity geometry (.geo.json) and specific targeting conditions.

Example of an entity definition and its corresponding model and texture mapping.

{your_namespace}:catharsis/entity_definitions/{entity_name}.json

{
    "target": {
        "type": "..."
    },
    "type": "minecraft:..."
}

{your_namespace}:catharsis/entities/{entity_name}.json (Single Variant)

{
    "texture": "{your_namespace}:textures/{texture_path}.png",
    "model": "{your_namespace}:models/{model_path}.geo.json"
}

{your_namespace}:catharsis/entities/{entity_name}.json (Weighted Randomization)

{
    "variants": [
        {
          "weight": 5,
          "texture": "{your_namespace}:textures/mob1.png",
          "model": "{your_namespace}:models/mob.geo.json"
        },
        {
          "weight": 1,
          "texture": "{your_namespace}:textures/mob2.png",
          "model": "{your_namespace}:models/mob.geo.json"
        }
    ]
}

Entity Definition Explanation

To override an entity, you need to provide two JSON files. The first handles the targeting and conditions, while the second links the actual model and texture assets.

An Entity Definition object (`catharsis/entity_definitions/{entity_name}.json`)

• target: The condition logic required to match the entity.
  • type: The condition type (e.g., identity, is_baby, all, etc.).
  • (Additional keys depend on the condition type used. See Condition Types below.)
• type: The vanilla entity registry name to target (e.g., minecraft:zombie).

An Entity Asset Mapping object (`catharsis/entities/{entity_name}.json`)

• Either a list of variants or a single variant can be provided.
  • variants: A list of variations to apply to the entity to support randomizing models and textures. Selecting is based on the entity's UUID.
    • variant: A single entity model/texture variant.
      • weight: (Optional) The chance this variant is selected relative to other variants. Defaults to 1.
      • texture: The path to your custom texture image.
      • emissive_texture: (Optional) The path to an emissive texture image, if your model uses emissive textures. Defaults to none.
      • model: The path to your Bedrock entity geometry file.
      • translucent: (Optional) If the model has translucent textures. Defaults to false.
  • The singular variant.
    • texture: The path to your custom texture image.
    • emissive_texture: (Optional) The path to an emissive texture image, if your model uses emissive textures. Defaults to none.
    • model: The path to your Bedrock entity geometry file.
    • translucent: (Optional) If the model has translucent textures. Defaults to false.

Note: Ensure you place the actual .png texture and .geo.json model in the specific paths you declare. If you use vanilla names for the bones in your model, the entity will automatically use vanilla animations. If a bone has the wrong name, the mod will send an error to the log.

Condition Types

There are multiple different definitions you can use inside the target object to precisely match entities.

All / Any (all, any)

Used to evaluate multiple conditions in combination with each other. all requires every condition in the list to be met, while any matches if at least one condition is true.

• type: Either all or any.
• conditions: A list of condition objects.

Skin (npc_skin, player_skin)

Allows you to access state about a player entity.

• type: Either npc_skin or player_skin.
• skin: A reference to a skin URL. The entity is only matched if it uses this skin exactly.

Identity (identity)

Allows you to access state about regular entities based on their core identifiers.

• type: identity
• uuid: (Optional) Matches the entity's exact UUID. Note: Skyblock mostly uses random UUIDs.
• name: (Optional) Matches the entity's custom name.

Attribute (attribute)

Allows access to check entity attributes, such as maximum health or movement speed.

• type: attribute
• attribute: The specific attribute to check.
• value or values: Matches one or multiple specific attribute values.

NBT Number (nbt_number)

Checks if a specific numeric NBT tag on the entity matches a given value, list of values, or a range. Works for any number as well as booleans (0 or 1, I think at least).

• type: nbt_number
• key: The NBT key to check.
• value or values: Matches one or multiple specific numeric values, or a range.

Max Health (max_health)

Allows you to access the entity's maximum health value.

• type: max_health
• max_health: Matches a specific maximum health value or a range of values.
• use_modifiers: (Optional) Use Health Modifiers like mayor perks etc, see a full list here.

Island (island)

Matches if the entity (or player) is located on a specific Skyblock island.

• type: island
• island or islands: Matches one or multiple island identifiers.

Baby State (is_baby)

Matches an entity based on whether it is a baby or an adult.

• type: is_baby
• is_baby: The boolean value to compare against (true for baby, false for adult).

Equipment Conditional (equipment_conditional)

Matches based on a boolean item model property evaluated on the item currently equipped by the entity.

• type: equipment_conditional
• slot: Which equipment slot to check (e.g., head, chest, mainhand).
• property: The conditional item model property to check.

Equipment Select (equipment_select)

Evaluates a select item model property on the equipped item against a set of values.

• type: equipment_select
• slot: Which equipment slot to check.
• property: The select item model property to check.
• cases: A list of match cases.
  • case
    • when: A list of valid values to match.
    • result: The boolean result if matched.
• fallback: (Optional) The result if no cases match. Defaults to false.

Equipment Range Dispatch (equipment_range_dispatch)

Evaluates a numeric item model property on the equipped item using threshold entries.

• type: equipment_range_dispatch
• slot: Which equipment slot to check.
• property: The numeric item model property to check.
• scale: (Optional) Multiplier applied to the property's value. Defaults to 1.0.
• entries: A list of threshold entries.
  • entry
    • threshold: The numeric threshold.
    • result: The boolean result applied when the property value is matched.
• fallback: (Optional) The result if the value falls outside thresholds or is invalid. Defaults to false.

Has Passengers (has_passengers)

Matches if an entity has passengers.

• type: has_passenger

Passenger Conditions (passengers)

Runs matches on a specific passenger, or false if none.

• type: passenger
• index: (Optional) The index of the passenger, defaults to 0. (0 is first, 1 is second, etc.)
• entityType: (Optional) The entity type of the passenger, defaults to null. (Null means entity type does not matter)
• condition: The conditions to run on the passenger.

Model Quirks

When creating your Bedrock .geo.json models, please keep the following in mind:

• Per-face UVs: The mod cannot handle per-face UV mapping. Using this feature will break the model.
• Everything else should work fine out of the box.