ScubaStudy

🌊 Scuba Study: Dive Deep and Defeat the Midterm Shark 💡 Inspiration: The "Productivity vs. Play" Tug-of-War We’ve spent countless hours at Sidney Smith Commons huddling over one screen, procrastinating with games like Wordle, Heardle, and Connections. But when it was time to start studying, that collaborative magic disappeared. Group study sessions can quickly become unproductive. We realized there was a massive gap: why isn't there a way to play games productively? Existing educational games like Kahoot are highly competitive, which often discourages students who are struggling with the material while only rewarding those who already know it. We asked ourselves: How can we make studying as addictive as a cooperative gaming session?

🎮 The Solution: Cooperative, AI-Driven Mastery We wanted to build a learning environment that captures the real-time thrill of a multiplayer game, but focuses on cooperative growth rather than individual ranking. Drawing on mechanics from past personal projects like battle optimizers and pet simulators, we realized we could merge the charm of playing as cute creatures with intense, real-time academic strategy. By leveraging generative AI to ingest our actual course notes, we dynamically generate a unique underwater expedition every time. We built Scuba Study to turn the isolation of exam prep into a high-stakes, collaborative deep-sea dive. 🐙 What it does Scuba Study is a multiplayer RPG where your knowledge is your oxygen, and you play as a squad of adorable aquatic animals working together to take down an ocean leviathan. The Dive: Players join a submarine lobby, choose their cute creature avatar , upload their study material (PDF or text), and dive down to face a massive shark whose HP scales with the group's size and the material's complexity. Adaptive Combat (The Real-Time DM): Generative AI allows us to move past static question banks. The AI acts as a real-time Dungeon Master—gauging your skill level on the fly. Get answers right, and the pressure increases with harder questions; struggle, and it recalibrates, providing instant personalized feedback to help you learn. Smart Player Targeting: The AI tracks your "weakest links," targeting topics you haven’t mastered yet to ensure no gaps in your knowledge. Damage Decay: The damage mechanics ensure that everyone contributes meaningfully. We implemented streak decay—the longer your streak, the less damage you do. This encourages consistent accuracy over "speed-running" easy questions and allows struggling students who finally nail a tough concept to land massive, satisfying critical hits on the boss. Post-Game Intel: Once the boss falls, you return to the surface with a treasure map of analytics. The AI maps out the team’s collective strengths and weaknesses, intelligently pairing students who need help with peers who have mastered the concept. It’s not just a game; it’s an AI-facilitated peer-tutoring ecosystem.

🛠️ How we built it We built a robust, asynchronous stack designed for real-time interaction: The Brain: We used FastAPI and Uvicorn for a high-performance WebSocket server, allowing for seamless real-time communication between the host and our squad of diving players. The AI Engine: We integrated the OpenAI SDK but pointed it at HuggingFace-hosted LLMs. We used an asyncio.Semaphore system to cap concurrent requests, ensuring the game stays snappy even as the player count grows. The Logic: Built with Pydantic for strict data validation and SQLAlchemy (with a custom SQLite migration workaround) to manage our game state, player stats, and AI-generated question banks. PDF Extraction: We used PyMuPDF (fitz) to parse complex study documents and feed them into our AI analysis pipeline.

🚩 Challenges we ran into Navigating the deployment trenches was our biggest hurdle. Ensuring WebSockets maintained a stable connection on Railway required a lot of trial and error with proxy configurations. Additionally, since we used a local SQLite database, we had to get creative with persistence and manual migrations—since SQLite doesn't natively support DROP COLUMN, we wrote a custom _migrate() function to handle schema updates on the fly without wiping our GitHub-hosted data.

🏆 Accomplishments that we're proud of The Adaptive Math: We’re incredibly proud of the game_logic.py engine. Balancing damage formulas, struggle bonuses, and streak penalties to make the game feel "fair" but challenging took hours of playtesting. Seamless Persistence: Building a system where a player can lose their WebSocket connection but immediately fetch their state via a REST fallback without losing their progress in the boss fight. AI Context Sampling: We developed a sampling logic that reads large documents across five different positions, ensuring the AI gets a holistic view of the material rather than just the first few pages.

📖 What we learned We leveled up our understanding of asynchronous Python and the complexities of WebSocket state management. We also learned that prompt engineering isn't just about the "ask"—it's about the "format." We had to build a robust _extract_json utility to handle cases where the LLM wrapped its answers in markdown code fences, ensuring our Pydantic schemas didn't break.

🚀 What's next for Scuba Study Aquarium Mode: A dashboard for TAs to upload weekly readings and see a heat map of which topics the entire class is struggling with. Character Classes: Introducing specific aquatic roles, like "Healer" Dolphins (who boost teammate damage by answering questions correctly) or "Tank" Crabs (who mitigate boss damage). Mobile App: A React Native version to allow for quick "micro-study" dives on the TTC.

🧰 Built With Backend: FastAPI, Python, Uvicorn Database: SQLAlchemy, SQLite AI: HuggingFace, OpenAI SDK, Pydantic Parsing: PyMuPDF Deployment: Railway, GitHub