10. Overlay Effects

The Overlay Effects allows you to add an overlay based on the player's current combat state, whether based on their style, ability, or animation.

💡 What's New in v2.2: The old overlay system was, to say the least, unintuitive and not very useful. In the past, you could only trigger an overlay based on the current animation style. However, now skills and animations are allowed!

📁 File Location & Naming

Place your configuration files inside your resource pack or mod assets at:
assets/<any_modid>/overlay_packet/*.json

📄 File Structure & Schema

Field	Description	Valid Options
category	Target weapon category (Required).	e.g., epicfight:sword
trigger_item	Targeted item id. Defaults to all if missing.	"all" or "modid:item_id"
activation_type	The root gameplay trigger context.	"Skill", "Style", "Animation"
effect	The effect in question with its respective data.	Overlay Entry

---

🔄 Matrix (Valid Pairings)

• Skill ➡️ When a skill is active, primarily of the time type for Weapon Innate (Like Longsword).
• Style ➡️ As long as the configured style is the same as the one that holds the item.
• Animation ➡️ At the moment an animation is executed.

---

🔗 Config Matrix (Valid Pairings)

• overlay_times ➡️ They determine the temporary configuration of the effect; for OneShot effects, a hold_time must be declared; for Skill or Style effects, it is not necessary.
• overlay_path➡️ relevant settings, such as animation size (if applicable), alpha, and path

---

📄 JSON Structure & Schema | Animated Overlay

In this example, there are 2 overlays, one soft and subtle that is executed when performing the skill "battojutsu" in dash mode, and one in a normal way when the style is "sheat", that is, the katakana is sheathed.

{
  "overlay_packet": [
    {
      "category": "uchigatana",
      "trigger_item": "epicfight:uchigatana",
      "activation_type": "animation",
      "effect": {
        "animation": "epicfight:biped/skill/battojutsu_dash",
        "elapse": 0.5,
        "overlay_times": {
          "time_in": 9,
          "time_hold": 5,
          "time_out": 8
        },
        "overlay_path": {
          "size": 150,
          "fps": 20,
          "alpha": 100,
          "path": "epicfight:overlays/firelay/morningstar_*.png"
        }
      }
    }
  ]
}

🎥 In-Game Showcase

2026-06-21.12-06-30.mp4

---

📄 JSON Structure & Schema | Static Overlay

Additionally, it is possible to use non-animated overlays, as it is not mandatory; here is an example: instead of running an array of files, we only run a single texture file.

{
  "overlay_packet": [
    {
      "category": "uchigatana",
      "trigger_item": "epicfight:uchigatana",
      "activation_type": "animation",
      "effect": {
        "animation": "epicfight:biped/skill/battojutsu_dash",
        "elapse": 0.5,
        "overlay_times": {
          "time_in": 9,
          "time_hold": 5,
          "time_out": 8
        },
        "overlay_path": {
          "alpha": 100,
          "path": "epicfight:overlays/firelay/morningstar_50.png"
        }
      }
    }
  ]
}

🎥 In-Game Showcase

2026-06-21.12-05-53.mp4