Core Impact Framework - API Usage

Table of Contents

• Introduction
• Prerequisites
• Location of JSON Files
• Impact Mapping
• Hit Mapping
• Filters
• Modifiers
• Biped Mapping
• Testing in the Game

📌 Introduction

The Core Impact Framework (CIF) is an advanced and modular overhaul of Skyrim's impact system, designed to offer fine-grained customization of interactions between weapons, projectiles, and actors in the game. This framework allows for the adjustment, modification, and enrichment of impact effects in a wide variety of situations, making combat more immersive and dynamic. With a flexible system of filters and modifiers, it gives mod creators precise control over how impacts are managed based on context.

For example, CIF can adapt effects based on the armor worn by the target, differentiating impacts on heavy armor, light armor, or simple clothing. However, it goes beyond that: the impact calculation is done based on each piece of armor and the position of the impact. This means that the system evaluates the specific piece of armor the impact hits and applies effects accordingly.

In addition to this, the target's state, equipment, type of weapon used, the nature of the attack, and many other parameters can influence the result. Numerous filters and options allow for fine-tuning every detail, and everything is fully documented in this presentation.

🔹 Available Filters

Filters allow for further refinement of impact management based on several criteria:

• Global factors: Global variables, custom conditions, race, actor, material type, keywords.
• Equipment: Armor type (heavy, light, clothing) and specific skins.
• Biped slot: Specific body slots the equipment affects.
• Weapons & projectiles: Generic types (sword, axe, bow, magic…) or specific weapons and projectiles.
• Type of attack: Normal hit, power attack, bash. Sneak or critical strike.
• Blocking: Heavy shield, light shield, parry with weapon, or unblockable hit.
• Target state: Alive, dying, in killmove, dead.
• Thresholds: Maximum health and minimum required damage.

Thanks to this approach, CIF allows for deep customization, providing a more realistic, varied, and impactful combat experience.

🔹 Advanced Modifiers

The CIF modifiers offer in-depth customization of impacts with a multitude of options. You can not only adjust visual, sound, and dynamic effects but also influence elements such as blood splatter, objects appearing after a hit, or specific sounds associated with each impact.

Here are some examples of possible modifiers:

• Dynamic blood splatter effects.
• Modifications of impact data (visual and physical effects).
• Preservation, replacement, or removal of sounds and decals.
• Adding additional or custom sounds.
• Applying spells on impact.
• Placing objects after the impact.
• Enabling a bounce effect on impacts (especially for arrows).

These modifiers offer maximum flexibility to make impacts even more immersive and varied.

📌 Prerequisites

Before starting this tutorial, and to save time, make sure you have the following skills:

• Basic knowledge of Creation Kit: You should understand the basics of Creation Kit, including creating and modifying elements within this environment.
• Basic knowledge of JSON: An understanding of JSON files and their structure is essential for correctly creating and modifying the files needed for the Core Impact Framework (CIF).
• Understanding of impacts in Skyrim: While not essential, a general knowledge of impact systems in Skyrim will help you better understand how the CIF interacts with the game.

If you're not comfortable with any of these skills or tools, it is recommended to acquire them before following this tutorial.

Great, now that we're all set up, let's dive into using the Core Impact Framework API.

📌 Location of JSON Files

The JSON files should be placed in Data/SKSE/CoreImpactFramework. The exact organization of these files doesn't matter as long as they remain in this directory. You are free to organize them in subfolders as you see fit.

Similarly, there are no specific rules for naming the files: you are completely free to name them however you like.

In summary: as long as they are in this folder, everything is fine. The rest is up to you! ✅

📌 Impact Mapping - Structure and Functioning

{
  "ImpactMapping": [
    {
      "Comment": "Replaces the head impact (biped slot 30) with sparks for heavy armor when struck by arrows.",
      "Priority": 10,
      "Filters": {
        "Materials": ["Skyrim.esm:0x12F3F"],
        "BipedSlot": [31],
        "ArmorClasses": ["Heavy"],
        "WeaponsType": ["Ranged"],
        "Blocked": ["No"]
      },
      "Modifiers": {
        "ImpactData": "Skyrim.esm:0xF69C4"
      }
    }
  ]
}

