Skip to content
airalcorn2Public

About

A magical cauldron for casting spells.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

27 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Interactive Halloween Cauldron

Demo

Featured on the official Claude Instagram account:

Claude Instagram feature

An interactive prop built on a Raspberry Pi. Drop some items into the cauldron and an IR beam break starts the sequence: the camera takes a photo, a vision model writes a three-line spell about what it sees, and three text-to-speech "witch" voices recite it with the LED ring set to each witch's color. A USB gamepad live-switches between that and five other photo-reactive modes, plus two gamepad-only mini-games that skip the camera entirely. The same prop also hosts a phone-driven trivia game for a crowd, and a bridge to a separate Halloween-themed Godot game, so ingredients collected and spells completed over there trigger real witch voices and lighting back here. See Materials for the full parts list.

Table of Contents

Modes

The controller takes --mode react (default), --mode story, --mode joke, --mode prophecy, --mode request, or --mode category.

react — the witches conjure a spell about whatever the mortal drops in. The beam has to go quiet for a couple of seconds before the photo is taken, so a second item dropped in right after the first still makes the shot.

story — identical to react, except the witches tell a short spooky story featuring the dropped items instead of reciting a rhyming spell, with each witch continuing where the last left off.

joke — identical to react, except the witches tell a fun, spooky joke featuring the dropped items instead of reciting a rhyming spell, split the same three ways.

prophecy — identical to react, except the witches deliver a campy, over-dramatic fortune about the mortal's future, reading the dropped items as omens, split the same three ways.

request — the witches announce a recipe of two objects to fetch, some named plainly and some as riddles. The mortal drops items in (holding a hand in the beam instead replays the request); once the beam has gone quiet for a couple of seconds, the camera takes one photo and the model checks it against the recipe. One attempt only: success gets a triumphant spell and a green shimmer, anything less gets a comedic curse and a red fizzle. On an API failure the recipe falls back to a small built-in pool.

category — like request, but the witches challenge a property instead of naming objects (e.g., "something round" or "something that makes noise") rather than a fixed list — the mortal picks what counts, and the model judges whatever lands against the property. Same wait/repeat-gesture/one-attempt mechanics and outcome lighting as request.

brew and play exist alongside these six but aren't --mode options — they're one-shot gamepad detours, reached live (see Live Mode Switching below) rather than started from the command line.

