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:

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

• 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. Swap blue and green channels
2. Invert green channel

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>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 use. See materials.
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. TODO: Can this be used on the regular shader or only when using the detailmap4 shader?
flags	<flags no_collision=true double_sided=true/>	Used to set boolean values on the object (see flags)

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

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		Standard shader.
cubemapobj		Same as Cubemap but uses object-space normal maps instead of tangent space.
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	NormalMap A - Sun fresnel mask	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.
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. Enables the optional use of a TranslucencyMap and a WindMap, see tags.
detailmap4		Requires a WeightMap and a DetailMaps tag when used. TODO: Does this also enable the optional use of the DetailObjects tag, or can that be used anyway?

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.

Items

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.

As an example, here is the item .xml file for the flint_knife weapon that comes with the game:

<?xml version="1.0" ?>
<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>

Tags

Tag	Example use	Description
type	<type>weapon</type>	Defines what kind of item the object is. Can be weapon, collectible or misc.
appearance	<appearance obj_path="Data/Objects/Weapons/MyWeapon.xml"/>	Path to the object .xml file to use as a visual representation of this item.
grip	<grip ik_attach="rightarm" anim="Data/Animations/r_dogweapongrip.anm"/>	ik_attach defines what bone the object is attached to when it's held. Anim is the place where the weapon will be held at. You create these in blender using one of the existing rigs that comes with the game (preferably the rabbit_rig).
sheathe	<sheathe ik_attach="hip" anim="Data/Animations/r_dogweaponsheathed.anm"/>	ik_attach defines where to attach the object when sheathed. Anim is the place where the weapon will be sheathed at. You create these in Blender using one of the existing rigs that the game comes with (preferably the rabbit_rig).
physics	<physics mass="1 kg"/>	Changes the pitch of the sound made by the object hitting things. Also changes how overall heavy it is.
points	<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>	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	<lines> <wood start="pommel" end="guard"/> <metal start="guard" end="tip"/> </lines>	Defines what materials go between what points that are defined in the points tag.
anim_blend	<anim_blend idle = "Data/Animations/r_bigdogsword.xml"/>	Override the animation for part of a character holding the item. Animation keywords that can be overridden are idle and movement. This is used for for instance two handed weapons, spears and so on, where the default animations don't fit.
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, movement, medleftblock, medrightblock, blockflinch and more. (See the 3. xml file under Custom Characters: Basics for the keywords.) This is used for for instance two handed weapons, spears and so on, where the default animations don't fit.
attack_override	<attack_override moving="Data/Attacks/knifeslash.xml" moving_close="Data/Attacks/knifeslash.xml" stationary="Data/Attacks/knifeslash.xml" stationary_close="Data/Attacks/knifeslash.xml"/>	What attacks should be used with this weapon in different contexts.
range	<range multiply="0.8"/>	Multiply multiplies the range with the specified value to make a weapon reach further or shorter.