ComponentBase Class

PROP_PARAM(Toggle, auto_adjustment, false);
PROP_PARAM(Float, setting_1, 2.0f / 1.0f, "Setting 1", "", "", "auto_adjustment=0");
PROP_PARAM(Float, setting_2, 1.0f, "Setting 2", "", "", "auto_adjustment=0");

PROP_PARAM(type, name, default_value, items, title, tooltip, group, condition);

PROP_STRUCT(type, name, title, tooltip, group, condition);

class SomeComponent: public Unigine::ComponentBase
{
public:
	// constructor and destructor for our component
	COMPONENT(SomeComponent, Unigine::ComponentBase);

	// name of the property associated with the component
	PROP_NAME("my_component");

	// methods to be executed at certain stages of the execution sequence
	COMPONENT_INIT(init);
	
	// parameters
	PROP_PARAM(Float, speed, 30.0f);
	PROP_PARAM(Node, some_node);

	// declaration of a structure (a property inside a property) named "ParentStruct"
	struct ParentStruct : public Unigine::ComponentStruct
	{
		// parameters, that will be displayed in the UnigineEditor
		PROP_PARAM(Int, var1, 1);
		PROP_PARAM(Float, var2, 2.0f);
		PROP_PARAM(Double, var3, 3.0f);
		
		// auxiliary variables, that won't be visible in the UnigineEditor
		float my_var1 = 2.0f;
		int my_var2 = 10;
	};

	// declaration of the structured parameter named "my_struct" of the ParentStruct type declared above
	PROP_STRUCT(ParentStruct, my_struct);

	// declaration of a child structure named "ChildStruct" inherited from the ParentStruct
	struct ChildStruct : public ParentStruct
	{
		// parameters, that will be displayed in the UnigineEditor
		PROP_PARAM(Int, child_param1, 1);
		PROP_PARAM(Double, child_param2, 2.0f);
		
		// declaration of a nested structure
		struct NestedStruct : public Unigine::ComponentStruct
		{
			// parameters, that will be displayed in the UnigineEditor
			PROP_PARAM(String, string_param1, "This is my string!");
		};
		
		// declaration of the structured parameter named "my_nested_struct" of the NestedStruct type declared above
		PROP_STRUCT(NestedStruct, my_nested_struct);
	};
	
	// declaration of the structured parameter named "my_struct2" of the ChildStruct type declared above
	PROP_STRUCT(ChildStruct, my_struct2, "Child Struct", "Example of an inherited structure with a nested one");
	
	// ...
};

PROP_ARRAY_STRUCT(struct_type, name, title, tooltip, group, condition);	// for arrays of structures
PROP_ARRAY(type, name, title, tooltip, group, condition);				// for arrays of all other types

// ...

// declaring a simple array of integer elements named int_array
PROP_ARRAY(Int, int_array, "Integer Array", "This is an array of integer elements");
					
// declaring an array of ParentStruct elements named struct_array (ParentStruct should be declared earlier)
PROP_ARRAY_STRUCT(ParentStruct, struct_array);

// ...

// ...

SomeComponent::init()
{
	// ...
	
	// changing the value of the speed parameter 
	speed = 120.0f;
	
	// changing array's size and setting values of a couple of its elements
	int_array.resize(5);
	int_array[0] = 1;
	int_array[4] = 10;
	
	// setting the value of the var3 parameter of the first ParentStruct element of the array named struct_array
	struct_array[0]->var3 = struct_array[0]->var3 + 20.0f;
	
	// changing the value of the var1 parameter of the my_struct structured parameter
	my_struct->var1 = 5;
	
	// printing the value of string_param1 parameter of the nested structured parameter (my_nested_struct) inside the my_struct2 of the ChildStruct type inherited from the ParentStruct
	Log::message("String parameter value: %s",my_struct2->my_nested_struct->string_param1.get());
	
	// ...
}

