View source for 3D Objects

== Introduction ==
Phoenix uses .xml files to store information about what textures a certain model should use as well as other information such as what shader it should use. This is the file you choose when loading an object. Here is an example object .xml file:

<pre>
<?xml version="1.0" ?>
<Object>
	<Model>Data/Mods/example_mod/Data/Models/SimpleObject.obj</Model>
	<ColorMap>Data/Mods/example_mod/Data/Textures/SimpleObject_Color.tga</ColorMap>
	<NormalMap>Data/Mods/example_mod/Data/Textures/Blank_Norm.tga</NormalMap>
  	<ShaderName>envobject #TANGENT</ShaderName>
	<MaterialPath>Data/Materials/default.xml</MaterialPath>
</Object>
</pre>

All object .xml files that ship with the game are located in ../Overgrowth/Data/Objects/.

=== Model and Texture Requirements ===
* Only triangles in models
* Models use the Wavefront .obj format
* Textures need to be square
* Texture resolution need to be a power of two (32x32, 64x64, 128x128 and so on)
* The .tga format is recommended for textures, but .png and .tif work also.

==== Converting normal maps ====
[[File:Convert_normals_tutorial.mp4|400px|thumb|right|Video tutorial on how to convert normal maps in GIMP]]
The normal maps that you get from some applications might not be instantly usable in the Phoenix engine without some edits. For instance, if you are using an object space normal map from Substance Designer you need to do this:

# Invert the blue channel
# Swap blue and green channels

You can do this in Photoshop, Substance Designer, or GIMP. Note that Gimp does not work well with alpha channels. On the right is a tutorial on how to convert object space normal maps into tangent space using GIMP.

== Object .xml File ==
The object .xml files contain all information about a single object (model) that can be spawned in the engine. This aims to be a full reference over all tags and flags that can be used in an object .xml.

