OAR Converter can take an OpenSimulator Archive (OAR) and from it create textures, meshes and terrain suitable to import into a Unity scene. From Unity a range of virtual world or virtual reality experiences can be created. The converter has been created by Fumikazu Iseki (Avatar: @Fumi.Hax – @fumi_hax) and his colleagues at the Network Systems Laboratory of Tokyo University of Information Sciences (TUIS) in Japan with support from Austin Tate at the University of Edinburgh.
- OAR Converter from OpenSimulator Archive (OAR) to Collada files for use in Unity3D.
- Software developed by Fumi Iseki, Austin Tate, Daichi Mizumaki and Kohe Suzuki.
This blog post is provided for convenience and using content from the original TUIS OAR Converter Japenese Web Site which should be considered definitive.
OAR Converter can run on Linux and Windows and source code is available. Full instructions for compiling and using the source code version on these platforms is available via the TUIS Wiki OAR Converter Page. For convenience a version with Windows UI is also available as a ready to run package.
Note that an OAR file is actually a .tar.gz (.tgz) file, and hence is a Unix TAR format contents zipped to compress it to a smaller file. Sometimes downloading an OAR file can lead to the web server of underlying file save unzipping it automatically. Make sure you are using a normal OAR file or the OAR Converter will report the error message “File Extract Error”.
OAR Converter with Windows UI – Quick Start
Download the OAR Converter for Windows latest version from http://www.nsl.tuis.ac.jp/xoops/modules/xpwiki/?OARConvWin
[Local Copy]. Latest Version at the time of this blog post in September 2017 is v1.0.6 (at 2016/5/11) which is based on oarconv-1.4.4.
For straightforward conversions, simply follow these steps:
- Place your OpenSim OAR file in a suitable directory. Using defaults, the conversions will be placed in separate directories in this same directory with names based on the OAR file name prefixed by OAR_ and DAE_
- Run the OAR Converter and using “File” -> “Open OAR File” select the OAR file you wish to convert. This will create a directory called OAR_ with the unpacked contents of the OAR file ready for conversion.
- Now select “File” -> “Convert Data” from the OAR Converter File menu. This will create a directory called DAE_ with the converted content in it.
- The DAE_ directory created will contain the DAE/Collada objects for the conversion which have colliders (are solid) and one special DAE/Collada object for the terrain (named the same as the OpenSim region name). It will also have sub-directories for all Textures and for the Phantoms (objects with no collider).
Import to Unity3D
You could follow the video instructions in this YouTube video by Fumikazu Iseki. The first part of this video shows the use of the Linux version of the converter, but the part from [2:23] to [6:10] gives an example of importing the converted DAE/Collada folder contents and merging that with a Unity project/scene including adding a Unity Standard Asset water surface. Importing the included “UnityChan” character is shown in the last part of the video.
Import to Unity3D – Quick Start
- Ensure you add the contents of “forUnity3D” folder in the OAR Converter distribution into your Unity project, adding Editor/SelectOARShader.cs at least. A slight improvement to one file in this distribution is available… the file in Unity3D/Editor named SelectOARShader.cs can be replaced with a version which fixes materials on bright objects imported to Unity. Replace it with UnitySelectOARShaderBrightFixed.cs [directory for right-click download] [direct link]. Don’t leave both versions in place.
- In your Unity project add an empty game object at 0,0,0 and name it the same as your OpenSim region name. Under this add three empty game objects named Solid, Phantom and Terrain also at 0,0,0.
- Drag the DAE_ folder in its entirety onto the Unity “Project” (Assets) panel.
- Select all the objects in the top level of this directory except the Textures and Phantoms sub-directories and drag them onto the “Solids” game object in the Unity “Hierarchy” panel.
- Optional: As the (large) terrain object for the region is imported it is usually split automatically by Unity into three sub-meshes of less than 64k polygons. These are all under one object named the same as your OpenSim region and will have sub-mesh names starting “GEOMETRY_”. You may wish to move this terrain objects and its three parts to the “Terrain” object in the hierarchy for tidiness and ease of management.
- Select all the objects in the Phantom directory and drag them onto the “Phantoms” game object in the Unity “Hierarchy” panel.
- Optional: Add a water layer at 0,0,0. [Instructions in YouTube Video][2:23] to [6:10].
- Optional: Add a ThirdPartyController/Avatar to be able to run the scene and view the contents. [Instructions in YouTube Video] after [6:10].
Project Base for OAR Converter Projects
Once you have successfully tried a conversion and understand the elements, you may wish to create a base for any future OAR conversion… which can include all the steps except for the drag and drop in of the actual DAE converted content. Do this yourself to incorporate the very latest OAR Converter content, scripts and Unity assets. You can if you wish save this as a “unitypackage” to incorporate into future Unity projects.
Make a copy of the base project you created, or create a new unity project andimport the chosen unitypackage as a base, and then drag the OAR Converter produced “DAE” directory into the Unity Project Assets area, add the DAE folder assets and those in the DAE/Phantoms folder to the hierarchical view panel. Adjust the position of the chosen character and attached camera to suit the region, save the project, save the scene, and you should be good to go.
Advanced Uses – Settings
Exported objects can be shifted in the X, Y and Z (up/down) directions, perhaps for multiple side by side regions on a 256mx256m grid. [Note: this is also easily done afterwards in the Unity editor also.]
Once objects are converted they can also be examined in a 3D viewer built into the tool.
Access via a Virtual World – Sinespace
The region can be made available for use by multiple simultaneous users using Massive Multiplayer Online (MMO) servers or platforms. One example is Sinespace.
For more details see the Sinespace Wiki or tutorial videos:
The OAR Converter creates a lot of materials with repetitive (identical) textures. These are used to maintain other properties of materials such as shininess used by the Shader used to import OAR Converted content (via Editor/SelectOARShader.cs). This leads to rather large regions in Sinespace and hence larger than necessary download sizes for users using the content. The Sinespace developers have provided a useful and effective tool to reduce the repetitive textures used without effecting the visual appearance of the imported content. Always use this tool before uploading the region containing OAR Converter content before uploading a region to Sinespace. Use it via the Unity3D “Sine” -> “Tools” -> “OAR Material Cleanup” menu. The Sine menu is added to Unity when the Sinespace unitypackage is imported as described in “Sinespace – Getting Started“.
In recent versions of Unity and Sinespace there can be some bright emissive objects created by the OAR Conversion process which are due to the use of “Legacy” shaders in Unity. These can be changed to Standard shaders (Standard/Diffuse or Standard/Diffuse-Emissive) in a bulk fashion, but some manual tidyup afterwards might be necessary especially to correct for the addition of shininess and metallic effects, and for emissive and semi-transparent objects.
Iseki, F., Tate, A., Mizumaki, D. and Suzuki, K. (2017) OpenSimulator and Unity as a Shared Development Environment, Journal of Tokyo University of Information Sciences, Vol. 21, No. 1, pp.81-87 (2017). [PDF Format]
Iseki, F., Tate, A., Mizumaki, D. and Suzuki, K. (2017) OAR Converter: Using OpenSimulator and Unity as a Shared Development Environment for Social Virtual Reality Environments, OpenSimulator Community Conference 2017 (OSCC-2017), 9th-10th December 2017. [PDF Format] [Presentation: PDF Format]
Further Information and Resources
- OpenSim OAR Convert to Unity Scene Blog Post by Austin Tate on 30th August 2015.
- OpenSim OAR Convert to Unity Scene with Windows Interface Blog Post by Austin Tate on 24th October 2015.
- YouTube: OAR Converter Instruction video by Fumikazu Iseki [10:34]
- YouTube: OAR Converter Presentation at OpenSimulator Community Conference 2017 (OASCC17) [25:51]
OAR Converter License
OAR Converter © 2014-2016 Fumi Iseki, Austin Tate, D.Mizumaki and K.Suzuki
License (2016 11/19) – http://www.nsl.tuis.ac.jp/, All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the OAR Converter nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
- Please respect the copyright of content providers when using OAR Converter.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Example OAR Conversions Used During Developing and Testing
DirectX and Missing .dll
Some of the image conversion or other packages used by OAR Converter will use Windows OS utilities or .dll libraries which are normally installed. If you get error messages about missing .dll files look online for advice. Try always to use official download links at Microsoft and the full install of the missing elements for such packages rather than using third party download sites just to get the specific .dll file. Such sites can be a source of viruses and Trojans, or point at commercial utilities marketed as driver repair systems. A user also reported that this may occur when trying to run OAR Converter from Google Drive, rather than directly from local disk.
OAR Converter uses the user’s region information to pick up decimalisation formats. In some regions, such as in Germany, the decimalisation character can be a comma rather than the full stop used for decimalisation in English speaking regions. Users in Germany for example have found that this causes problems with the OAR Conversion and especially when imported to Unity this can lead to multiple empty materials folders and a failure to create correct mesh objects from the Collada (.dae) files. The result being that the imported meshes do not have the usual pictorial thumbnail. To fix this and allow OAR Converter to work correctly, the decimalisation character can be set temporarily to a full stop in Control Panel -> Region -> Additional Settings -> Decimal Symbol. But remember to set it back to the usual region setting (e.g. a comma) after doing the conversion.
Thanks to Frank Klafzinski at gmx.de and his colleagues for identifying this issue and providing the images above (click on thumbnails for full size images) from a German region Windows system for how to set the decimal point to a full stop temporarily before doing the OAR Conversion.