Official RF Toolkit

From Red Faction Wiki
Revision as of 18:40, 6 November 2020 by Goober (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search
Rededitlogo1.jpg This page is part of the Red Faction Editing Knowledgebase
Editing Main Page


The Official RF Toolkit is a collection of standalone utilities and 3ds max plugins used to create content for Red Faction. These are some of the same tools used by Volition in the creation of the game.

You can download the Official RF Toolkit here: [Download]

CCrunch

Captain Crunch (CCrunch) is a standalone command-line utility included in the Official RF Toolkit that does three things:

  • converts .v3d files into .v3m files (Static Meshes)
  • converts .vcm files into .v3c files (Skeletal Meshes)
  • creates .vpp packfiles out of regular datafiles

Usage

Static Meshes

Static mesh files exported from 3ds Max via the RF Toolkit Plugins are .v3d files. These need to be converted into .v3m files before Red Faction can load them.

The command-line syntax for this conversion is:

ccrunch.exe FILENAME.v3d

Where FILENAME is the relative path & filename of your .v3d file. If you specify no path, it will assume the same directory you’re running it from. The resulting .v3m file will be placed in the same directory as the source file. The output spew for this process is confusing at best, but if it created the file and you don’t see the word “ERROR” anywhere in the spew, you’re good to go.

Skeletal Meshes

Skeletal meshes are used for characters and first person weapons. They are exported from 3ds Max via the RF Toolkit Plugins are .vcm files. These need to be converted into .v3c files before Red Faction can load them.

The command-line syntax for this conversion is:

ccrunch.exe FILENAME.vcm

Where FILENAME is the relative path & filename of your .vcm file. If you specify no path, it will assume the same directory you’re running it from. The resulting .v3c file will be placed in the same directory as the source file. The output spew for this process is confusing at best, but if it created the file and you don’t see the word “ERROR” anywhere in the spew, you’re good to go.

VPP Packfiles

.vpp packfiles must be used for any data modification in Red Faction PC. This goes for levels, .tbl files, models, textures, everything. If it’s not inside a .vpp file, the game will not recognize it.

Building .vpp packfiles with CCrunch is pretty straightforward. The command-line syntax is like so:

ccrunch.exe <output VPP filename> <input TXT filename>

A text file list of individual files to include in the .vpp must be specified. You can make the .txt file with Notepad, or any other text editor. A sample .txt input file might look like this:

data\effects\lights\LightBeam02.tga
data\maps\skins\enviro_guard_face_b-mip1.tga
data\levels\single\L11S3.rfl
data\levels\single\L12S1.rfl
data\audio\music\ambience\*
data\audio\music\game\*
data\audio\music\menu\*

One file per line. The pathname must be relative to the directory you run CCrunch from. Note, wildcards are permitted, as shown in the “music” lines above. This feature of CCrunch is designed for massive, automated .vpp building. If you're only packing a few stray files, it might be better to use one of the other RF Tools.

MakeVBM

MakeVBM is a standalone command-line utility used to create .vbm files for use in Red Faction 1. These are animated or single-frame 2D bitmaps, in a proprietary Volition format. Volition's MakeVBM program is included in the Official RF Toolkit.

In 2020, rafalh released his own completely rewritten version of MakeVBM, which adds many enhanced features over the original. This enhanced tool uses the same syntax as the Volition tool, adds additional functionality, and retains all functionality of the original.

Key improvements in rafalh's enhanced MakeVBM are:

  • Support for high resolution image files
  • Support for many common image formats as input (.jpg, .png, .dds, etc.), rather than only .tga like the Volition tool

Usage

The source input for MakeVBM is one or more image files, either 24 or 32 bit with alpha, in a supported image file format. A list of supported image file formats is available here.

The first step is to get your image files in one place, and name them correctly. MakeVBM requires sequences to be named like so:

name-0000.tga
name-0001.tga
...
and so on.

“name” can be any prefix you like, but it must be followed by the “-XXXX” ending. Once you have your files together, decide what color format your VBM will use.

While all VBMs use 16 bits of color, that 16 bits can be broken down several ways. The output VBMs can be in one of four color formats. The numbers represent the ARG and B channels (alpha, red, green, and blue).

4444 4 bits for each RGB channel, 4 bits for alpha. Use this format when you want a full, varied alpha channel with semi-transparency.
1555 5 bits of color for the RG and B channels, 1 bit for alpha. Use this when you have alpha, but it’s only the “on/off” variety. Pixels are either totally opaque or totally transparent. Useful largely for interface art.
565 5 bits of alpha for the R and B channels, 6 bits for Green, and zero for alpha. Use this when the image needs no alpha transparency at all.

Next, decide what framerate the animation will need, measured in frames-per-second.

When you’re ready, open a command prompt window, make sure “makevbm.exe” is on your path, and go to the directory where your frames are located. Then type:

makevbm <colormode> <framerate> <prefix>.tga

Where <colormode> is either 4444, 1555, or 565, <framerate> is an integer like 15 or 30, and <prefix> is the first part of your sequence filenames, minus the “-XXXX” suffix.

The Red Faction invulnerability overlay effect is a .vbm using 565 color mode at 8 frames per second. To create that file from its frames, I would type:

makevbm 565 15 pow.tga

This would create “pow.vbm”, which the game can now use.

When everything is run correctly, the output spew looks like this:

MakeVBM Output

FontTool2

FontTool2 is a standalone command-line utility used to convert properly-formatted .tga images into .vf font files for use in Red Faction.

Usage

Basic Usage

In order to create a source .tga, you will need a paint program that supports 32-bit images with an alpha channel (Photoshop, Paint Shop Pro, etc). The first thing to note is that Red Faction uses the ANSI character set, not ASCII. The set coding determines in what order characters appear in the “chart”. Here is a list of ANSI character codes, and their characters:

ANSI Character Codes

Red Faction fonts must start at the first entry, 32, which is the space character. The .vf files that ship with the game include every character from 32 to 126, and also any characters marked in green or violet in the above chart. Green characters are included as-is, while violet are used for special symbols and don’t match the characters shown in the above chart.

An example formatted source file is provided (rfpc-medium.tga) in the Official RF Toolkit. This example includes each character, starting from ANSI 32, through the diacritics characters needed for German and French, ending with ANSI 252. It looks like this:

rfpc-medium.tga: example FontTool2 source file

Note that while there’s a “cell” for every character from 32 to 252, there isn’t a character in every cell. Some are empty, one-pixel wide slots. In your font, you can skip as many characters as you like, but you must include an empty cell for each of them. You can see the basics of how to create a font just by looking at the PSD file. Every character sits in a cell, every cell is made up of a 1-pixel, full green border.

Here are the basic rules for creating the source .tga:

  • Cells must start with ANSI 32 (the space character), but can end on any ANSI cell.
  • You must not skip cells. If you wish to not include a character, you need to include an empty cell for it, at least one pixel wide.
  • The green borders that make up the cells must be one-pixel in width on all sides, and must be full green (0, 255, 0).
  • Rows of cells can be broken anywhere, but at least one black pixel row must seperate each row of cells.
  • All cells must be the same height.
  • Cells can be varying widths, to match the size of each particular character. One black pixel should be included on the right side of each character. This extra space is what determines the default spacing, or “kerning” between that character and the next one.
  • You must have an alpha channel. See “rfpc-medium.tga” for an example of how the alpha channel should be used.
  • Non-black pixels in the alpha channel must not overlap the green border pixels in the RGB channels.

The example .psd, as it appears, is not ready to make a source .tga just yet. The way it’s shown is how it’s most easily edited, however, with layers for the black background, the characters, and the green borders.

Before saving it out as a .tga, copy the characters channel into the alpha channel, and floodfill the characters channel with full white. Since the alpha channel is what determines the actual shape of the characters, the RGB channels should be full intensity white (except the green borders) to make sure the characters are evenly colored. See rfpc-medium.tga for an example of how it should look.

Once you have the .tga saved out (use 32 bits, not 24), you’re ready to run it through FontTool2.

Open a command prompt window and go to your \fonttool2\ directory. Type the following:

fonttool2 FILENAME.tga

Where “source.tga” is the name of the .tga file you saved out. If everything worked, it should spit out a bunch of output, and end with something that looks like this:

FontTool2 output

If you get any sort of error message, something isn’t right with the source .tga. A common cause of errors is non-black alpha pixels underneath the green borders. If this occurs, or if your green borders aren’t connected correctly, it will give you coordinates where the problem is. Once things are straight, you’ll get a source.vf file (named however you named the .tga file). This is what the game actually loads.

Advanced Usage

Once you’ve played with making fonts, you may wish to change the kerning information. Kerning is what determines how far apart one character appears from the next. In proportional fonts like the ones seen in RF, some characters look too far from others unless you modify the kerning data. A good example of this is a T followed by a J. You may want to make the J overlap the T just a little.

Do edit the kerning data on your .vf file, go to your \fonttool2 directory and type:

fonttool2 FILENAME.vf

Where “source.vf” is the name of your .vf file. This will start the interactive kerner in FontTool2. With this you can alter the spacing between any two characters in your font, on a case-by-case basis. Instructions on how to use the interactive kerner should appear onscreen.

MVFReduce

MVFReduce is a tool that reduces the amount of keyframes in .mvf animation files. It doesn’t remove all of them, but it removes keys along a curve that aren’t necessary. It’s necessary to use MVF Reduce, as animation files can get large and won’t always fit into memory. MVF Reduce works by replacing adjacent keyframes that are "similar" to one another with a single keyframe. Adjacent keyframes that are within a certain tolerance limit of one another are considered "similar" and can therefore be merged.

Usage

Copy mvfreduce.exe into the directory containing your .mvf file(s), then open a command prompt window and run the following command:

mvfreduce -m MORPHREDUCTION –d ROTATIONREDUCTION –e POSITIONREDUCTION FILENAME.mvf
  • -m : (Optional) Float value as input, determines the keyframe reduction of morphing vertices. The lower this number, the less reduction is applied. Defaults to .005 if no float input value is provided.
  • -d : Float value as input, determines the rotational keyframe reduction. The lower this number, the less reduction is applied. Volition's recommendation is to use .00007, unless it is necessary to reduce more to fit into memory.
  • -e : Float value as input, determines the positional keyframe reduction. The lower this number, the less reduction is applied. Volition's recommendation is to use .00007, unless it is necessary to reduce more to fit into memory.
  • -a : (Optional) If you don't want to specify a specific .mvf filename to apply the reduction to, you can instead use the -a switch to apply the specified reduction to all .mvf files in the current directory.

NOTE: Do not run MVFReduce twice on the same file, as it will reduce an already reduced file. Re-export the animation file first.

3ds Max Plugins

  • NOTE: All included 3ds Max plugins require version 4.2 or 5.x of 3ds Max. They will not work on earlier or later versions.

VBMImporter

VBMImporter allows 3ds Max to read and display .vbm bitmap files. When you install this plugin, you'll get a VBM Importer (*.vbm) option in any 3ds max dialog that takes bitmap files as input. You can use this to assign .vbm bitmaps directly to models through the Material Editor. Animated .vbm files will correctly animate in the Material Editor as well.

Installation:

  1. Copy VBM_importer.bmi into the plugin directory. Example: “\3dsmax4\plugins\”
  2. Make sure this directory is in your plugin paths for Max. Check this in Max under Customize/Configure Paths/Plugins/
  3. Restart 3ds Max

VParticle

VParticle adds a new Particle emitter type to 3ds Max, called VParticle. This plugin is solely for use in .vfx files used in Red Faction. It’s not fully supported as a standard “renderable” particle type in 3ds Max, so do that at your own risk.

Installation:

  1. Copy vparticle.dlo into the plugin directory. Example: “\3dsmax4\plugins\”
  2. Make sure this directory is in your plugin paths for Max. Check this in Max under Customize/Configure Paths/Plugins/
  3. Restart 3ds Max

You can find the VParticle object under the Create panel, in the Geometry/Particle Systems category. Create it just like any other 3ds Max emitter.

The supported parameters for VParticle appear in its Modify dialog, just like other emitters. Most of the parameters are self-explanatory, or match those of other Max emitters. The VParticle-specific stuff is as follows:

  • Drops/Facing: These are the two types of VFX particles supported by Red Faction. Facing is the default type, and uses camera-facing bitmaps onscreen. Drops are untextured, triangular shapes used for sparks, water drops, etc. Unlike other VFX objects, Drop particles do not require a texturemap in their Diffuse channel. Instead, the material’s Diffuse color is used.
  • Tail Distance: Used only for Drop particles. Determines how “long” each drop is.
  • Shrink at birth: When set above 0.0, causes particles to “grow” from nothing, reaching full size at the frame indicated by this percentage multiplier value. Example: particle life is set at 30, and Shrink at Birth is set to 0.2. From frame 0 to frame 6, the particles will grow from size zero up to the size specified in Particle Size, reaching full size at frame 6.
  • Shrink at death: Same as Shrink at Birth, but operates at the end of the particle’s life.
  • Fade at Birth/Death: Similar to Shrink at Birth/Death, but causes the particle’s opacity to fade in/out based on the timing values. Unless the Shrink values are used as well, particle size is not affected by this.
  • Fast Particles: When enabled, tells the game to use the more optimized “fast particle” system instead of the default particle renderer. This was largely a feature for the PlayStation 2 version of RF, and has little effect on the PC renderer. Some options my be unavailable/greyed-out when this is enabled.
  • Apply Gravity: When enabled, does automatic gravity on the emitted particles, along the global “down” axis in Max.
  • Randomize Orientation: Randomly orients each particle’s bitmap, to prevent strobing. Only supported for Facing particle types.
  • No Cull: Forces particle rendering even if the emitter is offscreen. It’s highly recommended that you keep this off, as enabling it is expensive.

That’s basically it. If you have a VParticle emitter selected during a .vfx file export, all the parameters will be written out into the .vfx file. Note, the “scale” and specific shape of particle emissions will vary a bit from Max to RF. Some tweaking of values is often necessary.

See VFXExporter for more information on exporting .vfx files.

V3DExporter

V3DExporter is a 3ds Max plugin which allows you to export meshes into the Volition .v3d format. These files are used for static meshes like clutter, powerups, etc.

.v3d files are not directly loadable by Red Faction. Before they can be used, they must be run through the CCrunch utility to be converted into .v3m files.

Installation:

  1. Copy v3d_exporter.dle into the plugin directory. Example: “\3dsmax4\plugins\”
  2. Make sure this directory is in your plugin paths for Max. Check this in Max under Customize/Configure Paths/Plugins/
  3. Restart 3ds Max

Exporting

  1. Scale your model correctly in 3ds Max. Red Faction uses meters for measurements, so you should keep this in mind when scaling your model.
  2. Center the mesh at the world origin in 3ds Max. To do this, select it, and right click the "select and move" icon on the toolbar. A "Move Transform Type-In" dialog will come up. Enter 0.0 for all 3 axis under Absolute:World.
  3. Select the model, then from the File dropdown menu, choose "Export...". Under "Save as type", choose RF Mesh - V4.32 (*.V3D) and save the mesh to the desired directory.
  • NOTE: .v3d and .v3m files do not include textures. You must include any textures used by your mesh separately in your packfile/project.

VFXExporter

VFXExporter is a 3ds Max plugin which allows you to export meshes, lights, and other supported objects into a .vfx effects file for Red Faction. .vfx files are used for any visual effect that can't be achieved through other means. If you have non-.vfx solutions to something you want to show, via RED or through .tbl files, you should probably try that approach first.

.vfx files do provide some features not supported elsewhere. An example of this is powerups. Nearly all the powerups seen in multiplayer RF are .v3m static meshes, much like other items. There are a few exceptions, like the flags in CTF games. Since those use cloth-like deforming animation, .vfx effect files are used instead of .v3m static meshes. Another example is cutscene08, which shows the shuttle lifting off in the single-player game. Since it involved multiple, non-character objects moving along a path, a big .vfx was definitely the way to go. The 3ds Max source files for both the CTF flag and shuttle cutscene examples are included in the Official RF Toolkit download: Cutscene08.max & CTFflag-red.max

There’s no step-by-step instructions for these files, but a lot can be learned simply by looking at them. Make sure to look at the User Defined Object Properties of the objects in those scene files. The usage of flags there (as discussed below) are central to how .vfx effects work. The .vfx system is pretty complicated, and this doc won’t cover everything.

Installation:

  1. Copy vfx_exporter.dle into the plugin directory. Example: “\3dsmax4\plugins\”
  2. Make sure this directory is in your plugin paths for Max. Check this in Max under Customize/Configure Paths/Plugins/
  3. Restart 3ds Max

There’s four types of objects supported by the .vfx system:

  • Static meshes
  • Morphed meshes
  • Lights
  • Particles

Materials and Textures

  • Materials assigned to meshes or particle emitters need to have the texturemap assigned in the Diffuse Map channel for the game to recognize it. This can be either a 24 or 32 bit .tga file, a Volition .vbm file, or a .dds file (Dash Faction only).
  • Multi-Subobject Materials are supported.
  • Blinn is the only Shader with .vfx export support. Other shaders may work, but they're not guaranteed.
  • Self-illumination and Opacity are both supported. The two values in the Basic Parameters rollout will both be exported normally into the .vfx. Opacity, additionally, may be keyframe-animated with the standard Bezier Float controller.
  • Additive transparency is supported for bright objects like thruster glows, light coronas, etc. To mark a material as additive, open its Extended Parameters rollout. Under Advanced Transparency, there’s a Type radio with choices for Filter, Subtractive, and Additive. Change it to Additive. Filter is the “normal” opaque blending method. Subtractive is not supported.

Any material parameters/animation not mentioned above are unsupported.

Static Meshes

  • These are non-deforming meshes like a spaceship, a rock, a vehicle. Static meshes do not need any special flags or parameters to be exported into a .vfx. They do need mapping coordinates on all faces.
  • Any mesh with Position or Rotation animation keyframes will animate in the game, as expected. Position must use the default Bezier Position controller, and Rotation must use the TCB Rotation controller. Scale animation may or may not work (Volition has indicated that this functionality may have been removed for optimization reasons).
  • Hierarchy links are not directly supported by the .vfx system. If you export a mesh that’s linked to another mesh in a hierarchy, it is automatically treated as a “morphed mesh” (see below). Morphed meshes are more expensive than static keyframed meshes, so be careful.
Static Mesh Flags

There are special exporter features that can only be used via the User Defined Object Properties in Max. To view an object’s User Defined flags, right-click it and choose Properties. Under the User Defined tab, there will be a list of any flags assigned to that object. Flags must appear one-per-line in that text field. Here’s what’s supported for Static Meshes:

  • fullbright: This tells the game to not apply darkening to this mesh. Essentially the same as giving its material a 100% self-illumination value.
  • facing: This is used for “billboard” meshes. Any glow or corona you want to face the camera all the time needs to have this flag.

Morphed Meshes

Any mesh that requires vertex-based animation (like waving flags, pools of churning lava, etc) need to be treated as morphed meshes, rather than static. The waving team banners seen in some of the Volition-made CTF levels are morphed meshes. Instead of having their vertices stored once in the .vfx, with a simple list of animated position & rotation keyframes like static meshes do, morphed meshes store whole vertex sets inside the .vfx file. This is done at a variable framerate, depending on the user defined flags for that mesh. Animating the vertices for a .vfx morphed mesh can be done using any tool available to you in Max. This can include an animated FFD modifier, Max morphing, noise, SimCloth, basically anything.

In addition to making large .vfx files, morphed meshes are very expensive for the game to process. Only use these when absolutely necessary, and use them in moderation.

Morphed Mesh Flags

There are special exporter features that can only be used via the User Defined Object Properties in Max. To view an object’s User Defined flags, right-click it and choose Properties. Under the User Defined tab, there will be a list of any flags assigned to that object. Flags must appear one-per-line in that text field. Here’s what’s supported for Morphed Meshes:

  • morph: This is the main flag, telling the exporter to treat this as a morphed mesh rather than a static one. This parameter is automatically assumed if the mesh is linked to another.
  • fps=VALUE: This tells the exporter how many samples-per-second to use when dumping out the morphed vertex positions for that mesh. VALUE must be an integer. If no fps flag is present, it will assume 15, which can result in some pretty large .vfx files. Rarely do you need an fps value above 5-7. Slower objects can tolerate much lower numbers.

Particles

In addition to the table-driven particle system used in RF PC, you can also use emitters inside .vfx files. You must use the VParticle Max plugin for this to work, however. The .vfx exporter won’t recognize any other particle emitter types.

Lights

Only Max lights of type “Omni” are supported. The following Omni light parameters are supported for .vfx export:

  • On/Off: Simple checkbox indicating the on/off status of the light. Not animatable.
  • RGB Channels: Determines intensity and color of the light. I believe animation is supported for these.
  • Multiplier: A global brightness value, with animation support. Only values from 0.0-1.0 are supported.
  • Far Attenuation: The Start and End values are both supported, if the “Use” checkbox is enabled. Volition has indicated that the .vfx system likely assumes this is on.

All other Omni light parameters are unsupported and ignored when exporting. Animated position for Omni lights is supported, however, just like a mesh.

Exporting

When you have all objects ready for export in Max, here is all you need to do:

  1. Select all objects you wish to export (static/morphed meshes, lights, VParticle emitters). Objects not selected will simply be ignored.
  2. Under File, choose Export.
  3. In the “Save as Type” drop-down, choose “VFX – V 4.6 (*.VFX)” filetype.
  4. Save the .vfx with a name of your choosing.

There are a number of error messages you may get during export. They should provide basic information on any problems you have in your scene. Unlike .v3d and .vcm files, .vfx files do not need further processing through CCrunch or any other utility - they can be loaded directly by the game, assuming they’re located in the proper place.

  • NOTE: Like any other RF model file, .vfx files do not include textures. You must include any textures used by your mesh separately in your packfile/project.

RFBone

RFBone is a 3ds Max plugin that allows you to rig, animate, and export custom skeletal meshes for use in Red Faction. Generally, skeletal meshes are used for characters and first person weapons.

Installation:

  1. Copy rf_bone.dlm into the plugin directory. Example: “\3dsmax4\plugins\”
  2. Make sure this directory is in your plugin paths for Max. Check this in Max under Customize/Configure Paths/Plugins/
  3. Restart 3ds Max

Using RFBone

Rules
  1. Scale your mesh, and center its pivot point. This center of the mesh should be at 0,0,0 in the Max file.
  2. Make sure you reset the transform of your mesh after you scale it to the right size.
  3. There can be nothing else in the stack of the mesh
  4. Never, ever ever ever after setting up a character in RF Bone, should you change the name of your bones or the names inside the RF Bone modifier panel. This could break the setup, and if code is using a bone name as reference for anything, it will cause that to not work. (As a note, if you DO accidentally change a bone name in RF Bone, just figure out what it was and retype it in by hand).
  5. There is a 50 bone limit for RFBone. NO character can have more than 50 bones. It won’t work. At all.
Naming Conventions for FK Bones

All FK bones have a similar naming convention. I will list what all bones should be, with the “XXXX” being the four letter code unique to each character. There has to be a four letter code unique to each character in front of each bone name. For example, the Ultor Suit’s code is ULT1. Here are the bones for that mesh:

Bone Name: What it is:
XXXX-BDBN-Fingers-L01, 02, 03, etc. Fingers on left hand.
XXXX-BDBN-Fingers-R01, 02, 03, etc. Fingers on right hand.
XXXX-BDBN-Foot-L Left Foot
XXXX-BDBN-Foot-R Right Foot
XXXX-BDBN-Hand-L Left Hand
XXXX-BDBN-Hand-R Right Hand
XXXX-BDBN-Head Head
XXXX-BDBN-LowerArm-L Left forearm
XXXX-BDBN-LowerArm-R Right forearm
XXXX-BDBN-LowerLeg-L Left Calf (between knee and ankle)
XXXX-BDBN-LowerLeg-R Right Calf (between knee and ankle)
XXXX-BDBN-Root Root Bone
XXXX-BDBN-Pelvis Pelvis
XXXX-BDBN-Spine01, 02, 03, etc. Spine Bones. 01 is closest to root, on up.
XXXX-BDBN-Thumb-L Left Thumb
XXXX-BDBN-Thumb-R Right Thumb
XXXX-BDBN-UpperArm-L Left bicep/tricep
XXXX-BDBN-UpperArm-R Right bicep/tricep
XXXX-BDBN-UpperLeg-L Left thigh
XXXX-BDBN-UpperLeg-R Right thigh

These naming conventions are set in stone. Use them as a rule so that ALL character setups are similar. It’ll help you in the long run. Any extra bones needed for any particular setup, name accordingly (a rocket launcher on the left shoulder would be something like “XXXX-BDBN-Rocket-L” or something). Some of the listed bones won’t be needed. Thumbs, fingers and shoulders won’t be used for many characters. Don’t make them if they aren’t needed, try to use as FEW bones as possible (while keeping enough to animate properly). More bones means more memory used. I would keep a setup around 25 bones. There is generally no need for more than that.

Making an FK Chain
  1. Select the Mesh and scale it to the proper size. This is VERY important, as once you set the character up in RFBone there is no scaling allowed. Once it’s scaled, you MUST reset the transform through the utilities panel.
  2. Collapse to Editable mesh, make it a selection set called “XXXX-Mesh”, and freeze it.
  3. Make boxes to create the bones for the character. See the Max file for an example, or use those already created bones for your own. If you are creating new bones, apply edit mesh to all bones and collapse the stacks. Then reset the transforms of the bones, and collapse them again so that they are editable meshes. If you are using the supplied bones from the sample Max file, there is no need to do that.
  4. Once you have them all set, you get to use edit mesh 2 (or edit mesh)! DO NOT, under any circumstance, use the scale tool for this. You MUST use edit mesh to resize/reshape the bones to match the new character mesh. Get it as close as possible, because these bones are going to represent this mesh while you animate. Remember where your pivot points are, and restrict the shape of the bones to not become too deceiving.
  5. Make any new bones for extra parts of the character, if they are needed. If they are part of the spine (i.e., an animatable rocket pack), copy a spine bone to keep the same pivot point orientation. The same with any other part, copy whatever bones it relates to the most, and reshape/resize it.
  6. Once you have all the pieces resized/reshaped, link them up FK style (don’t reset transform ANY of these bones, they have pivot points set up that would be bad to ruin). The legs should end at the pelvis, which links to the root. The arms and head link to the topmost spine bone, which links in order down to the lowest spine bone. The lowest spine bone links to the root.
  7. Rename the bones to what they should be. Follow the bone naming chart above. Also rename any new bones you made yourself. Now select all the FK bones, and make them into a selection set called “XXXX-FKBones-All”.
  8. Make keyframes for ALL FK bones at frame zero and frame 1. Use trackview to select all the keyframes on both frames, and make the position keys linear and the rotation keys have continuity of zero. Check to make sure everything rotates properly.
  • IMPORTANT: Make sure you keep frame zero at the character’s rest pose. THIS IS VERY IMPORTANT. If you have to add a bone or add tags later, or do ANYTHING to the mesh in ANY animation file, this frame is where you would do it, since it will remain consistent throughout all the files.
Setting up a Character
  1. Unhide/unfreeze your FK Bones and your Mesh.
  2. Select your mesh.
  3. Apply the RF Bone modifier.
  4. In the RF Bone modifier, go to the “Mesh Parameters” list, and click “Add Bones”
  5. Select ALL the FK bones. This will list the FK bones in the RF Bone channels. Most characters shouldn’t have more than 20-25, some will.
  6. Each Channel can be selected by clicking on the name. If you want to select more than one, hold down the control key while selecting.
  7. Weight the vertices. The weighting is from 0 to 100, 0 being the lowest and 100 being the highest. If you want to select vertices that are already weighted to a bone, hold down the shift key and select the bone.

After you have weighted all the vertices, freeze the mesh and rotate/move the mesh around. Use only the root bone to move the whole character (this should be the only bone with translation keys). Rotate joints, make sure it looks nice. DON’T scale bones. RF Bone doesn’t like it.

HINT: You can setup a “test pose” animation with frame 0 being the default setup pose and frame 30 being a pose with all the joints bent. Then you can just scrub the time slider while you’re still setting up the character to see how things deform and make changes.

Setting up LODs

LODs are “Levels of Detail” models. They are basically the same character with lower geometry. If you want them for your character, you’d basically polychop your model, reset the transform, and follow the same setup instructions as the higher resolution mesh. When you export the .vcm, you named it XXXX_b.vcm for the middle resolution mesh, and “XXXX_c.vcm” for the lowest resolution mesh. “XXXX” is the name of the original .vcm. (i.e., masako.vcm would have masako_b.vcm and masako_c.vcm)

Using BIPED

If you want to use Biped to animate with, follow these steps. Please keep in mind that not all robots will be able to use Biped. If a robot has part on their arms that translate along an axis, don’t use Biped. But if they are a typical humanoid with arms and hands, use Biped. (NOTE: There may be cases where you can and want to mix Biped with custom FK bones, see step 9). ONLY BEGIN THIS STEP IF YOU HAVE ALREADY SETUP YOUR CHARACTER WITH RFBONE. You cannot use Biped bones as your bones for setting up a character. They must be FK Bones.

  1. Hide Mesh, Unhide FK bones and freeze them.
  2. Make a Biped with the right amount of bones.
  3. In figure mode, resize the Biped so that the pivot points of each bone match up to their corresponding FK bone. Use the non-uniform scale, it works best.
  4. Edit mesh each Biped bone and reshape them to fit each corresponding FK bone. Don’t worry about it being perfect, you actually want it to be a little different.
  5. Once Edit meshing is done, select the whole Biped and make a selection set called “Bones-BipedOnly”.
  6. Unfreeze FK bones.
  7. Use the link tool and link each FK bone to it’s corresponding Biped bone. NOT vice versa, you’ll break the Biped.
  8. Once they are all linked, make sure they move/rotate right.
  9. If there are extra FK bones, like a turret on a shoulder or an antenna, you don’t need to Biped it. Just leave it as an FK bone and animate this FK bone. The Biped is more for the legs than anything else.
  10. TIP: if you have bones in your setup, that are not going to be linked to Biped bones, they will be exported with linear keyframes. That means say goodbye to any smooth movement you have on them. In order to work around this, I suggest you make a copy of those bones, naming them “IK-Skirt-Left01”, etc, and linking each FK bone to its corresponding IK bone. This way, the animation will get exported the same way the FK bones that are linked to Biped bones gets exported (at the specified framerate)
  11. Select the bones you would actually be animating (all the Biped bones, any extra FK bones) and make a selection set called “XXXX-BonesAnim”. Hide the other FK bones.
  12. Make sure that the deformation with the Biped pivot point locations works and that you didn’t forget to link any FK bones. Make any adjustments necessary.
  13. Make keys for the BIPED bones at frames 0 and 1, and adjust each key continuity to be at 0.

IMPORTANT: I will once again stress this point. Make sure you keep frame zero at the character’s rest pose. THIS IS VERY IMPORTANT. If you have to add a bone or add tags later, or do ANYTHING to the mesh in ANY animation file, this frame is where you would do it, since it will remain consistent throughout all the files.

Weighting Bones

OK, bone weighting is different from vertex weighting. Bone weighting determines the amount a bone will blend from one animation file to the next, “in game”. The weights go from zero (no blending) to 10 (full blending). Here’s how to weight the bones:

  1. Unhide Mesh and FK bones.
  2. Select Mesh
  3. In the RF Bone modifier, go to the “MVF Parameters” list and click on the bones you want to weight. Use the control key to select multiple bones.
  4. Take the bone weighting from the list below and plug them into the box next to the bone names.

Now, for the original setup file, weight them for Ready/Stand. It’s the easiest one to do, since most animations will have this weighting. For each other type of animation (they are listed), set those bone weightings.


Bone Weighting Chart

Animation Spine Arms Legs Hip/Root IK Exporting
Stand 40 20 100 20 15
Walk /Run 40 20 100 80 15
Attack Firing / Flinch / Reload / Talk 80 100 0 0 15
Death 100 100 100 100 15
Exporting VCM Files

Once the setup is complete, you need to export the .vcm file. The .vcm file is the actual geometry of the character, and it stores what bones move what vertices.

  1. Select the mesh.
  2. Click “Export” button in RF Bone .
  3. Here it will bring up a box for your prop tags. Make sure the ones you want to export are visible, and select them. Then click “select”.
  4. Go to your local project tree.
  5. Save the .vcm in the models folder (name it appropriately for what the character is).
Exporting MVF Files

For every animation you do, you must export it as an .mvf file. This file stores all the motion/bone data for each animation. After you weight the bones, export it as follows:

  1. Make sure all FK bones NOT linked to BIPED have position and rotation keys at the first and last frame. Any bones linked to BIPED bones will have keys placed at a specified framerate. You must remove keys from ALL FK bones that are linked to Biped bones, otherwise, RF Bone will ignore the fact that the bones are linked to Biped bones when you export. So make sure ONLY FK bones, that aren’t linked to Biped bones, have keys.
  2. Select the mesh.
  3. In the “MVF Parameters”, there are boxes for Ramp In and Ramp Out. Depending on your animation, you set these differently. These values are the amount of time (frames) this animation will be blended to and from. See chart below for general values, but keep in mind you may have to play around with them to make them look right, as each animation is different.
  4. Click “Export” button under “MVF Parameters” in RF Bone .
  5. Go to your local project tree.
  6. Save the .mvf in the motions folder.


General Animation Time Chart

Animation Ramp In Ramp Out
Ready / Stand 3 3
Walk / Run 3 3
Attack Firing / Flinch / Reload / Talk 5 10
Death 5 0
Naming Conventions for MVF Files

Each character has a basic animation set. Standing, Walking/Running, Attacking, etc. Some might not have walking, as they are flight only. This is special case, so these four are the base. The naming of the .mvfs is the same for ALL characters, with one difference:

  • IMPORTANT: There has to be a four-letter code unique to each character in front of each .mvf name. Only four letters!

For example, the Ultor Suit’s code is ULT1. A name of his animation would then be “ULT1_stand.mvf”. These have to be different for each character, and must be present on each character. Another example: you have a village man, say VMN4, who talks, walks, stands, runs normally. then the same model is used for another village man whose stand state is him sitting, and he does not move from the sitting position. Name this sitting village man VMN5, NOT VMN4_sitting. The 4 letter code must be different for EVERY character. Here is an example list of how naming should go, minus the 4 letter code at the beginning that is specific for each character:

MVF name Animation
Stand.mvf Standing, in attack mode (arm up to fire, etc)
Stand_idle.mvf Standing, in non attack mode. Generally in a guarding or shut down position
Hover.mvf Hovering, in attack mode
Hover_idle.mvf Hovering, arms down, just floating there.
Walk.mvf Walking, in attack mode
Walk_idle.mvf Walking, arms swinging like normal.
Flying.mvf Flying, in attack mode
Flying_idle.mvf Flying, arms at side or doing something non-attack like. 
Attack_(attack type).mvf Attacking, doing whatever he does to attack.
Reusing MVF Animations for Multiple Characters

This section is important. It will help save time and memory when animating characters and getting them in game. The premise is, to have multiple characters use the same .mvfs. So all guards in RF, for example, would share animations and not take up memory that can be used elsewhere. Here’s how it works:

  1. Make sure you know ahead of time general design ideas for the characters. So if there are 2 guards, and one has hair and the other doesn’t, put bones in for the pony tail even though one wont use it.
  2. Make the most complex guards first. The one with armor, or long hair, etc, so you can put the bones in for them. They won’t be used for everyone, but they are there.
  3. Make sure the characters are modeled in the same proportion (all pivot points should be in the same spot). **This is important. Make sure the meshes of the characters that will share skeletons match up PERFECTLY along the major jointed areas (shoulders, elbows, wrists, must match seamlessly in a front and top view, pelvis, knees, ankles must match seamlessly in a front and side view). If they don’t match, fix it so they do.
  4. Now, when you get the characters, they will all share the same FK setup. That way, all you need to do is setup and export the .vcm, and it will use the same .mvfs as the first guard you animated.

As a little helper, if you were to create a character with Masako’s proportions (the sample file character in the Official RF Toolkit download), you could use her skeleton, set the character up, and use the already existing animations for that character.

Adding Bones to an Already Setup and RF-Boned Character

If you have a character already setup, and you want to add bones to it or are copying a setup to a mesh that requires extra bones, do the following:

  1. The bones MUST be at the end of a hierarchy. This means you can add things to the hierarchy, but cannot add them in between bones. See explanation below, where Spine1 is the start of the hierarchy, and “Shoulder” is the new bone.
    1. Spine1 -> Spine2 -> Shoulder is CORRECT
    2. Spine1 -> Spine2 -> Shoulder -> Upperarm is INCORRECT, since Upperarm was originally linked to Spine2
  2. If the setup is only FK, skip to part 3.
    1. a) If the setup is a BIPED setup, ie the FK bones are linked to the BIPED bones already, you must re-link the FK bones into their original FK hierarchy (the one used when RF Bone was applied).
  3. Reset X-Form on the NEW bones only, and collapse the stack.
  4. Link the new bones to an appropriate FK bone.
  5. Click “Add Bones”, with ALL FK bones visible, and select the new FK bones along with the old ones.
  6. Click “Hierarchy”. This will reinitialize the FK hierarchy.
  7. If the setup is only FK, skip to part 8.
    1. a) If the setup was BIPED, re-link the FK bones to their corresponding BIPED bones.
  8. Export a test MVF and V3D/VCM to see if it exports without a crash.
  9. If it exports OK, assign the appropriate vertices to the new bones.
  10. Re-export the new V3D/VCM for the new character/setup, and start animating.
