updated README for scripts

experiment-scripts/README.md

@@ -1,16 +1,164 @@
-# README
+# VR Charades Experiment Scripts
 
-The documentation for most files can be found inside the file itself.
-The most important files are:
+This directory contains scripts to run and control VR Charades experiments.
 
- - control.py: For setting up the conditions
- - app.py: For running the HTML user interface
- - server.py: For running the relay server
- 
- To setup the experiment environment, you should:
-  1. Connect the HMDs to same network as the server
-  2. Start the relay server (i.e. server.py)
-  3. Start the HTML user interface (e.g. using `fastapi dev app.py`)
-  4. Communicate the server IP to the HMDs using `TARGET_IP=<HMD IPs> python3 control.py 'IP:<server ip>'`
-  5. Setup the desired condition (see control.py for more information)
-  6. Shuffle the word-list (i.e. word-list.txt); on linux this can be achieved using shuf e.g. `shuf word-list.txt > word-list-shuffled.txt`
+## Installation
+
+1. Create and activate a virtual environment:
+```bash
+# Windows
+python -m venv venv
+venv\Scripts\activate
+
+# Linux/Mac
+python3 -m venv venv
+source venv/bin/activate
+```
+
+2. Install Python dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+## Files Overview
+
+- **app.py**: Web interface for controlling the experiment and word list
+- **server.py**: UDP relay server for communication between VR clients
+- **control.py**: Command-line tool for setting VR client modes and server IP
+- **index.html**: Web UI served by app.py
+- **word-list.txt**: Default list of charade words
+
+## Setup Instructions
+
+### 1. Prepare Dependencies
+```bash
+# Activate your virtual environment first
+# Windows: venv\Scripts\activate
+# Linux/Mac: source venv/bin/activate
+
+pip install -r requirements.txt
+```
+
+### 2. Network Setup
+- Connect all VR headsets to the same network as the server
+- Note the IP addresses of the VR headsets (you'll need these for configuration)
+- **Important**: Update `server.py` lines 19-20 with your actual VR headset IPs
+  ```python
+  # Replace these example IPs with your actual headset IPs
+  DEVICE1_ADDR = ("YOUR_PLAYER1_IP", 5001)  # e.g., ("192.168.1.100", 5001)
+  DEVICE2_ADDR = ("YOUR_PLAYER2_IP", 5001)  # e.g., ("192.168.1.101", 5001)
+  ```
+
+### 3. Start the Relay Server
+```bash
+python server.py
+```
+
+### 4. Start the Web Interface
+```bash
+python -m fastapi dev app.py
+```
+Then navigate to `http://localhost:8000`
+
+### 5. Configure VR Clients
+
+Tell clients which server to connect to:
+```bash
+# Windows PowerShell (replace with your actual VR headset IPs)
+$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "IP:127.0.0.1"
+
+# Linux/Mac (replace with your actual VR headset IPs)
+TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" python3 control.py "IP:127.0.0.1"
+
+# Example with actual IPs:
+# $env:TARGET_IP="192.168.1.100,192.168.1.101" ; python control.py "IP:127.0.0.1"
+```
+
+### 6. Set Experiment Condition
+
+Choose one of these modes (replace YOUR_PLAYER1_IP,YOUR_PLAYER2_IP with actual IPs):
+```bash
+# Dynamic Face only
+$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:1;1;1;0"
+
+# Dynamic Hands only  
+$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:0;0;0;1"
+
+# Dynamic Hands + Face
+$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:1;1;1;1"
+
+# Static Face only
+$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:1;0;0;0"
+
+# Static Hands only (requires controllers)
+$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:0;0;0;1"
+
+# Static Hands + Face (requires controllers for hands)
+$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:1;0;0;1"
+```
+
+### 7. Prepare Word List
+
+Shuffle the word list for randomization:
+```bash
+# Windows PowerShell
+Get-Content word-list.txt | Sort-Object {Get-Random} | Out-File word-list-shuffled.txt
+
+# Linux/Mac
+shuf word-list.txt > word-list-shuffled.txt
+```
+
+## Web Interface Usage
+
+Once you have the web interface running at `http://localhost:8000`, follow these steps:
+
+### Setting Up a Charades Session
+
+1. **Configure Player IPs**
+   - Enter the IP addresses of Player 1 and Player 2 VR headsets
+   - These should match the IPs you used in the `control.py` commands
+   - **Note**: The default placeholders (10.42.0.38, 10.42.0.100) are examples - use your actual headset IPs
+
+2. **Prepare Word List**
+   - Copy your shuffled word list from `word-list-shuffled.txt`
+   - Paste it into the large text area on the right side
+   - Click the **"Modify"** button to generate interactive word items
+
+3. **Set Game Parameters**
+   - **Current Player For Acting**: Select which player will be acting out the words
+   - **Time (s)**: Set the time limit for each word (e.g., 30 seconds)
+   - **Last Word Status**: Set to "None" for the first word
+
+### Running the Experiment
+
+#### Manual Mode (Individual Words)
+1. Enter a word in the "Word" field
+2. Select the acting player (Player 1 or Player 2)
+3. Set the time limit
+4. Click **"Send"** to transmit the word to the VR headsets
+
+#### Automatic Mode (Word List)
+1. After clicking "Modify" with your word list, the interface shows all words with timers
+2. The system automatically:
+   - Starts with the first word
+   - Sends it to the selected acting player
+   - Counts down the timer for each word
+   - Moves to the next word when time expires or word is marked correct
+
+3. **During the session**:
+   - **Mark words correct**: Hover over a word and check the checkbox if guessed correctly
+   - **Timer display**: Shows remaining time for current word
+   - **Visual indicators**: 
+     - ▶ = Current word being acted
+     - ✅ = Correctly guessed word
+     - ❌ = Time expired / incorrect word
+
+4. **Stop the session**: Click **"Stop"** to end early
+
+### Exporting Results
+
+1. After completing the word list, click **"Save as CSV"**
+2. This downloads a CSV file with:
+   - Word name
+   - Whether it was guessed correctly (true/false)
+   - Time remaining when completed

experiment-scripts/requirements.txt

@@ -0,0 +1 @@
+fastapi[standard]>=0.116.0