Abilities - BetterTrims

Better Trims provides many built-in abilities of varying types.

Count Based Values

A lot of the abilities use "count-based values". These are values that scale based on the number of matching trims the player is wearing. See Count Based Values for more information.

Ability Types

Value Abilities

Abilities that modify the numerical value of a specific ability component. I.e. Incoming Damage, Trade Offer Costs, etc.

Add Value

{
    "type": "bettertrims:add",
    "value": <count-based-value>
}

Multiply Value

{
    "type": "bettertrims:multiply",
    "value": <count-based-value>
}

Set Value

{
    "type": "bettertrims:set",
    "value": <count-based-value>
}

Remove Binomial

Chance to subtract the value provided by the component by 1, based on a binomial distribution.

{
    "type": "bettertrims:remove_binomial",
    "chance": <count-based-value>
}

All Of

Combines multiple value abilities together. The abilities are applied in the order they are listed and the result of one ability is passed to the next.

{
    "type": "bettertrims:all_of",
    "abilities": [
        {
            "type": "<value_ability_type>",
            // Ability specific fields here
        },
        {
            "type": "<value_ability_type>",
            // Ability specific fields here
        }
    ]
}

Event Abilities

Abilities that trigger on specific events, such as after attacking, when the game ticks, when hitting a block, etc.

Apply Status Effect

{
    "type": "bettertrims:apply_mob_effect",
    "effect": "<namespace>:<effect_id>",
    "duration": <count-based-value>,
    "amplifier": <count-based-value>
}

Field	Type	Required	Description
`effect`	string	Yes	The ID of the status effect to apply (see Status Effect).
`duration`	count-based-value	Yes	The duration of the effect in seconds.
`amplifier`	count-based-value	Yes	The amplifier level of the effect (0 for level 1, 1 for level 2, etc.).

Change Item Damage

{
    "type": "bettertrims:change_item_damage",
    "amount": <count-based-value>
}

Field	Type	Required	Description
`amount`	count-based-value	Yes	The amount to change the item's damage by (negative to repair).

Damage Entity

Deals between min_damage and max_damage damage of damage_type to the entity in context.

{
    "type": "bettertrims:damage_entity",
    "min_damage": <count-based-value>,
    "max_damage": <count-based-value>,
    "damage_type": "<namespace>:<damage_type_id>"
}

Field	Type	Required	Description
`min_damage`	count-based-value	Yes	The minimum amount of damage to deal.
`max_damage`	count-based-value	Yes	The maximum amount of damage to deal.
`damage_type`	string	Yes	The type of damage to deal (see Damage Type).

Warning

If this is used in a post_attack ability, the damage may not be applied as expected as the target may have invulnerability frames.

Explode

{
    "type": "bettertrims:explode",
    "attribute_to_wearer": <boolean>,
    "damage_type": "<namespace>:<damage_type_id>",
    "knockback_multiplier": <count-based-value>,
    "immune_blocks": "#<namespace>:<tag_id>",
    "offset": <vector>,
    "radius": <count-based-value>,
    "create_fire": <boolean>,
    "block_interaction": "<block_interaction_type>"
    "small_particle": "<namespace>:<particle_type_id>",
    "large_particle": "<namespace>:<particle_type_id>",
    "sound": "<namespace>:<sound_event_id>"
}

Field	Type	Required	Description
`attribute_to_wearer`	boolean	No	Whether the explosion should be attributed to the wearer. Defaults to false.
`damage_type`	string	No	The type of damage to deal (see Damage Type). If not provided, the explosion will not deal damage.
`knockback_multiplier`	count-based-value	No	The multiplier for knockback applied by the explosion. Defaults to 1.0.
`immune_blocks`	string	No	A tag of blocks that the explosion will not destroy regardless of the explosion's strength.
`offset`	vector	No	The offset from the context position to create the explosion at. Defaults to (0, 0, 0).
`radius`	count-based-value	Yes	The radius of the explosion.
`create_fire`	boolean	No	Whether the explosion should create fire. Defaults to false.
`block_interaction`	string	Yes	How the explosion should interact with blocks. One of `none` (no effect), `block` (like a bed explosion), `mob` (like a creeper explosion), `tnt` (like tnt explosion), `trigger` (like a wind-charge explosion).
`small_particle`	string	Yes	The small particles in the explosion effect (see Particles).
`large_particle`	string	Yes	The large particles in the explosion effect (see Particles).
`sound`	string	Yes	The sound to play when the explosion occurs.

