1. Objective

Create an XML editor with an easy to use graphical user interface (gui) to open, edit, save, and create entity files for use within Wildfire Game’s Pyrgenesis RTS game engine. This tool will enable creation and revision of entity files without the need to get into the ‘code’ of an XML file in a text editor, enhancing not only the speed of the game’s development, but also the ease of tuning unit attributes. End users that modify the game will also make use of this tool.

2. Entity Overview

Entities refer to any kind of object or person in the game - basically any "thing" which you can place on a map which plays a role in the world. These include units, resources, buildings, ships, siege weapons, etc. Entities in 0 A.D. are described by a set of parameters inside an XML file. These parameters alone will determine whether the entity acts like a unit, a building, a siege weapon, etc. There is no hard-coded representation "class hierarchy" for different types of entities.

4. Technical Requirements

· Open and read .xml entity files

· Save .xml entity files

· Modification of the .xml file through an intuitive UI

· Form Input Types

· Text Entry (numeric and string)

· Check Box

· Drop Down Selection

· Browse for file/path

· Code Documentation

· Ability to limit numerical values, and notify user if exceeds

· Visual representation of the hierarchy structure within the editor

· Bonus: Shortcut to open .xml file in Notepad (default), Option to set path to alternate text editor.

· Bonus: Load parent .xml files. Inherited fields would be rendered as disabled (greyed-out) with a link to the entity xml file that the data was inherited from and a check box that would toggle an override of any inherited parameters.

· Bonus: Use of wxWidgets

· Bonus: Tabbed windows when opening multiple Entities

· Bonus: Help, Basic User Guide

· Bonus: Undo

· Bonus: Autosave Option

· Bonus: Listing of recently opened entities in Menu=>File

· Bonus: Remember last saved and opened file location

· Bonus: Up and down arrows near numerical input to increment by whole numbers

Click, hold, drag on an arrow to increment fast

· Bonus: Tree view of all entities in a given folder

5. Suggested Implementation

Menu

File: New, Open…, Save, Save As…, Exit

Edit: Cut, Copy, Paste, Delete

Tools: Open with Text Editor, Options

Help: Help Contents, About

New

This image shows how the entity editor might look when first opening the program, with the exception that there would not be any information in the 'Parent Entity' or 'Actor' fields. There also would not be a name in the title in the title menu of the program either. Once the user browses for the location of the 'Parent Entity' and 'Actor', they then save the file. The contents of the XML might look something like this:

<?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>

<Entity Parent="template_unit_super_infantry">

<Traits>

</Traits>

<Actions>

</Actions>

<Actor>units/persians/super_unit_1.xml</Actor>

</Entity>

Open…

If you already have an entity file open, prompt: “Do you want to save changes?” Yes, No, Cancel.

If you select Yes or No, the “Open” window will appear allowing navigation to the file.

File Name: <text box>

File Type: <drop down> (.xml file type only)

<Open>

<Cancel>

Bonus: Remember opened file location

Save

If the file is new, treat as a “Save As…” command

Save the file

Save As…

“Save As” window will appear allowing navigation to the file.

File Name: <text box>

File Type: <drop down> (.xml file type only)

<Save>

<Cancel>

Bonus: Remember last saved file location

Exit

If entity has been modified, prompt: “Do you want to save changes?” Yes, No, Cancel.

Open with Text Editor

Gives a command to open the entity file in the Text Editor of choice (see Options)

Bonus: Options

Bonus: Path to the executable of preferred Text Editing Software.

Bonus: Turn autosave feature on (default is off)

Bonus: Set minutes at which the file will automatically save.

Bonus: Help Contents

Bonus: Link to a .html user guide.

About

Author, Version

Parameters

