Eden Editor: Configuring Attributes

From Bohemia Interactive Community
Revision as of 11:48, 2 December 2015 by Str (talk | contribs)
Jump to navigation Jump to search
⚠
Work In progress

A scenario and each entity in it are defined by their attributes. An attribute is a value customizable by the user, and it has some function tied to it. For example position object attribute tells engine where to create the object, and respawn scenario attributes determines what rule set will be used when players respawn.

Each attribute is configured in the global Config.cpp. Major engine-driven attributes are already present in the default Editor and can be modified to a degree. Modders can also add completely new attributes and decide how will they appear in the attribute window and what scripted functionality will they execute in the scenario.

Attributes can be added for general entity type (e.g., shared by all objects) or for specific entity types (e.g., just for BLUFOR Rifleman). An entity type can also override default values of general attributes (e.g., story character can have customized name and rank).

Structure

Attributes are configured and presented in the following structure:

Owner - defines what does the attribute set. Can be an entity, a scenario or editor preferences. In user interface, this is the whole attributes window.
└ Category - thematic category. Used only for sorting in the window, has no effect on the scenario.
└ Attribute - setting itself, represented by tailored user interface.


3den editAttributes.jpg

Configuration

Entity

General

General attributes are available for all entity classes of given type. Optional conditions can be applied to show the attribute only for limited subset of entities. For example rank attribute is shared by every object, be it a character, a vehicle or a prop. But its condition makes sure only characters have it available.

Attribute functionality is determined by its expression property. It is a code called at the scenario start, and it's purpose is to apply the attribute's value. The expression is saved to the scenario file together with value, which makes it independent on the addon which introduced the attribute. Only attributes with values different from the default are saved to the scenario file, which means only their expression will be called. 

class Cfg3DEN
{
	// Configuration of all objects
	class Object
	{
		// Categories collapsible in "Edit Attributes" window
		class AttributeCategories
		{
			// Category class, can be anything
			class MyCategory
			{
				displayName = "Object Init"; // Category name visible in Edit Attributes window
				collapsed = 1; // When 1, the category is collapsed by default
				class Attributes
				{
					// Attribute class, can be anything
					class MyAttribute
					{
						property = "MyAttributeUniqueID"; // Unique config property name saved in SQM
						control = "Edit"; // UI control base class displayed in Edit Attributes window, points to Cfg3DEN >> Attributes
						unique = 0; // When 1, only one entity of the type can have the value in the mission (used for example for variable names or player control)
						validate = "code"; // Validate the value before saving. Can be "none", "expression", "condition", "number" or "variable"
						condition = "object"; // Condition for attribute to appear (see the table below)
						// Expression called when applying the attribute in Eden and at the scenario start
						// Entity is passed as _this, value is passed as _value, property name is passed as _property
						// %s is replaced by attribute config name. It can be used only once in the expression
						expression = "_this setVariable [%s,_value];";
						// Expression called when custom property is undefined yet (i.e., when setting the attribute for the first time)
						// Entity is passed as _this
						// Returned value is the default value
						// Used when no value is returned, or when it's of other type than NUMBER, STRING or ARRAY
						// Custom attributes of logic entities (e.g., modules) are saved always, even when they have default value
						defaultValue = "42";
					};
				};
			};
		};
	};
};

Scenario

Some attributes are available for the scenario as a whole. Instead of belonging to an entity, they are configured for a section. All attributes within a section are shown in one window, for example weather and time of the day settings are in Environment section, while scenario name or picture are in Scenario section.

Scenario attributes work together with properties in Description.ext. An attribute "respawnDelay" can be configurable in Eden, but it can be also defined in the external file like this: 

respawn = 10;

Values in external files have priority over the ones set in the Eden Editor.

Configuration of scenario attributes is similar to general entity attributes. Sections are placed in pre-defined Mission class, and they contain attribute categories with attributes in them. 

class Cfg3DEN
{
	class Mission
	{
		class MySection // Custom section class, everything inside will be opened in one window
		{
			displayName = "My Attributes"; // Text visible in the window title as "Edit <displayName>"
			display = "Display3DENEditAttributesPreview"; // Optional - display for attributes window. Must have the same structure and IDCs as the default Display3DENEditAttributes
			class AttributeCategories
			{
				// The following structure is the same as the one used for entity attributes
				class MyMissionCategory
				{
					class Attributes
					{
						class MyMissionAttribute
						{
							property = "MyMissionAttributeUniqueID";
						};
					};
				};
			};
		};
	};
};

Special script commands can be used to manipulate scenario attributes:

  • Open window with attributes belonging to given section:
edit3DENMissionAttributes "MySection";
  • Set value of scenario attributes:
set3DENMissionAttributes [["MySection","MyMissionAttributeUniqueID",42]]
  • Get value of scenario attribute:
