An actor is the 'physical' aspect of an entity.  Each entity that has a 'physical' appearance in the game requires an actor file.  The entire actor is wrapped in <object></object>.

The properties of Actors can be randomised for visual variety by defining them as ''variants'' under certain property ''groups'' with a defining ''name'' and certain ''frequency'' of occurrence. For more information, see [wiki:Actors].

Conditional variant groups aren't yet implemented at time of writing, but Philip has a plan for linking the variant strings to global and entity events, detailed here: http://www.wildfiregames.com/forum/index.php?showtopic=1799#

For simplicity, this document will simply alphabetically list the actor properties in a flat format, all of which can be combined in variants.

'''Example:'''

{{{
        <CastShadow />
        
        <Colour>248 132 86</Colour>
        
        <Animations>
                <Animation>
                        <Name>Idle</Name>
                        <File>biped/inf_idle_spear.psa</File>
                        <Speed>200</Speed>
                </Animation>
        </Animations>
        
        <Material>player_trans.xml</Material>
        
        <Mesh>skeletal/m_pants_c.pmd</Mesh>
        
        <Props>
                <Prop>
                        <AttachPoint>Head</AttachPoint>
                        <Actor>props/units/heads/head_celt.xml</Actor>
                </Prop>
        </Props>
        
        <Texture>skeletal/celt_isw_b_01.dds</Texture>
}}}

= !CastShadow =
''BRIEF DESCRIPTION ::'' If an actor has this property, it casts a dynamic shadow generated by the rendering engine.

= Colour =
''BRIEF DESCRIPTION ::'' The RGB colour used for this actor's transparency. It can be used to vary shade within a texture (for example, use the same texture for a horse, but have different variants with chestnut, black, chocolate, etc, coats.

= Animations =
''BRIEF DESCRIPTION ::'' This contains the multiple animations that this actor uses when performing linked actions.

'''object.animations.animation''' is the content of '''object.animations'''. '''actor.animations.animation''' has no content.

== Animation ==
''BRIEF DESCRIPTION ::'' An animation for an action.

=== Name ===
''BRIEF DESCRIPTION ::'' The name of this animation. 

The animation is used when the entity performs this event. Multiple animations can be listed with the same name; in which case, an animation is chosen at random when needed.

Here are some names of common animations:

 * Attack = Default attack animation. 
 * Build = Animation used when constructing a building.
 * Chop = Animation used when cutting down a tree.
 * Death = Default death animation. 
 * Idle = Default idle animation. 
 * Ready = Idle animation where actor has noticed an opponent.
 * Run = Movement animation when moving at maximum speed. 
 * Special = Custom animation. 
 * Pack = Animation of packing or unpacking (if played in forward or reverse).
 * Walk = Movement animation when moving at low speed. 

=== File ===
''BRIEF DESCRIPTION ::'' Path under actors/ to the .psa animation file that contains this animation's frame data.

=== Speed ===
''BRIEF DESCRIPTION ::'' The rate at which the animation is played back.

=== Event ===
''BRIEF DESCRIPTION ::'' Position in the animation at which an "event" is fired. 

For example, with a value of "0.5" for an archer's attack animation, an arrow projectile (the prop at the archer's "projectile" attachpoint) is fired towards the target when the archer is halfway through his animation.

=== Load ===
''BRIEF DESCRIPTION ::'' Position in the animation at which a projectile to be fired is spawned into the actor's "loaded-rhand" attachment point.

For example, with a value of "0.16" for an archer's attack animation, an arrow projectile (the prop at the archer's "loaded-r_hand" attachpoint) appears in the archer's hand at the point in the animation where he takes one from his quiver, at 16% of the way through the animation.

= Material =
''BRIEF DESCRIPTION ::'' Name and location of the material.

The material of an actor specifies material attributes the actor has when rendered.  This points to the material file that the actor will use.  These could include: alpha, refection, specular, ambient color, emissive.

Common materials are player_trans (for actors that belong to players and therefore need player colour) and basic_trans (for gaia objects).

= Mesh =
''BRIEF DESCRIPTION ::'' Name and location of the mesh/model.

This points to the specific location and name of the mesh used for this actor.  There is only one mesh per actor; if more are needed - use a prop.

Meshes are exported from 3dsmax R5 and R6 and their file extension is *.pmd (Pyrogenesis Model Data).

This information is specified as the content of the '''object.model''' element.

= Props =
''BRIEF DESCRIPTION ::'' This contains the multiple actors (props) that are connected at sockets/prop-points/attach-points of this actor.

A prop is simply another actor that is located at a prop point.  The type, number, orientation, and locations of a prop point are specified in the *.pmd mesh file.  Only one prop per prop point is allowed.  There may be multiple props for the actors.

'''object.props.prop''' is the content of '''object.props'''. '''actor.props.prop''' has no content.

== Prop ==
''BRIEF DESCRIPTION ::'' A prop attached to this actor.

=== !AttachPoint ===
''BRIEF DESCRIPTION ::'' The name of the attachment point (defined in the mesh data) where this prop will be connected. 

Here are some names of common !AttachPoints:

 * Back = Object on the actor's back.
 * CandyA = Prop point for eyecandy object. 
 * CandyB = Prop point for eyecandy object. 
 * CandyC = Prop point for eyecandy object. 
 * CandyD = Prop point for eyecandy object. 
 * CandyE = Prop point for eyecandy object. 
 * Destruct = Rubble from destruction. 
 * Head = Object on head.
 * Head_Extra = An extra prop attached to the head.
 * Hip = Object on hip.
 * L_Hand = Object in left hand.
 * R_Hand = Object in right hand.
 * Loaded-R_Hand = Object that appears in the actor's right hand when the "Load" stage of an animation is fired.
 * Mast = The mast of a ship.
 * Projectile = Projectile fired by the actor during the "Event" stage of an animation.
 * Props_Main = The main combination of props used to decorate a building.
 * Props_Extra = An additional set of building props.
 * Props_Stone = A set of stone building props.
 * Props_Donkey = A donkey attached to a mill building.
 * Props_Hay = A bale of hay attached to a mill building.
 * Rider = The rider of a cavalry mount.
 * Snow = Prop for applying a snow texture. 
 * Torso = Object on chest.
 * Tree = The leafy top part attached to a tree's trunk.

=== Actor ===
''BRIEF DESCRIPTION ::'' Path under actors/ to the .xml actor that defines this prop.

= Texture =
''BRIEF DESCRIPTION ::'' Name and location of the texture.

This points to the specific location and name of the texture used for this actor.  There is only one texture per actor; if more are needed - use a prop.  Textures are saved as dds files (dxt1).  

Alternate textures for the seasons may be specified as an attribute of the '''name.texture''' element.  The default texture is 'Summer'.  The other attribute options are:

 * Autumn
 * Winter
 * Spring

If unspecified it will use the default that is specified as the content of the '''object.texture''' element.