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. This will greatly enhance not only the speed of the game's development, but also ease the balancing the game's statistics. End users that modify the game will also make use of this tool.

Entity Overview

Entities refer to basically any kind of object or person in the game that has an affect on the game's simulation. Basically any "thing" which you can place on a map that affects the way the game is played. These include units, resources, buildings, ships, siege weapons, etc. Entities in 0 A.D. will be described by a set of parameters. These parameters alone will determine whether the entity acts like a unit, a building, a siege weapon, etc. There will not be any hard-coded representation, like a class hierarchy for different types of entities.

Entity Definitions

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 allowing 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 that could ever exist 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_entity_full.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

Actions and Traits: 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, and against what 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, amour, and vision, what units can garrison in it, and how much it costs to create one. It also covers abilities and effects that occur automatically.

Technical Requirements

Open and read .xml entity files Save .xml entity files Modification of the .xml file through an intuitive UI Form Input Types o Text Entry (numeric and string) o Check Box o Drop Down Selection o 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 jsWidgets 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: Memory of last saved and opened file location

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 <Explain what happens when you hit Menu=>File=>New. How the interface might look (ignoring inheritance for now – explain in a later section). Explain expand and collapse feature. >

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 only) <Open> <Cancel> Bonus: Memory of last saved and 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 only) <Save> <Cancel> Bonus: Memory of last saved and opened file location

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

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

<Need parameters, variables, minimum values, maximum values, etc… for all the entity characteristics that we want to have the students include in their entity editor. We will show them an example of the xml code as well as the user interface using Michael's mockups>

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 (hitpoints, 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.

<Will add more terms with input from Stu>