User Tools

Site Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
mapping:cawe:dialogs:entityinspector [2008-02-26 19:10]
Carsten Revised the text
mapping:cawe:dialogs:entityinspector [2013-01-07 12:07] (current)
Line 1: Line 1:
 ====== The Entity Inspector Dialog ====== ====== The Entity Inspector Dialog ======
  
-This dialog presents ​all kinds of detailed information about your map and its entities ​that is not found elsewhere and cannot be seen in the 2D or 3D views+This dialog presents detailed information about your map and its entities. 
-It allows ​you to see the hierarchically structured ​entity ​list that your map is composed of, to inspect the properties of each entity, and to edit the map script.+It shows you the hierarchically structured list of entities ​that your map is composed of, 
 +allows you to inspect the properties of each entity, and provides a built-in source code editor for the map script.
  
-The dialog is opened by selecting **Entity Inspector** from the [[mapping:​cawe:​menureference:​edit|Edit]] menu.+The dialog is opened by selecting ​the **Entity Inspector** ​item from the [[mapping:​cawe:​menureference:​edit|Edit]] menu.
  
-The following text describes the three "​tabs"​ that each implements one of the main features of the dialog.+The following text describes the three "​tabs"​ that implement ​the main features of the dialog.
  
  
Line 13: Line 14:
 {{:​mapping:​cawe:​dialogs:​dialog_entity_inspector_page1.png }} {{:​mapping:​cawe:​dialogs:​dialog_entity_inspector_page1.png }}
  
-The Entity Report ​contains ​a list of all entities that exist in the map. It can be used to find and select individual entities+The Entity Report ​keeps a list of all entities that exist in the map. 
-Filtering the list is possible by several options.+It is used to easily manage, ​find and select individual entities, and thus provides a convenient alternative to locating entities in your map manually.
  
-  * **Entity list**: A list of all entities ​in this map consisting of the entities ​class and its name (if set)The list is filtered by the filter options described below. Clicking on a list entry selects the entity in the map. You can selected ​multiple entities ​here as well by holding ​down the ''​CTRL''​ or ''​SHIFT''​ key when clicking on a list entry: ​This works just like in the Windows Explorer.+The entities ​are listed by the name of their entity ​class and their instance ​nameif one has given, e.g"''​static_detail_model (TreasureChest)''"​. 
 +Clicking on a list entry selects the related ​entity in the 2D and 3D views of the map as well. 
 +You can select ​multiple entities ​at the same time by holding the ''​CTRL''​ or ''​SHIFT''​ key while clicking on an entry: 
 +this works just like in Windows Explorer
 +The presented list is sorted in alphabetical order and can be filtered by several options as described below.
  
-  * **Go to**: Centers the 2D views onto the selected entities ​from the list+  * **Go to**: Centers the 2D views on the selected entities. 
-  * **Delete**: Deletes the selected entities from the list and the map.+  * **Delete**: Deletes the selected entities ​(both from the list and from the map).
  
-  * **Filter** +  * **Filter**: The controls in the filter box determine which entities are included in the list above. 
-    * **Brush Entities**: ​Show brush entities in list. +    * **Brush Entities**: ​When checked, the brush-based ​entities ​are included ​in the list. 
-    * **Point Entities**: ​Show point entities in list. +    * **Point Entities**: ​When checked, the point-based ​entities ​are included ​in the list. 
-    * **Include hidden Entities**: ​Show hidden ​entities in list+    * **Include hidden Entities**: ​When checked, ​entities ​are included even though they are normally hidden (as part of a VisGroup) ​in the 2D and 3D views
-    * **By Key/​Value**: ​Filter ​the list by a specific ​key/value pattern ​in the entity properties+    * **By Key/​Value**: ​You can reduce ​the list of entities to those whose properties match the given key/value pattern. 
-    * **Exact**: Toggles if the key/value pattern has to be exact the same or if partial match counts. +    * **Exact**: Toggles if the key/value pattern has to be an exact match, ​or if partial match counts ​as well
-    * **By Entity Class**: ​Filters ​the list by entities from a specific ​entity class.+    * **By Entity Class**: ​If checked, only entities of the specified ​entity class are shown.
  
  
Line 34: Line 39:
 {{:​mapping:​cawe:​dialogs:​dialog_entity_inspector_page2.png }} {{:​mapping:​cawe:​dialogs:​dialog_entity_inspector_page2.png }}
  
-In the Properties tab, you can inspect all the properties ​of the currently selected entity.+The Properties tab is one of the most important dialogs in CaWEbecause it allows ​you to inspect, set and modify ​all of the advanced attributes ​of the currently selected entity.
  
