└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Unity - Runtime OBJ Loader 2 | More Extensive Documentation for the Free Unity Runtime OBJ Loader by Aaro4130. 3 | 4 | ## What is Unity Runtime OBJ Loader (ROL)? 5 | ROL is a script that imports OBJs and their materials from a place on Disk into a unity scene during runtime. 6 | 7 | ### Features 8 | (From https://forum.unity.com/threads/free-runtime-obj-loader.365884/) 9 | - Ability to load OBJ file from stream 10 | - mtl file loading, and texture loading (dds, crn, jpg, jpeg, png, tga, bmp) 11 | - Triangle, Quad, and Ngon import 12 | - Fast loading times 13 | - Works in both the editor, and runtime* 14 | - Usable in the editor 15 | 16 | ### Requirements 17 | In order for this to work in runtime, you must go to the "Edit > Project Settings > Graphics" tab, and add "Standard (Specular Setup)" to the always included shaders. This will make your next build take a while. 18 | 19 | If you don't do this, the required shader / shader variants won't exist. 20 | 21 | - Current Recommended Unity Version: 2018.3.1 or higher 22 | 23 | ## Installation 24 | Import into Unity from the Unity Asset Store, or here: https://assetstore.unity.com/packages/tools/modeling/runtime-obj-importer-49547 25 | 26 | ## Usage 27 | (From https://forum.unity.com/threads/free-runtime-obj-loader.365884/) 28 | ### Editor 29 | Select the GameObject menu (up top) 30 | Then select "Import from OBJ" 31 | 32 | ### Runtime 33 | ```Csharp 34 | using Dummiesman; 35 | using System.Collections; 36 | using System.Collections.Generic; 37 | using UnityEngine; 38 | 39 | /** Doesn't have to be run from start, can be used on any trigger. */ 40 | public class Startup : MonoBehaviour 41 | { 42 | void Start() 43 | { 44 | //file path 45 | /** Sample OBJ from 46 | * https://www.turbosquid.com/3d-models/free-obj-model-ivysaur-pokemon-sample/1136333 47 | * Model .mtl file needs editing to add the texture by default 48 | */ 49 | string filePath = @"Assets/Ivysaur_OBJ/Pokemon.obj"; 50 | // MTL should be linked in the OBJ file by default, 51 | // but if not, you can specify it manually 52 | string mtlPath = @"Assets/Ivysaur_OBJ/Pokemon.mtl"; 53 | 54 | var loadedObj = new OBJLoader().Load(filePath, mtlPath); 55 | 56 | } 57 | 58 | void Update() 59 | { 60 | 61 | } 62 | } 63 | ``` 64 | 65 | ## Functions 66 | ```Csharp 67 | public GameObject Load(Stream input); 68 | ``` 69 | Loads an OBJ from an input stream. 70 | If there is no mtl file referenced in the input stream (ie by the OBJ file), the default Specular Shader (White) will be attached to the OBJ. 71 | 72 | ```Csharp 73 | public GameObject Load(Stream input, Stream mtlInput); 74 | ``` 75 | Loads an OBJ from an input stream, and loads the associated mtl from the mtlInput Stream. 76 | 77 | ```Csharp 78 | public GameObject Load(string path, string mtlPath); 79 | ``` 80 | Loads an OBJ from the given path, and the associated mtl from the given mtlPath. 81 | 82 | ```Csharp 83 | public GameObject Load(string path); 84 | ``` 85 | Loads an OBJ from a given path. 86 | 87 | ## Notes on MTL 88 | *.mtl files refer to the material list that is saved next to the .obj file, they configure a set of Renderers. 89 | Some .mtl files are missing things, or have shader settings misconfigured. It's not ROL that's failing here, we can edit the .mtl to work correctly. 90 | 91 | ### MTL Keys 92 | Source: http://paulbourke.net/dataformats/mtl/ 93 | `newmtl ` Creates a new material with the following settings. 94 | 95 | `Ka ` - Ambient illumination component, RGB Range 0.0-1.0 96 | `Kd ` - Diffuse illumination component, RGB Range 0.0-1.0 97 | `Ks ` - Specular illumination component, RGB Range 0.0-1.0 98 | `Tf ` - Transmission Filter, RGB Range 0.0-1.0 99 | The above also may use Spectral Curves or CIEXYZ colours, see the above source for more info. 100 | 101 | `illum ` - Choose the illumination model. 102 | | Illum # | Model | 103 | |---|---| 104 | | 0 | Color on and Ambient off| 105 | | 1 | Color on and Ambient on | 106 | | 2 | Highlight on | 107 | | 3 | Reflection on and Ray trace on | 108 | | 4 | Transparency: Glass on
Reflection: Ray trace on | 109 | | 5 | Reflection: Fresnel on and Ray trace on | 110 | | 6 | Transparency: Refraction on
Reflection: Fresnel off and Ray trace on | 111 | | 7 | Transparency: Refraction on
Reflection: Fresnel on and Ray trace on | 112 | | 8 | Reflection on and Ray trace off | 113 | | 9 | Transparency: Glass on
Reflection: Ray trace off | 114 | | 10 | Casts shadows onto invisible surfaces | 115 | 116 | 117 | `d ` - Dissolve for the material, factor Range 0.0-1.0 118 | `Ns ` - Specular Exponent, Range 0-1000 119 | 120 | `map_Kd -options ` 121 | Specifies that a color texture file or color procedural texture file is 122 | linked to the diffuse reflectivity of the material. During rendering, 123 | the map_Kd value is multiplied by the Kd value. 124 | 125 | "filename" is the name of a color texture file (.mpc), a color 126 | procedural texture file (.cxc), or an image file. 127 | 128 | The options for the map_Kd statement are listed below. 129 | ``` 130 | -blendu on | off 131 | -blendv on | off 132 | -cc on | off 133 | -clamp on | off 134 | -mm base gain 135 | -o u v w 136 | -s u v w 137 | -t u v w 138 | -texres value 139 | ``` 140 | Similar keys for Ambient (`map_Ka`), and Specular (`map_Ks`) mapping 141 | 142 | `bump -options ` 143 | Specifies that a bump texture file or a bump procedural texture file is 144 | linked to the material. 145 | 146 | "filename" is the name of a bump texture file (.mpb), a bump procedural 147 | texture file (.cxb), or an image file. 148 | 149 | ### MTL Format 150 | '#' denotes comments. 151 | ```mtl 152 | newmtl my_red 153 | Material color 154 | & illumination 155 | statements 156 | 157 | texture map 158 | statements 159 | 160 | reflection map 161 | statement 162 | 163 | newmtl my_blue 164 | Material color 165 | & illumination 166 | statements 167 | 168 | texture map 169 | statements 170 | 171 | reflection map 172 | statement 173 | 174 | newmtl my_green 175 | Material color 176 | & illumination 177 | statements 178 | 179 | texture map 180 | statements 181 | 182 | reflection map 183 | statement 184 | ``` 185 | Typical organization of .mtl file 186 | 187 | ### MTL Example 188 | The following imports an Ivysaur model from 189 | https://www.turbosquid.com/3d-models/free-obj-model-ivysaur-pokemon-sample/1136333 190 | which has 2 materials attached, Outline and Pokemon. 191 | I've added the map_Kd line at the bottom to load the texture. 192 | ```mtl 193 | # MTL written from C:\3D_Exchange_Folder\Pokemon.obj 194 | newmtl Outline 195 | Kd 0 0 0 196 | Ns 256 197 | d 1 198 | illum 2 199 | Ka 0 0 0 200 | Ks 0 0 0 201 | newmtl Pokemon 202 | Kd 0.48 0.48 0.48 203 | Ns 256 204 | d 1 205 | illum 2 206 | Ka 0 0 0 207 | Ks 0 0 0 208 | map_Kd Assets/Ivysaur_OBJ/Final_Pokemon_Diffuse.jpg 209 | ``` 210 | 211 | ## About This Document 212 | This document has been prepared by PhalanxHead for the purposes of making usage of the Unity Runtime OBJ Loader more clear. 213 | 214 | PhalanxHead is not in any way associated with the development of the Project. 215 | --------------------------------------------------------------------------------