Input System

Input device is a peripheral hardware equipment providing data and control signals to the processing unit. It is one of the key resources for the interactive virtual reality systems. Each input device regardless of its type has an ID and is characterized by the number and states of its axes and buttons.

Input represents the input data provided to the engine.

Button

Axis

Virtual axis

The user can perform a number of actions in the virtual world, such as moving in different directions, jumping, or shooting. The actions can be activated in many ways: by pressing a button or rotating an analogue stick of the gamepad. The Unigine engine makes it possible to assign multiple Inputs for each of the action. The names of the actions and input axes assigned to them can be saved in the configuration file.

Create 2 configuration files: controls_def.xml and controls.xml.

Controls_def file defines the action attributes:

<?xml version="1.0" encoding="utf-8"?>
<controls_def>
	<action_def name="accelerate" min="0" max="1" neutral="0" type="state"/>
</controls_def>

Action tag has the following attributes:

• Name — action name.
• Min — minimum axis value for application accepted input.
• Max — maximum axis value for application accepted input.
• Neutral — neutral axis value for application accepted input.
• Type — action type:
  • State specifies the action having effect until the corresponding input is pressed. In other words, state action is used when it is necessary to change something continuously according to key / axis state. An example is car steering.
    Notice

    In the case of a state action, getState() returns the current input state (corrected according to the input range and action range).
  • Switch is used when it is necessary to toggle something on and off. It allows to handle key up and key down events (just one at a time). An example is turning car head lights on and off.
    Notice

    In the case of a switch action, the current state is irrelevant, but rather the difference between the current and the previous state matters.

    • When the key is pressed down, getState() returns the maximum value.
    • When the key is up, getState() returns -1 * maximum value.
    • If the key did not change its state since the previous update, the function will return the minimum value.

Controls file binds input with actions:

<?xml version="1.0" encoding="utf-8"?>
<controls definition="/config/controls/controls_def.xml">
	<action name="accelerate"/>
	<action name="brake"/>
	<!-- etc. -->
</controls>

To load control configuration use:

// somewhere in initialization code
Unigine::Input::Control control = new Unigine::Input::Control();
control.loadFromFile("you_config_file.xml");

// somewhere in update code
control.update(engine.game.getIFps())

Unigine::Input::Action action = control.getAction("accelerate");
current_car.setAccelerator(action.getState());
action = control.getActionByName("brake");
current_car.setBrake(action.getState());
// etc.

To enable this function do the following:

Step 1. Include headers:

#include <scripts/input/control_setup_window.h>

Step 2. Add initialization, update and shutdown handlers for ControlSetupWindow to corresponding code sections:

int init() {
	Unigine::Input::ControlSetupWindow::init(engine.getGui());

	/*...*/

	return 1;
}

int update() {
	Unigine::Input::ControlSetupWindow::update();

	/*...*/

	return 1;
}

int shutdown() {
	Unigine::Input::ControlSetupWindow::shutdown();

	/*...*/

	return 1;
}

Step 3. Example of the code used to show configuration window:

void cotroller_setup_button_clicked() {
	if(controller_setup_button.isToggled()) {
		// show window
		Unigine::Input::ControlSetupWindow::addOnHideCallback("TestCarGui::on_save_car_controls",NULL);
		Unigine::Input::ControlSetupWindow::show(control); // see control definition above
	} else {
		// hide window
		Unigine::Input::ControlSetupWindow::hide();
	}
}