Adding Prop Tags to Characters

IMPORTANT: If there are weapons to be held by a character, you need to make dummy objects parented to the FK hand bones of the character.

Prop dummies should be aligned as if they were created in the FRONT viewport. That is the Z axis should point outwards toward the front of the character in the setup pose, or be the same as the blade of a sword. If you just create them in Front view, you’ll be fine.

IMPORTANT: If you want to animate the Prop Dummies, usually needed for large or two handed weapons, the prop dummies MUST be part of the initial FK bone hierarchy and picked as a BONE when the character is first setup.

Otherwise, you can simply have them as tags. To do this, just pick them as tags when you go to export your .v3m/.vcm. The tags for you RF character should be as follows (see Sample Max file in Official RF Toolkit download): “primary_weapon_1”, where the character will hold their weapon. “csphere_0”, “csphere_1”, “csphere_2” are collision spheres which determine the character’s collision with the world. See the sample Max file in the Official RF Toolkit download for how these should be linked and placed. They are in the “dummies” selection set.

Setting up entity.tbl
  • NOTE: This is not an in-depth explanation of the entity.tbl file, just a brief overview in the context of RFBone.

So you’ve got your character setup, animated and exported. What next? Here’s a brief view of the entity.tbl, which is the table file you add your characters to. I’ll use, as an example, the entry for Masako, who is the sample character in the sample max file.


Extract from entity.tbl

Entry Name Entry Contents Description
Name: “masako” This is the name of the character in game.
$V3D Filename: "masako.vcm" This is the name of the .vcm you exported for this character.
$LOD Distances: {6 9} This is the distance, in meters, that the game will draw the LODs for your character, if you have them.
$Allowed Weapons: ("scope_assault_rifle") These are the weapons the character is allowed to use.
$Default Primary: "scope_assault_rifle" This is the weapon the character starts out with as a default
+State: "stand" A state is an animation that loops when no action is played, ie, standing, walking, running. If you are sharing animations with another character, you’d add that character’s .mvfs here.
+Action: "reload" A action is an animation like firing, reload, flinch. It plays over the state, blending with it. If you are sharing animations with another character, you’d add that character’s .mvfs here.
$Collision Sphere: "csphere_0" The entry for your character’s collisions spheres.