ImpactMapping is an array in your JSON file that allows you to define rules for customizing impacts. Each object in this array contains:

• Filters (conditions): to check if the rule should apply.
• Modifiers (actions): defines the effect applied if the conditions are met.
• Priority (optional): defines the evaluation order when multiple rules are valid.

This system allows you to adapt impacts based on a multitude of in-game situations.

🔹 Priority - Rule Priority

The Priority field defines the order in which rules in the ImpactMapping are processed. A rule with a higher priority will be applied first and can override those with lower priority.

This system allows for the addition of exceptions and specific behaviors based on the importance of the rules.

🔹 Filters - Conditions to Validate

When an impact occurs, the Filters are evaluated. All conditions must be met for the Modifiers to be applied.

📝 Important Notes:

• An empty filter group is always valid.
• Filters are inclusive: all conditions must be met to be validated.
• In a filter array (array), the values work in OR. Example:
  • A ranged weapon with 3 different projectiles means that only a ranged weapon will be considered,
  • But it must use at least one of the 3 listed projectiles.
• ⚠️ The only exception: Global and Conditions work in AND, all must be validated.

🔹 Modifiers - Actions to Perform

The Modifiers are the actions that will be executed once the Filters have been validated. These actions allow you to replace or enhance the impact effects, adding sound effects, visual effects, or modifying the behavior of the impacts in the game.

The specific details of each Modifier element will be covered in a later step. For now, just remember that these are the actions that will truly customize the impact once the filters are validated.

🔹 Other parameters

Override : When this parameter is enabled (true), the framework continues to process objects even if the filters are valid. The Modifiers of the highest-priority objects will be kept and will override those of subsequent objects. This allows for the merging of multiple rule sets for the same impact event, where the highest-priority Modifiers take precedence.

For example, one set of rules might replace the sound effect, while another sets a new decal to be displayed, all within a single impact event. You can use this parameter as many times as necessary to create layered and varied effects.

OverrideMerge : This parameter, used in conjunction with Override, is less commonly used but allows merging array-type elements (such as ExtraImpactData) with those of lower-level objects. When OverrideMerge is enabled, the array elements will be added to those already present in the subsequent objects, rather than completely replacing them. This allows you to enrich effects without removing existing data, offering more flexibility in customizing impacts.

📌 Hit Mapping - Structure and Functioning

{
  "HitMapping": [
    {
      "Comment": "Plays a sound and a slight magical effect upon impact.",
      "Priority": 10,
      "Class": "MyCustomEffects",
      "Filters": {
        "Materials": ["Skyrim.esm:0x12F3F"],
        "Blocked": ["No"]
      },
      "Modifiers": {
        "ExtraImpactData": ["Skyrim.esm:0x7331F"],
        "ExtraSound": ["Skyrim.esm:0x51939"]
      }
    },
    {
      "Comment": "When a hit is made to the head, in addition to the previous sound effect, the magical effect is replaced by a new, more dazzling one.",
      "Priority": 20,
      "Class": "MyCustomEffects",
      "Override": true,
      "Filters": {
        "Materials": ["Skyrim.esm:0x12F3F"],
        "BipedSlot": [31],
        "Blocked": ["No"]
      },
      "Modifiers": {
        "ExtraImpactData": ["Skyrim.esm:0x105F36"]
      }
    }
  ]
}

HitMapping is an array in your JSON file that defines additional rules for handling impacts, similar in structure to ImpactMapping but intended for different use cases.

While ImpactMapping is strictly reserved for replacing visual and sound effects related to impacts, HitMapping is specifically designed for gameplay-related modifications that do not directly affect visuals or sounds. It supports stacking, allowing multiple entries to coexist and be executed together without overwriting each other.

The elements of HitMapping are:

• Priority: sets the evaluation order of rules.
• Class: 💥 Only for HitMapping. See the explanation below.
• Override: Replaces or adds modifiers from lower-priority objects if they are not present, keeping other properties intact.
• OverrideMerge: A less commonly used parameter that works with Override to merge array-type elements from lower-priority objects.
• Filters: to determine if the rule applies.
• Modifiers: defines the effects applied if the conditions are met.

🔹 Class - Grouping and Overriding Objects

The Class parameter is a new addition that enables the use of the override system across multiple objects sharing the same class name. When you define a Class for an entry, it allows all objects with the same class name to either override or merge their modifiers depending on the Override setting. This provides greater control and flexibility when you want to apply specific behaviors or effects to a group of similar objects without needing to manually manage each individual entry.

For the override system to function correctly, it is mandatory to define a Class. If no Class is provided, the override mechanism will not be applied, and the object will remain independent. The Class parameter should be a string value, preferably concise and clear, to ensure ease of use and avoid conflicts with other class names.

🔹 Filters - Conditions to Validate

Filters in HitMapping are identical to those used in ImpactMapping.

Please refer to that section for a detailed explanation of how filters work.

🔹 Modifiers - Actions to Perform

⚠️ Only specific modifiers are available for HitMapping. Modifiers that directly alter the primary visual or audio effects of an impact are reserved for ImpactMapping and cannot be used globally through HitMapping.

The following modifiers are available for use in HitMapping to customize the impact effects:

• BloodSpray: Casts a gore spell toward the impact direction with physics adjustments.
• ExtraImpactData: Adds extra visual impact effects without sounds or decals.
• ExtraSound: Plays additional sound effects on impact.
• Spells: Instantly casts spells on the hit target.
• PlacedObjects: Places objects at the exact point of impact.

📌 Filters

Each filter is a condition that must be met for the modifiers to be applied. It's not necessary to declare all filters, only the ones you wish to use should be defined. Filters are inclusive, meaning all conditions within the same group must be fulfilled to be valid. However, within the arrays of each filter, the values work in OR: for example, if a weapon (WeaponsType) is filtered by the "Ranged" type and you have declared 3 specific projectile IDs (Projectiles[...]), it will mean that only ranged weapons will be compatible, but one of the three listed projectiles must be used by the weapon for the condition to be validated.

The only exception to this OR system is for Global Variables and Conditions, which must all be validated for the filter to be considered fulfilled. In other words, if multiple Globals or Conditions are defined, they function in AND, and each condition must be satisfied for the modifiers to apply.

📝 Before moving on to the filter list, here are a few clarifications on the use of FormID and EditorID in the JSON:

• FormID : Any FormID must be formatted as follows: "Skyrim.esm:0x123456". This format is valid for all filters where a game element is required. If a FormID is incorrect or cannot be found, an error will be logged in the CoreImpactFramework.log file.
• EditorID : This is the name of the element as it appears in the Creation Kit. Unlike FormID, the EditorID does not require the plugin name where the element is located. However, its use is limited to certain types of variables, notably Global Variables and Races. If you are unsure of an EditorID's compatibility for a given filter, it is recommended to use a FormID to avoid any issues.

Complete List of Filters

"Globales": [
  ["My_Custom_GV", "==", 1],
  ["Plugin.esp:0x800", ">=", 100.0]
]

"Conditions": ["Plugin.esp:0x800", "Plugin.esp:0x801", "Plugin.esp:0x802"]

"Races": ["RaceNord", "Plugin.esp:0x800", "Plugin.esp:0x801"]

"Keywords": ["Plugin.esp:0x800", "Plugin.esp:0x801", "ActorTypeNPC"]

"Skins": ["Plugin.esp:0x800", "Plugin.esp:0x801", "Plugin.esp:0x802"]

"Materials": ["Skyrim.esm:0x12F3F", "Plugin.esp:0x800", "Plugin.esp:0x801"]

"FormID": ["Plugin.esp:0x800", "Plugin.esp:0x801"]

"BipedSlot": [30, 32, "Plugin.esp:0x800", "MyGlobalEditorID"]

"ArmorClasses": ["Light", "Heavy"]

