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
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
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.
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.
Note: This list is incomplete.
|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 (see flags)|
These tags are deprecated and should not be used.
|ShaderPath||<ShaderPath>Data/GLSL/cubemapobj</ShaderPath>||path to the shader to use (.frag & .vert), replaced by ShaderName|
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.
|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.|
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:
|YourObject_COL.obj||Contains simplified geometry for physics calculations.|
|YourObjectHULL.obj||Same as _COL but has extra info, used with weapons.|
Note HULL doesn’t have an underscore to separate it from the file name!
Physics objects (_COL)
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.
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.
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:
RGB - Color
A - Reflectivity
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|
|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.|
Texels that do not have a transparency of 0.0 or 1.0 have depth sorting issues with each other.
|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.|
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.
These are the materials that can be assigned to objects. These only work on terrains and not on objects placed in the world.
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>
|Defines what kind of item the object is. Can be weapon, collectible or misc.|
|Path to the object .xml file to use as a visual representation of this item.|
<grip ik_attach="rightarm" anim="Data/Animations/r_dogweapongrip.anm"/>
|ik_attach defines what bone the object is attached to when it's held. Don't know what anim does.|
<sheathe ik_attach="hip" anim="Data/Animations/r_dogweaponsheathed.anm"/>
|ik_attach defines where to attach the object when sheathed. Don't know what anim does.|
<physics mass="1 kg"/>
|Changes the pitch(?) of the sound made by the object hitting things. (Maybe also actual weight?)|
<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> <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.|
|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.|
<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.|
|Multiply multiplies the range with the specified value to make a weapon reach further or shorter.|