3D Objects

based on 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

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/Custom/Markuss/Examples/Models/SimpleObject.obj</Model>
	<ColorMap>Data/Custom/Markuss/Examples/Textures/SimpleObject_Color.tga</ColorMap>
	<NormalMap>Data/Custom/Markuss/Examples/Textures/Blank_Norm.tga</NormalMap>
  	<ShaderName>cubemap</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

Simple object and texture UV layout

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). Textures can be in .png, .tga or .tif format.

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

Note: This list is incomplete.

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>cubemapobj</ShaderName>	Name of shader to use from ../Overgrowth/Data/GLSL/ (.frag and .vert)
MaterialPath	<MaterialPath>Data/Materials/DirtyRock.xml</MaterialPath>	Path to the material to be used
flags	<flags no_collision=true double_sided=true/>	Used to set boolean values on the object

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

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. 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. If a character jumps into this object at high enough speed they will ragdoll.

Alternative object System

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:

Suffixes

Suffix	Description
YourObject_COL.obj	Contains simplified geometry for physics calculations.
YourObject.obj_UV2	Contains same object but with no overlapping UVs.
YourObjectHULL.obj	Same as _COL but has extra info, used with 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.

Physics objects (_COL)

Physics mesh should be placed on top of the render mesh

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.

Shadow UV objects (_UV2)

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.

Hull objects (HULL)

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

ColorMap
RGB - Color
A - Reflectivity

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

Tag	Non-standard channel designation	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	ColorMap A - Transparency NormalMap A - Reflectivity	cubemapalpha shader Texels that do not have a transparency of 0.0 or 1.0 have depth sorting issues with each other.
cubemapobjchar		Intended for use with characters, shine is sharp, uses object space normals.
plant	ColorMap A - Transparency NormalMap A - No effect TranslucencyMap RGB - Translucency color A - No effect WindMap R - Wind mask GBA - No effect	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 and Weapons

Example weapons, handles show the location of characters hands

Items and Weapons are aligned to the character based on their position relative to the center of the scene in your 3D app, you should load the .obj files of the example objects for reference. To make an object “pick-up-able” you need another .XML file that you load in place of the regular object properties file, it stores the info needed that is not defined in the regular object properties file:

<?xml version="1.0" ?>
<item>
    <type>weapon</type>
    <appearance obj_path = "Data/Custom/Markuss/Examples/1-Handed.xml"/>
    <grip ik_attach = "rightarm"
          anim = "Data/Animations/r_dogweapongrip.anm"/>
    <physics mass = "1 kg"/>
</item>

Tags

Tag	Example use	Description
type	<type>weapon</type>	Defines what type of item the object is.
appearance	<appearance obj_path="Data/Objects/Weapons/MyWeapon.xml"/>	Path to the regular object definition file.
grip	<grip ik_attach="rightarm" anim="Data/Animations/r_dogweapongrip.anm"/>	ik_attach defines what bone the object is attached to, anim is the path to an animation file that the character should use with the weapon.
physics	<physics mass="1 kg"/>	Changes the pitch(?) of the sound made by the object hitting things. (Maybe also actual weight?)
anim_override	<anim_override idle="Data/Animations/r_weaponidlestance.xml"/>	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.

NOTE:

Not sure what the animation file in <grip ik_attach anim> does.