ProductionGame/PRODUCT_GENERATOR_GUIDE.md

# Plug-and-Play Production Unit & Sector Generator Guide

This guide describes how to add **5, 10, 50, or 100+** new production units, commodities, and industrial sectors to **Production: The Idle Game**.

The game uses a **Single-Source-of-Truth** architecture:
* Adding or modifying a sector file in `frontend/js/data/sectors/<sectorName>.js` **automatically** updates both the frontend UI and the Python authoritative simulation backend.
* You never need to touch engine code, database schemas, or calculation formulas!

---

## 1. Quick-Start: Adding a New Product to an Existing Sector

To add a new product to an existing sector (e.g. `frontend/js/data/sectors/chemicals.js`):

Simply copy and append this block to the sector's `PRODUCTS` array:

```javascript
{
    id: 'bio_fertilizer',                             // Unique snake_case string ID
    name: 'Bio-Organic Fertilizer',                   // User-facing commodity name
    sector: 'chemicals',                              // Parent sector ID ('agriculture', 'chemicals', etc.)
    tier: 2,                                          // Industrial Tier (1, 2, 3, 4+)
    icon: 'lucide:sprout',                            // Lucide or Iconify icon name
    color: '#10b981',                                 // Hex accent color
    unit: 'barrels',                                  // Measurement unit (e.g. 'bushels', 'ingots', 'crates')
    
    // DAG Supply Chain Inputs (Leave empty [] for raw extraction)
    inputs: [
        { id: 'sugar_beet', amount: 2 },
        { id: 'polymers', amount: 1 }
    ],
    outputAmount: 1,                                  // Yield per batch
    baseCycleTime: 3.2,                               // Raw cycle duration in seconds
    
    // Capital Investment & Economics
    unlockCost: 65000,                                // Cost to acquire the industrial permit
    unlockedDefault: false,                           // True only for starter tier 1 units
    baseFacilityCost: 45000,                          // Base line cost (scales exponentially by 1.15^lines)
    baseManagerCost: 110000,                          // Cost to hire automating Operations Lead
    baseLogisticsCost: 80000,                         // Cost to commission 1st wholesale logistics fleet
    basePrice: 95.00,                                 // Base wholesale market spot price
    
    // Immersive Corporate Metadata
    facilityName: 'Bio-Synthesis Complex',            // Name of the physical production building
    managerName: 'Bio-Process Engineer',              // Title of the facility operations lead
    logisticsName: 'Sealed Tanker Fleet',             // Name of the dedicated logistics fleet
    description: 'Eco-synthesized agricultural nutrients formulated from organic biomass.'
}
```

---

## 2. Quick-Start: Adding a Completely New Sector

To add a brand new industrial sector (e.g. `Biotechnology & Pharmaceuticals`):

### Step A: Create `frontend/js/data/sectors/biotech.js`
```javascript
// Sector: Biotechnology & Pharmaceuticals
export const BIOTECH_SECTOR = {
    id: 'biotech',
    name: 'Biotech & Pharma',
    icon: 'lucide:dna',
    color: '#8b5cf6',
    description: 'Advanced genomics, clinical pharmaceuticals, and synthetic biochemistry.'
};

export const BIOTECH_PRODUCTS = [
    {
        id: 'cell_culture',
        name: 'Cellular Cultures',
        sector: 'biotech',
        tier: 1,
        icon: 'lucide:microscope',
        color: '#a78bfa',
        unit: 'vials',
        inputs: [], // Raw bio-harvesting
        outputAmount: 1,
        baseCycleTime: 1.5,
        unlockCost: 50000,
        unlockedDefault: false,
        baseFacilityCost: 35000,
        baseManagerCost: 90000,
        baseLogisticsCost: 60000,
        basePrice: 65.00,
        facilityName: 'Bio-Incubator Lab',
        managerName: 'Chief Microbiologist',
        logisticsName: 'Cryo-Courier Unit',
        description: 'Living cell cultures cultivated in sterile bioreactor vessels.'
    },
    {
        id: 'synthetic_insulin',
        name: 'Synthetic Pharmaceuticals',
        sector: 'biotech',
        tier: 2,
        icon: 'lucide:pill',
        color: '#c084fc',
        unit: 'doses',
        inputs: [
            { id: 'cell_culture', amount: 2 },
            { id: 'refined_sugar', amount: 1 }
        ],
        outputAmount: 1,
        baseCycleTime: 3.5,
        unlockCost: 280000,
        unlockedDefault: false,
        baseFacilityCost: 220000,
        baseManagerCost: 450000,
        baseLogisticsCost: 320000,
        basePrice: 380.00,
        facilityName: 'Pharmaceutical Synthesis Line',
        managerName: 'Clinical Director',
        logisticsName: 'Cold-Chain Express',
        description: 'Purified medicinal formulations synthesized for global hospital networks.'
    }
];
```

### Step B: Register the Sector in `frontend/js/data/products.js`
Open `frontend/js/data/products.js` and add 2 lines:
```javascript
import { BIOTECH_SECTOR, BIOTECH_PRODUCTS } from './sectors/biotech.js';

export const SECTORS = [
    ...,
    BIOTECH_SECTOR
];

export const PRODUCTS = [
    ...,
    ...BIOTECH_PRODUCTS
];
```

---

## 3. Automated Verification Tool: `validate_dag.py`

Whenever you add new products or sectors, run the built-in integrity validator:

```bash
python backend/validate_dag.py
```

This validator checks:
1. **Acyclic Invariant:** Confirms there are zero circular dependency loops (e.g. A requires B, B requires A).
2. **Missing Reference Guard:** Confirms every `inputs[].id` exists in the catalog.
3. **Economic Balance Check:** Confirms that a product's output wholesale revenue exceeds the cost of its raw input materials.
4. **Tier Consistency:** Checks that products don't accidentally consume items from higher tiers.

---

## 4. Visual Asset Generation Prompt Recipe

For every product added, generate matching visuals and place them in the assets folders:
* **Product Specimen Photo:** `frontend/assets/images/products/{id}_product.jpg`
* **Facility Blueprint Photo:** `frontend/assets/images/facilities/{id}_facility.jpg`

### AI Image Generator Prompt Template:
> **Product Prompt:**  
> `Commercial studio macro photograph of {Product Name} ({Unit}). Isolated on a dark matte slate workbench, soft directional studio rim lighting, razor-sharp focus on material texture, hyper-detailed, Hasselblad H6D-100c 120mm macro lens, 8k.`
>
> **Facility Prompt:**  
> `Cinematic wide-angle architectural exterior photo of a high-tech {Facility Name}. Modern industrial engineering, stainless steel pipes, clean structural geometry, volumetric twilight lighting, subtle atmospheric steam, National Geographic documentary style, 35mm tilt-shift lens.`

*Note: If image files are not yet created, the game gracefully displays crisp SVG icons and styled placeholders without breaking!*