_myAttributes = "MySection" get3DENMissionAttribute "MyMissionAttributeUniqueID";
  • Access attribute value in the scenario itself. Compatible with Eden Editor attributes and with properties defined in external Description.ext file.
getMissionConfigValue "MyMissionAttributeUniqueID"

Preferences

There is a special scenario attribute section called Preferences. Any attribute configured in it will be saved in player's profile instead of inside mission file. This is used for global editor preferences, like camera speed or autosave settings.

Values are saved to <profileName>.3den.Arma3Profile file in your profile folder. As opposed to scripted variables, they are saved unbinarized and can be edited manually. 

class Cfg3DEN
{
	class Mission
	{
		class Preferences // Anything in this section will be displayed in Editor Preferences
		{
			class AttributeCategories
			{
				// ... Attribute categories
			};
		};
	};
};

Entity Specific

Some entities can also have attributes available only for them. This is most commonly used by systems - for example Air Strike module can have attribute for picking attack type and plane used, both of which would be unusable by other modules.

Entity specific attributes are configured directly in the entity class. For user, they are visible in single category which also shows entity name.

  • CfgVehicles - objects and systems
  • CfgNonAIVehicles - triggers
  • CfgWaypoints - waypoints
  • CfgMarkers - markers
class CfgVehicles
{
	class B_Soldier_F;
	class MyEntity: Soldier_F // Your entity class
	{
		class Attributes // Entity attributes have no categories, they are all defined directly in class Attributes
		{
			class MyEntityAttribute
			{
				// ... attribute properties, see entity attributes
			};
		};
	};
};

Presets

Apart from being able to add their own attributes, entities can also overwrite default values of general attributes. This can be useful for customizing story character (a character can have pre-defined name, face and rank, but mission designer will be still able to change it).

In the example below, we create a trigger with custom area size: 

class CfgNonAIVehicles
{
	class EmptyDetector;
	class MyTrigger: EmptyDetector
	{
		class AttributeValues
		{
			sizeA = 1000; // Property name match the attribute name
			sizeB = 1000;
		};
	};
};

Conditions

Conditions are written as simple expressions. Example: 

condition = "objectBrain * (1 - objectDestructable)";

Object must be indestructible AI character (theoretical example, no such object exists in unmodded game).

Supported conditions:

Condition For Type Description
objectBrain Object Object with simulation "soldier" or "UAVpilot"
objectControllable Object Object with simulation "soldier"
objectAgent Object Object with non-empty agentTasks[], i.e., animals
objectVehicle Object Vehicle which can be boarded
objectSimulated Object Object which is simulated (e.g., falls down when in the air)
objectDestructable Object Indestructible object, i.e., when destrType config property set not DestructNo
logicModule Logic Logic which is a module (vehicleClass config property is "Modules")

User Interface Controls

List

Class Description Saved Value
ActivationType Combo box with triggerActivation options
AmmoBox Table with all weapons and equipment in the game, filtered by type. Array in format: 
[
 	[
 		[<W>,<M>,<I>,<B>],
 		[<Wn>,<Mn>,<In>,<Bn>]
 	],
 	<isVirtual>
 ]
  • Arrays with String class names
    • Weapons
    • Magazines
    • Items
    • Backpacks
  • *n - Arrays with counts. Indexes match class name indexes
  • isVirtual - Bool, true if equipment is in infinite number (array with counts is empty then)
