Arma Toolbox is a script set for Blender, the free open source graphics modelling and rendering package. It should work with all of the latest Blender versions since 2.60, but was tested only with the latest (at the time of writing) 2.66a release.
This document aims to introduce the functioning of the Arma Toolbox, and as such assumes a certain knowledge of Blender as well as the Arma 2/Arma 3 engine and BIS tools.
Note that the Arma Toolbox can be used for both Arma 2 and Arma 3.
Installation and Setup
To install the Arma toolbox, download the ZIP file and save it some place on your harddisk. Then, open up Blender and open the User Preference window:
Press the “Install from file” and browse to the ZIP archive. This should install the plugin, and present you with the view above. Click the Checkbox to enable/activate the plugin. Close the User Preference window.
To verify that the plugin is active, look at the Properties shelf in your main window (Press ‘N’ if you don’t see it). There should be an Arma Toolbox Settings panel that looks like this:
Currently there is only one setting, namely the path to O2Script.exe, which is a part of the Oxygen 2 /BIS Tools package. By default, this should be in C:\Program Files (x86)\Bohemia Interactive\Tools\Oxygen 2 Personal Edition\, but it depends on where you installed the BIS tools (which reminds me, I should mention you need to have the BIS tools installed, but you should have that anyway if you intend to mod for Arma 3)
Clicking the folder icon will open a file selection. Browse to the place where your Oxygen 2 is installed, and click okay. Then click “Save Settings” once. This should save the setting permanently, and the next time you use the script, it should work without this step.
Using the Arma Toolbox
Once you have a Mesh object selected in your viewport, you should see a new Arma Object properties panel in the Properties shelf (again, press ‘N’ if you don’t see the properties shelf). The original content of this panel will be a single button “Make ARMA object”. If you click on this button, the Arma Toolbox will make the object you have selected usable for exporting. The button will then be replaced by more settings, as seen in this graphic:
Depicted on the left is the Arma Object properties panel before the toolbox takes control of it. Once you click it, there will be three major areas in this properties panel: LOD Preset (A), Mass (B) and Named Properties (C)
The LOD preset (LOD stands for Level Of Detail) is the same thing you would select in Oxygen 2’s ‘LODs’ Window. By default, it shows the Custom LOD distance, which means that this object represents a render LOD of the distance given below it. Selecting other LOD’s. like Pilot View, will hide the Custom Lod Distance field. Each object you export using this script will represent one LOD in the final P3D file (note that the option for merging LODs in the export dialog hasn’t been thoroughly tested yet). For a weapon model, you will typically have Custom lod’s 1 to 5, a Pilot View, two to four shadow lods, a Geometry LOD, and a Memory LOD.
Mass is only relevant for the Geometry LOD. It specifies the mass of the object, while the weights of the Vertex groups (Component01 and following) will determine the distribution of the weight.
Oxygen 2 / Arma 3 can associate so-called named properties with each LOD. For example, to prevent re-centering of components in model.cfg rotate anims, you would typically set the property “autocenter” to 0. To add a named property, click the Plus sign. This adds an empty property. Click the property in the list, and edit the name and value at the bottom.
Smoothing and Sharp Edges
Without Arma Toolbox, the only thing you can do to obtain sharp edges is to add an edge split modifier to your object and apply it to double the edges that make up the sharp angle. Arma Toolbox, however, can export sharp edges that are flagged with the “Sharp Edge” property in Blender. For reference, look at this screenshot of the Blender GUI:
In this screenshot, the bright blue edges are marked as sharp. To mark an edge as sharp in Blender, select the edge, then press CTRL-E to get the Edge special menu, and select “Mark Sharp” (Be sure to select the right option; there is also a “Mark Seam” option that is easily mistaken).
Due to how Blender works, the sharpness of the edge is not displayed correctly within Blender. However, exporting the object will export it as a sharp edge. There is a simple trick to get Blender to display the correct model. As you can see in the picture, go to the modifier tab and add an Edge Split modifier, making sure to only have “Sharp Edges” enabled. However, DO NOT APPLY the modifier. This modifier is just there to trick Blender into correctly showing you the sharp edges.
Arma Toolbox will export an edge as sharp if it is either marked as sharp like in the example above, or the face is marked as flat (in that case, all edges for that face will be exported as sharp). Typically, though, you will want to immediately switch your object to Smooth shading and use the edge split modifier like described above in order to have full control over the process.
Textures and Materials
The Arma engines can associate one texture and one RVMAT file for each face of a model. The texture itself can either be a file (like a .paa or a tga file), or a so-called procedural texture (in its simplest form, the procedural texture is merely a color). The RVMat file is a description of the surface properties of the face. You can find more info on the topic on the Bohemia Interactive Wiki page.
Arma Toolbox uses Blender Materials to assign these. When you create a material on an object that was made an Arma object, you will see an additional panel in the material’s property window (you might need to scroll down all the way to see it):
The Arma Toolbox Materials Settings panel is divided into a Texture part and an RV Material part. The latter is simply a .rvmat file, and may be empty. The folder icon next to the RV Material file text field lets you browse to an rvmat file. The file name entered here, upon export of the P3D file, is stripped of any leading drive letters (P: in this case) and any leading backslash characters, since the paths for textures and materials always start with the addon’s name. In this case, the addon’s name is FHQ_Accessories, and the resulting material name in the P3D file would be FHQ_Accesories\HOLO\HWS_black.rvmat.
The Texture field on top has three tabs, “Texture”, “Color” and “Custom”. The Texture tab above allows you to specify a texture file directly, abiding by the same rules for filenames as the RVMat file. In the example above, the resulting texture name would be FHQ_Accessories\HOLO\hws_black_co.paa.
The “Color” field looks like this:
The red box (which is white by default) is a color selector, clicking on it will allow you to use Blender’s default color selection dialog, and the box will show the color afterwards. The “Type” field selects the type of color, and corresponds to the similar prefix for texture files (like CO for color textures, CA for color textures with alpha, etc.).
Finally, the “Custom” tab allows you to enter any string directly. The string will not be modified by Arma Toolbox, and common examples would be procedural textures that are not a color.
In Oxygen 2, the dialog looks like this
In Arma games, Named Selections are sometimes used to reference specific parts of a model by name. For example, in order to move the trigger on a weapon when the soldier squeezes off a round, it has to be specifically marked and animated using model.cfg.
Named Selections in Arma map to Vertex Groups in Blender. Each vertex group defined for an Arma object will be exported as a named selection on that LOD in the output P3D file. The weights associated with each vertex will also be exported.
Exporting to P3D
When it’s all said and done, you will want to export your file into a format that Arma 3 understands. This is done from the File->Export -> Arma 2/3 .p3d menu option. This will open up the P3D Export view:
Besides the obvious panels in this dialog, the “Export to P3D” panel is of interest. Normally, it is at the bottom of the stack, so you might need to scroll the side bar all the way down. I have moved it up here for clarity.
There are three checkboxes in the panel.
By default, this option is off. When off, the exporter will save all Arma objects in the scene. When checked, only the selected objects will be saved (provided they are actual Arma objects; non-Arma objects are never saved)
Merge Identical LODs
NOTE: This feature is currently still experimental. Use with caution
While it is theoretically possible to have to LODs of the same kind in a P3D file, it doesn’t make sense at all. Therefore, by default, Arma Toolbox will output all objects of identical LOD into the same LOD in the P3D file. That is, if you have two models which are flagged “View Pilot”, there will be only one “View Pilot” LOD in the resulting P3D file, and it will contain the geometry of both objects. This is useful if you have e.g. attachments for an Arma 2 weapon that you just load into your file; with this option enabled, the attachment will end up in the same single LOD in the output file.
If this checkmark is off, then Arma Toolbox will save all LOD’s separately regardless of LOD distance.
Keep BITXT file
Arma Toolbox uses two temporary files to export the model, a BITXT file, and a settings file. Theses files are then read and interpreted by the O2Script.exe file which is basically O2 with all GUI elements stripped. The settings file will be used to export the named selections that cannot be part of the BITXT file.
By default (the checkmark is off) the temporary files are deleted after the export. If, however, you want to keep them for whatever purpose, checking this box will prevent the exporter from deleting them after the operation finished.