Actors are the graphical representations of objects in the game. They combine meshes, textures, animations and props, and also control some other graphical features (such as whether the objects casts shadows or has transparent textures - see MaterialSystem).

Actor data is stored in XML files, which can be edited by hand, but usually the Actor Editor is used instead. Actor XML files are located in subdirectories of art\actors\ for a given mod (see mod layout).

To test how an actor will look in-game, use Atlas' actor viewer.

Terminology

• Variant: a named collection of data items, specifying the actor's texture, animations, etc (or any subset of those data). Shown in the Actor Editor as a single row. A variant can also be defined in an external file (located under art/variants/), or as a combination of an external file with extra internal definitions (which merges both definitions).
• Group: a set of variants; represented in the Actor Editor by a block of rows, separated from other groups by blank rows.
• Choice: a variant from a group, which has been chosen to be used on the actor. Choices are often made randomly, and combine to form:
• Variation: a set of choices, one from each group, making up a particular version of the actor.
• Selection: a text string that usually matches a variant name; the chosen variation will use variants which match one of the selections, where possible.

Randomness and selections

Variants are both used to generate random variety amongst the entities(f.e. giving a different shield type to different units), and to let the game code choose certain configurations of the entities (f.e. a unit that's chopping wood holds an axe, and no sword).

To achieve this, the actor is split into groups, each of which contains several variants.

From each group, a variant is chosen, and the chosen variants are combined into a variation. Most actors have a single "Base" variant in a group that defines the general properties of the actor (a single mesh to use, some default props, ...). And that default definition is extended by choices from the other groups.

Variants have the following attributes in their XML:

• A frequency controls how likely it is to be chosen. This must be set if the variant should be chosen randomly, or if there's a default variant (f.e. the Idle state of a unit). If two variants have equal frequency values, they have equal chance of being selected. A zero-frequency variant can still be selected by the game.
• A name makes it possible for the game code to select a certain variant. These names should be standardised, and follow the terms the game uses (f.e. gather-tree and not chop-wood). If a name is chosen (either by randomness or by the game code), it's selection is also passed on to the props. So when that name appears in a variant of the included props, that variant will be chosen. But variants that are chosen randomly don't need a name.
• The file attribute makes it possible to include a variant from an external file. The contents of the file gets merged with the contents of the actor (note that the external file may also have a name and/or a frequency defined).

Then finally, the look of the actors is defined in the content of the variants. These are the different elements you'll find there:

• mesh: The *.dae or *.pmd model to use.
• props: A list of extra actors that are attached to "prop points" (bones). Setting a prop with a certain attachpoint but no actor will clear the actor chosen in a previous variant. By setting a minHeight and maxHeight, the prop will stay relative to the ground level (within it's given bounds). This allows to create "drop-props" that make a building adapt to the terrain. Setting the selectable to false will ignore the prop when calculating the selection box.
• textures: A list of textures to use. This includes AO, Specular, and Normal maps. The name should show what type of texture it is.
• animations: A list of animations. The default animation is always "Idle", but other animations are chosen by the game. When multiple animation have the same name, the graphic code will choose a random animation from the list every time an animation ends (unlike randomness in variants, which is more permanent). As a result, animations with the same name should blend well together. Depending on the action used, the animation will be played at the speed given, or the engine will try to sync the animation on a certain event (f.e. when shooting an arrow, the animation speed is altered so every arrow that departs matches the event).
• decal: only used on special decal actors (which are in turn used as props on regular buildings), the parameters here define how a textures (defined under the textures list) are placed on the terrain.
• particles: only used on special particle actors that define smoke, fire and other special effects.
• color: (no idea what this does)

For example here is how an actor might appear in actor editor:

This female citizen has 3 groups: one with a single variant called "Base", a second with variants for model and texture, and a third group for prop variants.

• In the first group, the "Base" variant will always be chosen as there is no other variant and its frequency is 1. This variant defines props and animations common to all the other groups. Note that a prop is also an actor and may be randomized in its own file, as in this case. We only need to reference a single "dudette_head" prop actor which can vary in texture, shape, and other qualities.
• The second group contains different body models and textures. This flexibility means we can have a single mesh with altered appearance due to random texture variants. In this example, "Dress-Chiton" has the greatest chance of being chosen and is 3x as likely to be chosen as "Dress-linen".
• The last group contains prop variants which differ based on the actor's current behavior. If the female is idle, her hands will be empty; if she's woodcutting, she will have an axe in her left hand, etc. She will be idle by default, since that's the only variant in this group with a non-zero frequency. The game's logic will select other variants when appropriate.

Actor XML format

The following is an example of version 1 of the actor XML (edited for clarity):

<?xml version="1.0" encoding="utf-8"?>
<actor version="1">
  <castshadow/>
  <group>
    <variant frequency="100" name="Base">
      <animations>
        <animation file="biped/inf_sword_ready_a.dae" name="Idle" speed="100"/>
        ...
        <animation file="biped/walk_spearshield.psa" name="Walk" speed="120"/>
        <animation file="biped/walk_spearshield.psa" name="Walk" speed="111"/>
        ...
      </animations>
      <mesh>skeletal/m_tunic_short.dae</mesh>
      <props>
        <prop actor="props/units/heads/head_hele_b.xml" attachpoint="head"/>
        <prop actor="props/units/shields/rome_parma_b.xml" attachpoint="shield"/>
        ...
      </props>
      <textures>
        <texture file="skeletal/rome_ijv_b.png" name="baseTex"/>
      </textures>
    </variant>
  </group>
  <group>
    <variant frequency="100" name="Idle"/>
    <variant name="Melee">
      <props>
        <prop actor="props/units/weapons/verutum_reverse.xml" attachpoint="loaded-r_hand"/>
        <prop actor="props/units/weapons/verutum.xml" attachpoint="projectile"/>
        <prop actor="" attachpoint="r_hand"/>
      </props>
    </variant>
    <variant name="gather_tree">
      ...
    </variant>
    ...
  </group>
  <material>player_trans.xml</material>
</actor>