Algebradiction

Welcome to Algebradiction! Wield algebraic might in thrilling courtroom duels. Solve math puzzles, present clues, and outsmart AI foes to become a legal math whiz. Are you ready for the challenge?

Comment

Inspiration

The inspiration behind Algebradiction stems from the desire to make learning mathematics, particularly algebra and related concepts, more engaging and interactive for students. Traditional math learning can sometimes feel dry, so Algebradiction aims to gamify the experience by placing students in a thrilling courtroom setting. The idea is to transform abstract mathematical problems into compelling "cases" where logic, problem-solving, and mathematical prowess are the keys to "winning" and defending a client. The project draws inspiration from popular courtroom drama games, adapting the narrative tension and character interactions to an educational context.

What it does

Algebradiction is an interactive educational game where players take on the role of a defense attorney. Their mission is to defend "clients" (who are often personified mathematical concepts or entities) accused of mathematical "crimes" (i.e., incorrect calculations or flawed logic).

Here's how it works:

  1. User Authentication: Players can sign up or log in to save their progress, including their current level, completed tutorials, and learned mathematical concepts.
  2. Dynamic Case Generation: The game uses the Google Gemini API (gemini-2.5-flash-preview-04-17) to dynamically generate unique math "cases" tailored to the player's current level and a specific Indian CBSE/NCERT curriculum topic for Classes 8, 9, or 10. Cases include a title, client details, an accusation (the math problem), evidence (some of which may be flawed), key mathematical concepts, and verdicts. Evidence visuals (SVGs) are also described in the generation prompt for dark themes.
  3. Case Briefing: Before a trial, players review the case details, including the accusation, initial arguments, and hints from their AI co-counsel.
  4. Courtroom Interaction:
    • Players interact with AI-powered characters: The Judge, a "Silly Prosecutor," and a helpful "Super Helper" (Co-Counsel).
    • The Prosecutor presents arguments based on the alleged mathematical error.
    • The Co-Counsel offers advice and hints to the player.
    • Dialogues are generated by the Gemini API, with characters having distinct personalities and roles.
  5. Player Actions:
    • Clue Checker (Evidence Terminal): Players examine available evidence, some of which may contain mathematical flaws.
    • My Story Board (Proof Board): Players construct their defense arguments, explaining the mathematical reasoning to prove their client innocent.
    • Wait a Minute! (Objection System): Players can object to the Prosecutor's statements, providing their mathematical counter-arguments.
  6. AI Judge's Ruling: The player's arguments and objections are sent to the Gemini API (acting as The Judge) for analysis. The Judge evaluates the mathematical validity and relevance of the player's input.
  7. Verdict: Based on the player's success in identifying and explaining mathematical concepts or flaws, The Judge delivers a verdict. Winning a case allows the player to level up and records key learnings. Losing a case (or running out of time) means the player stays at the current level.
  8. Learning Reinforcement: "My Learnings" section allows players to review mathematical concepts and flaw explanations from cases they've successfully won.
  9. Tutorial System: An interactive tutorial guides new players (Level 1) through the game's features.

The game aims to improve students' understanding of algebraic concepts, problem-solving skills, and logical reasoning in a fun, narrative-driven environment.

How we built it

Algebradiction is a web-based application built with a modern frontend stack and powered by AI:

  • Frontend Framework: React with TypeScript for a robust and type-safe user interface.
  • Styling: Tailwind CSS for rapid and responsive UI development, with custom global styles for theming (dark mode, glassmorphism, scrollbars) and specific component aesthetics.
  • AI Integration:
    • Google Gemini API:
      • gemini-2.5-flash-preview-04-17 model is used for:
        • Generating complex case data in JSON format, including mathematical problems, evidence descriptions (and SVG content for visuals), character dialogues, and flaw explanations.
        • Powering the in-game character (Prosecutor, Co-Counsel) responses through a chat-like interaction.
        • Analyzing player arguments and objections as The Judge, determining their mathematical validity and relevance.
    • Image generation with imagen-3.0-generate-002 is mentioned in constants and a service function, suggesting an intent for visual evidence generation, though its direct use in generateCaseData for content is primarily through SVG descriptions.
  • State Management: Primarily using React's built-in hooks (useState, useEffect, useCallback, useRef) to manage application state, game flow, and UI updates.
  • Routing/Screen Management: A custom state-based system (currentScreen in App.tsx) manages navigation between different parts of the game (Auth, Case Generation, Briefing, Courtroom, Verdict).
  • Persistence:
    • LocalStorage: Used extensively to store:
      • User accounts (username and a simple password hash for this version).
      • The last logged-in user.
      • User-specific progress: current level, completed tutorial steps, status of "all tutorials skipped."
      • Learnings acquired by the user.
      • Current topic index for each class (8, 9, 10) to ensure progressive learning through curriculum topics.
  • Component Structure: The application is broken down into reusable React components for different UI elements and game screens (e.g., Header, Courtroom, DialogueBox, EvidenceModal, AuthScreen, InteractiveTutorialHint).
  • Services: API interactions with Gemini are encapsulated in services/geminiService.ts.
  • Modularity: Code is organized into components, services, types, and constants for better maintainability.

