View source for Creating and Using Custom Debris

{{RF1Tutorial|Goober (with information provided by rafalh)}}

Custom debris provides a way to make new [[RED Objects#Clutter|clutter]] meshes and [[RED Objects#Entity|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 [[Rafalh RF Tools#VMesh|VMesh]] tool for converting it to an RF-compatible format. If you're using the [[Official RF Toolkit#3ds Max Plugins|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 [[Rafalh RF Tools#VMesh|VMesh]], run the conversion command: <code>vmesh MESHNAME.gltf</code>
*'''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.

<blockquote>
$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"
</blockquote>

'''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.

[[Category: Red Faction]]
[[Category: RF1 Editing]]
[[Category: Tutorials]]