Ricochet - Arrow Physics Framework - API Usage

Table of Contents

• Introduction
• Prerequisites
• Location of JSON Files
• Ammo Mapping
• Fracture Mapping
• Fracture Mapping - Filters
• Fracture Mapping - Modifiers
• Testing in the Game

📌 Introduction

Ricochet - Arrow Physics Framework is a modular system that lets mod creators define custom behaviors, visuals, and sounds for projectiles upon fracture. It provides a simple but flexible JSON-based mapping API to control how each arrow or bolt reacts when hitting different materials or objects.

Creators can assign durability values, fracture probabilities, and sound or impact effects to any projectile type. Filters and modifiers allow fine-grained control based on weapon type, ammunition, material, impact velocity, or even global conditions.

In short, the Ricochet Framework provides a flexible and fully configurable foundation that allows any mod to add fracture behavior to its arrows or bolts, without requiring a direct dependency on the framework.

🔹 Available Filters

Filters let you control when and how arrows or bolts break, based on simple criteria:

• Global factors: Game variables, percentage, material, keywords.
• Weapons & projectiles: Specific bows, arrows, or generic types.
• Impact conditions: Velocity, power, or whether the arrow hits an actor, an object or a surface.

These filters make it easy to customize fracture behavior for different situations.

🔹 Modifiers

Modifiers control the visual and sound effects when arrows break. You can choose which effects play, add extra sounds, or spawn broken arrow pieces.

• Custom sound effects for breaking arrows.
• Extra visual effects or debris.
• Control whether arrows stick or bounce.

With filters and modifiers, you can make arrow impacts feel varied, realistic, and immersive.

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

📌 Location of JSON Files

The JSON files should be placed in Data/SKSE/RicochetFramework. 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 (or sub-folder), everything is fine. The rest is up to you! ✅

📌 Ammo Mapping

AmmoMapping defines how a specific arrow or bolt behaves when it breaks. Each entry specifies the original projectile (ammunition), its durability, the broken item it produces, and the possible broken states with associated effects.

Example: Defining a custom broken state for Falmer Arrows.

{
  "AmmoMapping": [
    {
      "ID": "FalmerArrow",
      "AmmoBase": "Skyrim.esm:0x38341",
      "AmmoBroken": "Broken Feathers.esp:0x809",
      "Durability": 20.0,
      "BrokenStates": [
        {
          "Chances": 50.0,
          "ProjectileSwap": "Broken Feathers.esp:0x827"
        },
        {
          "Chances": 50.0,
          "ProjectileSwap": "Broken Feathers.esp:0x828",
          "ExtraProjectiles": ["Broken Feathers.esp:0x829"]
        }
      ]
    }
  ]
}

🔹 Properties

"AmmoBase": "Skyrim.esm:0xCEE9E"

"AmmoBroken": "Plugin.esp:0x800"

"Durability": 25.0

"BrokenStates": [
  {
    "Chances": 50.0,
    "ProjectileSwap": "Broken Feathers.esp:0x827"
  },
  {
    "Chances": 50.0,
    "ProjectileSwap": "Broken Feathers.esp:0x828",
    "ExtraProjectiles": [
      "Broken Feathers.esp:0x829"
    ]
  }
]

With Ammo Mapping, mod creators can add fracture behavior and custom visual effects to any arrow or bolt, fully configurable and without creating hard dependencies on the Ricochet Framework.

📌 Fracture Mapping - Structure and Functioning

{
  "FractureMapping": [
    {
      "Priority": 10,
      "Override": false,
      "Filters": {
        "Ammunitions": ["Skyrim.esm:0x38341"]
      },
      "Modifiers": {
        "Fracture": true,
        "AmmoID": "FalmerArrow"
      }
    }
  ]
}

FractureMapping is an array in your JSON file that defines the conditions under which arrows or bolts can break upon impact. Each entry specifies filters that determine when a fracture may occur and, if triggered, which configuration from AmmoMapping should be used to handle the resulting behavior.

This link is established through the AmmoID field, which directly corresponds to the ID value defined in an AmmoMapping entry. When a projectile meets all the fracture conditions, the framework automatically applies the associated AmmoMapping, allowing you to define what broken model to spawn, and whether additional effects or projectiles should be generated.

The elements of FractureMapping are:

• Priority: Sets the evaluation order. Higher numbers are processed first.
• Override: Determines whether this entry replaces or merges with lower-priority entries.
• Filters: Conditions that must be satisfied for the fracture to occur.
• Modifiers: Actions that are applied when all filter conditions are met.

📌 Fracture Mapping - Filters

Each filter represents a condition that must be satisfied for the modifiers to be applied. You only need to define the filters you intend to use; it is not required to declare all of them. Filters within the same group are inclusive, meaning all specified filters in that group must be satisfied simultaneously for the effect to trigger.

However, within the arrays of each filter, the values work in OR: For example, if a weapon filter lists multiple specific weapons in the Weapons array and you define multiple projectiles in the Projectiles array, the effect will only apply when at least one of the listed weapons is used and that weapon must have shot at least one of the listed projectiles to satisfy the condition.

The only exception to this OR system is for Global Variables, which must all be validated for the filter to be considered fulfilled. In other words, if multiple Globals 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 RicochetFramework.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]
]

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

"WeaponKeywords": ["WeapTypeBow", "Plugin.esp:0x800"]

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

"AmmunitionKeywords": ["VendorItemArrow", "Plugin.esp:0x800"]

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

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

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

"Percentage": 25.0

"MinPower": 0.5

"MaxPower": 1.0

"MinVelocity": 1000.0

"MaxVelocity": 1500.0

"ArrowSticks": true

"IsActor": true

📌 Fracture Mapping - Modifiers

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

"AmmoID": "ArrowIron"

"Fracture": true

"ImpactBounce": true

"ImpactSound": "Plugin.esp:0x800"

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

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

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