COMPONENT_INIT(function_name, order);
COMPONENT_UPDATE_ASYNC_THREAD(function_name, order);
COMPONENT_UPDATE_SYNC_THREAD(function_name, order);
COMPONENT_UPDATE(function_name, order);
COMPONENT_POST_UPDATE(function_name, order);
COMPONENT_UPDATE_PHYSICS(function_name, order);
COMPONENT_SWAP(function_name, order);
COMPONENT_SHUTDOWN(function_name, order);
COMPONENT_DESTROY_RENDER_RESOURCES(function_name, order);

// Component1
	COMPONENT_INIT(init, 2);

	// ...

	// Component2
	COMPONENT_INIT(init, 3);

	// ...

class A
{
	COMPONENT_UPDATE(update);
	void update();
};

class B: public class A
{
	COMPONENT_UPDATE(update);
	void update();
};

// In this case only B::update() will be executed. It doesn't matter that A::update() is not virtual.

class A
{
	COMPONENT_UPDATE(update, -1);
	void update();
};

class B: public class A
{
	COMPONENT_UPDATE(update);
	void update();
};

// In this case A::update() is run first, and then B::update().

class A
{
	COMPONENT_UPDATE(update);
	void update();
};

class B: public class A
{
	COMPONENT_UPDATE(update, -1);
	void update();
};

// In this case B::update() is run first, and then A::update().

REGISTER_COMPONENT ( your_component_name );

class MyComponent: public Unigine::ComponentBase
{
public:

	// constructor and destructor for our component
	COMPONENT(MyComponent, Unigine::ComponentBase);

	// name of the property associated with the component
	PROP_NAME("my_component");

	// methods to be executed at certain stages of the execution sequence (see the "protected" section)
	COMPONENT_INIT(init);
	COMPONENT_UPDATE(update1, 3);
	COMPONENT_UPDATE(update2, 5);
	
	// parameters
	PROP_PARAM(Float, speed, 30.0f);
	PROP_PARAM(Node, some_node);

	// declaration of a structure (a property inside a property) named "ParentStruct"
	struct ParentStruct : public Unigine::ComponentStruct
	{
		// parameters, that will be displayed in the UnigineEditor
		PROP_PARAM(Int, var1, 1);
		PROP_PARAM(Float, var2, 2.0f);
		PROP_PARAM(Double, var3, 3.0f);
		
		// auxiliary variables, that won't be visible in the UnigineEditor
		float my_var1 = 2.0f;
		int my_var2 = 10;
	};

	// declaration of the structured parameter named "my_struct" of the ParentStruct type declared above
	PROP_STRUCT(ParentStruct, my_struct);

	// declaration of a child structure named "ChildStruct" inherited from the ParentStruct
	struct ChildStruct : public ParentStruct
	{
		// parameters, that will be displayed in the UnigineEditor
		PROP_PARAM(Int, child_param1, 1);
		PROP_PARAM(Double, child_param2, 2.0f);
		
		// declaration of a nested structure
		struct NestedStruct : public Unigine::ComponentStruct
		{
			// parameters, that will be displayed in the UnigineEditor
			PROP_PARAM(String, string_param1, "This is my string!");
		};
		
		// declaration of the structured parameter named "my_nested_struct" of the NestedStruct type declared above
		PROP_STRUCT(NestedStruct, my_nested_struct);
	};
	
	// declaration of the structured parameter named "my_struct2" of the ChildStruct type declared above
	PROP_STRUCT(ChildStruct, my_struct2, "Child Struct", "Example of an inherited structure with a nested one");
	
	// declaration of a simple array of integer elements named int_array
	PROP_ARRAY(Int, int_array, "Integer Array", "This is an array of integer elements");
						
	// declaration of an array of ParentStruct elements named struct_array (ParentStruct should be declared earlier)
	PROP_ARRAY_STRUCT(ParentStruct, struct_array);
	
protected:
	// world main loop
	void init();
	void update1();
	void update2();

};

#include "MyComponent.h"