BehaviourGroup Drop-down list which shows all behaviour states String
BehaviourWaypoint Drop-down list which shows all waypointBehaviour states String
Checkbox Simple checkbox Bool - true if the checkbox is ticked
CheckboxNumber Simple checkbox with numeric ouput Number - 1 if the checkbox is ticked, 0 if it isn't
CheckboxReversed Simple checkbox with reversed output Bool - false if the checkbox is ticked
CheckboxState Category toggle. When ticked off, all other attributes in the category will be disabled and greyed out. Bool - true if the checkbox is ticked
CombatModeGroup Drop-down list which shows all combatMode states String
CombatModeWaypoint Drop-down list which shows all waypointCombatMode states String
Combo Empty drop-down list, used as a base class. 
class Value: Combo
{
	// Static items
	class Items
	{
		class None
		{
			text = "None";
			data = "";
		};
	};
	// Dynamically loaded items
	class ItemsConfig
	{
		path[] = {"CfgNotifications"}; // Path to config container
		localConfig = 1; // 1 to search local Description.ext as well
		// Name of the property which will be used for item text
		propertyText = "title";
		// Name of the property which will be used for item right text
		propertyTextRight = "description";
		// Name of the property which will be used for item picture
		propertyPicture = "iconPicture";
		// Name of the property which will be used for item text color
		propertyColor = "color"; 
	};
};
String or Number (depends on original value type)
ComboPreview Empty drop-down list with preview button, used as a base class. If data of the selected item are found in CfgSounds, CfgEnvSounds, CfgMusic or CfgSFX, clicking on the button will play the sound. String
Date
Daytime
Default
Edit Single line text input. String
EditAB Two-dimensional size setting. String
EditArray Array input. Items must be divided by commas or semicolons. String
EditCode Single line code input. Uses monospace font and offers scripting help. String
EditCodeMulti3 Multi line code input. Uses monospace font and offers scripting help. String
EditCodeMulti5 Multi line code input. Uses monospace font and offers scripting help. String
EditCodeShort Single line code input with decreased width. Good for shorter values, like numbers. Uses monospace font and offers scripting help. String
EditMulti3 Multi line text input. String
EditMulti5 Multi line text input. String
EditShort Single line text input with decreased width. Good for shorter values, like numbers. String
EditXY Position setting of X and Y axis. Array
EditXYZ Position setting of X, Y and Z axis. Array
EditZ Position setting of Z axis. Number
EnableDebugConsole Combo box
Face
GameType
GarbageCollectorMode
GuerAllegiance
Lock
MarkerBrush
MarkerColor
ModuleInfo
Music
Pitch
PreferencesSavegame
Respawn
RespawnTemplates
RscTitle
Skill Slider in range <0.2; 1> (AI is too dumb with skill 0, so designer shouldn't be unable to set it), with customized tooltip describing specific values Number
Slider Percentage slider, value is in range <0; 1>, default value is 1, description adds "%" at the end (e.g., "100%") Number
SliderMultiplier Multiplier slider, value is in range <0.5; 1.5>, default value is 1, description adds "x" at the end (e.g., "1x") Number
SliderTime Time slider, value is in seconds and in range <0; 3600>, default value is 0, description appears in format "HH:MM:SS" Number
SliderTimeForecast Variation of SliderTime, with range <1800; 28800> (30 min to 8 h) and default 3600 (1 h) Number
SliderTimeRespawn Variation of SliderTime, with range <0; 300> (0 min to 5 min) and default 0 Number
Sound Drop-down list which shows all sounds from CfgSounds. String
SoundEffect Drop-down list which shows all sounds from CfgSFX. String
SoundEnvironment Drop-down list which shows all sounds from CfgEnvSounds. String
SoundVoice Drop-down list which shows all sounds from CfgSounds. As opposed to "Sound" control, its "No Sound" option has different value. String
Speaker Drop-down list which shows all voices from CfgVoice. String
StructuredText
Timeout
TriggerActivation
TriggerActivationOwner
TriggerActivationOwnerStatic
TriggerType
Type

Configuration

New UI controls can be added to introduce more advanced functionality. They are Controls, not Displays, and they are define in Cfg3DEN >> Attributes. Using controls group will allow you to create more complicated structures. Configuration is possible only in global Config.cpp, not in Description.ext.

See Eden Editor: User Interface for more details about GUI configuration. 

// Include Eden Editor UI macros
// For attributes, you'll be interested in these:
// ATTRIBUTE_TITLE_W - title width
// ATTRIBUTE_CONTENT_W - content width
#include "\a3\3DEN\UI\macros.inc"

// Inherit base classes
class ctrlEdit;

class Cfg3DEN
{
	class Attributes // Attribute UI controls are placed in this pre-defined class
	{
		// Base class templates
		class Default; // Empty template with pre-defined width and single line height
		class Title: Default {class Title;}; // Two-column template with title on the left and space for content on the right
		class TitleWide: Default {class Title;}; // Template with full-width single line title and space for content below it

		// Your attribute class
		class MyAttributeControl: Title
		{
			// Expression called when the control is loaded, used to apply the value
			// Passed params are: _this - control, _value - saved value
			attributeLoad = "(_this controlsGroupCtrl 100) ctrlSetText _value";
			// Expression called when attributes window is closed and changes confirmed. Used to save the value.
			// Passed param: _this - control
			attributeSave = "ctrlText (_this controlsGroupCtrl 100)";
			// List of controls, structure is the same as with any other controls group
			class Controls
			{
				class Title: Title{}; // Inherit existing title control. Text of any control with class Title will be changed to attribute displayName
				class Value: ctrlEdit
				{
					idc = 100;
					x = ATTRIBUTE_TITLE_W * GRID_W;
					w = ATTRIBUTE_CONTENT_W * GRID_W;
					h = SIZE_M * GRID_H;
				};
			};
		};
	};
};

Data Validation

Scripting Commands

Event Handlers

Retrieved from "https://community.bistudio.com/wiki?title=Eden_Editor:_Configuring_Attributes&oldid=93035"