0 A.D. Actor Editor

Actor editor is a tool which provides a GUI for creating and modifying actors for the game. Since actors are stored in XML format, they can be edited in any text editor, but actor editor aims to be a more user-friendly method.

Actor editor is located next to the main pyrogenesis executable (pyrogenesis.exe on Windows), this location varies for a release install or SVN. If building the game yourself, you need to build Atlas too, since actor editor depends on it.

Note: Actor editor is currently broken on Linux and OS X, see #1553 and #1554. If you're not on Windows, you should use a text editor to modify the actor XML directly.

Interface

Here's an example of Actor Editor in use:

The interface consists of the following sections:

• Menu bar
• Actor properties
• Material
• Variant editor

Menu bar

The menu has a fairly standard layout, where File allows you to create a new actor, open existing ones, and save the currently opened actor; Edit allows you to undo or redo previous actions.

The Actor menu allows you to create a new entity template, after you have modified and saved the current actor. Not all actors require an entity template, generally actors that need to be interacted with by the player (units and buildings) require an entity while props and decorative actors (e.g. grass) don't require an entity template. Entity templates are located in simulation\templates\ (see mod layout).

Actor properties

These are per-actor settings that change how the actor appears in the game. Cast shadow determines whether the actor will cast a shadow, which is useful to disable for certain transparent actors like grass clumps. Float on water is useful for actors which should float on water (e.g. boats or water lilies) instead of conforming to terrain.

Material

Material files are per-actor settings that describe how to render the actor with some combination of effects like the following:

• transparency: alpha blending or alpha testing
• player color
• specularity or specular mapping
• normal mapping
• parallax
• ambient occlusion

Materials are located in art\materials\ (see mod layout). To create a new set of effects, you should create a new material. See MaterialSystem for more information.

Variant editor

Note: See here for definitions of actor terminology.

The main purpose of the actor editor UI is to edit groups and variants, displayed as a table with editable rows and cells. Each row in the table is a different variant. Contiguous sets of rows are called groups, separated by empty rows. A variant describes some subset of the actor's appearance and behavior, which can either be selected by game logic or at random (based on a specified ratio/frequency). Each actor has at least one group with at least one variant.

The columns describe properties of each row or variant:

• Variant: the name of this variant. It should be something descriptive for clarity, but some variants require a certain name as the game will reference them as such (e.g. Base, Idle, gather_tree)
• Ratio: the ratio or frequency at which this variant will be randomly chosen. Note: only non-zero ratio will be randomly selected by the game, but others can be selected in response to game activity (e.g. gathering or melee combat)
• Model: the mesh for this variant, the path must be relative to art\meshes\ (see mod layout).
• Texture: the texture(s) for this variant. Double-clicking this cell will open the Texture editor.
• Animations: the animation(s) for this variant. Double-clicking this cell will open the Animation editor.
• Props: the prop(s) for this variant. Double-clicking this cell will open the Prop editor.
• Colour: the colour for this variant. Double clicking this cell will open a standard color picker.

Texture editor

With the addition of rendering techniques like normal, specular and ambient occlusion mapping, there is now a need to support multiple textures per model. You open the animation editor by double-clicking the Textures cell for a given row/variant.

The texture type is specified with the Tex name field. Every actor should at least have a base texture ("baseTex") which is the standard diffuse or color texture. Other texture types are optional but may be required by a given material.

The texture File's path is relative to art\textures\skins\ (see mod layout).

Animation editor

Because a single actor variant can have multiple animations associated with it, there is an animation editor which allows setting these. You open the animation editor by double-clicking the Animations cell for a given row/variant.

Each animation requires a name (Anim name), but it's generally best to choose one from the cell's dropdown list as the game expects them to be spelled a certain way.

The animation File's path is relative to art\animation\ (see mod layout). For a description of the other animation properties (Speed, Load, Event) see AnimationSync.

Prop editor

A single actor variant can also have multiple props (other actors attached to a given node on the model). You open the prop editor by double-clicking the Props cell for a given row/variant.

Each prop references an Attachment point, which names the node on the actor's model where the prop gets attached by the game. The dropdown list for this cell contains some of the most common attachment points.

The Prop model may be left empty if the prop point should have no actor attached (e.g. an idle worker will have empty hands), or an actor may be referenced. The path is relative to art\actors\ (see mod layout).

Controls

General controls for the editor windows:

• Drag rows (using the left mouse button) to rearrange them.
• Use Ctrl+Z/Ctrl+Y, or the Edit menu, to undo/redo changes. There is no limit to the size of the undo history, though some actions (e.g. exporting to a file) can't be undone (yet).
• Double-click or right-click cells to edit them. The editing method depends on what column they're in.
  • In the text editing boxes: Use the escape key to cancel. Use the enter key, or click outside the box, to accept the changes.
  • In the table-style boxes (props, animations): Mostly identical to the main actor editor window, but without the menu. Use Ctrl+Z/Ctrl+Y to undo/redo.
• Double-click the dividing line between column headers for the standard 'resize to fit contents' behaviour. Drag the dividing line to resize.