Changes between Version 3 and Version 4 of EntityEditorDesign


Ignore:
Timestamp:
2008-10-09 17:35:25 (5 years ago)
Author:
jason
Comment:

updating from the last document. Need to include photos. See here: http://www.wildfiregames.com/forum/index.php?s=&showtopic=11311&view=findpost&p=185830

Legend:

Unmodified
Added
Removed
Modified

  • EntityEditorDesign

    v3 v4  
    1 == Objective == 
    2  
    3 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. 
    4  
    5 == Entity Overview == 
    6  
    7 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. 
    8  
    9 == Entity Definitions == 
    10  
    11 '''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: 
     11.   '''Objective''' 
     2 
     3Create 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. 
     4 
     52.   '''Entity Overview''' 
     6 
     7Entities 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. 
     8 
     94.   '''Technical Requirements''' 
     10 
     11·       Open and read .xml entity files 
     12 
     13·       Save .xml entity files 
     14 
     15·       Modification of the .xml file through an intuitive UI 
     16 
     17·       Form Input Types 
     18 
     19·       Text Entry (numeric and string) 
     20 
     21·       Check Box 
     22 
     23·       Drop Down Selection 
     24 
     25·       Browse for file/path 
     26 
     27·       Code Documentation 
     28 
     29·       Ability to limit numerical values, and notify user if exceeds 
     30 
     31·       Visual representation of the hierarchy structure within the editor 
     32 
     33·       Bonus:  Shortcut to open .xml file in Notepad (default), Option to set path to alternate text editor. 
     34 
     35·       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. 
     36 
     37·       Bonus:  Use of wxWidgets 
     38 
     39·       Bonus:  Tabbed windows when opening multiple Entities 
     40 
     41·       Bonus:  Help, Basic User Guide 
     42 
     43·       Bonus:  Undo 
     44 
     45·       Bonus:  Autosave Option 
     46 
     47·       Bonus:  Listing of recently opened entities in Menu=>File 
     48 
     49·       Bonus:  Remember last saved and opened file location 
     50 
     51·       Bonus:  Up and down arrows near numerical input to increment by whole numbers 
     52 
     53  Click, hold, drag on an arrow to increment fast 
     54 
     55·       Bonus:  Tree view of all entities in a given folder 
     56 
     57'''[[BR]] '''5.   '''Suggested Implementation''' 
     58 
     59'''Menu''' 
     60 
     61File: New, Open…, Save, Save As…, Exit 
     62 
     63Edit: Cut, Copy, Paste, Delete 
     64 
     65Tools: Open with Text Editor, Options 
     66 
     67Help: Help Contents, About 
     68 
     69'''New''' 
     70 
     71[[BR]] 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: 
     72 
     73<?xml version="1.0" encoding="iso-8859-1" standalone="no" ?> 
     74 
     75<Entity Parent="'''template_unit_super_infantry'''"> 
     76 
     77<Traits> 
     78 
     79</Traits> 
     80 
     81<Actions> 
     82 
     83</Actions> 
     84 
     85<Actor>units/persians/super_unit_1.xml</Actor> 
     86 
     87</Entity> 
     88 
     89'''Open…''' 
     90 
     91If you already have an entity file open, prompt: “Do you want to save changes?” Yes, No, Cancel. 
     92 
     93If you select Yes or No, the “Open” window will appear allowing navigation to the file. 
     94 
     95File Name: <text box> 
     96 
     97File Type: <drop down> (.xml file type only) 
     98 
     99<Open> 
     100 
     101<Cancel> 
     102 
     103Bonus: Remember opened file location 
     104 
     105'''Save''' 
     106 
     107If the file is new, treat as a “Save As…” command 
     108 
     109Save the file 
     110 
     111'''Save As…''' 
     112 
     113“Save As” window will appear allowing navigation to the file. 
     114 
     115File Name: <text box> 
     116 
     117File Type: <drop down> (.xml file type only) 
     118 
     119<Save> 
     120 
     121<Cancel> 
     122 
     123Bonus: Remember last saved file location 
     124 
     125'''Exit''' 
     126 
     127If entity has been modified, prompt: “Do you want to save changes?” Yes, No, Cancel. 
     128 
     129'''Open with Text Editor''' 
     130 
     131Gives a command to open the entity file in the Text Editor of choice (see Options) 
     132 
     133'''Bonus: Options''' 
     134 
     135Bonus: Path to the executable of preferred Text Editing Software. 
     136 
     137Bonus: Turn autosave feature on (default is off) 
     138 
     139Bonus: Set minutes at which the file will automatically save. 
     140 
     141'''Bonus: Help Contents''' 
     142 
     143Bonus: Link to a .html user guide. 
     144 
     145'''About''' 
     146 
     147Author, Version 
     148 
     149'''Parameters''' 
     150 
     151'''<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: 
     152 
     153template_entity.xml 
     154 
     155- template_unit.xml 
     156 
     157- template_unit_cavalry.xml 
     158 
     159- template_unit_cavalry_ranged.xml 
     160 
     161- template_unit_cavalry_ranged_javelinist.xml 
     162 
     163- cart_cavalry_javelinist_b.xml 
     164 
     165- cart_cavalry_javelinist_a.xml 
     166 
     167'''<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: 
     168 
     169Actions 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). 
     170 
     171If 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. 
     172 
     173Traits, 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. 
     174 
     175When 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. 
     176 
     177<Trait> -                 Drop down selection between the following: 
     178 
     179Id, !MiniMap 
     180 
     181<Action> -              Drop down selection between the following: 
     182 
     183Attack, Move 
     184 
     185The following are specific details about parameters for the required traits and attributes. 
     186 
     187'''''[[BR]] 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.'' 
     188 
     189<Specific> -            String, limit to 25 characters 
     190 
     191<Civ> -                   Drop down selection between the following: 
     192 
     193Carthaginians, Celts, Hellenes, Iberians, Persians, Romans 
     194 
     195<History> -              2000 Character limit, scrollable field 
     196 
     197'''''TRAIT:''' <!MiniMap> – This attribute specifies how the entity appears on the Mini-Map'' 
     198 
     199<Type> -                Drop down selection between the following: 
     200 
     201Unit, Support, Hero, Structure, Stone,Ore, Wood, Food, Settlement, Special 
     202 
     203'''''[[BR]] ACTION:''' <Attack> – An object with this ability is able to attack opponents or wild animals.'' 
     204 
     205<Hack>, <Pierce>, <Crush> -         Number with value of 0-300 
     206 
     207<!MinRange> -                              Number with value of 0-50 
     208 
     209<Range> -                                  Number with value of 0-100 
     210 
     211<Speed> -                                  Number with value of 0-3000 
     212 
     213<!ProjectileSpeed> -                      Number with value of 0-300 
     214 
     215'''''ACTION:''' <Move> - An object with this ability can be commanded to move from one location to another.'' 
     216 
     217<Speed> -                        Number with value of 0-50 
     218 
     219<Turning Radius> -             Number with value of 0-5 
     220 
     221<Range> -                        Number with value of 0-1000 
     222 
     223<!RangeMin> -                    Number with value of 0-100 
     224 
     225<!RegenRate> -                  Number with value of 0-10 
     226 
     227<!DecayRate> -                  Number with value of 0-20 
     228 
     229<!PassThroughAllies>           Boolean, True or False 
     230 
     231<Patrol>                           << Ignore this parameter >>[[BR]][[BR]]'''''''''' 
     232 
     233'''6.   Glossary''' 
     234 
     235·       '''Template:''' definition of a class of units: traits and characteristics. 
     236 
     237·       '''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). 
     238 
     239·       '''Actor:''' the visual representation of a unit defined in an xml file; has a reference to a model, textures, proped actors, animations, etc. 
     240 
     241[[BR]] '''Appendix A - '''Example of a Complete Entity Editor''''''''''' 
     242 
     243'''[[BR]] Appendix B –  '''pers_super_infantry_example.xml 
     244 
     245 
    12246{{{ 
    13  template_entity.xml 
    14  -> template_entity_full.xml 
    15     -> template_unit.xml 
    16        -> template_unit_cavalry.xml 
    17           -> template_unit_cavalry_ranged.xml 
    18              -> template_unit_cavalry_ranged_javelinist.xml 
    19                 -> cart_cavalry_javelinist_b.xml 
    20                    -> cart_cavalry_javelinist_a.xml 
     247 
     248<?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>  
     249<Entity Parent="template_unit_super_infantry"> 
     250        <Traits> 
     251                <Id> 
     252                        <Specific>Anusiya</Specific>  
     253                        <Civ>Persians</Civ>  
     254                        <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>  
     255                </Id> 
     256                <MiniMap> 
     257                        <Type>Unit</Type>  
     258                </MiniMap> 
     259        </Traits> 
     260        <Actions> 
     261                <Attack> 
     262                        <Melee> 
     263                                <Hack>30.0</Hack>  
     264                                <Pierce>0.0</Pierce>  
     265                                <Crush>0.0</Crush>  
     266                                <Range>.75</Range>  
     267                                <Speed>1500</Speed>  
     268                        </Melee> 
     269                        <Charge> 
     270                                <Hack>75.0</Hack>  
     271                                <Pierce>0.0</Pierce>  
     272                                <Crush>0.0</Crush>  
     273                                <Range>1.0</Range>  
     274                                <Speed>1000</Speed>  
     275                        </Charge> 
     276                        <Ranged> 
     277                                <Hack>0.0</Hack>  
     278                                <Pierce>45.0</Pierce>  
     279                                <Crush>0.0</Crush>  
     280                                <MinRange>14.0</MinRange>  
     281                                <Range>4.0</Range>  
     282                                <Speed>1250</Speed>  
     283                                <ProjectileSpeed>25.0</ProjectileSpeed>  
     284                        </Ranged> 
     285                </Attack> 
     286                <Move> 
     287                        <Speed>8.5</Speed>  
     288                        <TurningRadius>0.25</TurningRadius>  
     289                        <Run> 
     290                                <Speed>16.5</Speed>  
     291                                <Range>50.0</Range>  
     292                                <RangeMin>0.0</RangeMin>  
     293                                <RegenRate>2.5</RegenRate>  
     294                                <DecayRate>5.0</DecayRate>  
     295                        </Run> 
     296                        <PassThroughAllies>true</PassThroughAllies>  
     297                </Move> 
     298                <Patrol />  
     299        </Actions> 
     300        <Actor>units/persians/super_unit_1.xml</Actor>  
     301</Entity> 
    21302}}} 
    22  
    23 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:  
    24  
    25 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). 
    26  
    27 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. 
    28  
    29 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. 
    30  
    31 == Technical Requirements == 
    32  
    33 Open and read .xml entity files 
    34 Save .xml entity files 
    35 Modification of the .xml file through an intuitive UI 
    36 Form Input Types 
    37 o       Text Entry (numeric and string) 
    38 o       Check Box 
    39 o       Drop Down Selection 
    40 o       Browse for file/path 
    41 Code Documentation 
    42 Ability to limit numerical values, and notify user if exceeds 
    43 Visual representation of the hierarchy structure within the editor 
    44  
    45  
    46 Bonus: Shortcut to open .xml file in Notepad (default), Option to set path to alternate text editor. 
    47 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. 
    48 Bonus: Use of jsWidgets 
    49 Bonus: Tabbed windows when opening multiple Entities 
    50 Bonus: Help, Basic User Guide 
    51 Bonus: Undo 
    52 Bonus: Autosave Option 
    53 Bonus: Listing of recently opened entities in Menu=>File 
    54 Bonus: Memory of last saved and opened file location 
    55  
    56  
    57 == Suggested Implementation == 
    58  
    59 Menu 
    60 File:   New, Open…, Save, Save As…, Exit 
    61 Edit:   Cut, Copy, Paste, Delete 
    62 Tools:  Open with Text Editor, Options 
    63 Help:   Help Contents, About 
    64  
    65 New 
    66 <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. > 
    67  
    68 Open… 
    69 If you already have an entity file open, prompt: "Do you want to save changes?" Yes, No, Cancel. 
    70 If you select Yes or No, the "Open" window will appear allowing navigation to the file. 
    71 File Name: <text box> 
    72 File Type: <drop down> (.xml only) 
    73 <Open> 
    74 <Cancel> 
    75 Bonus: Memory of last saved and opened file location 
    76  
    77 Save 
    78 If the file is new, treat as a "Save As…" command 
    79 Save the file 
    80  
    81 Save As… 
    82 "Save As" window will appear allowing navigation to the file.   
    83 File Name: <text box> 
    84 File Type: <drop down> (.xml only) 
    85 <Save> 
    86 <Cancel> 
    87 Bonus: Memory of last saved and opened file location 
    88  
    89 Exit 
    90 If entity has been modified prompt: "Do you want to save changes?" Yes, No, Cancel. 
    91 Exit 
    92  
    93 Open with Text Editor 
    94 Gives a command to open the entity file in the Text Editor of choice (see Options) 
    95  
    96 Bonus: Options 
    97 Bonus: Path to the executable of preferred Text Editing Software. 
    98 Bonus: Turn autosave feature on (default is off) 
    99 Bonus: Set minutes at which the file will automatically save. 
    100  
    101 Bonus: Help Contents 
    102 Bonus: Link to a .html user guide. 
    103  
    104 About 
    105 Author, Version 
    106  
    107 Parameters 
    108  
    109 <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> 
    110  
    111  
    112  
    113  
    114  
    115 == Glossary == 
    116  
    117 Template: definition of a class of units: traits and characteristics.  
    118 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).  
    119 Actor: the visual representation of a unit defined in an xml file; has a reference to a model, textures, proped actors, animations, etc.  
    120  
    121 <Will add more terms with input from Stu> 
    122