🎡 Name Randomizer — Discord Wheel-Spin Bot

A Discord bot that collects a list of names and picks a random winner with a spinning prize-wheel animation that everyone in the server can watch. Every name gets its own colored slice; type /spin and the bot posts a short spinning GIF that slows down and lands on the winner.

A friendly replacement for wheel-spin bots that have shut down.

---

What it can do

Type this in Discord	What happens
/adduser member: @Alice	Adds a server member — start typing to pick them. Winners get pinged.
/addmany	Opens a menu to pick several server members at once (up to 25).
/addextra names: Mom, Table 3	Adds custom name(s) that aren't members (one, or comma-separated).
/names	Shows the current names and a picture of the wheel.
/remove name: Bob	Removes one name (or @mention a member).
/clear	Removes everyone.
/spin	Spins the wheel and announces the winner 🎉
/spin remove_winner: True	Spins, then removes the winner — great for drawing several winners in a row.
/spinbot-help	Shows these commands inside Discord (only you see it).

Every server has its own separate list, so different servers won't interfere with each other. The winner is picked fairly and at random, and the animation is built to land exactly on that winner — the picture always matches the result.

📖 Just want to use the bot in Discord? See the non-technical User Guide — no setup or tech knowledge required.

---

Setup — step by step

You'll do this once. It takes about 10 minutes. You need a computer that can stay on while people use the bot (your own PC for testing, or a small server — see Keeping it running).

Step 1 — Create the bot and get its token

A "token" is the secret password your program uses to log in to Discord as the bot. Treat it like a password — never share it or post it publicly.

1. Go to the Discord Developer Portal and sign in.
2. Click New Application, give it a name (e.g. Name Randomizer), and create it.
3. In the left menu click Bot.
4. Click Reset Token, confirm, then Copy the token. Paste it somewhere safe for a moment — you'll need it in Step 3.

Step 2 — Invite the bot to your server

1. In the left menu click OAuth2.
2. Under OAuth2 URL Generator, tick bot and applications.commands.
3. A new Bot Permissions box appears below. Tick Send Messages, Embed Links, and Attach Files.
4. Copy the link at the very bottom, open it in your browser, choose your server, and click Authorize.

The bot now appears in your server (offline until you start it in Step 3).

Step 3 — Download and run it

You'll need Python 3.10 or newer installed. Then open a terminal / command prompt and run:

# 1. Get the code
git clone https://github.com/dcchillin46/name_randomizer.git
cd name_randomizer

# 2. Install what it needs
pip install -r requirements.txt

# 3. Tell it your token
cp .env.example .env        # Windows: copy .env.example .env
#   ...then open the new ".env" file in a text editor and paste your token
#   after "DISCORD_TOKEN=" so it reads, e.g.:  DISCORD_TOKEN=MT234...

# 4. Start the bot
python bot.py

When you see Logged in as ..., the bot is online. Go to your server and type /spin 🎉

The very first time, Discord can take a minute or two to show the new slash commands. If /spin doesn't appear right away, wait a moment and try again.

---

Keeping it running

The bot only works while python bot.py is running. Closing the terminal or shutting down the computer takes the bot offline.

• Just trying it out? Running it on your own computer is perfectly fine.
• Want it online 24/7? Run it on an always-on machine — Unraid, a cheap VPS, a Raspberry Pi, or any small cloud host.

Good news for self-hosting: the bot only makes outbound connections to Discord. You do not need a domain, a public URL, port forwarding, or a reverse proxy, and nothing is exposed to the internet. It just needs normal outbound internet access.

Serving someone else's server

One running copy of the bot can serve many Discord servers at once — each server keeps its own separate name list. To let someone use it on their server, just send them your bot's invite link (the OAuth2 URL from Step 2); they click it and pick their server. You (the host) hold the token and run the single instance. Don't run two instances with the same token.

Option A — Docker Compose (recommended)

cp .env.example .env        # then edit .env and paste your token
docker compose up -d --build

That's it — it auto-restarts on reboot and saves names to a data/ folder next to the file. Update later with git pull && docker compose up -d --build.

Option B — Unraid

Easiest: the Compose Manager plugin. Install Compose Manager from Community Apps, add a new stack, paste in the docker-compose.yml from this repo, create a .env file in the stack folder containing DISCORD_TOKEN=your-token, and hit Compose Up.

Or the plain Docker UI — open the Terminal, build the image once:

cd /mnt/user/appdata
git clone https://github.com/dcchillin46/name_randomizer.git
cd name_randomizer && docker build -t name-randomizer .

then Docker → Add Container and fill in:

Field	Value
Name	name-randomizer
Repository	name-randomizer
Network Type	bridge (leave all Port mappings empty — none are needed)
Variable → Key / Value	DISCORD_TOKEN / your bot token
Variable → Key / Value	NAMES_FILE / /data/names.json
Path → Container / Host	/data / /mnt/user/appdata/name-randomizer/data

Set the container's restart policy to unless-stopped, then Apply. The /data path keeps saved names across restarts and updates.

Plain docker run

docker build -t name-randomizer .
docker run -d --restart unless-stopped \
  -e DISCORD_TOKEN="your-token-here" \
  -e NAMES_FILE=/data/names.json \
  -v "$PWD/data:/data" \
  name-randomizer

---

Troubleshooting

Problem	Fix
DISCORD_TOKEN is not set	You didn't paste your token into .env, or .env isn't in the same folder as bot.py.
Slash commands don't show up	Wait a minute or two after the first start; make sure you ticked applications.commands in Step 2.
Bot can't post the wheel	Re-check the bot has Send Messages, Embed Links, and Attach Files in that channel.
command not found: python	Use python3 instead, or reinstall Python and tick "Add to PATH".

---

For developers

The project is small and split into clear pieces:

File	Purpose
bot.py	Discord slash commands and event handling.
wheel.py	Wheel + spin-GIF rendering with Pillow. No Discord dependency — run python wheel.py to preview demo_wheel.png / demo_spin.gif.
storage.py	Per-server name lists saved to a JSON file.
test_wheel.py	Tests for the geometry, rendering, and storage.

pip install -r requirements.txt
python test_wheel.py        # run the tests (or: python -m pytest)
python wheel.py             # preview the wheel without touching Discord

Because wheel.py is Discord-free, you can freely tweak colors, size, frame count, or spin feel and see the result instantly. The winner is chosen first, then the animation is generated to land on it, so the rendered GIF and the announced winner can never disagree.

Settings

Environment variable	Default	Meaning
DISCORD_TOKEN	(required)	Your bot token.
NAMES_FILE	names.json	Where each server's name list is saved.