Unity Samples Learning Resources

Problem

It is challenging to know how to “start” with many of our different parts in Bessy Unity. Multiple unfinished introductory resources currently exist in isolation from one another which, could address this issue in part or in full. Any successfully suite of learning resources would discretely address the needs of the multiple different types of user in the wide range this tool is intended to serve.

How can we set package users up for success?

Users

As broadly adapted from Personas / Use Cases , there are three broad types of users to target:

• Technical
  • want to build something else that uses BCI-Essentials
    • might use the Unity package or interface with python themselves
  • have a game or application to be controlled by BCI
  • possibly unfamiliar with concepts, limitations, or specific input paradigms
  • need to know how to use, integrate, or build around it
    • adding both parts of Bessy to a Unity project
    • testing with simulated data
• Non-technical / Clinical
  • want to move sliders, change colours, and press keys for flashing squares
  • how to get the flashing squares up and running
    • drag-and-drop; not going to write any code
    • the smallest amount of the simplest possible steps
  • need to know where options are and what they do
• Internal Development Team
  • want to fix, refine, and improve specific parts of the tool
  • how to set up a development environment
  • need to understand the broad strokes of design
    • what does what
    • how the two pieces talk to each other
    • enough to contribute to specific parts without compromising wider intent

Resource Types

We have multiple fronts on which to address the disparate introductory needs of different user groups. Each could be made much more useful, both independently and interdependently, by establishing a clear intention for each platform. Below is a summary of the platforms we have and some theories of how they could be adapted to be a more effective part of a holistic knowledge resource strategy.

Confluence

• for internal developers
• spikes and internal resources
• sizable knowledge base
• navigation could be improved

recommendations

• revisit the overview
  • improve format
  • collect “index” of links to direct a new contributor towards

Samples

• public facing
• for technical users and internal developers
  • could provide certain non-technical users with a functional prototype
• development examples
• useful for smoke testing
• not documented or explained
• some are non-functional or misguiding
  • ES Stimulus Presentation is an old version of a previous project that has stuck around and been through multiple iterations of poor translation through package refactors.
  • an Environment Aware P300 Example is listed but not present in repository

recommendations

• add and rework samples to complete the set listed below
• add accompanying documentation for each example
  • add a README.md for each sample
  • create a “tutorial” wiki page walking through each sample

Minimum Setup Example(s)

Functional examples that can be re-created in the few amount of the simplest steps possible.
Already present in package in the form of the simple paradigm examples.

• behaviour configuration
• basic control flow
• separate, mirrored examples for both SSVEP and P300 can better represent a developer’s target paradigm

Controller Hot-Swapping

An example scene with multiple controller behaviours that can be swapped between on demand.
Already present in package.
It is doubtful that this behaviour-swapping will get used in an application, but it is way too useful for testing.

• behaviour registration
• use of a controller instance

ES Stimulus Presentation Reboot

A fixed up, streamlined version of the mini project present in package.

• custom implementation of BCIControllerBehaviour

Context-Aware P300 Example

A scene with simple controller/controller behaviour setup but complex SPO behaviour which causes them to move around between each other and sometimes off-screen. This would be most simply achieved by conventional first-person movement of a camera in a 3d space.

• context-aware flashing
• custom implementation of SPOFactory
• custom implementation of SPO

Low Level Switch Example - Just Markers

An example not using BCIController or any behaviours, interfacing with python directly using the LSL stream components provided.

• using the LSL framework
• example of a more direct interface with python

Wiki

Provides high level design/class information to technical users. Already mostly complete.

• public information
• for technical developers
• explains project setup
• high level conceptual reference guide

Outline

Home Page / Getting Started

• project setup
• basic example
• link hub to other resources

High Level Interface

• covers BCIController and related classes

Custom Behaviour

• implementing and using a custom behaviour
• implementing and using custom SPOs

Low Level Interface - LSL Markers

Unity

• how to write markers to python
• how to get responses from python

Python

• explain what markers are
• define set of expected markers
• outline provided responses

Tutorials

Functionally equivalent to samples with a little more documentation. Likely best as simple walk-through guides for each sample. What is going on and how could a reader could build it themselves?

API Reference

Automatically generated documentation from python docstrings. Public facing, most useful to a technical developer that might be using BCI Essentials as a library without reading the source code. Should be in good condition now that it’s working again and will continue to be so long as in-code documentation continues to be maintained to a consistent standard.