Re-Volt Add-On Documentation

Download

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.

Download (rva_18.0619)

Tutorial
Resources (Animations, textures, etc.)


Known Issues

Please report Bugs and suggest features on GitHub.


Installation

To install the add-on, locate the addons folder within your Blender folder.

In most cases, it is located at C:\Program Files\Blender Foundation\Blender\2.79\scripts\addons.

If you’re on Linux, your add-on folder might be located at ~/.config/blender/2.79/scripts/addons/, where 2.79 is the Blender version you are using.

Extract the io_revolt folder into the addons folder.

Installation Path
Installation Path

Now start up Blender and open the user preferences (File -> User Preferences…). Click on the Add-ons tab and enter Re-Volt.

User Preferences
User Preferences

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.


Tools Panel

The panel located on the left hand side of the 3D view.
Open/Close the tools panel using T.
The following panels are located in the Re-Volt tab. Its contents depend on the edit mode.
Some panels are collapsed by default. They can be expanded by clicking on the triangle on the left side of their header.


Import/Export

There are two main buttons, one for import and one for export. They have the same functions as the menu entries in the File -> Import/Export menus.
Import and Export settings can be found right beneath the buttons.

A repeat button can be found next to the Export button which repeats the last export.


Helpers

3D View

Texture:
Enables texture mode.

Textured Solid:
Enables solid shading mode and enables the textured solid option. This might be better for working with only half-textured models.


Add-On Settings

These settings can also be found when importing/exporting files in the bottom left.

General Settings

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.

Import Settings

Texture Mode after Import:
Switches to texture display mode when a mesh has been imported (applies to .prm and .w).

Export Settings

Triangulate n-gons:
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.

Export PRM (.prm/.m)

Apply Scale:
Applies the scale of the object when exporting.

Apply Rotation:
Applies the rotation of the object when exporting.

Import World (.w)

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.

Import Cubes:
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.

Export Collision (.ncp)

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

Grid Size:
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.


Light and Shadow

Shade Object

Shades a mesh by baking light to the vertex color layer.

Orientation:
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.

Direction:
Shows where the lights will be placed, depending on the chosen orientation.

Light:
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).

Intensity:
This defines the intensity of the light sources. This is the same setting as the lamp’s energy.

Generate Shadow Texture

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.

Method:
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.

Quality:
The amount of samples the shadow is rendered with (number of samples taken extra).

Softness:
Light size for ray shadow sampling.

Resolution:
The resolution of the resulting texture (height and width).

Table:
Shadow coordinates for use in parameters.txt of cars. Click to select all, then CTRL C to copy.


Instances

Instances
Shows the amount of instances in the current scene.

Rename selected
Renames all selected objects to the name given in the text field: example.prm, example.prm.001, example.002, ...

Select by name
Selects all instances that contain the name given in the textu field.

Mark as Instance
Assigns the instance property for all selected objects and makes Instance settings availabe in the Object properties (right panel).

Remove Instance property
Removes the instance property.

Bake all selected (Model RGB)
Bakes the light from the lamps in the current scene to the Model RGB property of selected objects. This allows to make instances blend in better if you’re working on a level with a specific light setup (night, sunset, etc.).


Face Properties

The list of properties is put together as follows:

Checkbox:
Enable or disable the property for all selected faces. The checkbox is checked when all selected faces have this property.

Number:
Indicates how many of the selected faces have this property.

Property Name:
Hover the property name to find out more about the property.

Select (sel) button:
Click to select/deselect all faces with this property.

Texture:
Sets the texture number for all selected faces. -1 if numbers of selected faces don’t match.

Material:
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

Vertex colors will be set depending on the selection mode.
Vertex, edge and face select modes (CTRL TAB) each have different effects.

Color Wheel:
An easy to access color selector to select the color hue and shade.
The Set Color button sets the color to the selected faces.
Click on the color preview to the left of the Set Color button to get a more detailed color wheel that supports RBG, HSV and Hex values and a color picker.
Get Color from active Face copies the average vertex color of the active face to the color wheel.

Shade buttons:
These buttons can be used for easily shading a mesh. They range from black to white.


Texture Animation

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.

Total Slots:
The total amount of texture animations you would like to use.
For example, set this to 3 to use slots 0, 1 and 2.

The maximum amount is 10 since a polygon’s animation is determined by the texture number.

Animation Slots

Slot:
The animation slot to display in the panel. The actual animation is set by the texture number/page.

