Difference between revisions of "3D Objects"

From Wolfire Games Wiki
Jump to: navigation, search
(Shaders: Added information on sun fresnel mask on cubemapibjchar shader.)
(Added "See also" section with two articles linked)
 
(48 intermediate revisions by 4 users not shown)
Line 1: Line 1:
''based on [http://forums.wolfire.com/viewtopic.php?f=16&t=11227 this] forum post by member Markuss.''
 
There is a linked .zip file attached to the forum post. it can be found here:
 
http://www.markstockton.com/misc/Guide/Examples.zip
 
 
 
== Introduction ==
 
== 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:
 
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:
Line 9: Line 5:
 
<?xml version="1.0" ?>
 
<?xml version="1.0" ?>
 
<Object>
 
<Object>
<Model>Data/Custom/Markuss/Examples/Models/SimpleObject.obj</Model>
+
<Model>Data/Mods/example_mod/Data/Models/SimpleObject.obj</Model>
<ColorMap>Data/Custom/Markuss/Examples/Textures/SimpleObject_Color.tga</ColorMap>
+
<ColorMap>Data/Mods/example_mod/Data/Textures/SimpleObject_Color.tga</ColorMap>
<NormalMap>Data/Custom/Markuss/Examples/Textures/Blank_Norm.tga</NormalMap>
+
<NormalMap>Data/Mods/example_mod/Data/Textures/Blank_Norm.tga</NormalMap>
   <ShaderName>cubemap</ShaderName>
+
   <ShaderName>envobject #TANGENT</ShaderName>
 
<MaterialPath>Data/Materials/default.xml</MaterialPath>
 
<MaterialPath>Data/Materials/default.xml</MaterialPath>
 
</Object>
 
</Object>
Line 20: Line 16:
  
 
=== Model and Texture Requirements ===
 
=== Model and Texture Requirements ===
Models need to be constructed from quads and triangles only and be saved in the Wavefront .obj format. Textures need to be square and their resolution need to be a power of two, so 32x32 works, 32x64 does not work (since it's not square) and 31x31 does not work (since 31 is not a power of two). The .tga format is known to work well with the engine, but .png and .tif should work as well.
+
* 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 ====
 +
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, [http://orsvarn.com/entry/channel-shuffle/ Channel Shuffle] or similar. Note that Gimp does not work well with alpha channels. So if your alpha channel is anything but solid white, using Gimp to convert the normal map will change your normal map in undesirable ways.
  
 
== Object .xml File ==
 
== Object .xml File ==
Line 26: Line 34:
  
 
=== Tags ===
 
=== Tags ===
''Note: This list is incomplete.''
 
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 32: Line 39:
 
|-
 
|-
 
! Model
 
! Model
| <Model>Data/Models/MyModel.obj</Model> || path to the model file (.obj)
+
| <pre><Model>Data/Models/MyModel.obj</Model></pre>
 +
|| path to the model file (.obj)
 
|-
 
|-
 
! ColorMap
 
! ColorMap
| <ColorMap>Data/Textures/MyColorMap.tga</ColorMap> || path to the color texture file (.tga, .tif or .png)
+
| <pre><ColorMap>Data/Textures/MyColorMap.tga</ColorMap></pre>
 +
|| path to the color texture file (.tga, .tif or .png)
 
|-
 
|-
 
! NormalMap
 
! NormalMap
| <NormalMap>Data/Textures/MyNormalMap.tga</NormalMap> || Path to the normal map texture file (.tga, .tif or .png)
+
| <pre><NormalMap>Data/Textures/MyNormalMap.tga</NormalMap></pre>
 +
|| Path to the normal map texture file (.tga, .tif or .png)
 
|-
 
|-
 
! ShaderName
 
! ShaderName
| <ShaderName>cubemapobj</ShaderName> || Name of shader to use from ../Overgrowth/Data/GLSL/ (.frag and .vert)
+
| <pre><ShaderName>envobject #TANGENT #KEEP_SPEC</ShaderName></pre>
 +
|| What shader to use, see [[#Shaders|shaders]] for more information
 
|-
 
|-
 
! MaterialPath
 
! MaterialPath
| <MaterialPath>Data/Materials/DirtyRock.xml</MaterialPath> || Path to the material to be used
+
| <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
 
! flags
| <flags no_collision=true double_sided=true/> || Used to set boolean values on the object
+
| <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
 
|}
 
|}
  
Line 58: Line 100:
 
|-
 
|-
 
! ShaderPath
 
! ShaderPath
| <ShaderPath>Data/GLSL/cubemapobj</ShaderPath> || path to the shader to use (.frag & .vert), replaced by ShaderName
+
| <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 ===
Flags are entered as boolean attributes in an element called "flags" that is located under the "Object" element. For more information about the "flags" tag, look under [[#Tags|tags]]. All flags have a default value of false.
+
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"
 
{| class="wikitable"
Line 75: Line 134:
 
|-
 
|-
 
! bush_collision
 
! bush_collision
| Makes the object give some resistance when passed through while the object wobbles a bit and generates leaf particles. If a character jumps into this object at high enough speed they will ragdoll.
+
| Makes the object give some resistance when passed through while the object wobbles a bit and generates leaf particles.
 
|}
 
|}
  
==Alternative object System==
+
==Collision/Physics Objects==
The engine automatically generates a simplified physics object and uses the object’s UV layout to place the shadow maps, these can be overridden by providing alternative .OBJ files that contain the desired information. These objects are placed in the same folder and share the same name as the original .OBJ file with a suffix to tell the engine what data they hold:
+
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===
 
===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"
 
{| class="wikitable"
 
|-
 
|-
Line 88: Line 149:
 
! <span style="color: gray">YourObject</span>_COL.obj
 
! <span style="color: gray">YourObject</span>_COL.obj
 
| Contains simplified geometry for physics calculations.
 
| Contains simplified geometry for physics calculations.
|-
 
! <span style="color: gray">YourObject</span>.obj_UV2
 
| Contains same object but with no overlapping UVs.
 
 
|-
 
|-
 
! <span style="color: gray">YourObject</span>HULL.obj
 
! <span style="color: gray">YourObject</span>HULL.obj
| Same as _COL but has extra info, used with weapons.
+
| Same as _COL but has extra info, used for weapons.
 
|}
 
|}
  
Note that the suffix formats are inconsistent, _COL is placed before the file extension while _UV2 is place after, and HULL doesn’t have an underscore to separate it from the file name.
+
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.
  
===Physics objects (_COL)===
+
===Hull objects (HULL)===  
[[Image:PhysicsObject.jpg|thumb|Physics mesh should be placed on top of the render mesh]]
+
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.
  
Simplified geometry such as boxes an 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.
+
== 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.
  
===Shadow UV objects (_UV2)===
+
The flags are put in the <ShaderName> tag after the shader name. Here is an example:
[[Image:UVObject.jpg|thumb|Color texture UVs left, shadow UVs right, each face needs its own UV space]]
 
  
These objects tell the engine how to place the shadow map on the rendered object if the original UV layout isn’t appropriate, the shadow maps require UV layouts with no over-lapping faces, this can usually be achieved using the “automatic unwrapping” tools found in most 3D applications.
+
<ShaderName>envobject #TANGENT #KEEP_SPEC</ShaderName>
  
===Hull objects (HULL)===
+
"#TANGENT" and "#KEEP_SPEC" in this example are flags.
[[Image:HullObject.jpg|thumb|Hull objects are placed over render mesh like physics objects]]
 
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==
+
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?
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 shaders allow - but do not require - for additional maps to be specified for different purposes. Shaders with "obj" in their name expect the supplied NormalMap texture to be in object space, those without expect tangent space.
 
  
Here are the most common channel designations of the ColorMap and NormalMap textures:
+
Here is the channel designations of the ColorMap and NormalMap textures:
  
 
<u>'''ColorMap'''</u><br />
 
<u>'''ColorMap'''</u><br />
Line 125: Line 183:
 
'''A''' - Color tint mask
 
'''A''' - Color tint mask
  
Any deviations from this standard for any shader in the table below can be seen in the ''Non-standard channel designation'' column. This includes any optional textures.
+
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"
 
{| class="wikitable"
 
|-
 
|-
! Tag !! Non-standard channel designation !! Description
+
! Tag !! Channel/Texture Changes !! Description
|-
 
! cubemap
 
|
 
|| Nothing notable.
 
|-
 
! cubemapobj
 
|
 
|| Same as Cubemap but uses object-space normal maps instead of tangent space.
 
|-
 
! cubemapitem
 
|
 
|| Same as Cubemap but the shine is sharper.
 
|-
 
! cubemapobjitem
 
|
 
|| Object space version of CubemapItem.
 
 
|-
 
|-
! cubemapalpha
+
! #TANGENT
 
|
 
|
<u>'''ColorMap'''</u><br />
+
|| 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.
'''A''' - Transparency
 
 
 
<u>'''NormalMap'''</u><br />
 
'''A''' - Reflectivity
 
||  
 
[[Image:CubemapAlpha.jpg|thumb|cubemapalpha shader]]
 
Texels that do not have a transparency of 0.0 or 1.0 have depth sorting issues with each other.
 
 
|-
 
|-
! cubemapobjchar
+
! #KEEP_SPEC
 
|
 
|
 
<u>'''NormalMap'''</u><br />
 
<u>'''NormalMap'''</u><br />
'''A''' - Sun fresnel mask
+
'''A''' - Smoothness
|| Intended for use with characters, shine is sharp, uses object space normals. The sun fresnel effect brightens up the edges of the object when it is between the camera and the sun.
+
|| 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.
 
|-
 
|-
! plant
+
! #DETAILMAP4
 
|
 
|
<u>'''ColorMap'''</u><br />
+
<u>'''WeightMap'''</u><br />
'''A''' - Transparency
+
'''R''' - The first detail texture<br />
 
+
'''G''' - The second detail texture<br />
<u>'''NormalMap'''</u><br />
+
'''B''' - The third detail texture
'''A''' - No effect
 
 
 
<u>'''TranslucencyMap'''</u><br />
 
'''RGB''' - Translucency color<br />
 
'''A''' - No effect
 
 
 
<u>'''WindMap'''</u><br />
 
'''R''' - Wind mask<br />
 
'''GBA''' - No effect
 
|| [[Image:Translucency.jpg|thumb|plant shader]]
 
Has transparency like cubemapalpha but no reflectivity.
 
 
 
The '''TranslucencyMap''' texture 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.
 
 
 
The '''WindMap''' texture defines intensity of a vertex wind effect. If unspecified it defaults to 1.0 (active) across the entire surface.
 
|}
 
 
 
==Materials==
 
These are the materials that can be assigned to objects. These only work on terrains and not on objects placed in the world.
 
 
 
* Cloth_Fabric
 
* Cloth_Leather
 
* Default
 
* Dirt
 
* DirtyRock
 
* Drygrass
 
* Grass
 
* Gravel
 
* Rock
 
* Rocks
 
* Sand
 
* Snow
 
* Wood
 
  
==Items==
+
<u>'''DetailMap colorpath'''</u><br />
Items are things that a character can pick up in the game, a large part of the items in the game are weapons. An item .xml file is needed to make an object into an item. The item .xml files that come with the game can be found in ../Overgrowth/Data/Items/. Items are picked up by their center point.
+
'''RGB''' - Color
  
As an example, here is the item .xml file for the flint_knife weapon that comes with the game:
+
<u>'''DetailMap normalpath'''</u><br />
<pre>
+
'''RGB''' - Normal
<?xml version="1.0" ?>
+
|| 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.
<item>
 
    <type>weapon</type>
 
    <appearance obj_path = "Data/Objects/Weapons/flint_knife.xml"/>
 
    <grip ik_attach = "rightarm"
 
          anim = "Data/Animations/r_dogweapongrip.anm"
 
  hands = "1"/>
 
    <sheathe ik_attach = "hip"
 
          anim = "Data/Animations/r_dogweaponsheathed.anm"/>
 
    <physics mass = "0.4 kg"/>
 
    <points>
 
        <pommel x="0" y="-0.081" z="0"/>
 
        <guard x="0" y="0.10" z="0"/>
 
        <tip x="0" y="0.33" z="0"/>
 
    </points>
 
    <label>knife</label>
 
    <lines>
 
        <wood start="pommel" end="guard"/>
 
        <metal start="guard" end="tip"/>
 
    </lines>
 
    <anim_override idle = "Data/Animations/r_knifestancerear.xml"
 
                  movement = "Data/Animations/r_weaponmovestance.xml"/>
 
    <attack_override moving = "Data/Attacks/knifeslash.xml"
 
                    moving_close = "Data/Attacks/knifeslash.xml"
 
                    stationary = "Data/Attacks/knifeslash.xml"
 
                    stationary_close = "Data/Attacks/knifeslash.xml"/>
 
    <range multiply = "0.8"/>
 
</item>
 
</pre>
 
  
===Tags===
+
* The WeightMap is used to decide which DetailMap texture to put where on the object
{| class="wikitable"
+
* Each DetailMap has its own color texture, normal texture and material
|-
+
* See the [[#Tags|tags]] heading for information about how to specify the DetailMaps
! Tag !! Example use !! Description
 
 
|-
 
|-
! type
+
! #BASE_TANGENT
 
|
 
|
<pre><type>weapon</type></pre>
+
|| '''TODO:''' What does this do?
|| Defines what kind of item the object is. Can be ''weapon'', ''collectible'' or ''misc''.
 
 
|-
 
|-
! appearance
+
! #AXIS_UV
 
|
 
|
<pre><appearance
+
|| '''TODO:''' What does this do?
    obj_path="Data/Objects/Weapons/MyWeapon.xml"/></pre>
 
|| Path to the object .xml file to use as a visual representation of this item.
 
 
|-
 
|-
! grip
+
! #AXIS_BLEND
 
|
 
|
<pre><grip
+
|| '''TODO:''' What does this do?
    ik_attach="rightarm"
 
    anim="Data/Animations/r_dogweapongrip.anm"/></pre>
 
|| ik_attach defines what bone the object is attached to when it's held. Don't know what anim does.
 
 
|-
 
|-
! sheathe
+
! #NO_DECALS
 
|
 
|
<pre><sheathe
+
|| No decals shows up on this object.
    ik_attach="hip"
 
    anim="Data/Animations/r_dogweaponsheathed.anm"/></pre>
 
|| ik_attach defines where to attach the object when sheathed. Don't know what anim does.
 
 
|-
 
|-
! physics
+
! #WHY_DOES_THIS_WORK
 
|
 
|
<pre><physics mass="1 kg"/></pre>
+
|| '''TODO:''' What does this do?
|| Changes the pitch(?) of the sound made by the object hitting things. (Maybe also actual weight?)
 
 
|-
 
|-
! points
+
! #INVISIBLE
 
|
 
|
<pre><points>
+
|| This object will not be rendered.
    <pommel x="0" y="-0.081" z="0"/>
 
    <guard x="0" y="0.10" z="0"/>
 
    <tip x="0" y="0.33" z="0"/>
 
</points></pre>
 
|| Defines a number of points on the weapon that can be used with the ''lines'' element to define what material a part of the weapon has.
 
 
|-
 
|-
! lines
+
! #ALPHA
|
+
|  
<pre><lines>
+
<u>'''ColorMap'''</u><br />
    <wood start="pommel" end="guard"/>
+
'''A''' - Transparency
    <metal start="guard" end="tip"/>
+
|| [[Image:CubemapAlpha.jpg|thumb|#ALPHA flag in action]]
</lines></pre>
+
Makes the alpha channel of the ColorMap work as transparency instead of reflectivity
|| Defines what materials go between what points that are defined in the points tag.
 
 
|-
 
|-
! anim_override
+
! #PLANT
 
|
 
|
<pre><anim_override
+
<u>'''ColorMap'''</u><br />
    idle="Data/Animations/r_weaponidlestance.xml"/></pre>
+
'''A (reflectivity)''' - No effect
|| Overrides animations of a character holding the item. Animation keywords that can be overridden are idle and movement (maybe more). This is used for for instance two handed weapons, spears and so on, where the default animation looks weird.
+
 
|-
+
<u>'''NormalMap'''</u><br />
! attack_override
+
'''A (color tint mask)''' - No effect
|
+
 
<pre><attack_override
+
<u>'''WindMap'''</u><br />
    moving="Data/Attacks/knifeslash.xml"
+
'''R''' - Wind intensity<br />
    moving_close="Data/Attacks/knifeslash.xml"
+
 
    stationary="Data/Attacks/knifeslash.xml"
+
<u>'''TranslucencyMap'''</u><br />
    stationary_close="Data/Attacks/knifeslash.xml"/></pre>
+
'''RGB''' - Translucency color<br />
|| What attacks should be used with this weapon in different contexts.
+
|| [[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
 
|-
 
|-
! range
+
! #WATER
 
|
 
|
<pre><range multiply="0.8"/></pre>
+
|| '''TODO:''' What does this do?
|| Multiply multiplies the range with the specified value to make a weapon reach further or shorter.
 
 
|}
 
|}
 +
 +
=== 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]]

Latest revision as of 11:40, 27 April 2018

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:

<?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>

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

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:

  1. Invert the blue channel
  2. Swap blue and green channels

You can do this in Photoshop, Substance Designer, Channel Shuffle or similar. Note that Gimp does not work well with alpha channels. So if your alpha channel is anything but solid white, using Gimp to convert the normal map will change your normal map in undesirable ways.

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

Tag Example use Description
Model
<Model>Data/Models/MyModel.obj</Model>
path to the model file (.obj)
ColorMap
<ColorMap>Data/Textures/MyColorMap.tga</ColorMap>
path to the color texture file (.tga, .tif or .png)
NormalMap
<NormalMap>Data/Textures/MyNormalMap.tga</NormalMap>
Path to the normal map texture file (.tga, .tif or .png)
ShaderName
<ShaderName>envobject #TANGENT #KEEP_SPEC</ShaderName>
What shader to use, see shaders for more information
MaterialPath
<MaterialPath>Data/Materials/DirtyRock.xml</MaterialPath>
Path to the material to use, see materials for more information.
WeightMap
<WeightMap>Data/Textures/Environments/Rocks/granite_vine_rocks/granite_vine_boulder_overgrown_w.tga</WeightMap>
Path to a black and white texture used for determining where each detail texture should be used. Required when using the detailmap4 shader.
TranslucencyMap
<TranslucencyMap>Data/Textures/Environments/cat_props/banner_t.tga</TranslucencyMap>
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 shader.
WindMap
<WindMap>Data/Textures/Environments/cat_props/banner_w.tga</WindMap>
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 shader.
DetailMaps
<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>
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 shader.
DetailObjects
<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>
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
<flags no_collision=true double_sided=true/>
Used to set boolean values on the object (see flags)
GroundOffset
<GroundOffset>0.5</GroundOffset>
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.

Tag Example use Description
ShaderPath
<ShaderPath>Data/GLSL/cubemapobj</ShaderPath>
path to the shader to use (.frag & .vert), replaced by ShaderName

Materials

These are the materials that can be assigned to objects using the <MaterialPath> tag. You can find the materials in ../Overgrowth/Data/Materials/. 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 tag called "flags" under the "Object" tag. All flags have a default value of false.

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

Physics mesh should be in the same place as the render mesh
Hull mesh should be in the same place as the render mesh
Suffix Description
YourObject_COL.obj Contains simplified geometry for physics calculations.
YourObjectHULL.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:

ColorMap
RGB - Color
A - Reflectivity

NormalMap
RGB - Normal
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.

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

NormalMap
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

WeightMap
R - The first detail texture
G - The second detail texture
B - The third detail texture

DetailMap colorpath
RGB - Color

DetailMap normalpath
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 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

ColorMap
A - Transparency

#ALPHA flag in action

Makes the alpha channel of the ColorMap work as transparency instead of reflectivity

#PLANT

ColorMap
A (reflectivity) - No effect

NormalMap
A (color tint mask) - No effect

WindMap
R - Wind intensity

TranslucencyMap
RGB - Translucency color

#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?

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 color picker. Black parts are not affected, the brighter the texel the more it is affected by tinting.

See also