========================================
3D PERSISTENT STREAM WHEEL
Setup & User Guide
========================================

OVERVIEW
--------
This system is a custom 3D Stream Wheel that runs using:
- A Python backend server
- OBS browser overlay
- Streamer.bot automation
- Optional Stream Deck controls

The wheel automatically:
- Loads entries from names.txt
- Removes used results permanently (blacklist.conf)
- Saves results between sessions


========================================
1. FILE STRUCTURE
========================================

All files MUST stay in the same folder:

- overlay.html              (Wheel overlay)
- admin.html                (Color settings panel)
- server.py                 (Python backend server)
- run.bat                   (Start server script)
- python-3.14.4-amd64.exe   (Python installer)
- names.txt                 (List of entries, one per line)
- colors.conf               (Saved wheel colors)
- blacklist.conf            (Removed/winning entries)
- wheel_of_fortune_tick.mp3 (Spin sound effect)


========================================
2. INSTALLATION
========================================

STEP 1 — Install Python
------------------------
1. Run: python-3.14.4-amd64.exe
2. IMPORTANT: Enable “Add Python to PATH”
3. Finish installation


STEP 2 — Start Server
---------------------
1. Run: run.bat
2. Keep the black command window open
3. Confirm message:
   "Wheel Server running at http://localhost:8000"


STEP 3 — Configure Colors
-------------------------
1. Open:
   http://localhost:8000/admin.html
2. Choose your wheel colors:
   - Segments
   - Border
   - Text
   - Center
3. Click: SAVE COLORS.CONF
4. Replace the file in your folder


STEP 4 — Launch Wheel
---------------------
1. Open:
   http://localhost:8000/overlay.html
2. Wheel loads automatically:
   - Reads names.txt
   - Removes blacklist entries
   - Spins after 2-second delay
3. Result is saved to blacklist.conf


========================================
3. OBS STUDIO SETUP
========================================

1. Open OBS Studio
2. Add Source → Browser
3. Name: Wheel Spinner
4. URL:
   http://localhost:8000/overlay.html
5. Set resolution:
   800 x 800 (recommended)

Optional:
- Enable "Shutdown source when not visible"
  (wheel resets when shown again)


========================================
4. MANAGING THE WHEEL
========================================

RESET WHEEL:
- Open blacklist.conf
- Delete all contents

ADD NEW ENTRIES:
- Edit names.txt
- One entry per line

AUTO BEHAVIOR:
- Removed entries are never reused
- Wheel updates dynamically
- Colors remain consistent even after removals


========================================
5. STREAMER.BOT SETUP
========================================

IMPORT:
Use the provided Streamer.bot import code to load all actions automatically.


Import_Code:
------------
 




ACTIONS INCLUDED
-----------------

1. Add_Item_To_Wheel
   - Adds entry from chat/reward input
   - Appends to names.txt

2. Start_Wheel_Spinner_Server
   - Starts Python backend server

3. End_Wheel_Spinner_Server
   - Stops Python server

4. Show_Overlay_And_Spin
   - Shows OBS overlay
   - Spins wheel

5. Hide_Overlay
   - Hides OBS overlay

6. Reset_Wheel
   - Clears:
     names.txt
     blacklist.conf


========================================
6. OBS INTEGRATION
========================================

Browser Source Setup:
- Path:
  C:\Program Files\obs-studio\Wheel_Spinner\overlay.html
- Recommended size:
  1920 x 1080
- Enable:
  "Refresh when scene becomes active"


========================================
7. STREAM DECK SETUP
========================================

INSTALL PLUGIN:
1. Open Stream Deck software
2. Go to Plugin Store
3. Install "Streamer.bot"
4. Set WebSocket:
   ws://127.0.0.1:8080


ENABLE IN STREAMER.BOT:
Settings → WebSocket Server → Enable


BUTTONS
-------

SPIN BUTTON
- Action: Show_Overlay_And_Spin

HIDE BUTTON
- Action: Hide_Overlay

OPTIONAL:
- Add Item → Add_Item_To_Wheel
- Reset → Reset_Wheel


========================================
8. HOW IT WORKS
========================================

1. Viewer adds item (command/reward)
2. Item saved to names.txt
3. Python server manages data
4. OBS displays wheel
5. Streamer.bot triggers spin
6. Winner is saved permanently in blacklist


========================================
9. TROUBLESHOOTING
========================================

- Server not starting:
  → Ensure Python is installed + PATH enabled

- Wheel not updating:
  → Refresh OBS browser source

- Stream Deck not working:
  → Check WebSocket connection (8080)

- Permissions issues:
  → Run Streamer.bot as Administrator


========================================
END OF GUIDE
========================================