FinMon Evolution

The FinMon Evolution system is a dynamic reflection of your financial habits. Unlike traditional pet simulators where growth is purely time-based, FinMons evolve based on your real-world financial data, transaction frequency, and budget discipline.

The Growth Stages

Every FinMon follows a four-stage lifecycle. Each stage increases the FinMon’s complexity, visual presence, and the sophistication of its AI-driven advice.

| Stage | Class | Description | | :--- | :--- | :--- | | 1 | Egg | The starting point. Responds only with wiggles and short sounds. | | 2 | Baby | Species like Cashmander. Speaks in broken English and loves "shinies" (savings). | | 3 | Teen | Species like Wealthasaur. High-energy, uses slang, and begins offering more proactive advice. | | 4 | Master | Species like Ledgerazard. A legendary form with a wise, grand persona. |

Dynamic Evolution Engine

The system uses an AI-powered analysis engine to determine which form your FinMon takes. At key level milestones, the EvolutionScene is triggered, and the AI evaluates your UserState against specific behavioral archetypes.

Evolution Trigger Rules

Your financial behavior determines the species your FinMon will evolve into:

• SQUIRREL: Triggered by micro-saving habits. If you log more than five small savings transactions per month, your FinMon adapts to mirror this "stashing" behavior.
• HAWK: Triggered by aggressive growth. Requires high investment activity or debt repayment exceeding 15% of your total income.
• TORTOISE: Triggered by budget discipline. Awarded to trainers who remain within 5% of their set budget for three consecutive months.
• PHOENIX: Triggered by financial recovery. This rare form appears after a user clears a major debt or recovers from a long-term negative balance.

AI Persona & Mood

The FinMon's personality is shaped by the getFinMonPersona service, which adjusts its dialogue based on two primary factors:

1. Stage-Based Vocabulary: An Egg "wiggles," while a Master speaks with "grandeur."
2. Budget HP (Mood):
   • Happy: (HP > 50%) Energetic and encouraging dialogue.
   • Neutral: (HP 20% - 50%) Calm, observant dialogue.
   • Sad: (HP < 20%) Weak and hungry; the FinMon will actively plead for "financial healing" (budget corrections).

Data Structure: FinMonState

For developers or advanced users tracking state via the DevControl Panel, the FinMon is governed by the following interface:

export interface FinMonState {
  name: string;
  species: 'Coinlet' | 'Cashmander' | 'Wealthasaur' | 'Ledgerazard' | 'SQUIRREL' | 'HAWK' | 'TORTOISE' | 'PHOENIX';
  stage: 1 | 2 | 3 | 4; // 1=Egg, 2=Baby, 3=Teen, 4=Master
  mood: 'happy' | 'neutral' | 'sad';
}

Caring for your FinMon

Evolution progress is maintained through the Gamification Hub. To ensure your FinMon reaches Stage 4:

• Log Expenses: Increases XP and provides "sustenance."
• Consult Professor Ledger: Using the AI Budget Analysis grants a significant XP boost.
• Participate in Raids: Contributing "damage" (payments) to a Debt Boss (like the Student Loan Serpent) accelerates the evolution trigger check.