REGISTER_COMPONENT( MyComponent );		// macro for component registration by C++ Component System

using namespace Unigine;
using namespace Math;

// method to be called on component initialization
void MyComponent::init()
{
	// changing the value of the speed parameter 
	speed = 120.0f;
	
	// changing array's size and setting values of a couple of its elements
	int_array.resize(5);
	int_array[0] = 1;
	int_array[4] = 10;
	
	// setting the value of the var3 parameter of the first ParentStruct element of the array named struct_array
	struct_array[0]->var3 = struct_array[0]->var3 + 20.0f;
	
	// changing the value of the var1 parameter of the my_struct structured parameter
	my_struct->var1 = 5;
	
	// printing the value of string_param1 parameter of the nested structured parameter (my_nested_struct) inside the my_struct2 of the ChildStruct type inherited from the ParentStruct
	Log::message("\nString parameter value: %s",my_struct2->my_nested_struct->string_param1.get());
}

// first method to be called on world update
void MyComponent::update1()
{
	Log::message("\nMyComponent::update1() method!");
}

// second method to be called on world update
void MyComponent::update2()
{
	Log::message("\nMyComponent::update2() method!");
}

ComponentBase Class

Members

---

const char * getClassName ( ) #

Returns the name of the class associated with the component. The name is generated automatically in the COMPONENT macro.

Return value

Component class name.

const char * getComponentDescription ( ) #

Returns the component description. The description can be specified in the COMPONENT_DESCRIPTION macro.

Return value

Component description.

const char * getPropertyName ( ) #

Returns the name of the property associated with the component. The name is automatically generated in the COMPONENT_DEFINE macro: in this case, the propert name will be same as the class name. To specify a custom name, use the COMPONENT and PROP_NAME macros instead.

Return value

Property name.

const char * getParentPropertyName ( ) #

Returns the name of the parent property from which the current property associated with the component is inherited. The name is automatically generated in the COMPONENT_DEFINE macro.

Return value

Parent property name.

void setEnabled ( int enable ) #

Enables or disables the component.

Arguments

• int enable - Use 1 to enable the component, 0 - to disable it.

int isEnabled ( ) #

Returns a value indicating whether the component is enabled.

Return value

1 if the component is enabled; otherwise 0.

int isInitialized ( ) #

Returns a value indicating whether the component is initialized (its init() method was already called).

Return value

1 if the component is initialized; otherwise 0.

int isAutoSaveProperty ( ) #

Returns a value indicating whether the property file associated with the component should be automatically generated each time C++ Component System is initialized or createPropertyFiles() method is called.

Return value

1 if the property file associated with the component should be automatically generated each time C++ Component System is initialized or createPropertyFiles() method is called; otherwise 0.

const NodePtr & getNode ( ) #

Returns the node, to which the component is attached.

Return value

Node, to which the component is attached.

const PropertyPtr & getProperty ( ) #

Returns the property associated with the component.

Return value

Property associated with the component.

int getPropertyNum ( ) #

Returns the number of the property associated with the component.

Return value

Number of the property in the list of properties assigned to the node.

template <C class>

C * addComponent ( const NodePtr & node ) #

Adds the component to the specified node. This method is equivalent to ComponentSystem::addComponent() method.

Arguments

• const NodePtr & node - Node, to which the component is to be added.

Return value

Pointer to the new added component, if it was successfully added to the specified node; otherwise nullptr.

template <C class>

int removeComponent ( const NodePtr & node ) #

Removes the component from the specified node. This method is equivalent to ComponentSystem::removeComponent() method.

Arguments

• const NodePtr & node - Node, from which the component is to be removed.

Return value

1 if the component was successfully removed from the specified node; otherwise 0.

template <C class>

C * getComponent ( const NodePtr & node, bool enabled_only = false ) #

Returns the first component of the specified type associated with the specified node. This method is equivalent to ComponentSystem::getComponent() method.

Arguments

