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:

{
    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

// 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:

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:

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!