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. You can use the Actor Editor or edit them by hand - the latter is necessary if you're working with quality levels.
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

• Quality level: actor files can define different actors for different quality levels. Depending on the user's graphics setting, he will then see different models/textures/props for a given unit.
• 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 to chose from randomly. Note that every time an animation ends, a new animation is chosen randomly. In contrary to the random variants, which are persistent for the life of the entity. Animations have the following properties:
  • name: The name of the animation. This name is important to select the right animations. If one or more animations matches the name used by the game for a certain task, then a random animation with that name is chosen (according to the frequencies). Some common animation names are "walk", "idle", death"…
  • id: An optional identifier for the animation. Need not be unique. This will be used to sync animations from all props. I.E. if a you have an actor with a horse and a rider prop, and the horse uses a walk animation with id "left", the rider will try using a walk animation with id "left".
  • frequency: similar to the frequency of the variant, but determines what animation will be chosen.
  • file: location of the actual animation file
  • speed: speed to execute the animation. Note that some actions in the game have an "event" in which case the speed will be ignored, and the animation will by synchronised to the events. For the walk animation, the speed is also altered with the movement speed of the unit.
  • event: time at which the event of a certain action (f.e. firing of an arrow) has to happen, so the game can synchronise the animation with the arrow being fired.
  • load: point at which the actor on the projectile attachpoint becomes visible.
  • sound: not used anymore, sounds are defined in the entity templates.
• 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>

Quality Levels

You have several options to define quality levels, illustrated below (they can be freely combined):

<?xml version="1.0" encoding="utf-8"?>
<qualitylevels version="1">
  <!-- Define the actor directly inline. This actor will be used for settings "low" and worse. -->
  <actor quality="low">
    <group>
      <variant frequency="100" name="Base">
        ...
      </variant>
    </group>
    <group>
      ...
    </group>
    ...
  </actor>
  <!-- Define the actor in a separate file -->
  <actor quality="medium" file="some_other_actor"/>
  <!-- Refer to the inline actor (see below). -->
  <actor quality="high" inline=""/>
  <!-- Quality is just a number from 0 to 255. "low" is 100, "medium" 150 and "high" is 200. -->
  <actor quality="255" inline=""/>
  <!--
    The inline actor is just a regular actor, but it will can be parsed several times.
    You can use "minquality" and "maxquality" to define a [minquality, maxquality[ range in which to use groups & variants.
    You can also use this for materials & other actor attributes (though not variant attributes, you will have to define different variants).
  -->
  <inline version="1">
    <!-- This group only exists if the actor quality is strictly under "high", e.g. "medium" or "low". -->
    <group maxquality="high">
      <variant frequency="100" name="Base">
      </variant>
    </group>
    <!-- This group exists if the actor quality is "high" or more. -->
    <group minquality="high">
      <!-- This variant exists if the actor quality is 230 or more.-->
      <variant minquality="230" frequency="100" name="Base">
        ...
      </variant>
      <variant frequency="100" name="Base">
        ...
      </variant>
    </group>
    <!-- This actor will only cast shadow if the actor quality is 220 or more.-->
    <castshadow minquality="220"/>
  </inline>
</qualitylevels>