Changes between Version 3 and Version 4 of EntityEditorDesign


Ignore:
Timestamp:
Oct 9, 2008, 7:35:25 PM (16 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