Weapons and Mobs

Perfect Parries supports modded weapons and entities. This page covers how to configure custom stats and animations for your custom weapons and entities.

info

As of now, only animations can be completely set on your end. For custom entity/weapoon parry stats to be officially implemented, please contact me via discord to let me know what stats you would like for your weapon/entity heavy weapon. In the future, I aim to create a way to automatically read information from your mod.

Weapons

Custom Parry Animations

Add a PP_Parry entry to your weapon's JSON file. This tells Perfect Parries which animation to play when a parry occurs with this weapon.

"PP_Parry": {
  "ThirdPerson": "Characters/Animations/Main_Handed/{Weapon_Name}/Attacks/Perfect_Parries/Parry.blockyanim",
  "ThirdPersonMoving": "Characters/Animations/Main_Handed/{Weapon_Name}/Attacks/Perfect_Parries/Parry_Moving.blockyanim",
  "FirstPerson": "Characters/Animations/Main_Handed/{Weapon_Name}/Attacks/Perfect_Parries/Parry_FPS.blockyanim",
  "BlendingDuration": 0.1,
  "KeepPreviousFirstPersonAnimation": true
}

Place your .blockyanim files at the paths specified above, adjusting {Weapon_Name} to match your weapon. {Weapon_Name} is the exact string you see when you hover over your weapon in your creative inventory.

Custom Parry Stats

You can override parry behavior for your weapons by adding entries to weapon_parry_settings.json in mods/Perfect_Parries/. Each entry is keyed by the weapon's item ID and can override any combination of the following properties:

Property	Type	Description
parryWindowMs	Long	the timing window in milliseconds
reflectDamagePercent	Float	percentage of damage reflected to attacker
knockbackX	Float	horizontal knockback force on attacker
knockbackY	Float	vertical knockback force on attacker
counterattackDamageMultiplier	Float	damage multiplier for counterattacks
counterattackWindowMs	Long	window for landing a counterattack (ms)
stunnedDamageMultiplier	Float	damage multiplier against stunned targets
parryStaminaDrainMultiplier	Float	stamina drain multiplier on perfect parry
signature_energy_gain	Float	signature energy granted per parry
flatBonusStaggerChance	Float	flat addition to the entity's stagger chance
percentageBonusStaggerChance	Float	percentage increase to the entity's stagger chance
parrySfxId	String	custom SFX ID for the parry sound
counterattackSfxId	String	custom SFX ID for the counterattack hit sound

Any property you don't specify will use the global defaults from parry_config.json.

Wildcards and Material Groups

You can use * as a wildcard to match multiple weapons at once. Two built-in material groups are also available:

• {METAL} — matches common metal materials (iron, cobalt, mithril, etc.)
• {NON_METAL} — matches non-metal materials (stone, wood, trork, etc.)

Example

{
  "Weapon_Narwhals_Karambit": {
    "signature_energy_gain": 10.0,
    "parryWindowMs": 150,
    "reflectDamagePercent": 0.05,
    "knockbackX": 2.5,
    "knockbackY": 2.5,
    "counterattackDamageMultiplier": 2.0,
    "stunnedDamageMultiplier": 3.0,
    "parryStaminaDrainMultiplier": 0.0,
    "counterattackWindowMs": 300,
    "flatBonusStaggerChance": 0,
    "percentageBonusStaggerChance": 0
  },
  "Weapon_Mjolnir_Starky": {
    "signature_energy_gain": 35.0
  }
}

Signature Energy Tag

If you ship a custom weapon and want to set its per-parry signature energy gain without asking server admins to edit weapon_parry_settings.json, add a PP_Signature_Gain tag inside your weapon's Tags block. The value is a single string-wrapped number that will be granted to the defender's signature energy stat on every successful parry.

"Tags": {
  "Type": ["Weapon"],
  "Family": ["Longsword"],
  "PP_Signature_Gain": ["25"]
}

The number is a flat per-parry amount, not a fraction or percentage — "25" means the defender gains 25 signature energy each time they parry while holding this weapon.

caution

The value must be a string inside a single-element array (["25"], not 25 or "25").

Unparryable Attacks

Mark a specific attack as unparryable by adding an Unparryable tag to the damage interaction JSON. Per-interaction, so different attacks of the same weapon or mob can have different parry rules (e.g. light swings parryable, charged swing unparryable).

When a player tries to parry an attack carrying this tag, damage goes through and the player's parry window is consumed.

Add the Tags block alongside your existing fields on the damage-dealing interaction:

"Tags": {
  "Unparryable": []
}

The tag goes on the leaf interaction that does the damage, not the root interaction or the parent attack chain. Works the same whether your damage interaction uses "Type": "DamageEntity", "Parent": "DamageEntityParent", or a custom mod-registered Type.

Use cases:

• Telegraph-heavy boss attacks that should be dodged, not parried
• Charged or signature attacks meant to break through guard

tip

Pair unparryable attacks with some visual telegraph so players know to dodge instead of parry.

Mobs

Custom Stun Animations

Add PP_Parried_Stun and PP_Parried_Wake entries to your entity's AnimationSets map in its model asset JSON. These tell Perfect Parries which animations to play when the entity is fully stunned and when it wakes up from stun.

"AnimationSets": {
  "PP_Parried_Stun": {
    "Animations": [
      {
        "Animation": "NPC/{Entity_Name}/Animations/Default/PP_Parry_Stunned.blockyanim"
      }
    ]
  },
  "PP_Parried_Wake": {
    "Animations": [
      {
        "Animation": "NPC/{Entity_Name}/Animations/Default/PP_Parry_Wake.blockyanim"
      }
    ]
  }
}

Place your .blockyanim files at the paths specified above, adjusting {Entity_Name} to match your entity. {Entity_Name} is the exact string you type to spawn the NPC.

Custom Entity Stamina Stats

You can configure stamina and stun behavior for your modded entities by adding entries to entity_stamina.json in mods/Perfect_Parries/. Each entry is keyed by the entity type ID and has the following properties:

Property	Description
max_stamina	maximum stamina pool for this entity type
stamina_regen_timer	delay in milliseconds before stamina starts regenerating after being drained
stamina_regen_rate	how fast stamina regenerates per tick
damaged_stamina_multiplier	how much normal (non-parry) damage drains stamina
parried_stamina_change	flat stamina drained when this entity is parried
stagger_chance	probability of a stagger on each parry (0.0 to 1.0)

When an entity's stamina reaches 0, it enters a full stun for the duration configured in parry_config.json (default 5 seconds).

Example

{
  "KF_Fire_Queen": {
    "max_stamina": 350.0,
    "stamina_regen_timer": 5000,
    "stamina_regen_rate": 25.0,
    "damaged_stamina_multiplier": 0.75,
    "parried_stamina_change": 35.0,
    "stagger_chance": 0.1
  },
  "Sentinel_Golem": {
    "max_stamina": 250.0,
    "stamina_regen_timer": 3000,
    "stamina_regen_rate": 25.0,
    "damaged_stamina_multiplier": 0.5,
    "parried_stamina_change": 35.0,
    "stagger_chance": 0
  }
}

info

Bosses typically have higher max_stamina and lower stagger_chance to not trivialize bosses while keeping parrying rewarding.