This is the documentation for Marv's Add-On for Re-Volt files.
It is intended to be used with Blender 2.79b or newer.
Note: Blender 2.8x series is not supported.
Please report Bugs and suggest features on GitLab.
- World (.w)
- Mesh (.prm)
- Collision (.ncp)
- Instances (.fin)
- Mirror Planes (.rim)
- Hulls (.hul)
- Texture Animations (.ta.csv)
- Car Parameters (parameters.txt; only partial import: body, wheels)
- Track Zones (.taz)
Missing Formats (help appreciated!)
- Objects (.fob)
- AI Nodes (.fan)
- Position Nodes (.pos)
- Visiboxes (.vis)
- Lights (.lit)
- Force Fields (.fld)
- Level Information (.inf)
- Level properties (properties.txt)
- Re-Volt tool panel
- Bake light to vertex color
- Simple vertex painting tool
- Car shadow generator
- Texture animation helper
- Convex hull generator
To install the add-on, locate the
addons folder within your Blender configuration folder.
In most cases, it is located at
If you're on GNU/Linux, your add-on folder should be located at
2.79 is the Blender version you are using.
For more information, see Configuring Directories ― Blender Manual.
io_revolt folder into the addons folder.
Now start up Blender and open the user preferences (File -> User Preferences...). Click on the Add-ons tab and enter Re-Volt.
Tip: Now, click on Save User Settings at the bottom of the User Preferences window to keep the add-on enabled when you restart Blender.
The following files are supported by the add-on:
- World (
- Mesh (
- Collision (
- Instances (
- Mirror Planes (
- Hulls (
- Texture Animation Spreadsheets (
- Car Parameters (
- Track Zones (
See Mesh. The only addition is the environment color list that defines a specularity color for certain polygons if the flag is enabled for them.
The environment color is accessible on a vertex color layer called
The alpha value of the color is only accessible via the face property editing panel since it's written to a per-face float layer (
Do note that environment colors are per-polygon. The average color will be sampled from the vertex color layer when an env-enabled polygon is selected.
There are debug options in the add-on settings (bounding boxes). They are for debug purposes only and they will not affect the export in any way.
Vertex Color Layers:
Col: Color layer
Alpha: Alpha layer (black: translucent, white: opaque)
Only the uv map called
UVMap will be exported.
The texture file name is used by the game engine to determine the texture number for exported faces. Make sure it's named correctly (e.g.
car.bmp). Currently one car texture and up to 64 track textures are supported, all present files must be named in order using scheme presented bellow. Example:
tracka.bmp ... trackk.bmp trackl.bmp is correct set but
tracka.bmp ... trackk.bmp trackm.bmp is incorrect - the last file and any further will be not loaded.
Note: For convenience add-on changes the imported image names (not file names) in blender's image editor to
<number>.bmp, please use same convention when adding a new images. There are built-in tools to take care of all the names, see helpers section.
If the imported mesh is a car mesh, the texture path will be taken from
If it's a level file, the texture name will be generated from the polygon's texture number and taken from the level folder.
If a texture file cannot be found, a 512x512 dummy texture will be generated.
If a texture with the same path already exists, it will be used instead.
The texture number is also written onto a bmesh integer layer. This layer can be used instead of the texture on the tex layer for exporting (see add-on settings).
Level of Detail:
If a PRM file includes mulitple meshes all of them will be imported.
A suffix will be appended to the mesh name (
|q0 is the highest quality,
|q3 is a lower quality).
A fake user will be assigned to them so they're not lost when saving the file.
Note: Only car wheels support LoD.
NCP flags and materials are written to the integer layers
Material. A preview color for the materials is written to the
NCPPreview vertex color layer.
All objects of the scene will be merged into one mesh and then exported to the file. Objects will be ignored if they're a debug object or have the ignore object property set (Properties Editor).
Faces that have the material
NONE assigned to them will not be exported.
The vertex color layer called
NCPPreview will be ignored since it's only for previewing purposes.
A lookup grid will be automatically exported. This can be turned off in the export settings.
Instances are PRM meshes placed around a level. An instance file contains metadata about multiple instances.
ModelRGB: Each RGB value ranges from -128 to 127. The color picker in Blender likes values from 0.0 to 1.0 most, that's why the default ModelRGB is (0.5, 0.5, 0.5).
Note: For importing hull files
qhull needs to be installed on GNU/Linux (macOS too) in order to import Hulls (on Arch, install it with
sudo pacman -S qhull, package name may be similar on your distro). The add-on is shipped with qhull.exe for Windows systems, nothing needs to be installed additionally.
Hull files are mainly used for car collision and some other moving objects (some of which can be found in the
Importing a hull file results several Blender objects:
One (sometimes more) convex hull which resembles the car body.
The interior (one per convex hull) consisting of spheres.
Note: Vertex and edge data is ignored when importing but written to exported files. Many custom
.huls don't include vertex and edge data, apparently the game works without them.
The add-on currently imports the car's body and wheels and their positions.
If a wheel file cannot be found, it will be represented with an empty object.
The panel located on the left hand side of the 3D view.
Open/Close the tools panel using
The following panels are located in the Re-Volt section. Its contents depend on the edit mode and whether an object is selected.
Some panels are collapsed by default. They can be expanded by clicking on the triangle on the left side of their header.
Panels can also be rearranged by dragging them using the handles at the right hand side.
Tip: Resize the tools panel to a comfortable size so the contents can be read more easily.
You can hover your mouse over any of the buttons to get a tooltip with an explanation.
Sometimes helper widgets pop up to make your life easier. They may prompt you about missing vertex color layers or a different view mode.
Note: Some panels are disabled until you click on a widget (e.g. missing vertex color layer).
The Import / Export panel is fixed to the top of the Re-Volt section of the tool panel. It can only be seen in Object mode.
There are two main buttons, one for import and one for export.
They have the same effect as the menu entries in the File -> Import/Export menus.
A repeat button can be found next to the Export button which repeats the last export.
Some of these settings can also be found when importing/exporting files in the bottom left.
Prefer Textured Solid Mode:
There are two encouraged ways to view textured meshes: Texture mode and Solid mode with Textured Solid shading enabled.
If this setting is enabled, the add-on will switch to Textured Solid mode instead of Texture mode.
In Textured Solid mode, objects have additional shading which makes white and untextured models a lot easier to work with.
Texture Mode after Import:
Switches to texture display mode when a mesh has been imported (applies to .prm and .w).
Check Parameters for texture:
Whether to read the parameters.txt from the car folder when importing a
.prm to find out the texture path.
Triangulates faces with more than 4 vertices (also called n-gons).
This will only affect the exported object, the mesh itself will not be triangulated.
Deselecting this might result in broken exports.
Use Number for Textures:
Instead of using the texture file to determine the texture number, the number set in the face properties panel will be used for exporting.
Applies the scale of the object when exporting.
Applies the rotation of the object when exporting.
Applies the position of the object when exporting.
Parent .w meshes to Empty:
Creates an empty object with the imported file's name and parents all meshes contained in the .w file to it. This makes the object outliner a lot less cluttered.
Import Bound Boxes:
Imports the bound box for every single mesh of the .w file.
Imports the cubes for every single mesh of the .w file.
Import Big Cubes:
Imports the big cubes surrounding multiple meshes of the .w file.
* Import Layers:
This option will be given as soon as one of the above debug settings have been enabled (boundary boxes, spheres and big cubes):
Selector for the layer(s) the debug objects will be placed on. Multiple layers can be selected by
Shift-clicking or dragging.
By default, all objects will be imported to the first layer.
When imported, the actual meshes are going to be on the first layer while the
debug objects potentially are on other layers.
To view multiple layers at once, hold down
Shift and press numbers, e.g.
1 and then
2. While doing that, make sure the mouse cursor hovers over the 3D view.
Only export selected:
When this setting is enabled, only selected objects will be exported to the NCP. If only one object is selected, the location of the object will be ignored and the center of the NCP will be the center of the selected object (useful for exporting NCPs for single PRM files).
Export Collision Grid (.w):
This setting is required when exporting a collision file that matches a .w file (e.g. nhood1.ncp for nhood1.w).
NCP files can be exported without the collision grid if the .ncp is intended to be used with an object or instance (.prm).
Defines the size of the lookup grid that is written to the end of the NCP file. The size defines the size of the single "cells". Choosing a higher number will result in a faster export but poorer performance in-game.
The Instances Panel provides some helper tools to make working with instances easier.
Select by data: Selects all objects with the same object data (mesh) as the currently selected object. You could, for example, place objects around the scene using
D to create duplicates with shared mesh data and then select all of them.
Rename selected: Instances that have the same mesh should also have the same name. This renames all selected objects to the name entered in the text field above.
Select by name: Selects all objects that contain the name entered in the text field above.
Mark as Instance: Sets the is instance property for all selected objects. These objects will then be exported when exporting to
Remove Instance property: Removes the is instance property for all selected objects so they won't be exported when exporting to
Generate Convex Hull:
Generates a convex hull from the selected object.
Create Hull Sphere:
Adds a hull interior sphere at the 3D cursor position to be placed inside the convex hull.
Shades a mesh by baking light to the vertex color layer.
Sets the orientation of the lights. The following options are available:
- Z (Vertical): Places lights above and beneath the selected object.
- Y (Horizontal): Places lights in the front and the back of the selected object
- X (Horizontal): Places lights on the left and right of the selected object.
Shows where the lights will be placed, depending on the chosen orientation.
Three options: Hard (sun, more contrast), Soft (hemisphere, smoother) and None.
- The hard option emits light in a distinct direction (Blender docs).
- The soft option emits light from a hemisphere which makes the model evenly lit (Blender docs).
This defines the intensity of the light sources. This is the same setting as the lamp's energy.
With this feature you can create shadows that are ready for use in-game. The shadows are negative which is a requirement by the game.
The add-on creates the shadows with ray-tracing and then baking them to an automatically sized textured plane (takes child objects into account).
To save the shadows, go into the UV/Image Editor, select the shadow (most recenty try has the highest number, e.g. Shadow.420) and then click Image -> Save as Image.
Warning: Start with low-quality settings first as Blender might hang a while during the creation of a shadow. If it appears to freeze, wait a few minutes. Depending on the settings you chose, it might take a while.
There are two options:
- Default (Adaptive QMC), which is the faster option. I recommend this for testing the shadow settings.
- High Quality (Constant QMC), which is the slower and less-grainy option. I recommend using this when you're done tweaking your shadow settings.
The amount of samples the shadow is rendered with (number of samples taken extra).
Light size for ray shadow sampling.
The resolution of the resulting texture (height and width).
Shadow coordinates for use in parameters.txt of cars. Click to select all, then CTRL C to copy.
This feature allows you to bake lights in the current scene to instance objects.
Bake to Model RGB:
Whether to bake the color to the Model RGB value. This can be used to darken or tint the instance.
Bake to Model Env:
Whether to bake the color to the Model Env value. This can be used to alter the reflection color of the instance.
Bake all selected
Bakes a full render to all selected objects. This usually takes a long time, Blender freezes until the action is done. A popup will show up when the baking process is complete.
Enables texture mode.
Enables solid shading mode and enables the textured solid option. This might be better for working with only half-textured models.
Launch RVGL: Starts RVGL in developer mode. The path has to be configured in the add-on settings.
Copy project textures: Renaming and checking many image files may be monotonous. This command copies all used track textures from their source to chosen destination track folder and renames them properly for you. Note: If you chose destination directory same as actual source for textures all files with matching names will be overwritten.
Rename track textures:
All used textures must be named (this is not referring file names) in numerical order in blender's image editor e.g.
0.bmp 1.bmp 2.bmp 3.bmp ... 63.bmp. This name uniquely identifies each texture, any gap in numeration may cause an issues. Command will assign new name (ID) to each texture.
Note: this may override existing (manual) numeration.
The list of properties is put together as follows:
Enable or disable the property for all selected faces. The checkbox is checked when all selected faces have this property.
Indicates how many of the selected faces have this property.
Hover the property name to find out more about the property.
Select (sel) button:
Click to select/deselect all faces with this property.
Sets the texture number for all selected faces.
-1 if numbers of selected faces don't match.
Set: Displays the material of the currently selected face. Select a material from the list to apply it to all selected faces. The select (sel) button selects all faces with the same material.
Select: Select a material from the list to select all faces with the same material.
Vertex colors will be set depending on the selection mode.
Vertex, edge and face select modes (
TAB) each have different effects.
Vertex Color Layers:
Select the currently active vertex color layer. Add and remove layers with the + and - buttons.
An easy to access color selector to select the color hue and shade.
The Set Color button sets the color to the selected vertices/edges/faces.
The Get Color button gets the color from the selected vertices/edges/faces.
Click on the color preview button to get a more detailed color wheel that supports RBG, HSV and Hex values and a color picker.
These buttons can be used for easily shading a mesh. They range from black to white.
An edit panel for texture animations. The animations themselves are saved in the scene, not the selected object. It is only accessible in edit mode to provide tools to use existing polygons and UV mapping to create an animation.
The total amount of texture animations you would like to use.
For example, set this to
3 to use slots
The maximum amount is 10 since a polygon's animation is determined by the texture number.
The animation slot to display in the panel. The actual animation is set by the texture number/page.
The amount of frames you want to use for the animation. For example, set this to
32 in order to access frames
The frame to display in the panel.
Click the Preview button to preview the frame's UV on the currently selected face. The buttons next to it go back or advance one frame and then preview the UV of that frame on the currently selected face.
The texture page number this animation frame uses.
The duration of the frame or the delay until the next frame shows up.
Functions for automatically generating animations.
Interpolates the UV coordinates between two given frames. (Animates from point A to B.)
The start frame the animation starts from. This frame will not be changed.
The frame the animation ends on. This frame will not be changed. To achieve a perfectly looping animation, it's sometimes necessary to leave the last frame out. To do so, decrease the amount of frames of the animation by 1.
The duration of all resulting frames.
The texture page applied to all resulting frames.
Lays out animation frames on a grid, much like the mars animation in Museum 2.
The frame the animation starts at.
The width of the grid.
The height of the grid.
The duration of all resulting frames.
The texture page applied to all resulting frames.
UV to Frame:
Takes the UV coordinates of the currently selected face and applies them to the texture animation frame.
The UV mapping for the currently displayed frame. For triangular faces, UV3 will be ignored.
The properties Editor is usually found at the right hand side of the user interface.
Most Re-Volt properties can be found in the Object tab (orange cube icon).
Some properties from Blender are used as well, such as vertex colors. Vertex color layers can be found in the object data section (symbol with three dots).
The Re-Volt Panel of the Object section is pinned to the top.
Ignore Collision: If enabled, the object won't be exported to .ncp.
Is Instance: If enabled, the object will be exported to
.fin. If a
.prm file with the name of the object doesn't yet exist, it will also be exported to
Model Color: Additional or subtractive RGB color. Default is (0.5, 0.5, 0.5). Setting this to 1.0 erases the existing vertex color, 0.5 leaves it where it is and anything closer to 0 darkens the instance.
EnvColor: Environment map color and intensity (alpha).
Hide: Hides the instances (only collision).
Don't show in Mirror Mode: The instance won't be shown if the level is played in mirror mode.
Is affected by Light: In-game lights affect the instance.
No Camera Collision: The camera will clip through the instance.
No Object Collision: The instance won't collide with cars and other moving objects.
Priority: If set to anything other than
0, the instance cannot be turned off using the video options.
LoD Bias: Unused
Is Mirror Plane: If enabled, the object will be exported to
These properties can be changed manually, however, it is encouraged to create hulls and spheres using the operators in the tools panel or via the Add menu.
Is Convex Hull:
If enabled, the object will be exported as a convex hull.
Is Interior Sphere: If enabled, the object will be exported as an interior sphere.
Only some debug stuff, not much to be scene.
Topics: Hull, Textures, Mesh
- Support up to 65535 polys per object (World Mesh, PRM and NCP).
- Support up to 1024 slots.
- 64 textures selectable.
- UV coords outside (0,1).
- Support for non-centered hulls exported by
qhullfiles are created in addon path to avoid permission issues.
- Fixed a missing newline in
- Properly handle empty
- Support for non-centered hulls exported by
- Fixed links to docs and GitHub issues.
Topics: Track Zones, Textures, Bugfixes
- Track zones
.tazimport and export, added zones commands in UI panel.
- New textures management commands in UI panel.
- Export important car parameters to clipboard.
- Aerial representation using axes.
- Track zones
- Changed convention for texture images names in blender, support for 64 (possible up to 702) track textures with backward compatibility.
- Fixed NCP face triangulation. Ensure invalid NCP flags are stripped on export.
- Better color layer compatibility for Blender 2.79 (sub 2) and above.
Topics: Mirror Planes, Hull, Bugfixes, Tools
- Mirror Planes:
- Import and Export
- Hulls tool panel with convex hull generation
- Vertex color layer list in the tools panel
- Batch Bake section in the Light and Shadow tool panel
- RVGL Launcher in the Helpers panel. The RVGL path (folder) has to be set in the add-on settings.
- Setting: Check Parameters for texture
- Mirror Planes:
- Crash when importing levels with texture animation (reported by Gotolei)
- Batch bake should not crash anymore
- Import and export of .fin properties (mainly colors)
- Set default model rgb to (0.5, 0.5, 0.5)
- Too many dummy textures when importing prm
- Catch error when parameters.txt files don't end with a '}' (reported by Shara)
- NCPs consisting of multiple objects are now exported with correct materials
- New documentation, yet again
- Code restructuring
- UI restructuring
- Support loading files with uppercase letters
- Throw an error message when exceeding polygon/vertex limits for meshes
- Activate NCP no-collision flag (reported by Kiwi)
- Inverted alpha vertex color layer: Black is translucent, white is opaque. I've done this to resemble the behavior of pure black on textures.
Topics: Instance (.fin), UI, Bugfixes
- Instances (.fin): Export (full support)
- Select by name button in the Instances panel that allows users to select all objects with a similar name
- Mark as Instance button in the Instances panel that sets the instance properties on all selected objects
- Batch baking feature for instance RGB in the Instances panel
- Initial hull support: Import (unfinished)
- Textures are now loaded when importing a mesh from the custom folder (reported by Gotolei)
- Ensure that NCP layers exist when exporting: All Material layers and Type layers are now kept. This fixes missing materials when exporting NCP. (reported by LoScassatore, Gorgonzola)
- Export of textures with suffixes like .bmp.001 (reported by Boy80)
- Moved the instances helper section to a dedicated Instances panel.
- Objects marked as instance (Is Instance) will no longer be exported when exporting to .w, use .fin instead
- Fixed all Re-Volt panels to the top (object and scene properties) so they're easier to find. This makes the add-on a lot more intrusive but most people using this add-on use Blender exclusively for Re-Volt.
- Message boxes for confirming actions in the helpers panel
- Texture number face property only shows when Use Number for Textures option is enabled
- Prefer Solid Textured Mode is now disabled by default
- NCP: Only export selected option added (check the documentation for details)
- Rewrote the parameters.txt parser, should now load all cars
- The light panel now only shows up if at least one object is selected
- New system for handling import and export errors
- Instance (.fin) import
- Batch-rename feature (Helpers panel)
- No collision flag for NCP (face properties)
- Prepared the add-on for 2.79a. All features should now work as expected.
- Various Import/Export fixes
- Improved UI
- Documentation is now generated with Ivy
- Fixed the following crash: Import mesh, clear .blend, import mesh again (reported by Zorbah)
- Shadowtable not added to the UI (reported by Mladen)
- Required vertex color layers weren't created on export (Issue #16, reported by progwolff)
- NCP: Setting for collision grid size (requested by Zorbah). Higher values = faster export (might slow down the game in return)
- Fixes (reported by Gotolei)
- Animation slot count can now be set to 10
- Frame count for animations reset itself
- Animation export didn't work in some cases
- Texture Animation: Transform animation feature (animates from frame A to frame B), Grid animation feature (for creating animations like the mars animation found in Museum 2). Added a resources link to the documentation which will include texture animation sheets ready to be used with the add-on.
- Re-Export Button: Press the button next to the Export button to export to the same file again.
- The vertex color picker now picks from selected faces or vertices. (Contribution by Boy80)
- Fixed persisting QUAD flag by removing it from the export mask. (Reported by Boy80)
- Importing cars with the same texture name resulted in them having the same texture. (Reported by Gotolei)
- Added icons to panels
- Moved add-on settings to a separate panel
- The settings, texture animation and the helpers panel are now collapsed by default
- Fixed the import/export panel to the top
- Notifications now have an icon
- Huge code refactoring and some fixes
- Restructured the documentation
- NCP (collision): Import and export is now supported. The face properties panel has a section for NCP now (face flags and materials).
- Settings: Prefer Textured Solid mode setting, enabled by default. This makes the add-on use textured solid mode (easier for editing NCP/untextured meshes).
- Import/Export: Import and export operators now show the matching settings in the bottom left.
- Vertex Colors: Button for getting the color from the active face (requested by Boy80)
- The y coordinates of bounding boxes were swapped.
- Faces can now be exported with no texture (reported by Boy80).
- Added Re-Volt file structure specifications to the documentation
- Light Baking Tool: Reverse horizontal X direction (light was shining from the wrong direction)
- Export .w, export .prm: Apply scale and rotation correctly. Parented objects should now be exported correctly.
- Rename bound spheres to cubes
- Import cubes instead of spheres
- Export .w
- Export complete .w files with meshes, boundary boxes/spheres, env colors and texture animation
- Texture animation panel
- Added buttons for copying UV from and to selected faces.
- Settings panel completed
- Parent .w meshes to Empty now disabled by default to avoid confusion
- New layout
- Decreased shadow table accuracy to 4 decimal places
- Tool panels
- Fixed a bug where the tool panels became unusable after CTRL Z.
- Import .w
- Bound boxes, bound spheres and big cubes, each of which can be imported on different layers
- Env colors with GUI implementation
- Import .prm completed
- Apply scale and rotation on export by default (no need for manual apply, can be disabled in the options)