🌌 Quantum Odyssey: The Arithmetic Saga

An epic, terminal-based math RPG — with AI-powered infinite adventures, ASCII scene art, and full bilingual support.

---

What Is This?

Quantum Odyssey is a story-driven, RPG-style math game that runs entirely in your terminal. You play as a Numerist — a math hero tasked with defeating Lord Miscalculus, who has stolen the Great Equations and thrown the Numeriverse into chaos.

The game features:

• A full story campaign (Chapter 1: The Arithmos Plains) with 5 zones, NPC dialogue, combat, and a final boss
• 7 unique minigames (Math Sprint, Rocket Launch, Bridge Builder, and more)
• An AI-powered infinite quest mode that generates endless story adventures + math challenges on any theme you choose
• Full Indonesian / English bilingual support that switches every UI string and all AI prompts
• ASCII art scene reveals, animated character portraits, and enemy flash effects — all in the terminal
• A built-in offline story engine so the AI quest works beautifully even without an API key

---

Screenshots (Terminal)

╔══════════════════════════════════════════════════════════╗
║  ☀️   ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·   ☀️  ║
║                                                          ║
║      ∿∿∿∿          ②+③=?         ∿∿∿∿∿                  ║
║                                                          ║
║   🌿🌿🌿  🌸  🌿🌿    ✦  🌿🌿🌿  🌸  🌿🌿🌿               ║
║   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓              ║
║   ░░ The Awakening Meadow ░░  Glowing Math Glyphs Float... ║
╚══════════════════════════════════════════════════════════╝

  (\  /)
  ( o.o )   Professor Figaro
 _( > < )_   Red Fox · Arithmos Scholar
 /  🔭  [ ]/
(___||___|___)

  [Professor Figaro]: "Greetings, young traveler! I am Professor Figaro."

---

Features

🗡️ Story Campaign

• 5 handcrafted zones per chapter, each with its own environment, NPCs, and narrative puzzles
• Live character portraits in ASCII art for every major character (Professor Figaro, Mayor Tally, Miner Max, Oracle Sera, Lord Miscalculus, and more)
• Animated scene reveals — zones wipe in line-by-line like a cinematic pan
• Layered weather ambients — sunshine, lightning storms, cave stalactites, starfields, neon grids
• 3-phase boss battle against Lord Miscalculus, with escalating difficulty and HP
• Combat system with skill-based damage modifiers and a Logic Shield mechanic

🌌 AI Infinite Quest

• Describe any adventure theme (e.g. "a starship escaping a black hole", "a wizard climbing a dragon tower", "a cyber-hacker infiltrating a neon megacorp")
• Gemini AI generates story rooms, NPC dialogue, and custom math puzzles tailored to your chosen difficulty
• Offline fallback: if no API key is configured, the built-in narrative engine provides 20+ hand-written rooms across 4 themed worlds (Space, Dungeon, Cyber, Wizard) in both languages — the game never goes blank
• Room banners escalate dramatically as you go deeper (🌅 Room 1 → 💀 Room 5 → 👑 Room 7)
• Persistent story history: your choices in earlier rooms influence future AI prompts

🎮 7 Minigames

Minigame	Description
🏃 Math Sprint	Answer as many problems as you can in 60 seconds. Streak combos up to 5× multiplier
🚀 Rocket Launch	Solve problems to fuel a rocket stage-by-stage and reach orbit
🏗️ Bridge Builder	Choose correct answers to place structural segments
🥷 Number Ninja	Rapid-fire problems in a ninja-training style
🎵 Pattern DJ	Identify the missing number in sequences
⭐ Star Collector	Navigate a path by solving arithmetic gates
💎 Treasure Chest	Riddle-based puzzles unlock chests of gold

📚 Math Material (12 Topics)

The game supports randomised, curriculum-appropriate problems across:

Topic	Examples
Arithmetic	Mental math, word problems, estimation
Pre-Algebra	Expressions, order of operations
Algebra	Linear equations, quadratics, systems
Number Theory	Primes, GCD/LCM, divisibility
Geometry	Area, perimeter, angles, triangles
Probability & Statistics	Mean, median, probability fractions
Calculus	Derivatives, integrals (Advanced+)
Trigonometry	Sin/cos/tan, identities
Matrix & Linear Algebra	Matrix ops, determinants
Discrete Mathematics	Combinations, logic, sequences
Mixed	All of the above, randomly selected

Difficulty scales from Beginner → Intermediate → Advanced → Expert → Master → Olympiad/Insane.

🌐 Bilingual Support (EN / ID)

• Switch between English and Indonesian in Settings — takes effect immediately, no restart needed
• All menu labels, HUD text, NPC dialogue templates, and AI quest prompts switch language
• The Gemini AI is prompted to respond entirely in the chosen language

🔑 Secure API Key Handling

• Your Gemini API key is stored in saves/config.json only on your local machine
• It is never committed to git (protected by .gitignore)
• Alternatively, set the GEMINI_API_KEY environment variable — the game reads it automatically with priority over the file

🏆 Achievements & Progression

• 20 achievements with XP rewards
• 4-skill tree: Mental Math, Logic Shield, Hint Oracle, Quick Calc
• Gold shop with potions and upgrades
• Daily play streak tracking
• Save/load with 3 slots + export/import Base64 save codes (portable across devices)

---

Requirements

• Python 3.10 or higher (uses match, | type unions)
• No third-party packages required — pure standard library
• A terminal that supports ANSI escape codes (Linux, macOS, Windows Terminal)
• (Optional) A free Google Gemini API key for the AI quest mode

---

Getting Started

🚀 Option A: Install as a global CLI tool (Recommended)

You can install the game directly from GitHub and run it from anywhere in your terminal:

pip install git+https://github.com/Axzo001/MathGame.git

💡 On Modern Linux (PEP 668 "externally-managed-environment" error): If your system blocks global installations, you can safely install it via pipx:

pipx install git+https://github.com/Axzo001/MathGame.git

Or install it using the system override flag (which is completely safe here as this project has zero external dependencies):

pip install --break-system-packages git+https://github.com/Axzo001/MathGame.git

Once installed, play the game simply by running:

quantum-odyssey

Note: In this mode, your configurations and game saves are stored safely inside your user home directory at ~/.quantum-odyssey/.

---

💻 Option B: Run locally from source

If you want to run it from the cloned repository:

1. Clone the repository:

   git clone https://github.com/Axzo001/MathGame.git
   cd MathGame

2. Configure your API Key: Copy the example config:

   cp saves/config.example.json saves/config.json

   Open saves/config.json and fill in your Gemini API key:

   {
       "gemini_api_key": "YOUR_API_KEY_HERE",
       "gemini_model": "gemini-1.5-flash",
       "language": "en",
       "math_material": "Mixed",
       "target_level": "Middle School",
       "ai_difficulty": "intermediate"
   }

3. Run the game:

   python -m quantum_odyssey

---

Project Structure

MathGame/
│
├── pyproject.toml             # Build system & CLI entrypoint configuration
├── LICENSE                    # MIT License
├── README.md                  # Project documentation
│
├── saves/                     # Local developer saves (git-ignored)
│   └── config.example.json    # Example configuration file
│
└── quantum_odyssey/           # Package directory
    ├── __init__.py            # Package initialization
    ├── __main__.py            # CLI entry point runner
    ├── main.py                # Main menu and loop orchestrator
    │
    ├── engine/                # Core game systems
    │   ├── display.py         # ANSI colors, typewriter, ASCII art renderer
    │   ├── game_state.py      # Player state, save/load, XP/level system
    │   ├── input_handler.py   # Arrow-key menus, answer validation, stats viewer
    │   ├── ai_engine.py       # Gemini API connection, query packaging
    │   ├── translation.py     # EN/ID translation with cached config I/O
    │   ├── scene_art.py       # ASCII art library (zones, characters, weather)
    │   ├── progression.py     # Achievements, skill tree, score bonuses
    │   ├── combat.py          # Battle system, enemy stats, turn logic
    │   └── sound.py           # Sound effects via system audio (optional)
    │
    ├── story/                 # Narrative content
    │   ├── chapter1_arithmos.py  # Chapter 1: 5 zones + boss (full story)
    │   ├── story_manager.py   # Shop, events, hub, minigame arcade, rewards
    │   ├── ai_quest.py        # AI infinite quest orchestrator
    │   └── offline_narrative.py  # Built-in story rooms (works without API key)
    │
    ├── puzzles/               # Math puzzle generation
    │   ├── puzzle_factory.py  # Procedural puzzle factory (all topics + difficulties)
    │   └── ...
    │
    ├── minigames/             # 7 standalone minigames
    │   ├── math_sprint.py
    │   ├── rocket_launch.py
    │   ├── bridge_builder.py
    │   └── ...
    │
    ├── data/                  # Static data files
    │   ├── achievements.json
    │   └── shop_items.json
    │
    └── sounds/                # Optional WAV sound effects

---

Configuring Settings In-Game

You can change all settings without touching any files directly. From the main menu, select ⚙️ Settings & Gemini AI:

Setting	Options
Language	English / Indonesian
Math Material	11 topics or Mixed
Grade Level	Elementary / Middle / High School / University+Olympiad
AI Difficulty	Beginner → Olympiad/Insane
API Key	Enter and test your Gemini key
Model	Switch between Gemini model versions

---

Contributing

Pull requests are welcome! A few notes:

• Keep the zero external dependencies design — standard library only
• All user-facing strings should be wrapped in tr() from engine/translation.py
• Add new math topics to puzzles/puzzle_factory.py and engine/translation.py
• New story chapters go in story/ and should follow the zone function pattern in chapter1_arithmos.py
• New scene art goes in engine/scene_art.py under _SCENES or _CHARACTERS

---

License

MIT License — see LICENSE for details.

---

Made with ❤️ and lots of math.
May your combo streak never break.