InvestPlay/specs/06-gamification-and-simulation-spec.md

06 Gamification & Simulation Spec — InvestPlay

Overview

Gamification in InvestPlay is designed to build healthy financial habits, not to simulate the dopamine loops of retail day-trading apps. The gamification mechanics and simulation engines reward consistency, risk management, critical thinking, and curriculum completion.

This document details the core gamification loops, the types of interactive mini-games, and the mechanics of the "Blind Scenario" simulation engine designed to eliminate hindsight bias.

1. Core Gamification Mechanics

XP and Leveling

• Earning XP: Students earn Experience Points (XP) for completing lessons, passing quizzes, maintaining daily login streaks, and completing interactive challenges.
• Leveling Up: Accumulating XP increases the user's overall Level. In B2C (self-guided) mode, reaching specific levels unlocks advanced modules (e.g., Level 10 unlocks "Macroeconomics").
• Consistency Over Spikes: XP payouts heavily favor consistency. Logging in and completing one 5-minute lesson a day for 5 days yields more XP than completing five lessons in a single 25-minute binge.

Badges & Achievements

Badges are permanent profile unlocks that celebrate specific educational milestones or behavioral victories during simulations.

• The Diversifier: Maintained a portfolio with at least 3 different asset classes for a full simulation.
• Crash Survivor: Held through a 20% market drop without panic-selling in a blind scenario.
• Debt Destroyer: Successfully paid off the simulated credit card debt in the "Debt Snowball" mini-game.
• The Skeptic: Successfully identified and ignored a "Hype Trap" (scam event) during a simulation.

2. Interactive Challenges & Mini-Games

Instead of relying solely on standard quizzes, lessons incorporate interactive, React/Phaser.js-based mini-games.

• The 50/30/20 Salary Drop: A drag-and-drop budgeting game where users must allocate a virtual €1,500 monthly paycheck into "Needs," "Wants," and "Savings" envelopes while unexpected life events (e.g., "Car breakdown: €200") disrupt their plans.
• The Debt Snowball: Users are given a simulated €5,000 credit card balance. They must allocate their monthly budget to pay it off, experiencing firsthand how minimum payments extend the debt lifespan vs. aggressive repayment.
• The Hype Trap (Anti-Finfluencer): A narrative-driven challenge where simulated "social media feeds" urge the user to buy a trending asset. The user must analyze the underlying metrics and choose whether to buy the hype or ignore it.

3. The "Blind Scenario" Simulation Engine

To solve the "Hindsight Bias" problem inherent in stock market games (where students know Apple will succeed and Enron will fail), InvestPlay uses Blind Scenarios.

The Mechanic

1. The Context Drop: The simulation starts by giving macroeconomic context without revealing the year or the asset. (e.g., "A global supply chain crisis is occurring. Inflation is rising. You are analyzing a manufacturing company...")
2. The Fast-Forward Play: Using historical CSV data (e.g., Yahoo Finance OHLCV), the NestJS backend streams market ticks (1 tick = 1 week of real time). The frontend chart draws dynamically. The asset is labeled only as COMPANY-X.
3. Injected News: The backend injects anonymized news headlines at specific ticks to simulate the real-world information environment.
4. The Reveal: Once the simulation ends, the UI overlays the real-world dates, the actual company logo, and the true timeline. The AI Coach provides a summary of why the asset behaved the way it did.

Procedural / Synthetic Markets (Infinite Replayability)

In addition to historical data, the engine supports Synthetic Data. An algorithm generates fake OHLC chart data based on defined volatility and trend parameters. Because the asset never existed, it is mathematically impossible for students to cheat, making it perfect for high-stakes classroom assignments.

4. Anti-Cheat Mechanisms

For classroom environments, integrity is critical.

• Data Obfuscation: During a Blind Scenario, the real ticker symbol and actual date timestamps are stripped from the WebSocket payload before being sent to the client. They are stored only in Redis on the backend until the session is explicitly marked as ENDED.
• No API Peeking: Because historical data is served from the InvestPlay backend (not fetched client-side from third-party APIs), tech-savvy students cannot inspect network requests to discover the asset.
• Time-Bounded Actions: During live classroom simulations, students have strict time windows (e.g., 30 seconds per tick) to execute trades. The backend rejects any orders stamped outside this window, preventing users from waiting to see what happens before acting.