Frames:
The amount of frames you want to use for the animation. For example, set this to 32 in order to access frames 0 to 31.

Animation Frame:

Frame:
The frame to display in the panel.

Preview:
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.

Texture:
The texture page number this animation frame uses.

Duration:
The duration of the frame or the delay until the next frame shows up.

Animate

Functions for automatically generating animations.

Transform Animation:

Interpolates the UV coordinates between two given frames. (Animates from point A to B.)

Start Frame:
The start frame the animation starts from. This frame will not be changed.

End Frame:
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.

Frame Duration:
The duration of all resulting frames.

Texture:
The texture page applied to all resulting frames.

Grid Animation:

Lays out animation frames on a grid, much like the mars animation in Museum 2.

Start Frame:
The frame the animation starts at.

X Resolution:
The width of the grid.

Y Resolution:
The height of the grid.

Frame Duration:
The duration of all resulting frames.

Texture:
The texture page applied to all resulting frames.

UV

UV to Frame:
Takes the UV coordinates of the currently selected face and applies them to the texture animation frame.

Coordinates:
The UV mapping for the currently displayed frame. For triangular faces, UV3 will be ignored.


Properties

Object Properties

This panel is at the far bottom of the Object section of the object properties. You may use the right top edge to drag it further up. 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).

Big Cube Properties:
This only shows when a big cube is selected.

Mesh Indices:
A list of mesh indices the selected big cubes belongs to. Does not affect export.

Scene Properties

Re-Volt .w Properties:
This panel is at the far bottom of the Scene section of the Properties editor. You may use the right top edge to drag it further up.

Texture Animations:
Texture animation dictionaries for .w files saved as a string. This property can be edited with the texture animation panel in edit mode.

Mesh Properties

Vertex Colors

Generally, meshes can have the following vertex color layers:

Col: The color/shade
Alpha: The translucency of the vertex/polygon. White is completely opaque (visible), black is completely transparent (invisible). This layer will only be used if the translucent flag is set in the face properties.
Env: The environment color (reflection). This layer is used for meshes and polygons of .w files. The env flag needs to be set in order for faces to use it.


Import/Export Specifications

Importing Files:
Re-Volt files can be imported via the File menu (File -> Import -> Re-Volt).
There also is a button in the Re-Volt tab of the tool shelf of the 3D view.

PRM:
Mesh Data:
Import:
An object with the mesh will be linked to the current scene. Meshes consist of quads and tris.

Export:
N-gons will be triangulate by default. This can be disabled in the export settings.

UV Map:
Export:
The UV map of the mesh can be found on the default UV layer (UVMap).

Export:
Only the uv map called UVMap will be exported.

Vertex Colors:
Import:
The vertex colors can be found on the Col and Alpha layers.
On the alpha channel, white is fully transparent while black is opaque.

Export:
Only the layers Col and Alpha will be exported.

Level of Detail (LOD):
Import:
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.

Textures:
Import:
If the imported mesh is a car mesh, the texture path will be taken from the parameters.txt. 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 name already exist, 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.

Export:
To set the texture using this number layer, the Use Number for Textures setting has to be set in the export settings.
When exporting, the texture number will be taken from the layer instead of being determined by the texture file assigned to the face.

If there is no texture present on a face, texture page 0 (A) will be used. If you actually want to export a mesh without a texture, enable the Use Number for Textures and set the number to -1.

Face Type:

Import:
The face types can be accessed with the Mesh properties which each have setter and getter functions that operate on int layers via bmesh.
The face type layer is called “Type”. There is a Re-Volt tab in the Tool panel of the 3D view that allows users to set face properties in Edit mode.

Export:
All selected face type properties will be set when exporting.

World (.w):
Import:

Meshes:

See PRM. 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 Env. 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 (EnvAlpha).

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.

Texture Animation:
Animations are stored in a dictionary that can be accessed in the Properties editor (Scene section).

Debug:
Bounding boxes, bounding spheres and “big cubes” (spheres) can be imported to selected layers. They are for debug purposes only and they will not affect the export in any way.

Export:

Nothing noteworthy. Exports files the way they have been imported.

NCP (Collision):

Import:

NCP flags and materials are written to the integer layers “NCPFlags” and “Material”. A preview color for the materials is written to the “NCPPreview” vertex color channel.

Export:

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.

parameters.txt (Car):

Import:
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.


https://re-volt.io