Interactive body-actuating play experiences built in Unity for research conducted within the Integrated Motor Play initiative.

New to Unity or Auto-Paizo? This guide walks you from cloning the repository to pairing EMS hardware and running playtests. Read it sequentially the first time, then use the table of contents as a quick reference.

• 1. What is Auto-Paizo?
• 2. Who is this repository for?
• 3. System requirements
• 4. Quick start (10-minute setup)
• 5. Project tour
• 6. External devices & services
• 7. Working inside Unity
• 8. Building the application
• 9. Testing & debugging tips
• 10. Troubleshooting
• 11. Contributing
• 12. License
• 13. Credits & further reading

Auto-Paizo is a collection of play experiences that explore Body-Actuating Play (BAP)--games where the human body is both an input and an output device through electrical muscle stimulation (EMS). The project was developed as part of Rakesh Patibanda's PhD research and supports experimentation with:

• Auto-Paizo Games
• Fused Spectatorship
• Shared Bodily Fusion

The application connects to custom-built EMS controllers--BioGen and BioGen 2.0--and includes calibration tools, Bluetooth pairing flows, and a suite of mini-games that can be tailored for different study protocols or installations.

• Researchers & designers replicating or extending the BAP studies.
• Developers adding new interaction mechanics, mini-games, or device integrations.
• Artists & practitioners running participatory workshops with the Auto-Paizo kit.
• Students learning how EMS-driven play experiences are built in Unity.

No prior EMS knowledge is required to read this README, but make sure you consult your institution's safety guidelines before running electrical muscle stimulation sessions.

Additional tooling:

• Git >= 2.30
• Unity Hub for managing editor installs
• (Optional) Git LFS if you plan to pull large binary assets

1. Clone the repository
   git clone https://github.com/Integrated-Motor-Play/Auto-Paizo.git
   cd Auto-Paizo
2. Install Unity 2022.3 LTS
   • Open Unity Hub - Installs - Add - choose 2022.3.x LTS.
   • Include build support modules you care about (e.g., Android, iOS).
3. Open the project
   • Unity Hub - Projects - Open - select the cloned Auto-Paizo folder.
   • Unity will import packages (first load can take up to 10 minutes).
4. Verify packages
   • Window - Package Manager - ensure dependencies (TextMesh Pro, DOTween, Photon, Recognissimo) are resolved.
   • If any package shows errors, click Install/Resolve to reimport.
5. Run the main menu
   • Open Assets/_Project/Scenes/MainMenu.unity.
   • Press > Play in the editor.
   • Use the UI to explore menus; hardware-dependent features will warn you if devices are missing.

You now have the project running locally; continue below to connect hardware or build for deployment.

Inside Assets/_Project/Scripts/ you will find key domains:

• Core/ - Shared managers, login flows, networking helpers, and general utilities.
• Hardware/ - EMS calibration, Bluetooth discovery (BluetoothConnector.cs, EMSGenerator.cs, etc.).
• UI/ - Menu panels, buttons, and navigation glue such as PageManager.cs.
• Gameplay/ - Scene-specific logic for play experiences (e.g., PlantControl.cs).
• Utilities/ - Support scripts like SceneReloader.cs and DebugToggle.cs.

Use these entry points when extending functionality.

• Firmware & schematics: follow the official setup guides in the BioGen repo or BioGen 2.0 repo.
• Pairing:
  1. Power the controller and ensure electrodes are not yet attached to participants.
  2. Put the controller in pairing mode (refer to the BioGen manual).
  3. In Windows/macOS Bluetooth settings, pair each controller so the OS remembers it.
  4. Within Auto-Paizo's Bluetooth Connect scene, select the device name detected via BluetoothConnector.
• Calibration: Use the in-app calibration panels (Assets/_Project/Scripts/Hardware/EMGCalibrationPanel.cs, Assets/_Project/Scripts/Hardware/EMGSensitivitySlider.cs) before engaging games with participants.
• Safety: Always comply with local ethics approval; keep stimulation levels conservative and communicate with participants throughout play.

• Recognissimo loads offline language models from Assets/StreamingAssets/LanguageModels/.
• To add languages, drop new .vosk models into that folder and reference them in the relevant scriptable objects or components.
• Ensure microphone permissions are granted when deploying to mobile/desktop.

• Photon support is scaffolded in Assets/_ThirdParty/Photon/ and Assets/_Project/Scripts/Core/Network/.
• Supply your own Photon App ID via the PhotonServerSettings asset if you intend to use real-time multiplayer.
• For local-only experiences, disable networking UI elements in the main menu.

• DOTween is imported under Assets/_ThirdParty/DOTween/. Open Tools - Demigiant - DOTween Utility Panel to regenerate setup if tweens behave unexpectedly.

• MainMenu.unity: Entry point; navigates to calibration, games, and device setup.
• BluetoothConnect.unity: Handles Bluetooth discovery and connection for EMS hardware.
• Login.unity and Lobby.unity: Provide user access flows and game session setup.
• Voice Recognization Test.unity: Isolated scene for speech subsystem testing.
• Assets/_Project/Scenes/Refactor/: Staging area for experiments; expect work-in-progress content.

