More generally, PropertyConnectionComponents are used to feed information (floats, integers, booleans, vectors etc.) from one property to another. Or, in less abstract terms, PropertyConnectionComponent can be thought of as a cable, which transmits a signal (the value of the property) between, for example, a graphics card's HDMI port (the input property) and the HDMI port of a screen or a tv (the output property).
Please note that property connection components are usually very buggy if they are used for gameplay logic in online multiplayer game since debugging and fixing them can take a lot of time. That's why property connection components are recommended to be used only for visual/art type of things or simple gameplay logic like moving an object.
The usage of PropertyConnectionComponent
PropertyConnectionComponents can be used to make life easier in the editor as well as for gameplay/art features. An example of the former is to connect the "Color1" property of AmbientLightEntity to it's "Color2" property. If this connection is set to active in editor, it enables the user to just change one color property to the desired value, and the other one changes automatically, due to the connection. In the latter case, PropertyConnectionComponent can feed e.g. "Time" from a TimerEntity to a KeyFrameComponent for animation purposes.
Conversions, conditions, validations and math
It's possible to do many types of operations to the input property before connecting it to the output property. Below are some examples of operations, but note that this isn't a complete list of all possible operations. All the available operations can be found by right clicking on the output property and choosing .
From the point of view of the PropertyConnectionComponent it's not relevant what type of information it transmits. It is relevant from the point of view of the properties, however, because it's not possible to connect two totally different properties (e.g. float to boolean) to each other, unless there's a converter in between. Much like when connecting old laptops with only a VGA port to a modern TV with an HDMI port, you need a separate converter to convert the analog signal to a digital one.
The conversion is almost as simple as just connecting two properties to each other:
- right click the input property and choose
- right click the output property and choose , then and finally choose the correct conversion from the list of available conversions
After this, a separate converter component is added to the output property's parent instance. In this case, when a float is converted to a boolean, it's called FloatValueConverterComponent.
With conditions, it's possible to check whether the input integer or float is
- not equal
- greater or equal
- less or equal
when compared to another integer or float. Based on these, the FloatCompareComponent or IntCompareComponent returns True or False (boolean).
Validations can be used to guarantee a float or an integer value between some limits. If the float or integer from the input property can have negative values, but the output property can only use positive or zero valued floats or integers (e.g. intensity, range), a validator can be used to make sure the value is always between some limits. When the input value is less than the minimum value of the limit (-2, when the limit is <math> \left] 0,1 \right[ </math> for example), the minimum value of the limit is used instead (so 0, instead of -2). The same happens when the input value is greater than the maximum value of the limit (5, with <math> \left]0,2\right[</math>), the maximum value is used instead of the input value (2 instead of 5).
Integers, booleans, floats, vectors and rotations each have their own math operations, for obvious reasons (you can't add 1.5 to "True" and you can't divide a vector by "False").
Float and integer math is mostly just simple arithmetic (addition, subtraction, multiplication and division) with some extra operations, like choosing the larger of two input values and using it as output. These operations are all quite self-explanatory.
Boolean math operations follow the rules of normal two-element Boolean algebra.
Available vector math operations consist of either:
- normal float arithmetic applied element-by-element <math>(x_1, y_1, z_1)/(x_2, y_2, z_2) = (x_1/x_2, y_1/y_2, z_1/z_2)</math> or
Rotation math applies a further rotation to the input rotation before outputting it.
The properties of PropertyConnectionComponent
Connections active in editor
In certain situations it's useful for the created connections to be active in editor as well as in game (like in the example with AmbientLightEntity above). This behaviour can be enabled with the "Make created connections active in editor" setting. Enabling this setting is done by right clicking on any property and clicking . The setting can be disabled by clicking the same field again.
While enabled, the setting forces all connections created in editor to be active in editor as well as in game. When the setting is disabled, the created connections will be active only in game. Note, that enabling/disabling this setting doesn't affect the already created connections in any way, it only determines whether connections created in the future will have the property set to True or False.Connections can be made active in editor also by going to the properties of the PropertyConnectionComponent in question and setting "ActiveInEditor" to true (tick the box)
Other notable properties include:
- "Enabled": whether the connection is enabled or not
- "InputInstance": which component of an instance in the scene is the owner of the property that is used as an input (e.g. "NonSyncedTimerComponent GUID(... ... ... ...)")
- "InputPropertyName": which property from the "InputInstance" component is used as the input (e.g. "Time")
- "OutPutInstance": same as "InputInstance" but for output
- "OutputPropertyName": same as "InputPropertyName" but for output
Usually the inputs and outputs of the PropertyConnectionComponent shouldn't be touched at all, since they are created automatically when the connection is made. In fact, it's encouraged to keep hands off, since manual fiddling with them will most often lead to confusion, anger and finally crippling despair, especially if there are multiple connections between different components with the same name. If manual adjustment is required, it's best to write down, take a screenshot of or otherwise save the original connection inputs and outputs. You have been warned.