Ignite

{
    "type": "bettertrims:ignite",
    "duration": <count-based-value>
}

Field	Type	Required	Description
`duration`	count-based-value	Yes	The duration to set the entity on fire for, in seconds.

Play Sound

{
    "type": "bettertrims:play_sound",
    "sound": "<namespace>:<sound_event_id>",
    "volume": <float-provider>,
    "pitch": <float-provider>
}

Field	Type	Required	Description
`sound`	string	Yes	The sound event to play.
`volume`	float-provider	Yes	The volume of the sound (see Float Provider).
`pitch`	float-provider	Yes	The pitch of the sound (see Float Provider).

Replace Block

{
    "type": "bettertrims:replace_block",
    "offset": <vector>,
    "predicate": <block-predicate>,
    "block_state": <block-state-provider>
    "trigger_game_event": "<namespace>:<game_event_id>",
    "replace_translation_key": "<lang_key>"
    "offset_translation_key": "<lang_key>"
    "with_translation_key": "<lang_key>"
}

Field	Type	Required	Description
`offset`	vector	No	The offset from the context position to replace the block at. Defaults to (0, 0, 0).
`predicate`	block-predicate	No	A predicate that the block to replace must match. If not provided, any block can be replaced (see Block Predicate).
`block_state`	block-state-provider	Yes	The block state to replace the block with (see Block State Provider).
`trigger_game_event`	string	No	A game event to trigger at the position of the replaced block (see Game Event).
`replace_translation_key`	string	No	A translation key for the replaced block to use in the ability tooltip. Eg. "Lit Redstone Lamp"
`offset_translation_key`	string	No	A translation key for the offset to use in the ability tooltip. Eg. "Below"
`with_translation_key`	string	No	A translation key for the new block state to use in the ability tooltip. Eg. "Glowstone"

Replace Disk

{
    "type": "bettertrims:replace_disk",
    "radius": <count-based-value>,
    "height": <count-based-value>,
    "offset": <vector>,
    "predicate": <block-predicate>,
    "block_state": <block-state-provider>
    "replace_translation_key": "<lang_key>"
    "offset_translation_key": "<lang_key>"
    "with_translation_key": "<lang_key>"
}

Field	Type	Required	Description
`radius`	count-based-value	Yes	The radius of the disk to replace blocks in.
`height`	count-based-value	Yes	The height of the disk to replace blocks in.
`offset`	vector	No	The offset from the context position to replace the block at. Defaults to (0, 0, 0).
`predicate`	block-predicate	No	A predicate that the block to replace must match. If not provided, any block can be replaced (see Block Predicate).
`block_state`	block-state-provider	Yes	The block state to replace the block with (see Block State Provider).
`trigger_game_event`	string	No	A game event to trigger at the position of the replaced block (see Game Event).
`replace_translation_key`	string	No	A translation key for the replaced block to use in the ability tooltip. Eg. "Lit Redstone Lamp"
`offset_translation_key`	string	No	A translation key for the offset to use in the ability tooltip. Eg. "Below"
`with_translation_key`	string	No	A translation key for the new block state to use in the ability tooltip. Eg. "Glowstone"

Run Function

{
    "type": "bettertrims:run_function",
    "function": "<namespace>:<function_id>",
    "tooltip_translation_key": "<lang_key>"
}

Field	Type	Required	Description
`function`	string	Yes	The ID of the function to run.
`tooltip_translation_key`	string	Yes	A translation key for the ability tooltip to describe the function being run.

Set Block Properties

{
    "type": "bettertrims:set_block_properties",
    "properties": {
        "<property_name>": "<property_value>",
        ...
    },
    "offset": <vector>,
    "trigger_game_event": "<namespace>:<game_event_id>",
    "properties_translation_key": "<lang_key>"
    "offset_translation_key": "<lang_key>"
}

Field	Type	Required	Description
`properties`	object	Yes	The block properties to set on the block (see Block States).
`offset`	vector	No	The offset from the context position to set the block properties at. Defaults to (0, 0, 0).
`trigger_game_event`	string	No	A game event to trigger at the position of the block (see Game Event).
`properties_translation_key`	string	Yes	A translation key for the block properties to use in the ability tooltip. Eg. "Facing North, Lit"
`offset_translation_key`	string	Yes	A translation key for the offset to use in the ability tooltip. Eg. "Below"