brew is a one-shot mini-game, not a persistent mode, so picking it doesn't change --mode — the show resumes whatever mode was active before once the round ends. Nothing is dropped in and no photo is taken; instead, balance the potion's heat and swirl live on the LED ring using the gamepad alone. D-pad up heats it up, D-pad down cools it down (held, not tapped — same buttons as play's heat control, just continuous here instead of stepped) — straying from the sweet spot speeds up the swirl, shown as a brighter band chasing around the ring. The talons (button_4/button_5) brake the swirl and steer its direction; boil over, freeze, or spin out of control and the brew is lost, while holding steady for 30 seconds is a win. See brew_game.py for the full rules; run it directly to play a round without going through mode selection.

play is also a one-shot detour, not a persistent mode — but it's a sandbox, not a game: no winning, losing, or timing out, just manipulating the potion for fun. Face buttons sprinkle that color into the potion, accumulating permanently; D-pad left resets the whole ring into a true rainbow gradient with a swirling fade, and D-pad right sends a comet sweeping once around, clearing colors as it passes. The talons give the potion a quick stir that settles back down on its own, and D-pad up/down steps through three heat levels, each with its own bubbling look and volume. Every action is interruptible — mashing buttons quickly only narrates the last one, not a backlog of all of them — and announced by a randomly chosen witch each time. See potion_play.py for the full rules; run it directly without going through mode selection.

Live Mode Switching

Plug in a USB gamepad (SNES-style clones work fine — run controller.py directly to confirm your pad's button mapping) and the mode can be changed without restarting the process.

Press Select + Start together to interrupt whatever's happening and open mode selection. A random witch asks which mode to pick, naming each button in-universe:

Button Mode
Blue face button react
Red face button story
Yellow face button joke
Green face button prophecy
Left shoulder button ("left talon") request
Right shoulder button ("right talon") category
D-pad up ("upper rune") brew
D-pad down ("lower rune") play

Press a mode's button at any point — even mid-sentence — to pick it immediately. Otherwise, once the witch finishes listing them, left/right on the D-pad browses back through the options, replaying each one's line, before committing. The LED ring mirrors all of this: a chasing rainbow during the intro and whenever idle (including between rounds), each mode's own fixed color while it's being named or confirmed, then back to the rainbow once a mode is chosen. Picking brew or play this way runs that round immediately and returns to whatever mode was active before — see Modes above for what each one does.

All of the witches' mode-selection lines are hand-written and cached to disk ahead of time (generated/mode_select/), so opening mode selection never waits on a network call.

Trivia

A two-team horror/Halloween trivia game, separate from everything above: it's phone-driven rather than gamepad-driven, so it isn't reachable through the gamepad's mode selection and doesn't need a beam break to start. Questions come from a public Jeopardy! clue dataset (its own maintainer prefers not to credit where the clues were sourced from), filtered down to horror/Halloween-adjacent categories and voice-cached ahead of time by trivia_data.py — run that once before a party; it never runs during a live round. For a kid-friendly crowd, run trivia_kids.py instead — it generates original, trick-or-treat-appropriate Halloween/monster trivia with Gemini rather than filtering the Jeopardy dataset, and writes to the exact same files, so it's a drop-in swap ahead of a kids' party.

Host a round with .venv/bin/python trivia_game.py, which prints two addresses: a group screen (put this on a TV or other shared display) that opens on the game's title and a QR code per team, then switches to a live scoreboard and the current question once the round starts; and a team page per team, reached by scanning that team's QR code, where that team submits answers on their own phones. Play alternates strictly between the two teams each question — whichever team held a question, the other team holds the next one, regardless of who scored — with one twist: if the team up misses (or the clock runs out), the other team gets a one-time steal attempt at the same question before play moves on. Answers are free text — just the answer itself, not phrased as a question — graded live by Gemini rather than a human judge or a local heuristic; the same call also writes the judging witch's in-character reaction, a roast for a wrong answer or praise for a right one, each one naming the mortal's actual answer and/or the correct one rather than reacting generically. Unlike every other mode in this project, that live grading means trivia genuinely needs network access during play, not just to prepare beforehand. See trivia_game.py for the exact rules and docs/trivia.md for how to prepare and host a round.

Hex Hollow Bridge

Hex Hollow title screen

A standalone HTTP bridge for Hex Hollow (source), a separate Godot game (a top-down witch-and-cauldron ingredient hunt) played on its own device on the same LAN rather than through this project's gamepad. Run .venv/bin/python game_bridge.py instead of cauldron_controller.py — both want the same LED ring and audio hardware, so this replaces the live show for as long as the game's being played, the same way trivia_game.py does. It prints the address to enter into the game's own CauldronBridge.BASE_URL setting. Idle, the ring bubbles under a chasing rainbow, same as the main show's own idle look. Dropping an ingredient into the game's cauldron briefly takes the ring over with a solid flash in that ingredient's color while a random witch names it, then returns to the idle rainbow; finishing the spell has a witch announce it, then all three witches recite a fixed victory spell in turn before a victory swirl. See game_bridge.py for the exact routes.

Software Layout

cauldron_controller.py orchestrates the show. Each hardware or service component is a standalone module that also runs on its own for bench testing.

Module Responsibility Bench test
ir_sensor.py IR break-beam sensor (GPIO 17) .venv/bin/python ir_sensor.py
camera.py USB camera capture .venv/bin/python camera.py test.jpg
light_control.py LED ring over SPI (GPIO 10) .venv/bin/python light_control.py leds
spell_generator.py Gemini vision model: spells (react), stories (story), jokes (joke), prophecies (prophecy), recipes (request), and category challenges (category) .venv/bin/python spell_generator.py test.jpg
voice_generator.py ElevenLabs text-to-speech .venv/bin/python voice_generator.py --text "..."
audio.py Sound-effect and speech playback .venv/bin/python audio.py --loop 5
actuator.py Stage-tipping linear actuator (GPIO 16 / 26) .venv/bin/python actuator.py dump
controller.py USB gamepad input, for live mode switching .venv/bin/python controller.py
brew_game.py The "brew" mini-game's physics, rendering, and game loop .venv/bin/python brew_game.py
potion_play.py The "play" sandbox's state, rendering, and control loop .venv/bin/python potion_play.py
trivia_data.py One-time download/filter/voice-cache prep for the trivia question bank .venv/bin/python trivia_data.py
trivia_kids.py Kid-friendly alternative to trivia_data.py: Gemini-generated, not dataset-filtered .venv/bin/python trivia_kids.py
trivia_game.py The trivia game's turn/steal/scoring rules and round orchestration .venv/bin/python trivia_game.py
trivia_web.py The HTTP+WebSocket server and the group/team pages, plus QR code generation .venv/bin/python trivia_web.py
game_bridge.py HTTP bridge letting the separate Hex Hollow Godot game trigger real witch/light reactions .venv/bin/python game_bridge.py

Every module accepts --help.

Setting Up

The wiring steps below get considerably more involved than the software ones — if you're new to electronics, keep this schematic open as a reference.

About

A magical cauldron for casting spells.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages