# RP Queue — Encounter Turn Tracker

A shared, always-visible panel for running RP-heavy sessions with large groups (built with 7-player tables in mind). It solves one problem: when everyone's in character at once, it's hard to tell whose turn it is to talk, and easy for one or two voices to dominate.

## What it does

- **A persistent panel every player can see**, listing every seat (player/character) in the party with a colored status: waiting, hand raised, speaking now, on hold, or done for the round.
- **Raise Hand** — any player can flag "I have RP to do" without interrupting whoever's talking. Raised hands automatically jump the queue the next time the GM advances.
- **Round-robin fallback** — the GM can just click "Next" to cycle through the whole party in seat order, catching anyone who has something small to add but wouldn't otherwise raise a hand.
- **Hold** — the GM's answer to "this needs to move the story forward, but I want to loop back to everyone else first." Click Hold on whoever's currently speaking; they're pulled out with a distinct "Holding — will return" badge, and they're automatically folded back into the queue once everyone else has had a turn.
- **Manual overrides** — the GM can jump straight to any seat, skip an absent player, or recall someone from "done"/"held" back into play, at any time.
- **Turn announcements** — an optional whispered chat message (and, per-player, an optional sound) when the queue reaches your seat.

## Requirements

- Foundry VTT **v12 or v13**.
- Works with any game system (it doesn't touch actors/combat — it's a standalone social layer).

## Installation

**Easiest — install by manifest URL** (once published, see below):
In Foundry's **Add-on Modules** tab, click **Install Module**, and paste:

```
https://github.com/TheBurlyViking/RP-Queue-for-FoundryVTT/releases/latest/download/module.json
```

**Manual install:** unzip `rp-queue.zip` directly into your Foundry `Data/modules/` folder, so you end up with `Data/modules/rp-queue/module.json`, then restart Foundry (or refresh the Setup page).

Either way, enable **RP Queue — Encounter Turn Tracker** in your world's Module Management afterward.


## Setup (do this once per campaign)

1. Load into the world. The panel opens automatically for everyone (as a small floating window — drag it wherever's convenient, and minimize it with the window controls when you don't need it open).
2. As GM, click the roster icon (👥) in the panel's toolbar.
3. Add one seat per player — pick their user account and, optionally, their character (for a portrait). If a player runs two characters, add two seats for them. Add extra seats with no linked player for GM-controlled NPCs you want in the rotation.
4. Reorder seats with the up/down arrows if you want a specific base order (this is the order "Next" walks through).
5. Close the config dialog. The roster is saved to the world and persists between sessions.

## Running a round

1. Click **Start Round**. The GM's queue is built from: anyone who's already raised a hand (in the order they raised it), then everyone else in seat order.
2. Whoever's up is highlighted with a glow. Use:
   - **Next** — they're done, move to whoever's next (raised hands still jump ahead of the round-robin order).
   - **Hold** — pull the current speaker out mid-round; they'll automatically come back up once everyone else has gone (or been held/skipped too).
   - The 💬 icon on any seat — jump straight to them, overriding the queue.
   - The ⏩ icon on any seat — skip someone who's away from keyboard.
3. Players can raise/lower their own hand at any point, including mid-round — it doesn't interrupt the current speaker, it just puts them next in line.
4. **End** finishes the round without clearing history (so you can see who went); **Reset** (the ↺ icon) wipes the round back to a blank slate, ready for the next scene.

## Notes on how it works

- Only the table's active GM ever writes the shared queue state — when a player raises their hand, that request is quietly relayed to the GM's client and applied there. **This means a GM (or Assistant GM) needs to be connected for changes to save**; if nobody with GM permissions is online, raising/lowering a hand will show a warning instead of silently failing.
- If your world ever has two GM-role accounts connected at once, only Foundry's designated "active GM" applies changes, so you won't get duplicate/racing updates.
- Turn-change chat announcements can be turned off in **Module Settings** (world setting). The "play a sound on my turn" option is per-player (client setting).

## Possible next steps 

- A drag-to-reorder roster instead of up/down buttons.
- A "spotlight" mode that dims the VTT canvas or posts a scene-wide banner naming the current speaker.
- Per-scene rosters instead of one campaign-wide roster, if you want different NPCs in rotation for different scenes.