Component Class
This is a base class implementing basic functionality of logic components.
Notice
All your components must be inherited from this class.
Component Parameters#
When you create a component you should declare all parameters to be used. You can choose which of them should be displayed in the Parameters window of UnigineEditor, and which should not.
Auto-generated UI for component parameters
C# Component System supports the following field types:
- bool
- int
- float
- double
- string
- vec3
- vec4
- Property
- Material
- Node (and nodes inherited from it: NodeDummy, ObjectMeshStatic, LightOmni, etc.)
- Enumerations (inherited from System.Enum)
- All classes inherited from Unigine.Component
- One-dimensional arrays (such as int[] my_array)
- Lists (such as List<int> my_list)
- Any nested structures and classes
Any public field of the supported type is displayed in the UI of UnigineEditor automatically. You can adjust UI representation of each field of your component by specifying additional attributes and indicating parameter type in brackets right above the class field declaration as follows:
Source code (C#)
Example:
[ParameterType(Attribute_1 = Value_1, ..., Attribute_n = Value_n)]Source code (C#)
[ParameterSlider(Title="Float Slider", Tootip="This is my float parameter", Min=0.0f, Max=10.0f)]
public float p_float;The type of field in UI can be configured using the following attributes:
- Parameter — a common attribute for all supported types of fields. It has the following parameters:
- Title — a parameter title to be displayed in UnigineEditor
- Tooltip — a tooltip to be displayed when the user hovers the mouse pointer over the parameter in UnigineEditor
- Group — a group to which the parameter belongs when displayed in UnigineEditor
NoticeThese three attributes are available for all parameter types. - ParameterColor — a vec4 parameter to be displayed using a Color widget in UnigineEditor
- ParameterFile — a string parameter to be displayed using the File Asset widget in UnigineEditor
- ParameterMask — an integer parameter to be displayed using the Mask widget in UnigineEditor
- ParameterSlider — an integer parameter to be displayed as a slider in UnigineEditor. It has the following attributes:
- Min — the minimum slider value (int, float, or double)
- Max — the maximum slider value (int, float, or double)
- ParameterSwitch — an integer parameter to be displayed as a combobox in UnigineEditor Attributes:
- Items — a comma-separated list of options to be displayed in the combobox
Notice
By default, parameters are displayed or hidden in UI in accordance with access modifiers: public — displayed, otherwise — hidden. But you can hide a public parameter, or show a private or protected one by specifying the corresponding visibility option (ShowInEditor or HideInEditor) in the brackets (see examples below).
Parameter declaration examples are shown below:
Parameter Declaration Examples
Source code (C#)
// int parameter to be displayed as a slider in the Editor
[ParameterSlider(Min=0.0f, Max=20.0f, Title="MySlider", Tooltip="This is my float parameter", Group="MyGroup")]
public float p_slider = 2.0f;
// int parameter to be displayed as a combobox in the Editor
[ParameterSwitch(Items="Option 1,Option 2,Option 3",Title="MySwitch")]
public int p_switch;
// int parameter to be displayed as a mask in the Editor
[ParameterMask(Title="MyMask")]
public int p_mask;
// vec4 parameter to be displayed as a vector in the Editor
[Parameter(Title="MyVector", Tooltip="My Vector parameter")]
public vec4 p_vector;
// vec4 parameter to be displayed using a Color widget in the Editor
[ParameterColor(Title="MyColor", Tooltip="My Color parameter")]
public vec4 p_color;
// protected string parameter you'd like to show in the Editor
[ShowInEditor, Parameter(Tooltip="This is a protected parameter displayed in the Editor!")]
protected string MyProtectedParam = "This is a string";
// string parameter to be displayed using a File Asset widget in the Editor
[ParameterFile(Tooltip="This is a protected parameter displayed in the Editor!")]
public string MyFile = "my_file.txt";
// public parameter you don't want to show in the Editor
[HideInEditor]
public string MyPublicParam = "This is a string";
// Material parameter
public Material MyMaterial;Complex parameters, such as structures and arrays, can be declared as follows:
Complex Parameter Declaration Examples
Source code (C#)
// structure declaration
public struct MyStruct{
public int p_int;
public float p_float;
public MyStruct(int p1, float p2)
{
p_int = p1;
p_float = p2;
}
};
// struct parameter
[Parameter(Title="My Struct Parameter")]
public MyStruct p_struct = new MyStruct(5, 2.0f);
// integer array parameter
[Parameter(Title="Integer Array")]
public int [] int_array = new int[5] { 99, 98, 92, 97, 95};
// Node array parameter
public List<Node> MyNodes;
// array of structures parameter
[Parameter(Title="Array Of Structs")]
public List<MyStruct> my_structures;Below is an example of a component named MyComponent that has multiple parameters of various types including structures:
Component Example
Source code (C#)
[Component(PropertyGuid = "09ba1bd2997a0909891bfed43d175c23a4bf9326")]
public class MyComponent : Component
{
[ParameterSlider(Min=0.0f, Max=20.0f, Title="SLIDER", Tooltip="This is my float parameter", Group="MyGroup")]
public float MyParam = 2.0f;
// int parameter to be displayed as a combobox in the Editor
[ParameterSwitch(Items="Option 1, Option2, Option 3",Title="MySwitch")]
public int p_switch;
// int parameter to be displayed as a slider in the Editor
[ParameterSlider(Min=1, Max=8,Title="MySlider")]
public int p_slider;
// int parameter to be displayed as a mask in the Editor
[ParameterMask(Title="MyMask")]
public int p_mask;
// vec4 parameter to be displayed as a vector in the Editor
[Parameter(Title="MyVector", Tooltip="My Vector parameter")]
public vec4 p_vector;
// vec4 parameter to be displayed using a Color widget in the Editor
[ParameterColor(Title="MyColor", Tooltip="My Color parameter")]
public vec4 p_color;
// protected string parameter you'd like to show in the Editor
[ShowInEditor, Parameter(Tooltip="This is a protected parameter displayed in the Editor!")]
protected string MyProtectedParam = "This is a string";
// string parameter to be displayed using a File Asset widget in the Editor
[ParameterFile(Tooltip="This is a protected parameter displayed in the Editor!")]
public string MyFile = "";
// parameter you don't want to show in the Editor
[HideInEditor]
public string MyPublicParam = "This is a string";
// Material parameter
public Material MyMaterial;
// Node array parameter
public List<Node> MyNodes;
// structure declaration
public struct MyStruct{
public int p_int;
public float p_float;
public MyStruct(int p1, float p2)
{
p_int = p1;
p_float = p2;
}
};
// struct parameter
[Parameter(Title="My Struct Parameter")]
public MyStruct p_struct = new MyStruct(5, 2.0f);
// integer array parameter
[Parameter(Title="Integer Array")]
public int [] int_array = new int[5] { 99, 98, 92, 97, 95};
// array of structures parameter
[ParameterColor(Title="My Struct Array Parameter")]
public List<MyStruct> my_structures;
// ...
};Component Methods#
Each component has a set of methods implementing its logic. These methods can be divided into two groups: methods of the main loop (such as void Init(), void Update(), void UpdateSyncThread(), etc.) and arbitrary methods.
The methods from the first group have names that define their behavior and are executed during the corresponding stages of the World Logic. There is only one attribute — Method. You can set multiple methods for each stage — they are executed according to their order value (optional) or in the order they appear in the declaration. For example:
Source code (C#)
// Component1
[Method(Order=2)]
void Init() {
// ...
}
// Component2
[Method(Order=3)]
void Init() {
//...
}In addition to the methods of the main loop, methods with arbitrary names can be created for any purpose and in any amount. They have such attributes as MethodInit, MethodUpdate, MethodShutdown, etc.
You can also define an order of the method execution, which is applied globally for all types of components.
Let's review the following example:
Source code (C#)
class A : Component {
[MethodUpdate(Order=5)] void Update() {}
[MethodRender(Order=-10)] void Render() {}
}
class B : Component {
[MethodUpdate(Order=-1)] void Update1() {}
[MethodUpdate(Order=1)] void Update2() {}
void Render() {}
}
class C : Component {
void Update1() {}
[MethodUpdate(Order=2)] void Update2() {}
}Suppose, we have 3 objects of class A, 2 objects of class B and 1 objects of class C. The methods for them are executed in the following order:
- Order -1 — B::Update1 and B::Update1
- Order 0 — C::Update1
- Order 1 — B::Update2 and B::Update2
- Order 2 — C::Update2
- Order 5 — A::Update, A::Update, A::Update
- Order -10 — A::Render, A::Render, A::Render
- Order 0 — B::Render and B::Render
See Also#
- C# Component System usage example for more details on using the C# Component System.
- C# Sample: source/samples/Api/Logics/ComponentSystem
Component Class
Members
public void SetEnabled ( bool enable ) #
Enables or disables the component.Arguments
- bool enable - Use true to enable the component, false — to disable it.
public int IsEnabled ( ) #
Returns a value indicating whether the component is enabled.Return value
true if the component is enabled; otherwise false.protected void OnReady ( ) #
This method is called by the Engine, when the component is ready for initialization. You can override this method and use it instead of the constructor for initialization, as the component is in an "undefined" state at construction time.protected void OnEnable ( ) #
This method is called by the Engine, when the component and node become enabled and active. You can override this method to implement some specific actions to be performed each time, when the component becomes enabled.protected void OnDisable ( ) #
This method is called by the Engine, when the component and node become disabled. You can override this method to implement some specific actions to be performed each time, when the component becomes disabled.protected T AddComponent<T>
(
Node node
)
#
where
T : Component
Adds the component to the specified node. This method is equivalent to ComponentSystem.AddComponent() method.Arguments
- Node node - Node, to which the component is to be added.
Return value
New added component instance, if it was successfully added to the specified node; otherwise null.protected T GetComponent<T>
(
Node node, bool enabled_only
)
#
where
T : Component
Returns the first component of the specified type associated with the specified node. This method is equivalent to ComponentSystem.GetComponent() method.Arguments
- Node node - Node, for which the component of this type is to be found.
- bool enabled_only - Enabled flag: true to get enabled component only, false to get component in any case.
Return value
Component if it exists; otherwise, null.protected T[] GetComponents<T>
(
Node node, bool enabled_only
)
#
where
T : Component
Returns all components of this type assigned to the specified node. This method is equivalent to ComponentSystem.GetComponents() method.Arguments
- Node node - Node, whose components are to be retrieved.
- bool enabled_only - Enabled flag: true to get only enabled components, false to get all components.
Return value
Array containing all found components of this type (if any); otherwise null.protected T GetComponentInChildren<T>
(
Node node, bool enabled_only
)
#
where
T : Component
Returns the first component of this type found among all the children of the specified node (including the node itself). This method searches for the component in the following order:
- node itself
- node reference
- node's children
- children of node's children
Arguments
- Node node - Node, whose hierarchy is to be checked for the components of this type.
- bool enabled_only - Enabled flag: true to get enabled component only, false to get component in any case.
Return value
Component if it exists; otherwise, null.protected T[] GetComponentsInChildren<T>
(
Node node, bool enabled_only
)
#
where
T : Component
Searches for all components of this type down the hierarchy of the specified node. This method is equivalent to ComponentSystem.GetComponentsInChildren() method.Arguments
- Node node - Node, whose hierarchy is to be checked for the components of this type.
- bool enabled_only - Enabled flag: true to get only enabled components, false to get all components.
Return value
Array containing all found components of this type (if any); otherwise null.protected T GetComponentInParent<T>
(
Node node, bool enabled_only
)
#
where
T : Component
Returns the first component of this type found among all predecessors and posessors of the specified node. This method is equivalent to ComponentSystem.GetComponentInParent() method.Arguments
- Node node - Node, whose hierarchy is to be checked for the components of this type.
- bool enabled_only - Enabled flag: true to get enabled component only, false to get component in any case.
Return value
Component if it exists; otherwise, null.protected T[] GetComponentsInParent<T>
(
Node node, bool enabled_only
)
#
where
T : Component
Searches for all components of this type up the hierarchy of the specified node. This method is equivalent to ComponentSystem.GetComponentsInParent() method.Arguments
- Node node - Node, whose hierarchy is to be checked for the components of this type.
- bool enabled_only - Enabled flag: true to get only enabled components, false to get all components.
Return value
Array containing all found components of this type (if any); otherwise null.protected T FindComponentInWorld<T>
(
bool enabled_only
)
#
where
T : Component
Returns the first component of this type found in the current world. This method is equivalent to ComponentSystem.FindComponentInWorld() method.Arguments
- bool enabled_only - Enabled flag: true to get enabled component only, false to get component in any case.
Return value
Component if it exists; otherwise, null.protected T[] FindComponentsInWorld<T>
(
bool enabled_only
)
#
where
T : Component
Returns the list of all components of this type found in the current world. This method is equivalent to ComponentSystem.FindComponentsInWorld() method.Arguments
- bool enabled_only - Enabled flag: true to get only enabled components, false to get all components.
Return value
Array containing all found components of this type (if any); otherwise null.protected int RemoveComponent<T>
(
Node component
)
#
where
T : Component
Removes the component from the specified node. This method is equivalent to ComponentSystem.RemoveComponent() method.Arguments
- Node component - Node, from which the component is to be removed.
Return value
1 if the component was successfully removed from the specified node; otherwise 0.protected int RemoveComponent ( Component node ) #
Removes the specified component. This method is equivalent to ComponentSystem.RemoveComponent() method.Arguments
- Component node - Component to be removed.
Return value
1 if the specified component was successfully removed; otherwise 0.Last update:
2019-08-16
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)