Component Class

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.

C# Component System supports the following field types:

• bool
• int, float, double
• string
• vec2, dvec2, ivec2
• vec3, dvec3, ivec3
• vec4, dvec4, ivec4
• quat
• mat3, mat4, dmat4
• Property
• Material
• Node (and nodes inherited from it: NodeDummy, ObjectMeshStatic, LightOmni, etc.)
• Link to asset (such as AssetLink link_to_asset for any type of asset and AssetLinkNode link_to_node exclusively for node assets)
• 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 including external ones (declared ouside the component)

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:

[ParameterType(Attribute_1 = Value_1, ..., Attribute_n = Value_n)]

Examples:

[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
  Notice

  These 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. It has the following attribute:
  • Filter — a list of acceptable asset extensions, separated by vertical bar (e.g. ".node|.txt|.mat")
• ParameterAsset — an AssetLink parameter to be displayed using the File Asset widget in UnigineEditor. It has the following attribute:
  • Filter — a list of acceptable asset extensions, separated by vertical bar (e.g. ".node|.txt|.mat")
• ParameterMask — an integer parameter to be displayed using the Mask widget in UnigineEditor. It has the following attribute:
  • MaskType — one of values included in the ParameterMaskAttribute.TYPE enumeration and corresponding to a bit mask type:
    • GENERAL = 0
    • INTERSECTION
    • COLLISION
    • EXCLUSION
    • VIEWPORT
    • SHADOWS
    • MATERIAL
    • SOUND_SOURCE
    • SOUND_REVERB
    • SOUND_OCCLUSION
    • NAVIGATION
    • OBSTACLE
    • PHYSICAL
    • FIELD
• 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)
  • Logarithmic — use nonlinear scale (with base 10) for the slider (bool)
  • Expand — A value indicating if the minimum and maximum values of the slider can be exceeded (bool)
  • MinExpand — A value indicating if the minimum value of the slider can be decreased (bool)
  • MaxExpand — A value indicating if the maximum value of the slider can be increased (bool)
• 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
• ParameterProperty — a Property asset parameter to be displayed as a combobox in UnigineEditor. Attributes:
  • InternalOnly — sets a filter allowing to use only properties that are attached to a node (internal)
  • ParentGUID — sets a GUID-based filter indicating the parent property for allowed properties.
• ParameterMaterial — a Material asset parameter to be displayed as a combobox in UnigineEditor. Attributes:
  • ParentGUID — sets a GUID-based filter indicating the parent material for allowed materials.

Parameter Conditions#

public bool my_toggle;
public int my_int;
    
[ParameterCondition(nameof(my_toggle), 0)]
[ParameterCondition(nameof(my_int), 1, 3, 5)]
[ParameterCondition("other_field_name", 2)]
public float my_float;

Parameter Declaration Examples#

// 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;

// enum parameter to be displayed as a combobox in the Editor
public enum MySwitch { Item1, Item2, Item3 }
public MySwitch p_switch2;
	
// 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";

// parameter accepting a node with a preset default value to be displayed using a File Asset widget in the Editor
public AssetLinkNode node_asset_link = new AssetLinkNode("some_node.node");
	
// public parameter you don't want to show in the Editor
[HideInEditor]
public string MyPublicParam = "This is a string"; 
	
// Material parameter
public Material MyMaterial;

// 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};

// Parameter with the Node links array
public List<Node> world_nodes;

// Parameter with the array of links to ".node" files
public List<AssetLinkNode> file_nodes;

// array of structures parameter
[Parameter(Title="Array Of Structs")]
public List<MyStruct> my_structures;

[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;
	
	// enum parameter to be displayed as a combobox in the Editor
	public enum MySwitch { Item1, Item2, Item3 }
	public MySwitch p_switch2;
	
	// 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;
	
	// ...
};

// External structure declaration
public struct ExternStruct
{
	public int i;
}

// ...
// first component declaring the NestedStruct structure
public class SomeComponent : Component
{
	public struct NestedStruct
	{
		public float f;
	}
}

// ...

// second component using the NestedStruct and ExternStruct structures
public class TestComponent : Component
{
	public ExternStruct extern_struct;
	public SomeComponent.NestedStruct nested_struct;
}

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:

// Component1
[Method(Order=2)]
void Init() {
    // ...
}

// Component2
[Method(Order=3)]
void Init() {
    //...
}

The InvokeDisabled value (optional) indicates if the method should be executed even if the component or the node is disabled. For example:

[Method(InvokeDisabled = true)]
void Init() {
    // initialize data even when disabled
}

void Update() {
    // execute only when enabled
}

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:

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 {
    [MethodUpdate] 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

Invoking and Overriding Private Methods#

public class ClassBase : Component {
	 void Init() { Log.Message("ClassBase::Init()\n"); }
	 void Update() { Log.Message("ClassBase::Update()\n"); }
}
public class ClassDerived : ClassBase {
	 void Update() { Log.Message("ClassDerived::Update()\n"); }
}

• C# Component System usage example for more details on using the C# Component System.
• C# Sample: source/samples/Api/Logics/ComponentSystem