View source for 3D Model Import

<translate>
<!--T:1-->
Importing 3D models is a great way to get existing content into [[Resonite]], whether it's for building environments, objects, avatars or simply for visualizing them. If the file type is [[Supported Formats|supported]], you can [[Importing Assets|import]] it in easily. The provided importer is based on the opensource [http://assimp.org/ Assimp] library and supports wide variety of 3D formats. Extra formats can be supported by installing 3rd party software on your computer.

For more details specific to importing avatars, see: [[Avatar creation]]  

<!--T:2-->
It is also possible to write your own importer or extend the one provided with Resonite using scripting and external programs using Resonite's libraries. The job of the importer is to read the input format and translate it into Resonite's native [[Type:StaticMesh|MeshX]] format for representing mesh data, extract any [[Type:StaticTexture2D|textures]], create and setup appropriate [[Material|materials]], setup the object hierarchy and any other components needed to represent the data from the format.

<!--T:3-->
Once the import is complete, the imported object isn't dependent on the source file anymore and exists as any other Resonite object.

<!--T:4-->
Supported file formats for 3D model import will show up in the [[File Browser|file browser]] as light yellow.

== Import Wizard == <!--T:5-->

<!--T:6-->
While importing 3D models, a wizard dialog will ask a few details about the model, which will help it determine the best settings for setting up the imported mesh, texture and material data. For example 3D scans usually look better with [[Unlit]]/PBR Emissive material, otherwise the lighting is applied "twice", leading to a very muddy look.

== Currently Supported 3D formats == <!--T:16-->

<!--T:17-->
These are the 3D formats supported by the Assimp library. Level of support for individual formats might vary.
{{note|VRM format can be loaded because it is based on glTF; This means that its extensions are not recognized at all!}}

<!--T:18-->
'''Common Interchange Formats'''

<!--T:19-->
*Autodesk ( .fbx ) '''- Must be FBX 2011, 2012 or 2013, newer ones won't work - Must be BINARY FBX format, ASCII FBX cannot be supported.'''
*Collada ( .dae )
*glTF ( .gltf, .glb )
*Blender 3D ( .blend )
*3ds Max 3DS ( .3ds )
*3ds Max ASE ( .ase )
*Wavefront Object ( .obj )
*Industry Foundation Classes (IFC/Step) ( .ifc )
*XGL ( .xgl,.zgl )
*Stanford Polygon Library ( .ply )
*AutoCAD DXF ( .dxf )
*LightWave ( .lwo )
*LightWave Scene ( .lws )
*Modo ( .lxo )
*Stereolithography ( .stl )
*DirectX X ( .x )
*AC3D ( .ac )
*Milkshape 3D ( .ms3d )
* TrueSpace ( .cob,.scn )

<!--T:20-->
'''Motion Capture Formats'''

<!--T:21-->
*Biovision BVH ( .bvh )
*CharacterStudio Motion ( .csm )

<!--T:22-->
'''Graphics Engine Formats'''

<!--T:23-->
*Ogre XML ( .xml )
*Irrlicht Mesh ( .irrmesh )
* Irrlicht Scene ( .irr )

<!--T:24-->
'''Game File Formats'''

<!--T:25-->
*Quake I ( .mdl )
*Quake II ( .md2 )
*Quake III Mesh ( .md3 )
*Quake III Map/BSP ( .pk3 )
* Inter-Quake Model ( .iqm )
* Return to Castle Wolfenstein ( .mdc )
*Doom 3 ( .md5* )
*Valve Model ( .smd,.vta )
*Open Game Engine Exchange ( .ogex )
*Unreal ( .3d )

<!--T:26-->
'''Other File Formats'''

<!--T:27-->
*BlitzBasic 3D ( .b3d )
*Quick3D ( .q3d,.q3s )
*Neutral File Format ( .nff )
*Sense8 WorldToolKit ( .nff )
*Object File Format ( .off )
*PovRAY Raw ( .raw )
*Terragen Terrain ( .ter )
*3D GameStudio (3DGS) ( .mdl )
*3D GameStudio (3DGS) Terrain ( .hmp )
*Izware Nendo ( .ndo )