-The tab starts with a text item containing information about the number ​and type of the currently selected ​entity. +The properties are presented in tabular form as pairs of //keys// (on the left) and their related //values// (on the right): 
-The top-left button ​is used to switch between a categorized and alphabetical view of all the properties. +The //set of keys// that are available for an entity is defined by the entity's class. It can therefore not be changed directly within CaWE
-Below that you find the actual list of properties, followed by a help text for the currently selected propertycontaining its name, type and description.+Adding, removing or renaming keys is only possible via the game's ''​EntityClassDefs.lua''​ script, which contains ​the definitions ​of all entity classes ​for a game. Updating this script possibly affects all maps of a game, and is consequently normally never done for an individual map, 
 +but in the early planning stages of a MOD.
  
-There are 3 different categories for properties:​ +Changing ​the //values// however is the daily bread and butter of a mapper. 
-  * **Properties**:​ These are the "​usual"​ properties. They are defined by their entities class and therefore mandatory for the entity+Therefore, doing so is not only easy, but it has also been made as convenient as possible. 
-  * **Undefined Keys**: Keys that are not defined by the entities class and added to the entity manually. +In most cases, you just click into the desired value field and enter a new value directly. 
-  * **Mixed Keys**: Keys that are only used by a subset of the currently selected entities or have different types for different entity classesKeys in this category can not be edited.+For each variable (that is, a key/value pair), also the variables //type// is known to CaWE, which is uses to assist you entering correct values: 
 +  * keys that only accept integer values do not accept commas, periods or letters, 
 +  ​keys that accept boolean values or a choice from an enumeration act accordingly,​ 
 +  ​keys that expect colors will provide you a color chooser ​and an automatic preview, 
 +  * keys whose values are multi-line strings come with an appropriate editor, 
 +  ​keys that expect file names (e.g. for sounds, models, etc.) will provide you with a three-dots "​..."​ browse button (which is //very helpful// :!:), 
 +  * and so on. 
 +We're currently working on improving ​this feature further, e.g. with "​Play"​ buttons for listening to sound files, a preview facility also for model files, etc.
  
-The background color of each property identifies ​the state of its valueThere are 4 different states ​value can have:+Note that at the top of the dialog, there is a summary about the number ​of selected entities and their classes. 
 +At the bottom of the dialog, ​short help text for the currently selected key is provided. 
 +Help is also available in form of tool-tips for the key the mouse pointer is currently over.
  
-  * The property'​s value matches the default value defined by the entities class and only used by one entity (light blue color). 
-  * The property'​s value is a custom value defined by the user and only used by one entity (no color). 
-  * The property'​s value matches the default value defined by the entities class and only used by more than one entity (darker blue color). 
-  * The property'​s value is a custom value defined by the user and only used by more than one entity (light orange color). 
  
-Since Mixed Keys can'be edited, their background is always ​white and the property ​is disabled.+==== Classname ==== 
 + 
 +Changing the class of an entity is a special action, because it corresponds to deleting the entity and re-instantiating it under a different class but with the same properties. Nonetheless,​ you can use the special ​''​classname''​ property to change an entity'​s class like any other property: 
 +You're provided with a choice box that contains all possible new classes for that entity, and just making the selection reincarnates the entity as an object of the new class. 
 + 
 +Please note that currently there is a restriction that brush-based (solid) entities can only be converted into entity'​s of classes that are brush-based,​ too. Similarly, entities that are point-based can only be converted into entity'​s that are point-basedtoo. 
 + 
 + 
 +==== Undefined Properties ==== 
 + 
 +Sometimes entities come with key/value pairs that have no corresponding definition in their entity class. 
 +Such key/value pairs can occur occasionally e.g. when an entity was converted to a different class (see below), an entity class got a variable definition removed after a map has already been made with it, or when an entity has been imported from an entirely different game. 
 +The entity might then bring in a key named e.g. ''​light_pulse_frq''​ that is utterly unknown in the context of the current games entity definitions. 
 + 
 +Another but similar case occurs when the entity'​s class name is unknown among all entity classes of the current game. 
 +This typically happens when you try to import for example an entity of class "​stuffed_animal"​ of a children'​s game into a game about aliens or robots, or in any other case when the current game just knows nothing about the imported entity class. 
 + 
 +In these cases, there is no corresponding definition for such keys in the game definition. 
 +CaWE therefore collects such occurrences separately and keeps them under the special category "​Undefined Properties"​. 
 + 
 +Because undefined properties are not dealt with by the game in any way, you're free to change and modify them at will. 
 +You can even right-click them to open a context menu that allows you to rename them, to add new ones or to delete them. 
 + 
 +In most practical cases, you'll want to get rid of undefined keys though, which can be achieved by renaming them to something meaningful,​ 
 +by deleting them, by changing the entire entity class to something else, or a combination thereof. 
 + 
 + 
 +==== Background Colors ==== 
 + 
 +The property grid employs several ​background ​colors in order to indicate certain conditions of the values: 
 +  * <color #​000000/#​FFFFFF>​White background</​color>​ indicates that this is just a normal value. 
 +  * <color #​000000/#​CCDDFF>​Light blue background</​color>​ also indicates a normal value that also happens to be the entity class'​s default value for this variable. 
 +  * <color #​000000/#​FFDDCC>​Light orange background</​color>​ is used whenever multiple entities are selected that have //​different//​ values for the //same// key. You can still enter a new value for such keys: The key of each selected entity will then be set to the same new value and the background color will change back to white accordingly. 
 +  * <color #​000000/#​FF9797>​Light red background</​color>​ is currently used at only one occasion: When you set a ''​model''​ key and have not yet specified a value for a ''​collisionModel'', ​the ''​collisionModel''​ variable ​is temporarily highlighted with this color in order to remind you to also set a collision model.
  
-To edit a property you have to click in it's editor field (right column) and enter a value. Note that properties can have different types and their input fields may only accept specific values (integers for example). 
-Some input field have an additional editor button, that can be used to set the property'​s value. Examples are a file chooser for model files or a color picker for color properties. 
  
 ==== Working with multiple entities ==== ==== Working with multiple entities ====
  
-The Properties tab works also very well when //more// than a single entity is selected, or in fact, any number of them at the same time. +The Properties tab works also very well when //more// than a single entity is selected, or in fact, any number of them is selected ​at the same time. 
-In order to present you the properties of multiple entities ​all at the same time, CaWE "​overlays"​ them for you, +In order to present you the properties of multiple entities, CaWE "​overlays"​ them for you, 
-so that even great amounts of them remain easy to understand and manage.+so that even great amounts of simultaneously selected entities ​remain easy to understand and manage.
  
-In order to achieve this, CaWE makes sure that properties that are candidates for layering, but otherwise incompatible ​to each other for any reason (e.g. because the property is known only to some but not all of the entities, or defined multiply with different types), are treated specially as "​mixed"​ properties. A property that is marked as "​mixed"​ has attributes in one entity that are non-existent or different in another, which generally makes them incompatible to each other.+In order to achieve this, CaWE makes sure that properties that are candidates for layering, but otherwise incompatible ​with each other for any reason (e.g. because the property is known only to some but not all of the entities, or defined multiply with different types), are treated specially as "​mixed"​ properties. A property that is marked as "​mixed"​ has attributes in one entity that are non-existent or different in another, which generally makes them incompatible to each other.
  
-Such mixed properties are therefore listed in separate category, ​but protected from editing ("​read-only"​). This makes sure that you can see such affected properties, but not inadvertently get nonsensical values written into lots of entities. Note that this is not a restriction,​ because it's another way of saying: //"​Stop! If you assign a value to this property, there is at least one entity affected for which doing this makes no sense at all."//​+Such mixed properties are therefore listed in another ​separate category, ​and they are protected from editing ("​read-only"​). This makes sure that you can see such affected properties, but not inadvertently get nonsensical values written into lots of entities. Note that this is not a restriction,​ because it'​s ​just another way of saying: //"​Stop! If you assign a value to this property, there is at least one entity affected for which doing this makes no sense at all."//​
  
 If you still want to edit a property that is listed as "​mixed",​ there is an easy way to overcome the problem: If you still want to edit a property that is listed as "​mixed",​ there is an easy way to overcome the problem:
Line 74: Line 116:
 ===== Map Script ===== ===== Map Script =====
  
-In the Map Script tab, you can view and edit the maps current script.+In the Map Script tab, you can view and edit the source code of the maps current script.
  
-FIXME This feature is not yet implemented -- I'm sorry for that. Both the functionality and the documentation will be provided later. +FIXME This feature is not yet implemented -- I'​m ​very sorry. Both the functionality and the documentation will be provided later. 
-However, please note that the game code and the Ca3D-Engine ​already fully implement and support map scripting! +However, please note that the game code and the Cafu engine ​already fully implement and support map scripting! 
-Use any text editor of your choice in order to program your map scripts independently and outside of CaWE -- all the example scripts that come with the Ca3DE releases have been written that way. ;-)+Use any text editor of your choice in order to program your map scripts independently and outside of CaWE. In fact, all the example scripts that come with the Cafu releases have been written that way. ;-)
  
mapping/cawe/dialogs/entityinspector.1204049454.txt.gz · Last modified: 2013-01-07 12:07 (external edit)