=== Tags ===
{| class="wikitable"
|-
! Tag !! Example use !! Description
|-
! Model
| <pre><Model>Data/Models/MyModel.obj</Model></pre>
|| path to the model file (.obj)
|-
! ColorMap
| <pre><ColorMap>Data/Textures/MyColorMap.tga</ColorMap></pre>
|| path to the color texture file (.tga, .tif or .png)
|-
! NormalMap
| <pre><NormalMap>Data/Textures/MyNormalMap.tga</NormalMap></pre>
|| Path to the normal map texture file (.tga, .tif or .png)
|-
! ShaderName
| <pre><ShaderName>envobject #TANGENT #KEEP_SPEC</ShaderName></pre>
|| What shader to use, see [[#Shaders|shaders]] for more information
|-
! MaterialPath
| <pre><MaterialPath>Data/Materials/DirtyRock.xml</MaterialPath></pre>
|| Path to the material to use, see [[#Materials|materials]] for more information.
|-
! WeightMap
| <pre><WeightMap>Data/Textures/Environments/Rocks/granite_vine_rocks/granite_vine_boulder_overgrown_w.tga</WeightMap></pre>
|| Path to a black and white texture used for determining where each detail texture should be used. Required when using the detailmap4 [[#Shaders|shader]].
|-
! TranslucencyMap
| <pre><TranslucencyMap>Data/Textures/Environments/cat_props/banner_t.tga</TranslucencyMap></pre>
|| Path to a color texture used for translucency, meaning light that shines through the object. Adds its color to the surface multiplied by the amount of light it receives, this effect ignores the normal of the surface, so if one side receives light from for instance the sun, the other side will also get the color added. If unspecified it defaults to 0.0 (no translucency) across the entire surface. Optional when using the plant [[#Shaders|shader]].
|-
! WindMap
| <pre><WindMap>Data/Textures/Environments/cat_props/banner_w.tga</WindMap></pre>
|| Path to a black and white texture used to define the intensity of a vertex wind effect. If unspecified it defaults to 1.0 (active) across the entire surface. Optional when using the plant [[#Shaders|shader]].
|-
! DetailMaps
| <pre><DetailMaps>
    <DetailMap colorpath="Data/Textures/Terrain/DetailTextures/gray_rock.tga" normalpath="Data/Textures/Terrain/DetailTextures/gray_rock_normal.tga" materialpath="Data/Materials/rocks.xml" />
    ...
</DetailMaps></pre>
|| Contains exactly 4 <DetailMap> tags describing textures and materials that will be tiled across the model using the <WeightMap> tag's texture. Required when using the detailmap4 [[#Shaders|shader]].
|-
! DetailObjects
| <pre><DetailObjects>
    <DetailObject obj_path="Data/Objects/Plants/Groundcover/Groundcover1.xml" weight_path="Data/Textures/Environments/Rocks/granite_vine_rocks/granite_vine_boulder_overgrown_vine_mask.tga" normal_conform="0.9" density="10" min_embed="0" max_embed="0.4" min_scale="0.7" max_scale="2" view_distance="40" jitter_degrees="10" overbright="0" />
</DetailObjects></pre>
|| Contains one or more <DetailObject> tags, each describing how to randomly distribute some object across the surface. Can be used for grass, small rocks etc.
|-
! flags
| <pre><flags no_collision=true double_sided=true/></pre>
|| Used to set boolean values on the object (see [[#Flags|flags]])
|-
! GroundOffset
| <pre><GroundOffset>0.5</GroundOffset></pre>
|| Moves the object up/down by the set amount when the object is created
|}

==== Deprecated tags ====
These tags are deprecated and should not be used.

{| class="wikitable"
|-
! Tag !! Example use !! Description
|-
! ShaderPath
| <pre><ShaderPath>Data/GLSL/cubemapobj</ShaderPath></pre>
|| path to the shader to use (.frag & .vert), replaced by ShaderName
|}

==== Materials ====
These are the materials that can be assigned to objects using the <code><MaterialPath></code> [[#Tags|tag]]. You can find the materials in <code>../Overgrowth/Data/Materials/</code>. The material affects what particles spawn when a character runs on the surface, what sound footsteps make on the surface, how easily weapons stick in the surface, and more.

* default
* dirt
* dirtytock
* drygrass
* grass
* gravel
* ice
* rock
* rocks
* sand
* snow
* wood

=== Flags ===
Flags are entered as boolean attributes ("true" or "false") in a [[#Tags|tag]] called "flags" under the "Object" tag. All flags have a default value of false.

{| class="wikitable"
|-
! Flag !! Description
|-
! no_collision
| Disables physics collisions with this object.
|-
! double_sided
| The backsides of the object gets rendered as well.
|-
! bush_collision
| Makes the object give some resistance when passed through while the object wobbles a bit and generates leaf particles.
|}

==Collision/Physics Objects==
The engine automatically generates a simplified physics object from your model but this can be overridden by providing an alternative .OBJ file. The file is placed in the same folder and shares the same name as the original .OBJ file with a suffix:

===Suffixes===
[[Image:PhysicsObject.jpg|thumb|Physics mesh should be in the same place as the render mesh]]
[[Image:HullObject.jpg|thumb|Hull mesh should be in the same place as the render mesh]]
{| class="wikitable"
|-
! Suffix !! Description
|-
! <span style="color: gray">YourObject</span>_COL.obj
| Contains simplified geometry for physics calculations.
|-
! <span style="color: gray">YourObject</span>HULL.obj
| Same as _COL but has extra info, used for weapons.
|}

Note that HULL doesn’t have an underscore to separate it from the file name!

===Physics objects (_COL)=== 
Simplified geometry such as boxes and cylinders which are used for collision detection, they are aligned to your object based on “relative position” in your 3D program so you should place the physics mesh on top of your render mesh upon export.

===Hull objects (HULL)=== 
They are very similar to physics objects but are used for items and weapons, the only difference is that they contain a free-floating triangle which defines the object’s center of gravity.

== Shaders ==
Overgrowth uses an "uber shader" approach to shader management, which means that there is one huge shader that almost everything in the game uses. So instead of choosing a shader for your object, you can set "flags" with your object that the game will use to change how it's rendered.

The flags are put in the <ShaderName> tag after the shader name. Here is an example:

 <ShaderName>envobject #TANGENT #KEEP_SPEC</ShaderName>

"#TANGENT" and "#KEEP_SPEC" in this example are flags.

There are two texture maps that are required for an object to be loaded in the engine. Those are the '''ColorMap''' and the '''NormalMap''' textures. Some flags allow you to use more than these two required textures, and some flags change how the required textures are used. '''TODO:''' Are there any default textures that can be used and what are they?

Here is the channel designations of the ColorMap and NormalMap textures:

<u>'''ColorMap'''</u><br />
'''RGB''' - Color<br />
'''A''' - Reflectivity

<u>'''NormalMap'''</u><br />
'''RGB''' - Normal<br />
'''A''' - Color tint mask

Any deviation from these designations or new textures caused by any flag in the table below can be seen in the ''Channel/Texture Changes'' column.

{| class="wikitable"
|-
! Tag !! Channel/Texture Changes !! Description
|-
! #TANGENT
|
|| The normal map is used as an object space normal map by default, with this flag it's used as a tangent space normal map instead.
|-
! #KEEP_SPEC
|
<u>'''NormalMap'''</u><br />
'''A''' - Smoothness
|| Instead of using the alpha channel of the normal map as a color tint mask, as is the default, that channel is used as a smoothness map. The object can still be tinted, you just can't control what parts get tinted.
|-
! #DETAILMAP4
|
<u>'''WeightMap'''</u><br />
'''R''' - The first detail texture<br />
'''G''' - The second detail texture<br />
'''B''' - The third detail texture

<u>'''DetailMap colorpath'''</u><br />
'''RGB''' - Color

<u>'''DetailMap normalpath'''</u><br />
'''RGB''' - Normal
|| Allows for repeating up to 4 different textures over a model so it looks more detailed up close. This also means you can scale the model up or down with less obvious texture stretching.

* The WeightMap is used to decide which DetailMap texture to put where on the object
* Each DetailMap has its own color texture, normal texture and material
* See the [[#Tags|tags]] heading for information about how to specify the DetailMaps
|-
! #BASE_TANGENT
|
|| '''TODO:''' What does this do?
|-
! #AXIS_UV
|
|| '''TODO:''' What does this do?
|-
! #AXIS_BLEND
|
|| '''TODO:''' What does this do?
|-
! #NO_DECALS
|
|| No decals shows up on this object.
|-
! #WHY_DOES_THIS_WORK
|
|| '''TODO:''' What does this do?
|-
! #INVISIBLE
|
|| This object will not be rendered.
|-
! #ALPHA
| 
<u>'''ColorMap'''</u><br />
'''A''' - Transparency
|| [[Image:CubemapAlpha.jpg|thumb|#ALPHA flag in action]]
Makes the alpha channel of the ColorMap work as transparency instead of reflectivity
|-
! #PLANT
|
<u>'''ColorMap'''</u><br />
'''A (reflectivity)''' - No effect

<u>'''NormalMap'''</u><br />
'''A (color tint mask)''' - No effect

<u>'''WindMap'''</u><br />
'''R''' - Wind intensity<br />

<u>'''TranslucencyMap'''</u><br />
'''RGB''' - Translucency color<br />
|| [[Image:Translucency.jpg|thumb|#PLANT flag in action together with the #ALPHA flag]]
* Enables use of a WindMap which makes the object move in the wind
* Enables use of a TranslucencyMap which makes it look like light can shine through the surface
* Disables reflectivity
* Disables color tint mask
|-
! #WATER
|
|| '''TODO:''' What does this do?
|-
! #METALNESS_PBR
|
<u>'''Colormap'''</u><br />
'''A''' - Metalness<br />

<u>'''Normalmap'''</u><br />
'''A''' - Roughness<br />

|| With this shader tag, you can make PBR objects in Overgrowth!
|}

=== Color Tint Mask ===
This mask is located in the alpha channel of the normal map, and determines what parts of the object should be tinted when using the [[Editor_Interface#Color_Picker|color picker]]. Black parts are not affected, the brighter the texel the more it is affected by tinting.

== See also==
* [[Custom Characters]]
* [[Custom Weapons & Items]]