== Blender == <!--T:28-->
Installing [https://www.blender.org/ Blender] will improve the support for importing .blend files, as Resonite will use Blender to export the file into GLB in the background, rather than use Assimp's limited support for the file format. For this to work Resonite needs to be able to find the Blender installation you are using. 

<!--T:29-->
By default Resonite will search the following directories to try and find a Blender installation:
* <code>C:\Program Files</code>
* <code>C:\Program Files (x86)</code>
* <code>C:\Program Files (x86)\Steam\steamapps\common\Blender</code>

<!--T:30-->
If that doesn't work you can also install Blender to the Tools folder of your Resonite Installation. E.g. <code>C:\Program Files (x86)\Steam\steamapps\common\Resonite\Tools\Blender</code>.

If you have an existing blender install that you would like to use from another location, you can create a symbolic link to Blender in the Tools folder. The folder you link to should directly contain `blender.exe` and you will need to restart the game for blender to be discovered in this new location.

An example command to create a symbolic link provided below, you will need to change the paths to where you have the game and blender installed.

<code>mklink /d "C:\Program Files (x86)\Steam\steamapps\common\Resonite\Tools\Blender" "D:\CustomPathToBlender"</code>

<!--T:31-->
If you have another common location that you know Blender installs to please open a [https://github.com/Yellow-Dog-Man/Resonite-Issues GitHub Issue] to suggest its addition.

== CAD Software file formats == <!--T:32-->

<!--T:33-->
'''FreeCAD'''
Installing the [https://www.freecadweb.org/ FreeCAD] software on your computer into the default directory will enable support for additional formats, particularly various CAD Files.

<!--T:34-->
*STEP Files (ISO 10303-21) ( .stp, .step )
*Open CAD format ( .oca, .gcad )
*Abaqus (.inp )
*CAD data NBSIR 80-1978 ( .iges, .igs )
*BREP Files ( .brep, .brp )
*Inventor ( .iv )
</translate>

== Binary FBX vs ASCII FBX ==
The [[wikipedia:FBX|FBX filetype]] is a proprietary 3d model format owned by Autodesk and has 2 distinct versions of this filetype: ASCII FBX (which is human-readable, a larger filesize, and ), and Binary FBX (a format that is smaller in size, non human-readable, and supported by most programs with an FBX format extension as it has been reverse engineered).


Autodesk software allows the export of both ASCII and Binary FBX formats as well as including a [https://aps.autodesk.com/developer/overview/fbx-converter-archives standalone converter tool] for converting existing ASCII FBX files to binary FBX formatted ones.


Resonite utilizes the [https://github.com/assimp/assimp Assimp library] for importing and exporting 3d models. Assimp currently does not support ASCII FBX files due to licensing issues of its FBX SDK and changes to its file format over time requiring constant updates. it is unlikely it will be supported in the future and its recommended in to use GLTF/GLB formats instead of FBX as they are royalty free, open formats.

== External Texture Convention for PBR == <!--T:7-->

<!--T:8-->
Because there's no well supported standard for PBR materials in model files, Resonite's model importer allows using a naming convention to automatically map texture files to the material based on the file naming.

<!--T:9-->
To enable this option, go to the '''Advanced Settings''' in the import wizard and check the '''Import External Textures''' option.

<!--T:10-->
This has currently following limitations:
* Works only with single-material models for now
* Each model must be in its own subfolder for now, there can't be multiple models with multiple albedo textures
* Files have to be named in style <myfilename>_<textype>.ext, case is irrelevant

<!--T:11-->
* Valid Examples, all map to albedo:
    Potato_albedo.png
    Potato_Albedo.png
    Potato_ALBEDO.png
    Alien Spaceship_albedo.tga
    _albedo.jpg
    albedo.jpg

<!--T:12-->
PBS MAPPING TABLE <textype>:

<!--T:13-->
Each property has multiple <textype> strings, only one should be used (preferably the first)

<!--T:14-->
* '''Albedo''': albedo, diffuse
* '''Normal''': normal, bump
* '''Specular map''': specular
* '''Metallic map''': metallic, metalness
* '''Emission map''': emission, emissive
* '''Ambient Occlusion''': ao, occlusion, ambientocclusion
* '''Heightmap/displacement''': height, heightmap, disp, displacement

<!--T:15-->
Specular/Metallic map's alpha channel maps to smoothness (inverse roughness)

[[Category:3D Model|*]]