aether-shards/specs/Research.spec.md

Research Specification: The Ancient Archive

This document defines the UI and Logic for the Research Facility. This is the primary sink for Ancient Cores (Rare Currency) and provides global, permanent buffs to the campaign.

1. Context & Unlock

What is it?
A facility where the player studies recovered technology and magical theory to improve the efficiency of their operation. Unlike Class Mastery (which buffs specific units), Research buffs the player's infrastructure.
How is it unlocked?

• Requirement: Complete Story Mission 3 ("The Buried Library").
• Narrative Event: The player recovers a damaged "Archive Core" AI. Installing it in the Hub opens the Research tab.

2. Visual Design & Layout

Setting: A cluttered corner of the camp filled with glowing blue hologram projectors and piles of scrolls.

• Vibe: Intellectual, mystical, high-tech.

Layout:

• Header: "Ancient Archive". Displays Ancient Cores count (Large).
• Main View (The Tree): A horizontal scrolling view of 3 distinct "Tech Trees".
  1. Logistics (Green): Economic and Roster upgrades.
  2. Intelligence (Blue): Map and Enemy info upgrades.
  3. Field Ops (Red): Combat preparation and starting bonuses.
• Inspector Panel (Right):
  • Selected Node Name & Icon.
  • Description ("Increases Roster Size by 2").
  • Cost ("2 Ancient Cores").
  • Status ("Locked", "Available", "Researched").
  • Button: "RESEARCH".

3. The Tech Trees

A. Logistics (Economy & Management)

1. Expanded Barracks I: Roster Limit +2.
2. Bulk Contracts: Recruiting cost -10%.
3. Expanded Barracks II: Roster Limit +4.
4. Deep Pockets: Market Buyback slots +2.
5. Salvage Protocol: Sell prices at Market +10%.

B. Intelligence (Information Warfare)

1. Scout Drone: Reveals the biome type of Side Missions before accepting them.
2. Vital Sensors: Enemy Health Bars show exact numbers instead of just bars.
3. Threat Analysis: Reveals Enemy Types (e.g. "Mechanical") on the Mission Board dossier.
4. Map Data: Reveals the location of the Boss Room on the minimap at start of run.

C. Field Ops (Combat Prep)

1. Supply Drop: Start every run with 1 Free Potion in the shared stash.
2. Fast Deploy: First turn of combat grants +1 AP to all units.
3. Emergency Beacon: "Retreat" option becomes available (Escape with 50% loot retention instead of 0%).
4. Hardened Steel: All crafted/bought weapons start with +1 Damage.

4. TypeScript Interfaces

// src/types/Research.ts

export type ResearchTreeType = "LOGISTICS" | "INTEL" | "FIELD_OPS";

export interface ResearchNode {
  id: string; // e.g. "RES_LOGISTICS_01"
  name: string;
  description: string;
  tree: ResearchTreeType;
  tier: number; // Depth in the tree (1-5)

  cost: number; // Ancient Cores

  /** IDs of parent nodes that must be unlocked first */
  prerequisites: string[];

  /** The actual effect applied to the game state */
  effect: {
    type: "ROSTER_LIMIT" | "MARKET_DISCOUNT" | "STARTING_ITEM" | "UI_UNLOCK";
    value: number | string;
  };
}

export interface ResearchState {
  unlockedNodeIds: string[]; // List of IDs player has bought
  availableCores: number;
}

5. Conditions of Acceptance (CoA)

CoA 1: Dependency Logic

• A node cannot be researched unless all its prerequisites are in the unlockedNodeIds list.
• The UI must visually distinguish between Locked (Grey), Available (Lit), and Completed (Gold).

CoA 2: Currency Consumption

• Researching a node must deduct the exact Ancient Core cost from the global persistence.
• The action must fail if availableCores < cost.

CoA 3: Effect Application

• Passive: "Expanded Barracks" must immediately update the RosterManager.rosterLimit.
• Runtime: "Supply Drop" must trigger a check in GameLoop.startLevel to insert the item.