"WeaponsType": ["OneHandSword", "TwoHandSword", "OneHandAxe", "TwoHandAxe"]

"Weapons": ["Plugin.esp:0x800", "Plugin.esp:0x801", "Plugin.esp:0x802"]

"Projectiles": ["Plugin.esp:0x800", "Plugin.esp:0x801", "Plugin.esp:0x802"]

"Attacks": ["Regular", "Power"]

"Blocked": ["ShieldLight", "ShieldHeavy"]

"States": ["Dying", "Killmove"]

"CriticalAttack": ["Yes"]

"SneakAttack": ["No"]

"Percentage": 25.0

"MaxHealth": 80.0

"MinDamage": 20.0

📌 Modifiers

Once the filters are validated, the following modifiers may be applied.

"ImpactData": "Plugin.esp:0x800"

"BloodSpray": "Plugin.esp:0x800"

"ExtraImpactData": ["Plugin.esp:0x801", "Plugin.esp:0x802"]

"ExtraSound": ["Plugin.esp:0x900", "Plugin.esp:0x901"]

"PreserveOriginalSound": true

"PreserveOriginalDecal": true

"SoundOverride": "Plugin.esp:0x800"

"DecalOverride": "Plugin.esp:0x800"

"RemoveDecal": false

"RemoveBloodSplatter": true

"ImpactBounce": true

"Spells": ["Plugin.esp:0x800", "Plugin.esp:0x801"]

"PlacedObjects": ["Plugin.esp:0x800", "Plugin.esp:0x801"]

📌 Biped Mapping (For new races/creature only)

This section explains how to define the nodes associated with biped slots. These definitions enable the use of certain filters and features. In most cases, only the biped slots of NPCs capable of wearing armor will be used, but nothing prevents you from creating your own mapping for specific custom creatures.

Example: The following configuration shows how to define the mapping for Draugr.

{
  "BipedMapping": [
    {
      "Priority": 20,
      "Filters": {
        "Races": ["DraugrRace", "DraugrMagicRace", "DLC2HulkingDraugrRace"]
      },
      "BipedBones": {
        "31": ["NPC Head [Head]", "NPC Neck [Neck]"],
        "32": ["NPC Spine [Spn0]", "NPC Spine1 [Spn1]", "NPC Spine2 [Spn2]", "NPC COM [COM ]", "NPC L Thigh [LThg]", "NPC R Thigh [RThg]", "NPC L UpperArm [LUar]", "NPC R UpperArm [RUar]"],
        "33": ["NPC L Forearm [LLar]", "NPC R Forearm [RLar]", "NPC L Hand [LHnd]", "NPC R Hand [RHnd]"],
        "37": ["NPC L Calf [LClf]", "NPC R Calf [RClf]", "NPC L Foot [LLft ]", "NPC R Foot [Rft ]"]
      }
    }
  ]
}

The table below shows the properties related to Biped Mapping. The priority system works the same way as for Impact Mapping, and the filters, though basic, also function in a similar manner.

"Priority": 10

"Filters": {
  "Races": ["RaceDarkElf", "RaceWoodElf"],
  "Keywords": ["ActorTypeNPC"],
  "Skins": []
}

"BipedBones": {
  "31": ["NPC Head [Head]", "NPC Neck [Neck]"],
  "32": ["NPC Spine [Spn0]", "NPC Spine1 [Spn1]", "NPC Spine2 [Spn2]", "NPC COM [COM ]"],
  "37": ["..."]
}

📌 Testing in the Game

After configuring your JSON files, it is crucial to test your changes in the game to ensure they work as intended. If you encounter a crash when launching the game, it likely means that the structure of one of your JSON files is malformed (possibly an extra comma). Feel free to use tools like JSON Formatter to validate your JSON files or find potential errors.

Once the game is running, be sure to check the CoreImpactFramework.log file (located in Documents\My Games\Skyrim Special Edition\SKSE) for any errors or issues with your JSON files. Regularly check this file during your testing to identify and quickly correct errors. This will help you refine your configuration and ensure smooth integration into the game.