Challenges we ran into

  1. Complex Prompt Engineering: Crafting precise and robust prompts for the Gemini API was crucial and likely challenging. This includes:
    • Ensuring consistent JSON output for dynamic case generation, especially with nested structures and specific requirements like SVG content for dark themes.
    • Guiding the AI to maintain character personalities (e.g., "Silly Prosecutor," "Super Helper," "The Judge") and provide contextually relevant dialogue.
    • Getting accurate mathematical analysis from the AI Judge for player arguments.
  2. Managing Asynchronous AI Calls: Integrating AI responses smoothly into the UI, handling loading states, and preventing race conditions or stale data would have been a focus.
  3. State Management Complexity: Orchestrating game state across various components (dialogue history, current speaker, modal visibility, timer, tutorial progression) with React hooks requires careful planning.
  4. Tutorial System Implementation: Creating a non-intrusive yet effective interactive tutorial system that tracks completion per user and handles various game states.
  5. Dynamic SVG Generation/Handling: The requirement for Gemini to generate valid, dark-theme-compatible SVGs within JSON is ambitious and error-prone. The fallback SVG indicates this was anticipated.
  6. Curriculum Progression Logic: Implementing the system to cycle through specific topics for Classes 8, 9, and 10 for each user correctly.
  7. Error Handling: Gracefully handling potential API errors from Gemini, API key issues, or unexpected AI responses.
  8. UI/UX for Engagement: Designing an interface that is both intuitive for a game and effective for learning mathematical concepts, especially within the courtroom metaphor.
  9. Balancing Difficulty: Ensuring the AI-generated cases and the Judge's evaluation provide a fair challenge that scales with player level without being overly frustrating or too easy.
  10. Timer and Tutorial Interaction: Pausing the game timer effectively when tutorials are active and resuming it correctly.

Accomplishments that we're proud of

  1. Innovative Educational Game Concept: Successfully merging a courtroom drama theme with mathematical problem-solving to create a unique learning experience.
  2. Deep Gemini API Integration: Leveraging Gemini for multiple core functionalities: dynamic content generation, character AI, and argument analysis.
  3. Personalized Learning Path: Implementing user accounts with persistent progress, including level progression and a "My Learnings" feature that tracks concepts from won cases.
  4. Structured Curriculum Delivery: The system for cycling through predefined math topics for Classes 8, 9, and 10 ensures a structured learning experience aligned with a curriculum.
  5. Interactive Tutorial System: Providing contextual hints and guidance for new players to ease them into the game mechanics.
  6. Dynamic and Engaging Dialogue: Creating a system where AI characters can respond dynamically to the game's situation and player inputs.
  7. Sophisticated Case Generation: The ability to generate varied and complex math cases on the fly, complete with flawed evidence and hints, tailored to player level and specific educational topics.
  8. Responsive and Thematic UI: Developing a visually appealing dark-themed interface with glassmorphic elements that fits the courtroom aesthetic.
  9. Robust (Client-Side) User Management: Implementing a functional login/signup system using LocalStorage for this iteration.

What we learned

  1. Power of LLMs in Education: How Large Language Models like Gemini can be used to create highly dynamic, interactive, and personalized educational content.
  2. Advanced Prompt Engineering: The nuances of designing effective prompts to elicit specific, structured (JSON), and role-consistent responses from an LLM.
  3. Managing Client-Side State: Techniques for managing complex application state in React, especially when dealing with asynchronous operations and multiple interconnected components.
  4. Importance of UI/UX in EdTech: How crucial intuitive design and engaging interactions are for educational games to be effective.
  5. Iterative Development with AI: The need for iterative testing and refinement when working with AI, as responses can be unpredictable initially.
  6. Client-Side Data Persistence Trade-offs: Understanding the capabilities and limitations of LocalStorage for user data and game state.
  7. Designing for Specific User Needs: Tailoring content (math problems, language) to specific educational levels (CBSE Classes 8-10).
  8. Component-Based Architecture: The benefits of a well-structured component hierarchy in React for building and maintaining a complex application.

What's next for Algebradiction

  1. Expanded Curriculum & Case Variety:
    • Add more mathematical topics and sub-topics for each class.
    • Introduce more diverse types of mathematical problems and case scenarios.
    • Incorporate more complex multi-step problems as player levels increase.
  2. Enhanced AI Interactions:
    • More nuanced AI personalities and responses from characters.
    • Allow players to cross-examine the Prosecutor or call witnesses (AI-driven).
    • More sophisticated feedback from the Judge on mathematical errors.
  3. Improved Evidence System:
    • Truly interactive evidence (e.g., manipulable graphs, sortable data tables).
    • Integrate the generateImageForEvidence service more directly to produce unique visual evidence beyond SVGs if feasible.
    • Allow players to combine or link pieces of evidence.
  4. Visual Proof Board: Instead of just text, allow players to visually organize their arguments, perhaps by dragging/dropping evidence snippets or drawing connections.
  5. Gamification & Engagement Features:
    • Achievements, badges, or a leaderboard system.
    • Unlockable character customizations or courtroom themes.
    • "Daily Challenge" cases.
  6. Teacher/Educator Dashboard: A separate interface for educators to track student progress, assign specific types of cases, or even create case templates.
  7. Backend Integration:
    • Move user authentication and data persistence to a secure backend database for better data integrity and scalability.
    • Potentially offload some complex AI interaction logic or case generation parameters to a backend.
  8. Accessibility Improvements: Further review and enhance accessibility features (ARIA attributes, keyboard navigation) to ensure the game is usable by a wider audience.
  9. User Feedback & Analytics: Implement mechanisms for collecting user feedback and basic analytics to understand how players interact with the game and identify areas for improvement.
  10. Multimedia Enhancements: Add sound effects, background music, and potentially simple character animations to increase immersion.

Built With

Share this project:

Updates