This page has been translated automatically.
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
Extending Editor Functionality
FAQ
编程
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
应用程序接口
Containers
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes
注意! 这个版本的文档是过时的,因为它描述了一个较老的SDK版本!请切换到最新SDK版本的文档。
注意! 这个版本的文档描述了一个不再受支持的旧SDK版本!请升级到最新的SDK版本。

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#)
[ParameterType(Attribute_1 = Value_1, ..., Attribute_n = Value_n)]
Example:
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
    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")
  • 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 — an 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 — an 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.
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() {
    //...
}

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

Source code (C#)
[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:

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

See Also#

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
This method is equivalent to ComponentSystem.GetComponentInChildren() 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[] 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-12-25
Build: ()