<Entity Parent="…"> (Inheritance): A listing of attributes which will be contained in entity definitions. (i.e. units, buildings, ships, siege weapons, resources, etc). We are following the "generic object" model where we just define a number of parameters, and then each object is customized by editing these parameters. In particular, one feature of this system is that it allows most of the properties of an individual entity class (template) to be left unspecified; these undefined properties are then filled in using the equivalent properties from a parent template. This allows unit classes to be designed referring to increasingly more generic classes. For example, a top-level 'Citizen Soldier' class (which isn't an actual type of unit in-game, just a collection of related classes) would specify attributes shared amongst all or most Citizen Soldiers. A lower level class 'Citizen Soldier Infantry' would keep the properties of 'Citizen Soldier', but also add new ones that are common to infantry. Similarly, 'Swordsman', 'Pre-Imperial Roman Swordsman' and 'Advanced Pre-Imperial Roman Swordsman' become increasingly more precise in their property definitions until they specify an individual class of unit. Example:

template_entity.xml

• template_unit.xml

• template_unit_cavalry.xml

• template_unit_cavalry_ranged.xml

• template_unit_cavalry_ranged_javelinist.xml

• cart_cavalry_javelinist_b.xml

• cart_cavalry_javelinist_a.xml

<Action> and <Trait>: We distinguish between two main categories of attributes for entities. These are simply groups to make it easier to digest all the different attribute types:

Actions are abilities that the entity can use, such as attacking an opponent, gathering a resource, or patrolling an area. These in turn have additional attributes that further define the behaviour of the action (such as how much damage the entity inflicts in attacks, how the damage is affected by armour types, and how quickly the entity moves when performing a move action).

If there is no action assigned to the entity, then we can assume that it doesn't have that ability. Actions typically have a cursor and GUI button that can be used to command the entity to perform this action.

Traits, on the other hand, are passive attributes that require little to no intervention from the player. Here we have information such as the entity's health, armour, vision, and resource cost. Traits also include abilities and effects that occur automatically, such as health regeneration.

When the user clicks on the [+] to expand the Trait or Action they are then presented with the option to add multiple a trait/action to this entity. For this exercise, we will limit the vast number of traits and actions to only four that cover all of the basic ui necessity widgets.

<Trait> - Drop down selection between the following:

Id, MiniMap

<Action> - Drop down selection between the following:

Attack, Move

The following are specific details about parameters for the required traits and attributes.

TRAIT: <ID> – These properties identify and classify an entity. Attributes include the unit's name, icon, class properties, tooltip rollover, historical information, and civilisation ownership.

<Specific> - String, limit to 25 characters

<Civ> - Drop down selection between the following:

Carthaginians, Celts, Hellenes, Iberians, Persians, Romans

<History> - 2000 Character limit, scrollable field

TRAIT: <MiniMap> – This attribute specifies how the entity appears on the Mini-Map

<Type> - Drop down selection between the following:

Unit, Support, Hero, Structure, Stone,Ore, Wood, Food, Settlement, Special

ACTION: <Attack> – An object with this ability is able to attack opponents or wild animals.

<Hack>, <Pierce>, <Crush> - Number with value of 0-300

<MinRange> - Number with value of 0-50

<Range> - Number with value of 0-100

<Speed> - Number with value of 0-3000

<ProjectileSpeed> - Number with value of 0-300

ACTION: <Move> - An object with this ability can be commanded to move from one location to another.

<Speed> - Number with value of 0-50

<Turning Radius> - Number with value of 0-5

<Range> - Number with value of 0-1000

<RangeMin> - Number with value of 0-100

<RegenRate> - Number with value of 0-10

<DecayRate> - Number with value of 0-20

<PassThroughAllies> Boolean, True or False

<Patrol> << Ignore this parameter >>

6. Glossary

· Template: definition of a class of units: traits and characteristics.

· Entity: instance of an Template (created from a Template definition); has its own stats (health, etc); has its own Actor; has its own 3D transform (determined by placement in Scenario Editor).

· Actor: the visual representation of a unit defined in an xml file; has a reference to a model, textures, proped actors, animations, etc.

Appendix A - Example of a Complete Entity Editor'

Appendix B – pers_super_infantry_example.xml

<?xml version="1.0" encoding="iso-8859-1" standalone="no" ?> 
<Entity Parent="template_unit_super_infantry">
	<Traits>
		<Id>
			<Specific>Anusiya</Specific> 
			<Civ>Persians</Civ> 
			<History>The Anusiya (or, as they are more commonly known, Immortals) were the elite of the Persian army, handsomely equipped with armor and weapons, including swords which were rare weapons in the normal ranks. A unit of 10,000 men, their number was always kept to full strength whenever a man was killed or wounded, resulting in their nickname. They were ferocious fighters and well respected.</History> 
		</Id>
		<MiniMap>
			<Type>Unit</Type> 
		</MiniMap>
	</Traits>
	<Actions>
		<Attack>
			<Melee>
				<Hack>30.0</Hack> 
				<Pierce>0.0</Pierce> 
				<Crush>0.0</Crush> 
				<Range>.75</Range> 
				<Speed>1500</Speed> 
			</Melee>
			<Charge>
				<Hack>75.0</Hack> 
				<Pierce>0.0</Pierce> 
				<Crush>0.0</Crush> 
				<Range>1.0</Range> 
				<Speed>1000</Speed> 
			</Charge>
			<Ranged>
				<Hack>0.0</Hack> 
				<Pierce>45.0</Pierce> 
				<Crush>0.0</Crush> 
				<MinRange>14.0</MinRange> 
				<Range>4.0</Range> 
				<Speed>1250</Speed> 
				<ProjectileSpeed>25.0</ProjectileSpeed> 
			</Ranged>
		</Attack>
		<Move>
			<Speed>8.5</Speed> 
			<TurningRadius>0.25</TurningRadius> 
			<Run>
				<Speed>16.5</Speed> 
				<Range>50.0</Range> 
				<RangeMin>0.0</RangeMin> 
				<RegenRate>2.5</RegenRate> 
				<DecayRate>5.0</DecayRate> 
			</Run>
			<PassThroughAllies>true</PassThroughAllies> 
		</Move>
		<Patrol /> 
	</Actions>
	<Actor>units/persians/super_unit_1.xml</Actor> 
</Entity>