• const NodePtr & 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

Pointer to the component if it exists; otherwise, nullptr.

template <C class>

void getComponents ( const NodePtr & node, Vector<C *> & components ) #

Returns all components of this type assigned to the specified node and puts them to the specified buffer vector. This method is equivalent to ComponentSystem::getComponents() method.

Arguments

• const NodePtr & node - Node, whose components are to be retrieved.
• Vector<C *> & components - Buffer vector, to which all found components of this type will be put.

template <C class>

C * getComponentInChildren ( const NodePtr & node, bool enabled_only = false ) #

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

• const NodePtr & 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

Pointer to the component if it exists; otherwise, nullptr.

template <C class>

void getComponentsInChildren ( const NodePtr & node, Vector<C *> & components ) #

Searches for all components of this type down the hierarchy of the specified node and puts them to the given buffer vector. This method is equivalent to ComponentSystem::getComponentsInChildren() method.

Arguments

• const NodePtr & node - Node, whose hierarchy is to be checked for the components of this type.
• Vector<C *> & components - Buffer vector, to which all found components of this type will be put.

template <C class>

C * getComponentInParent ( const NodePtr & node, bool enabled_only = false ) #

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

• const NodePtr & 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

Pointer to the component if it exists; otherwise, nullptr.

template <C class>

void getComponentsInParent ( const NodePtr & node, Vector<C *> & components ) #

Searches for all components of this type up the hierarchy of the specified node and puts them to the given buffer vector. This method is equivalent to ComponentSystem::getComponentsInParent() method.

Arguments

• const NodePtr & node - Node, whose hierarchy is to be checked for the components of this type.
• Vector<C *> & components - Buffer vector, to which all found components of this type will be put.

void setDestroyCallback ( Unigine::CallbackBase * func ) #

Sets a callback function to be called before destroying the component. This function can be used to implement certain actions to be performed when a component is destroyed.

Arguments

• Unigine::CallbackBase * func - Callback function.

void clearDestroyCallback ( ) #

Removes a destroy callback function previously set by the setDestroyCallback() method. This callback function can be used to implement certain actions to be performed when a component is destroyed.

void save_property ( const char * name ) #

Saves all parameters of the property associated with the component to the specified prop-file.

Arguments

• const char * name - Name of the target .prop-file.

void on_enable ( ) #

This method is called by the Engine, when the component becomes enabled and active (both, node and property are enabled). You can override this method to implement some specific actions to be performed each time, when the component becomes enabled and active.

void on_disable ( ) #

This method is called by the Engine, when the component becomes disabled (both, node and property are disabled). You can override this method to implement some specific actions to be performed each time, when the component becomes disabled and inactive.

void init ( ) #

Engine calls this function on world initialization. Put you code for resources initialization during the world start here.

void update ( ) #

Engine calls this function before updating each render frame. You can specify here all logic-related functions you want to be called every frame while your application executes.

void postUpdate ( ) #

Engine calls this function after updating each render frame. You can correct behavior after the state of the node has been updated.

void updatePhysics ( ) #

Engine calls this function before updating each physics frame. Here you can control physics, perform continuous physics-related operations (pushing a car forward depending on current motor's RPM, simulating a wind blowing constantly, perform immediate collision response, etc.). The engine calls updatePhysics() with the fixed rate (60 times per second by default) regardless of the fps number. Similar to the world script's updatePhysics() function.

void shutdown ( ) #

Engine calls this function on world shutdown. Here you can clean up resources that were created during world script execution to avoid memory leaks.

int is_equals ( const Ptr<Xml> & xml1, const Ptr<Xml> & xml2 ) #

Returns a value indicating whether the two xml nodes are actually equal (have the same set of parameters with the same values and the same hierarchy).

Arguments

• const Ptr<Xml> & xml1 - First xml node.
• const Ptr<Xml> & xml2 - Second xml node.

Return value

1 if the two specified xml nodes are equal; otherwise, 0.