Creating and Using Custom Debris

Custom debris provides a way to make new clutter meshes and entities added by mods feel more present and interactive in your world.

Firstly, let's differentiate between two terms that are often used interchangeably: debris and corpse.
 * Corpse - In RF, this refers to a mesh that replaces a clutter or entity mesh when that object dies. Dead bodies lying on the floor and destroyed computers are examples of corpses.
 * Debris - In RF, this refers to the chunks that fly out from a clutter or entity mesh when that object dies. A good example of debris is the crunched up oil drum that flies away from the point of impact when you shoot an oil drum clutter object.

This tutorial will cover how to create, import, and configure custom debris.

Creating and Importing
For the purposes of this tutorial, I'm going to assume you're using Blender for modeling and rafalh's VMesh tool for converting it to an RF-compatible format. If you're using the 3ds Max Plugins in the official RF toolkit, the steps for creating and importing the debris mesh will be different, but configuration is the same.
 * Step 1. When your debris explodes in game, each submesh in your scene is going to fly in the direction it is positioned relative to the origin of the scene (0,0,0). If you want a chunk to fly upward when a clutter mesh dies for example, position that chunk submesh just above the origin in your scene.
 * NOTE: It's important to not position any submeshes at the origin. Doing so will cause them to never appear in game. Each submesh should be offset from the origin in whichever direction you wish for it to fly.
 * Step 2. Ensure your mesh has no armature or animations - debris meshes are static meshes (.v3m).
 * Step 3. Export your scene as .gltf from Blender.
 * Step 4. Using VMesh, run the conversion command:
 * Step 5. Take the resulting .v3m static mesh file and pack it with your mod.

Configuring
I'll cover configuring debris for clutter, but the process is essentially identical for entities (aside from having to be configured in entity.tbl rather than clutter.tbl, of course.)

Looking at the clutter.tbl entry for Waste Basket (a default clutter class in the game), below in bold are the relevant entries for our purposes. Note that these are all optional settings, so your clutter class may not already have them. If that's the case, you'll need to add them. I've explained each of these options below - all of them can be customized, but if you just want a quick way to get debris working in-game, feel free to copy these settings from the Waste Basket below and just change the $Debris Filename to your mesh.

$Class Name:          "Waste Basket"

$V3D Filename:        "wastebasket1.V3D"

$Debris Filename:     "wastebasket1.V3D"

$Debris Sound Set:    "Tin Hit"

$Material:            "metal"

$Life:                10

$Explode Anim:        "Tin Hit Sound"

$Explode Anim Radius: .4

$Flags:               ("collide_object")

$Debris Velocity:     6

$RFE Level1:          "Office Stuff"

Configuring your debris:
 * Step 1. Specify a $Debris Filename. This will be the v3m filename of your debris mesh from earlier in this tutorial.
 * Step 2. Specify a $Debris Sound Set. This controls the sound your debris makes when colliding with the world. It must reference an existing foley class from foley.tbl
 * Step 3. Specify an $Explode Anim. This determines the explosion that actually pushes your debris submeshes apart. It must reference an existing vclip class in vclip.tbl. (it should be a VClip class with the "code_explode" flag)
 * Step 4. Specify an $Explode Anim Radius. Self-explanatory, the radius of the vclip as specified in the above line.
 * Step 5. Specify a $Debris Velocity. Self-explanatory, the velocity at which debris submeshes fly out from the origin of your clutter object.
 * Step 6. Ensure your clutter's $Life value is set to a value other than -1 (invulnerable). Debris is only used when an object is destroyed, so you'll never see it if your object is invulnerable.