Spawn Particles

{
    "type": "bettertrims:spawn_particles",
    "particle": "<namespace>:<particle_type_id>",
    "horizontal_position": <position-source>,
    "vertical_position": <position-source>,
    "horizontal_velocity": <velocity-source>,
    "vertical_velocity": <velocity-source>
    "speed": <float-provider>
}

Field	Type	Required	Description
`particle`	string	Yes	The particle type to spawn (see Particles).
`horizontal_position`	position-source	Yes	The source for the horizontal position to spawn the particles at (see below).
`vertical_position`	position-source	Yes	The source for the vertical position to spawn the particles at (see below).
`horizontal_velocity`	velocity-source	Yes	The source for the horizontal velocity of the spawned particles (see below).
`vertical_velocity`	velocity-source	Yes	The source for the vertical velocity of the spawned particles (see below).
`speed`	float-provider	Yes	The speed of the spawned particles (see Float Provider).

Position Source:

{
    "type": "<position_source_type>",
    "offset": <float>,
    "scale": <float>
}

Field	Type	Required	Description
`type`	string	Yes	One of `entity_position` (spawn at position of entity) or `in_bounding_box` (spawn at random position inside the bounding box of the entity)
`offset`	float	No	An offset to add to the position. Defaults to 0.
`scale`	float	No	A scale to multiply the `in_bounding_box` random position by. Defaults to 1. Only used if `type` is `in_bounding_box`.

Velocity Source:

{
    "base": <float-provider>,
    "movement_scale": <float>
}

Field	Type	Required	Description
`base`	float-provider	No	A base velocity to add to the particle. Defaults to 0. (see Float Provider).
`movement_scale`	float	No	A scale to multiply the entity's movement by and add to the particle's velocity. Defaults to 1.

Summon Entity

{
    "type": "bettertrims:summon_entity",
    "entity": "<namespace>:<entity_id>"
}

Field	Type	Required	Description
`entity`	string	Yes	The ID of the entity to summon.

Note

If the entity is a lightning bolt, it will be attributed to the wearer.

All Of

Combines multiple event abilities together. The abilities are applied in the order they are listed.

{
    "type": "bettertrims:all_of",
    "abilities": [
        {
            "type": "<event_ability_type>",
            // Ability specific fields here
        },
        {
            "type": "<event_ability_type>",
            // Ability specific fields here
        }
    ]
}

Toggle Abilities

Abilities that are active while the property is equipped, this is mostly useful for attribute modifiers.

Attribute

{
    "type": "bettertrims:attribute",
    "attribute": "<namespace>:<attribute_id>",
    "value": <count-based-value>,
    "operation": "<operation_type>"
}

Field	Type	Required	Description
`attribute`	string	Yes	The ID of the attribute to modify (see Attribute).
`value`	count-based-value	Yes	The value to modify the attribute by.
`operation`	string	Yes	The operation to perform (see Operation).

Toggle Status Effect

{
    "type": "bettertrims:toggle_mob_effect",
    "effect": "<namespace>:<effect_id>",
    "amplifier": <count-based-value>,
    "visible": <boolean>
}

Field	Type	Required	Description
`effect`	string	Yes	The ID of the status effect to apply (see Status Effect).
`amplifier`	count-based-value	Yes	The amplifier level of the effect (0 for level 1, 1 for level 2, etc.).
`visible`	boolean	No	Whether the effect should be visible on the player (particles and icon). Defaults to true.

Warning

Based on the nature of status effects, when unequipping the property any pre-existing effects of the same type will also be removed.

All Of

Combines multiple toggle abilities together. The abilities are applied in the order they are listed.

{
    "type": "bettertrims:all_of",
    "abilities": [
        {
            "type": "<toggle_ability_type>",
            // Ability specific fields here
        },
        {
            "type": "<toggle_ability_type>",
            // Ability specific fields here
        }
    ]
}

Flag Abilities

Abilities that toggle a boolean flag, such as Damage Immunity or Piglin Safety do not require any additional parameters.
Flag abilities are simply defined by the component type:

{
    "bettertrims:piglin_safe": [
        {
            "ability": {}
        }
    ]
}