# Egg Inc.: Path of Virtue API Context

This document provides critical context for AI agents analyzing data from the custom Egg Inc. Virtue API. It explains the core mechanics of the game's endgame "Path of Virtue," defines the API's JSON schema, and explains how to parse the game's mathematical shorthand notation.

## 1. Core Concepts: The Path of Virtue
Egg Inc. is an incremental idle game about building massive egg-laying farm empires. The "Path of Virtue" is a highly advanced, endgame mechanic that unlocks only after a player achieves the arduous goal of laying 100 Trillion "Enlightenment" eggs.

When a player "ascends" to the Path of Virtue, the game fundamentally changes:
*   **Five Eggs of Virtue:** Instead of linear progression, the Path consists of five specific eggs: **Curiosity**, **Kindness**, **Integrity**, **Humility**, and **Resilience**.
*   **Shifting:** Players must strategically "shift" (swap) between these five eggs to upgrade different aspects of their farm (habs, vehicles, research, etc.). Shifting costs **Soul Eggs (SE)**, and the cost increases cubically. Advancements carry over between shifts, but farm population and cash are reset.
*   **Massive Constraints:** Standard boosts are disabled (except for the 2x video ad multiplier). The player's standard massive Earning Bonus is effectively reset. 
*   **Path Artifacts:** Standard artifacts and spaceships are locked. Players must collect and equip specialized artifacts that only function on the Path of Virtue.
*   **Eggs of Truth (TE):** Instead of standard Soul Eggs, prestiging on the Path of Virtue grants "Eggs of Truth", awarded based on the cumulative amount of Eggs of Virtue delivered (`eovDelivered`). TEs provide a massive boost to in-house hatchery rates and earnings while on the Path.

## 2. Fetching Player Data: The API Payload Dictionary

To fetch real-time player data, make a `GET` request to the `/player-info` endpoint with the `eid` parameter containing the player's Egg Inc. ID (e.g., `/player-info?eid=EI1234567890123456`).

The resulting JSON maps directly to the player's progression.

### Virtue Tracking
*   `truthEggs`: An array `[C, K, I, H, R]` representing the collected Eggs of Truth for Curiosity, Kindness, Integrity, Humility, and Resilience respectively.
*   `truthEggsPending`: Array representing Truth Eggs that will be awarded upon next prestige.
*   `eovDelivered`: Array representing the cumulative raw Eggs of Virtue delivered (which calculates pending TEs).
*   `clothedTE`: "Clothed Truth Eggs" - The Effective Truth Egg count adjusted for currently equipped artifacts (e.g., using Lunar Totems or Demeter's Necklaces) and Epic Research. This is the primary metric to compare player progress.
*   `maxClothedTE`: The highest possible `clothedTE` attainable if the player were to equip their mathematically optimal artifacts.
*   `totalShifts`: Total number of times the player has shifted eggs.
*   `nextShiftSE`: The Soul Egg cost to perform the next shift.

### Farm Logistics & Economics
*   `population.totalHabSpace`: The maximum chicken capacity of all built Habitats.
*   `logistics.offlineIHRPerMinute`: Offline Internal Hatchery Rate (chickens hatched per minute while the app is closed).
*   `logistics.currentELRPerSecond`: Current Egg Laying Rate per second.
*   `logistics.shippingCapacityPerSecond`: Maximum number of eggs vehicles can transport per second. If `currentELRPerSecond` hits this bound, shipments are bottlenecked.
*   `earnings.farmerRole`: Community classification title based on `earningBonus`.
*   `earnings.maxRCB`: Maximum Running Chicken Bonus multiplier.
*   `earnings.earningRates`: Calculates actual cash earned per second. `activeBaselinePerSecond` assumes no running chickens, `activeMaxRCBPerSecond` assumes maximum running chickens, and `offlinePerSecond` assumes the app is closed.

### Artifacts Array
*   `artifacts.equipped`: The Artifacts currently active on the home farm.
*   `artifacts.optimal`: The mathematical ideal artifact loadout the player *should* be wearing to maximize their `maxClothedTE`.

## 3. POV Costs and Requirements

To fetch the costs and requirements for various aspects of the Path of Virtue (silos, rockets, houses, shipping, research, and TE requirements), make a `GET` request to the `/pov-costs` endpoint. This returns a markdown document with the relevant tables.

## 4. Order of Magnitude (OOM) Shorthand Notation

Because numbers in Egg Inc. grow astronomically large, the API returns formatted strings utilizing alphabetical suffixes instead of raw scientific notation (unless `&raw=true` is appended to the API request). 

To parse strings like `"1.830o"` or `"455.963S"` for strict mathematical evaluation, extract the suffix and multiply the base number by $10^{Magnitude}$.

**Suffix Map Dictionary:**
```json
{
  "K": 3,   // Thousand (10^3)
  "M": 6,   // Million (10^6)
  "B": 9,   // Billion (10^9)
  "T": 12,  // Trillion (10^12)
  "q": 15,  // Quadrillion (10^15)
  "Q": 18,  // Quintillion (10^18)
  "s": 21,  // Sextillion (10^21)
  "S": 24,  // Septillion (10^24)
  "o": 27,  // Octillion (10^27)
  "N": 30,  // Nonillion (10^30)
  "d": 33,  // Decillion (10^33)
  "U": 36,  // Undecillion (10^36)
  "D": 39,  // Duodecillion (10^39)
  "Td": 42, // Tredecillion (10^42)
  "qd": 45, // Quattuordecillion (10^45)
  "Qd": 48, // Quindecillion (10^48)
  "sd": 51, // Sexdecillion (10^51)
  "Sd": 54, // Septendecillion (10^54)
  "Od": 57, // Octodecillion (10^57)
  "Nd": 60, // Novemdecillion (10^60)
  "V": 63,  // Vigintillion (10^63)
  "uV": 66, // Unvigintillion (10^66)
  "dV": 69, // Duovigintillion (10^69)
  "tV": 72, // Trevigintillion (10^72)
  "qV": 75, // Quattuorvigintillion (10^75)
  "QV": 78, // Quinvigintillion (10^78)
  "sV": 81, // Sexvigintillion (10^81)
  "SV": 84, // Septenvigintillion (10^84)
  "OV": 87, // Octovigintillion (10^87)
  "NV": 90, // Novemvigintillion (10^90)
  "tT": 93  // Trigintillion (10^93)
}
```

*Example:* `"28.343S"` = $28.343 \times 10^{24}$ = `2.8343e+25`
*Note: Suffixes are strictly case-sensitive (`s` is sextillion, `S` is septillion).*