Tip: Use Unity's Scene Hierarchy search to locate UI panels quickly (e.g., type "CalibrationPanel").

1. Configure Play Mode Options
   • Edit - Project Settings - Player to check scripting backend (Mono is default).
   • Ensure Active Input Handling is set to Both (old + new) for hardware compatibility.
2. Simulate without hardware
   • Most UI flows can be tested using Unity's Play Mode.
   • For EMS-specific features, mock data is provided by scripts like EMSGenerator.cs.
   • You can temporarily stub IEmsController implementations for unit simulations.
3. Add new games or panels
   • Duplicate existing panels from Assets/_Project/UI System/.
   • Register them in PageManager.cs or the relevant controller class.
   • Hook gameplay scripts into ModeManager to surface them in the main menu.
4. Localization & audio
   • Update strings in the appropriate ScriptableObjects / UI Text components.
   • Replace audio clips under Assets/_Project/Resources/ or Assets/StreamingAssets/.

1. Pick your target platform
   • File - Build Settings.
   • Common targets: Android, Windows, macOS. The project ships with Android settings tuned for BioGen deployments.
2. Platform-specific notes
   • Android:
     • Install Android Build Support through Unity Hub.
     • In Player Settings, set a unique package name (e.g., com.yourlab.autopaizo).
     • Grant Bluetooth, microphone, and internet permissions in the Other Settings section.
   • Desktop:
     • Verify the correct architecture (x86_64).
     • On macOS, enable microphone and Bluetooth entitlements via the Info.plist generated post-build.
3. Run test builds
   • Use Build and Run to deploy directly to a connected device.
   • Perform on-device calibration to confirm EMS signals transmit correctly.
4. Versioning
   • Update Player Settings - Version with semantic versioning for each release.
   • Tag releases in Git to keep binaries reproducible.

• Console overlay: ConsoleToGUI.cs mirrors Unity logs to an in-app overlay--useful during builds where the Unity Console is unavailable.
• Debug toggles: Scripts like DebugToggle.cs and DefaultSelected.cs help reveal hidden UI and manage controller focus.
• Graphing EMS data: The Graph/ components visualize EMG input; use them to verify signal strength in real time.
• Play mode tools:
  • Enable Device Simulator (Window - General - Device Simulator) for mobile layout testing.
  • Use ParrelSync (Assets/_ThirdParty/ParrelSync) to run multiple editor instances for networked scenarios.
• Automated checks: While the project does not ship with Unity Test Runner suites, you can create PlayMode tests under Assets/Tests/ to verify calibration or UI flows.

• Missing packages
  • Symptoms: red console errors, missing scripts.
  • Fix: Open Window - Package Manager, switch to My Assets, install DOTween, TextMeshPro, or other missing items. Reimport All if necessary.
• Bluetooth device not discovered
  • Ensure the OS paired with the device first.
  • On Windows, turn off other apps using Bluetooth Low Energy to avoid conflicts.
  • Check Assets/_ThirdParty/BluetoothAPI/ scripts for hard-coded device names and update them.
• EMS output feels too strong
  • Recalibrate using EMGCalibrationPanel.
  • Confirm electrode placement matches the BioGen documentation.
  • Never test on yourself without supervision; use low-intensity settings first.
• Speech recognition not working
  • Confirm language models exist in Assets/StreamingAssets/LanguageModels/.
  • Grant microphone permissions on the target platform.
• Photon errors
  • Update the App ID under Assets/_ThirdParty/Photon/PhotonUnityNetworking/Resources/PhotonServerSettings.
  • Disable networking components if running offline demos.

If you encounter a blocker, capture the Unity console log (Editor.log) and open an issue describing the steps taken, hardware used, and any reproduction assets.

We welcome improvements ranging from documentation updates to new play modes. To contribute:

1. Fork & branch
   git checkout -b feature/your-feature-name
2. Follow project conventions
   • Keep scripts in relevant folders (Assets/_Project/Scripts/Core/Managers, Assets/_Project/Scripts/Core/Login, etc.).
   • Use descriptive component names and update prefabs where necessary.
   • Add inline comments sparingly to explain non-obvious EMS logic.
3. Test your changes
   • Run scenes impacted by your change in Play Mode.
   • If you alter Bluetooth or EMS logic, dry-run with hardware or documented mocks.
4. Commit & push
   git commit -am "Add short description of change"
   git push origin feature/your-feature-name
5. Open a pull request
   • Describe the motivation, implementation details, and testing performed.
   • Link related issues or research notes if applicable.

Please respect existing research protocols and do not commit participant data or proprietary binary assets.

This project is licensed under the MIT License.

• Integrated Motor Play Team - Organization GitHub
• Lead researcher - Rakesh Patibanda
• Research publications for deeper context:
  • Body-Actuating Play (BAP)
  • Auto-Paizo Games
  • Fused Spectatorship
  • Shared Bodily Fusion

For questions, suggestions, or collaboration requests, open an issue on GitHub or reach out via the links above.

Happy building, and remember to prioritize participant comfort and safety whenever working with EMS-driven play.