User Tutorial:BCI2000Unity OUTDATED

Synopsis

Unity is a cross-platform game engine with support for desktop, mobile, console, and virtual reality platforms. It is both easy for beginners to use and is popular for low-cost game development. This is a Unity package which integrates BCI2000. This tutorial assumes that you have already compiled BCI2000.

Video

This video is currently out of date. An updated video is coming soon!

Load video

YouTube

YouTube might collect personal data. Privacy Policy

Continue Dismiss

Tutorial

For information on how to use Unity itself, see the Unity manual. This tutorial assumes knowledge of how to use Unity. It is recommended to know how GameObjects and Components work. More in-depth detail on how UnityBCI2000 works is provided in the README.md file, and on this page.

This tutorial will walk through an example cursor control task, making use of the mouse position recorded from BCI2000 to control the cursor position in Unity. First, download UnityBCI2000 from this GitHub page and download the MWE_UnityBCI2000CursorDemo tutorial project from this GitHub page. Copy the UnityBCI2000.cs and BCI2000RemoteNET.dll files into the Assets folder of your Unity project.

Connect to an Instance of BCI2000

To connect to an instance of BCI2000 in Unity, you will need to create an empty GameObject and add the script UnityBCI2000 as a Component. This will serve as the central connection to the BCI2000 Operator. As of now, it is not possible to use multiple scenes with one BCI2000 connection.

1. Create a BCI2000 GameObject.

2. Add UnityBCI2000.cs to the GameObject as a Script Component.

3. Use the Operator Path field to specify the path to the BCI2000 Operator.exe (usually in the C:/bci2000/prog/ directory). If you already have an instance of the operator running, use the Telnet IP and Telnet Port fields to specify the IP and port it is listening on instead.

4. Specify the names of the modules to start up alongside it. Extensions can be added by expanding the Module Args field and adding an element with the appropriate extension flag. For the example that will follow, we will log the mouse extension with

--LogMouse=1

5. Specify the name of the log file to store the BCI2000 system log. NOTE: There is a known issue with writing to the log file; this is remedied by changing the name of the file to which to write. This is an issue with BCI2000RemoteNET and will be fixed in upcoming updates.

Save Unity Events in BCI2000

Next, we will modify a script to create new BCI2000 events and send event change information to BCI2000.

1. Open the TargetControl script (or any script from which you would like to send information to BCI2000).

2. In the class definition, instantiate BCI2000 with

UnityBCI2000 bci;

3. In the Awake() function, set the BCI2000 reference with

bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();

4. In the Awake() function, create new BCI2000 events with the bci.AddEvent() function. The second input specifies the number of bits assigned to the new event.

bci.AddEvent("t1hit", 32);

5. It can be helpful to add watches for the events you have created so you can see their behavior in real time during the experiment. In the Awake() function, use the generic bci.ExecuteCommand() function (this function can be used to execute any BCI2000 operator scripting commands)

bci.ExecuteCommand("visualize watch t1hit");

6. It can be useful to reduce the verbosity of event logging, as event logs are written to the log file with every frame

bci.ExecuteCommand("Set variable LogLevel 0");

7. Update the event value according to some change in the experiment using the bci.SetEvent() function in the Update() function. For example, change a target hit event "t1hit" to 1 every time a target is hit by a cursor. Note that events must be set as unsigned integers.

bci.SetEvent("t1hit",(int)(1));

Access BCI2000 Events for Control

We can also get event information from BCI2000 for Unity use. For example, you may want to control the Unity cursor position with a BCI2000 event, such as the mouse position. This example makes use of a BallMouseControl.cs script.

First you will need to instantiate BCI2000 and set the BCI2000 reference as in the TargetControl.cs script

1. Open the BallMouseControl.cs script.

2. In the class definition, instantiate BCI2000 with

UnityBCI2000 bci;

3. In the Awake() function, set the BCI2000 reference with

bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();

4. Get the value of the BCI2000 event using the bci.GetEvent() function and store the result in some variable

Mpx = bci.GetEvent("MousePosX"); Mpy = bci.GetEvent("MousePosY");

This value can then be used in Unity to influence the game activity.

Compile

Compile the project by navigating to file > Build and Run. This should launch the experiment and start up BCI2000!

Using BCI2000 Control Signal

The above example makes use of the BCI2000 Mouse Position events to control the Unity cursor position. However, the BCI2000 control signal can also be used in Unity. This is particularly useful for online experiments (for example, a neurofeedback task to move a cursor on the screen based on the decoded alpha power). In the demo script, navigate to the CursorTaskSignal Scene to see how the BCI2000 control signal can be utilized in Unity. Note that this only seems to work when the scene has been compiled!

Access the control signal using the function

bci.GetSignal("ChannelNumber",1);