Dynamic Bloodpool Framework - API Documentation

• Introduction
• Prerequisites
• JSON File Location
• Pool Profiles Mapping
• Variants
  • Primary Layer
  • Extended Layer
  • Shaders
• Complete Example
• Testing in the Game

📌 Introduction

The Dynamic Bloodpool Framework (DBF) is a mesh-based rendering system designed to dynamically generate fully animated blood pools using externally defined profile configurations.

Unlike Skyrim's traditional decal-based approach, which relies on static projections with limited flexibility, DBF creates real geometry-driven blood pools that expand, animate, and blend naturally with the environment. This ensures consistent visual fidelity across uneven terrain, complex surfaces, and varied environmental conditions.

Each blood pool is generated from a profile definition stored in a JSON file. These profiles control every aspect of the blood pool's behavior and appearance, including textures, expansion speed, size variation, animation curves, and shader properties.

A single blood pool animation can consist of up to two independent layers:

• Primary layer: Defines the initial formation and core structure of the blood pool.
• Extended layer (optional): Expands outward from the primary layer, allowing for more organic, irregular, and realistic growth patterns.

This layered approach enables complex and natural-looking animations while remaining extremely efficient.

All profile data is loaded and processed natively by the game engine, without relying on Papyrus scripts or runtime polling. This guarantees optimal performance, high scalability, and complete stability, even during intense gameplay scenarios.

Because profiles are defined externally and evaluated at runtime, any mod can create, extend, or override blood pool definitions without conflicts. This makes the Dynamic Bloodpool Framework a fully modular and future-proof solution for advanced blood pool rendering in Skyrim.

📌 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 Dynamic Bloodpool Framework (DBF).
• Understanding of impacts in Skyrim: While not essential, a general knowledge of impact systems in Skyrim will help you better understand how the DBF 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 Dynamic Bloodpool Framework API.

📌 Location of JSON Files

The JSON files should be placed in Data/SKSE/DynamicBloodpoolFramework. 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! ✅

📌 Pool Profiles Mapping

The PoolProfilesMapping array defines all available blood pool profiles. This array can contain an unlimited number of profiles, and the same structure applies to all DBF JSON files.

Each profile in the array represents a unique blood pool configuration identified by a ProfileID. If multiple profiles share the same ProfileID, the one with the highest Priority will override the others.

{
  "PoolProfilesMapping": [
    {
      "ProfileID": "MyProfile",
      "Priority": 0,
      "Variants": [ ... ]
    },
    {
      "ProfileID": "AnotherProfile",
      "Priority": 0,
      "Variants": [ ... ]
    },
    {
      "ProfileID": "AnotherProfile",
      "Priority": 10,
      "Override": true,
      "Variants": [ ... ]
    }
  ]
}

Each entry in PoolProfilesMapping contains the following parameters:

Notes:

• Every JSON file using the DBF system follows this same model: a top-level array containing multiple profile objects.
• The ProfileID serves as the reference key; other mods or scripts will request blood pools using this identifier.
• If a profile with the same ProfileID exists in multiple JSON files, the profile with the highest Priority wins, effectively allowing overriding and modular additions.
• The Variants array allows for visual and behavioral diversity: only one variant is chosen randomly per blood pool instance, giving natural variation in the game.

📌 Variants

Each Variants entry defines a set of blood pool behaviors and visual properties. When a profile is invoked, only one variant is randomly selected and played. A variant can have up to two layers: the Primary layer and an optional Extended layer, plus shader configuration.

🔹 Primary Layer

"TextureSet": {
	  "Diffuse": "MyMod\\Bloodpools\\BloodPool_01_P1.dds",
	  "Normal": "MyMod\\Bloodpools\\BloodPool_01_P1_n.dds"
	}

"TextureSet": "Plugin.esp:0x800"

🔹 Extended Layer (optional)

The Extended Layer is an optional secondary layer that plays either alongside or after the primary layer, depending on the blending settings. It adds extra visual detail, like organic expansion or irregular shapes.

Its final position is always centered on the primary layer, ensuring the animation stays aligned and natural-looking.

"TextureSet": {
	  "Diffuse": "MyMod\\Bloodpools\\BloodPool_01_P2.dds",
	  "Normal": "MyMod\\Bloodpools\\BloodPool_01_P2_n.dds"
	}

"TextureSet": "Plugin.esp:0x801"

🔹 Shaders

The Shaders section defines how the blood pool interacts with light and surfaces. It controls properties like specularity, glossiness, emissive color, and transparency, allowing each layer to have a unique visual style while blending naturally with the environment.

📌 Complete Example

{
  "PoolProfilesMapping": [
    {
      "ProfileID": "ExampleProfile",
      "Priority": 0,
      "Variants": [
        {
          "TextureSet": {
              "Diffuse": "MyMod\\Bloodpools\\BloodPool_01_P1.dds",
              "Normal": "MyMod\\Bloodpools\\BloodPool_01_P1_n.dds"
          },
          "Pivot": [0.25, 0.75],
          "SizeRange": [50.0, 75.0],
          "Duration": 3.0,
          "DurationMultRange": [1.0, 2.0],
          "EasePower": 2.5,
          "FadeOutRange": [0.7, 1.0],
          "Extended": {
            "TextureSet": {
              "Diffuse": "MyMod\\Bloodpools\\BloodPool_01_P2.dds",
              "Normal": "MyMod\\Bloodpools\\BloodPool_01_P2_n.dds"
            },
            "Pivot": [0.5, 0.5],
            "SizeMultRange": [1.0, 1.1],
            "Duration": 2.0,
            "EasePower": 3,
            "BlendFactor": 0.35,
            "FadeInRange": [0.0, 0.3],
            "OnTop": true
          },
          "Shaders": {
            "Type": "Default",
            "EmissiveColor": "#110000",
            "EmissiveMultiple": 1.0,
            "SpecularColor": "#FFDDDD",
            "SpecularStrength": 1.1,
            "Glossiness": 120.0,
            "RefractionStrength": 0.0,
            "SubSurfaceLightRolloff": 2.0,
            "RimLightPower": 0.5,
            "Alpha": 1.0
          }
        }
      ]
    }
  ]
}

📌 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 DynamicBloodpoolFramework.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.