Contributions:UnityBCI2000

Synopsis

UnityBCI2000 is a tool for integration of Unity applications with BCI2000.

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.

First, download UnityBCI2000 from GitHub. As of now, UnityBCI2000 is not a full Unity package, but it works the same. Place the C# files from the Runtime folder, as well as BCI2000RemoteNET.dll, within the Assets directory of your Unity project.

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. Add a UnityBCI2000.cs to the GameObject as a Script Component.

2.Specify the path to the operator using the Operator Path field, as well as the names of the modules to start up alongside it.

If you have an instance of the operator already running, specify the IP and port it is listening on using the Telnet Ip and Telnet Port fields instead.

You can also set a custom log file location, as well as tell the program to log sent states and received prompts. NOTE: There is a known issue with writing to the log file, this is remedied by changing the name of the file to write to. This is an issue with BCI2000RemoteNET, and will be fixed in upcoming updates.

3. Now, add a Script component of the script BCI2000StateSender to the object which you want to take data from.

4. Drag the BCI2000 GameObject from step 1 into the UnityBCI2000Object field of the BCI2000StateSender.

BCI2000StateSender comes with some predefined states to send, as well as values to scale them by. These are the global and screen coordinates, as well as whether the object is on screen.

Adding Custom Variables

Due to the way Unity works, adding custom variables must be done from a custom script, unique to each GameObject, if the GameObjects are not identical. Unfortunately, this means that some knowledge of C# programming is required, but templates for a CustomVariableSupplier script are provided within the README.md file.

There are two types of custom variables: custom send variables, which set a state in BCI2000 to some value, and custom get variables, which retrieve the value of a state variable from BCI2000.

Custom send variables contain the name of the state to write to, a Func<int> delegate(a piece of code represented by a method or lambda expression which returns the value to send to BCI2000), a scale factor to scale the variable by, in order to avoid truncation due to the fact that BCI2000 state variables are only unsigned integers, and a type. Types are defined by the enum UnityBCI2000.StateType, which currently holds 5 values, which are signed integers of bit widths 16 and 32, as well as boolean, which is an unsigned integer of bit width 1. Signed numbers will be represented in BCI2000 by two state variables: The magnitude of the number and its sign, which is 0 for positive and 1 for negative.

Custom get variables contain the name of the state to read from, as well as an Action<int> delegate(a piece of code which takes an int as a parameter), which will receive the value from BCI2000. For reference on delegates see the C# Programming Guide. Note: UnityBCI2000 uses reflection in order to reduce the amount of boilerplate code needed to implement a custom state variable, as well as simplify the process of adding and indexing of custom state variables.

Template for adding custom variables:

public class <ClassName> : CustomVariableBase {

   public override void AddCustomVariables()
   {
       customVariables.Add(new CustomSendVariable(  //Copy this for more send variables
           "[Name]",
           new Func<float>(() => [Code which returns variable to send]),
           [Scale],
           UnityBCI2000.StateType.[Type]
           ));
           
       customVariables.Add(new CustomGetVariable(  //Copy this for more get variables
           "[Name]",  
           new Action<int> ((int i) => [Code which uses i])
       ));

   }

}

Example of a custom variable provider script:

public class CustomVariableSupplier1 : CustomVariableBase {

   public override void AddCustomVariables() 
   {
       customVariables.Add(new CustomSendVariable( 
           "Custom variable 1",
           new Func<float>(() => {return 65 / 5;}),
           100,
           UnityBCI2000.StateType.SignedInt16
           ));

       customVariables.Add(new CustomSendVariable(
           "Custom variable 2: Frame count",
           new Func<float>(() => Time.frameCount),
           1,
           UnityBCI2000.StateType.UnsignedInt32
           ));

       customVariables.Add(new CustomGetVariable(  
           "StateName",  
           new Action<int> ((int i) => {score = i})
       ));
   }

}

1. Add a new C# script to the object which you want to take data from.

2. Edit the script to change the inherited class to be CustomVariableBase instead of MonoBehavior.

3. Implement the AddCustomVariables method, and have it add Custom Variables to the customVariables List, by calling customVariables.Add.

4. Drag this new script into the Custom Variable Supplier field of the BCI2000StateSender Component.