SDK (Software Development Kit)

[package]
name = com.DefaultCompany.MBGame06
version = 0.0.1

[run]
library_path = .
command = ./unitygames.x86_64

Running Your Game on MultiBall

1. Plug in the USB stick to a USB port on your MultiBall system (or extension cable, if present)
2. Either...
   1. Select the "USB Game" icon that should appear above the left folder switching button on the home screen of your MultiBall system.
   2. Log in to the MultiBall Admin webpage (You received your login with your MultiBall system). Select "Pick Game", and choose MBGame06.

1. Your game will start—enjoy!

SDK Usage

Check out GameManagerExample.cs/Start() in the example game for reference. Some useful input commands for testing in Unity:

• B = simulate ball hit (short touch) at the cursor position
• T = simulate touch (long touch) at the cursor position
• Q = add/remove player motion track 1
• E = hold to move player motion track 1 with the cursor
• W = add/remove player motion track 2
• R = hold to move player motion track 2 with the cursor

Preparation

Drag the lymb_sdk prefab into the scene.

Detect Ball Hits

Use the following call to subscribe to receiving ball hit events in your custom OnBallHit function:

LymbSDK.s_eventBallHit.AddListener(OnBallHit);

A ball hit is any impact detected lasting less than ~0.6s, so it will also detect taps with hands. The event sends a Vector2 (Screen Position) and a float (impact speed). The speed is not reliable and isn’t used by us as of now (ignore it!).

Ball hits also simulate left mouse clicks, so Unity's built in UI elements recognizes them out-of-the-box.

Detect Touches

Just subscribe to the event in Start()

LymbSDK.s_eventTouchDown.AddListener(OnTouchDown);

A touch is any impact detection lasting longer than ~0.6s. It will send TouchDown after those 0.6s and TouchUp once the user releases.

Note: In our system, touches are primarily used to open sub-menus like the pause menu. Thus, if you plan to add your game to our roster in the long term, you shouldn’t use touch for gameplay. If your game is the only one that should run on the system, you can obviously use it.

Touches also simulate right mouse clicks.

Track the position of Players in front of the wall

Subscribe to events that tell you when people were recognized or lost.

LymbSDK.s_eventPlayerTrackAdded.AddListener(OnPlayerTrackAdded);

LymbSDK.s_eventPlayerTrackRemoved.AddListener(OnPlayerTrackRemoved);

Those give you a key for the according track in the LymbSDK.s_dictPlayerTracks dictionary. Dictionary entries hold the player position (between 0 and 1 on each axis).

Please note that while the track IDs (keys for the dictionary) simulated with a keyboard are always 0 and 1, the IDs on an actual system will be more random. 

Tips & Tricks

1. System Hardware
   MultiBall is powered by entry-level hardware (Intel Celeron Processor J1900, 4GB RAM) running Ubuntu 16. One CPU core is typically reserved for motion tracking, leaving the rest for your game.

2. Testing on the actual system
   Playing on an actual system differs from testing in the editor with a mouse and keyboard. A few tips:

   • Short visual effects following ball hits may be perceived differently. After a ball impact, players will be preoccupied with cathcing or picking up the ball they just threw. Therefore, such visual effects might go unnoticed.
   • Precision is lower when throwing a ball versus using a mouse.
   • If you're using a projector-based system, contrast is lower than on a backlit screen; Black colors will take on the same color as the wall they're projected on. 
   • On projector-based systems, players can cast shadows that may block their view of game elements.

1. • If you're using an LED-based system, the display resolution is significantly lower than the internal render resolution. A MultiBall LED Club has an actual display resolution of 1024x640, the MultiBall LED Mini a resolution of 768x512. Be aware that in the latter case, the aspect ratio is 3:2, NOT 16:10. The base internal resolution is therefore 1800x1200 instead of 1920x1200.
   • On LED-based systems, image brightness can have a significant impact on power consumption and heat output of the screen. Darker colors may be preferrable.

1. • It is generally less fun to throw balls at targets near the bottom of the screen, since you may have to bend down catch or pick up any thrown balls. 

2. 2D Layering Issues in 2D Games
   Ensure front objects are truly in front by adjusting the z-position or renderer order in layer, to ensure that objects are displayed in the same order in the editor and built game 

3. False warning
   The debug log will say “Could not initialize fwbSDK” when testing in Unity. This is an expected message that will be removed with future updates.
4. Videos 
   If you plan to display videos in your game, keep in mind that Unity's list of supported video formats under Linux is quite limited, and many common formats are not supported. Consider converting them to .webm, e.g. with HandBrake. A guide on how to do this is available here.

5. Exiting Games
   The SDK currently doesn't include a pause menu. You'll need to implement a way to exit, otherwise the game can only be stopped using any of the following methods: 

   1. via the MultiBall admin page, by selecting a different game in the "Pick Game" section

   2. by connecting a keyboard to the MultiBall PC via USB and pressing ALT + F4

   3. by rebooting the system

6. Inspiration
   There are videos of our current games on our website that you can use for inspiration.