AddOSC BGE

Introduction

AddOSC comes with a game module to facilitate OSC usage in the BGE. There are 2 ways to use the OSC module in your BGE project. One extremely easy without any python coding for the native game properties and another one that allows more complex messages (vectors or any list of values) but with some -simple- scripting. In both cases, the intent has been to make things the easiest possible.

Usage

How to set up a game project to use OSC

Whatever way you chose you have at least to:

  1. Create an Empty and select it.
  2. In the logic editor, invoke the OSC module by connecting an Always sensor to a Python Controller set as a Module named 'bge_osc.io'. This setup has to be reproduced for each scene used in the game that requires OSC. Note: the Always sensors needs to have the Positive Pulse icon set to ON.
  3. Eventually set some options using some special game properties belonging to this empty. 

Here is the list of theses special properties:

  • UDP_OUT_IP (string, default:  '127.0.0.1') 
  • UDP_IN_IP (string, default: '127.0.0.1'): Please note that it's the IP of the interface to listen to, not the one of the remote device. You may use '0.0.0.0'  for listening to ALL interfaces (but at your own risk).
  • UDP_IN_PORT (integer, default: 9003)
  • UDP_OUT_PORT (integer, default: 9004)
  • PREFIX (string, default:''): Will specify a common route at the beginning of each OSC address.
  • ADD_NAME (bool, default: false)): Will insert the name of the object to the OSC address.
  • DEBUG_IN (bool, default: false): Will print in the console the incoming OSC messages.
  • DEBUG_OUT(bool, default : false): Will print in the console the sent OSC messages.
  • IO (string, 'IN', 'OUT', 'BOTH', default 'BOTH'): This allows to set the engine to only receive or send. 

Now you are ready... to use either one of the 2 following methods or both at the same time ! 

First method: for dealing with native game properties

This method is based on the native game properties created by the user with the Logic Editor.

For each object that needs to communicate, create properties of your choices and give them a name starting with a slash character ('/'). The name indeed has to be like '/prop1', for instance and not "prop1". That way the OSC module will automatically know that it has to send/receive content for this property.

As a conveniance, you can use the PREFIX string declared in your empty. If PREFIX='/blender', then your delivered message address will be '/blender/prop1'. And moreover if you use the ADD_NAME facility, the name of the object (for instance 'Cube') will be added to the address before the property name, giving '/blender/Cube/prop1'. Incoming OSC message will be parsed accordingly (ie, a well formed address from the outside world needs to be '/blender/Cube/prop1' not '/prop1', even if you property is '/prop1').

To sum up, it is now very easy to send/receive OSC messages but we are limited to the native game properties types (string, float, integer, bool, timer). What if we want to receive a list of 3 coordinates to move an object from a remote device ?

Second method: list of values

For complex message types (list of values), you have to use a script attached to an object. But as you will see, everything has been made to make this very easy to use, specially for people without many coding skills.

The module comes with 2 built-in functions named explicitly send() and receive():

  • receive(address): This function returns a list of values or None (if nothing has been received at this address yet).
  • send(address,list): This function send a list of values to the given address.  

 

PREFIX and ADD_NAME are taken in account by theses two functions.

As the functions belong to the module you have first to import it like that:

#for the bge API
import bge
#for the OSC module
import bge_osc 

And to invoke them, you need to specify the 'bge_osc' namespace, like this for instance:

co = bge_osc.receive('/accelerometer')

Equally to send a list:

co = (1,2,3)
bge_osc.send('/my_list',co))

Here is a very simple example of the script mode if you have a smartphone.

  • Install 'Control' on your device (iOS/Android), see this page. Then launch it.
  • On the 'Destinations' page, add your Blender computer IP and configure the port if necessary.
  • On the 'Interfaces' page choose 'Accelerometer'. The X, Y, Z value will be send to the address '/accelerometer' 
  • Download this .blend.
  • In Blender if not already done, load the .blend and start the game. You will see then that you can orientate the cube with your smartphone.

Notes

  • To be able to see the DEBUG messages you need to launch Blender from the console.
  • Despite being bundled with the Add-on this modules doesn't share any settings with the Add-on. The game engine has its own API and the properties in blender are not the same that the ones belonging to the game. Therefore if your interest is only in the BGE you can ignore completely the Add-on interface. However the Add-on has to be enabled int the user preferences of Blender, if not the module won't be find.
  • A little trick: if you need to share a variable between several objects, use the bge.logic namespace. Like this in the script of an object : bge.logic.my_var = "foo". The content will be then accessible to others scripts belonging to different objects.

JPfeP