## Overview
The simulation uses a **three-tier configuration system**:
- **Tier 1: World** - Global constraints outside Canada's control
- **Tier 2: Administration** - Multi-year government policy (4-5 year term)
- **Tier 3: Year** - Fiscal year-specific values
Later tiers override earlier ones. Access via `GameConfigService::get('path.to.value')`.
---
## Tier 1: World Variables (`world.yml`)
### International Monetary System
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| IMF SDR Rate | `international.imf_sdr_rate` | float | IMF Special Drawing Rights rate |
| US Federal Funds Rate | `international.us_federal_funds_rate` | float | US Federal Reserve rate |
| ECB Deposit Rate | `international.ecb_deposit_rate` | float | European Central Bank rate |
| BoE Bank Rate | `international.boe_bank_rate` | float | Bank of England rate |
### Sovereign Risk Spreads
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| AAA Rated | `international.sovereign_risk_spreads.aaa_rated` | float | Spread for AAA-rated debt |
| AA Rated | `international.sovereign_risk_spreads.aa_rated` | float | Spread for AA-rated debt |
| A Rated | `international.sovereign_risk_spreads.a_rated` | float | Spread for A-rated debt |
| BBB Rated | `international.sovereign_risk_spreads.bbb_rated` | float | Spread for BBB-rated debt |
### Global Commodity Prices (CAD)
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| WTI Crude Oil | `commodities.oil_wti_barrel` | float | WTI crude per barrel |
| Brent Crude Oil | `commodities.oil_brent_barrel` | float | Brent crude per barrel |
| Natural Gas | `commodities.natural_gas_mmbtu` | float | Natural gas per MMBtu |
| Gold | `commodities.gold_oz` | float | Gold per troy ounce |
| Lumber | `commodities.lumber_mbf` | float | Lumber per thousand board feet |
| Wheat | `commodities.wheat_bushel` | float | Wheat per bushel |
| Potash | `commodities.potash_tonne` | float | Potash per tonne |
| Copper | `commodities.copper_lb` | float | Copper per pound |
| Uranium | `commodities.uranium_lb` | float | Uranium per pound |
### Currency Environment
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| USD Strength Index | `currency_environment.usd_strength_index` | float | DXY index |
| CAD Pressure | `currency_environment.cad_pressure` | string | weak/neutral/strong |
| Trade Weighted Index | `currency_environment.trade_weighted_index` | float | Trade-weighted index |
### Global Trade Conditions
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| WTO Tariff Environment | `trade.wto_tariff_environment` | string | normal/elevated/trade_war |
| CUSMA Status | `trade.cusma_status` | string | active/renegotiation/suspended |
| Softwood Lumber Dispute | `trade.softwood_lumber_dispute` | bool | Active dispute flag |
| Supply Chain Stress | `trade.supply_chain_stress` | string | low/moderate/high/critical |
### Global Inflation Context
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| US CPI | `global_inflation.us_cpi` | float | US Consumer Price Index |
| Eurozone HICP | `global_inflation.eurozone_hicp` | float | Eurozone inflation |
| UK CPI | `global_inflation.uk_cpi` | float | UK Consumer Price Index |
| China CPI | `global_inflation.china_cpi` | float | China Consumer Price Index |
| Global Average | `global_inflation.global_average` | float | Global average inflation |
### Geopolitical Risk
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| Stability Index | `geopolitical.global_stability_index` | int | 0-100, higher = more stable |
| Energy Security Risk | `geopolitical.energy_security_risk` | string | low/moderate/high/critical |
| Trade Bloc Tensions | `geopolitical.trade_bloc_tensions` | string | normal/elevated/high |
---
## Game Mechanics (in `world.yml`)
### Staffing Ratios
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| Default Staff per Manager | `mechanics.staffing.ratios.default.staff_per_manager` | int | Default ratio (5) |
| Defence Staff per Manager | `mechanics.staffing.ratios.defence.staff_per_manager` | int | Defence ratio (8) |
| Regulatory Staff per Manager | `mechanics.staffing.ratios.regulatory.staff_per_manager` | int | Regulatory ratio (4) |
| Healthcare Staff per Manager | `mechanics.staffing.ratios.healthcare.staff_per_manager` | int | Healthcare ratio (6) |
| Technology Staff per Manager | `mechanics.staffing.ratios.technology.staff_per_manager` | int | Tech ratio (5) |
### Staffing Cascade Rules
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| Staff to Manager Threshold | `mechanics.staffing.cascade_rules.staff_to_manager_threshold` | int | Staff needed per manager |
| Manager to Director Threshold | `mechanics.staffing.cascade_rules.manager_to_director_threshold` | int | Managers needed per director |
| Director to ADM Threshold | `mechanics.staffing.cascade_rules.director_to_adm_threshold` | int | Directors needed per ADM |
### Classification Pay Ranges
| Level | Path | Min Salary | Max Salary |
|-------|------|------------|------------|
| Staff | `mechanics.staffing.classification_levels[0]` | $55,000 | $95,000 |
| Manager | `mechanics.staffing.classification_levels[1]` | $85,000 | $130,000 |
| Director | `mechanics.staffing.classification_levels[2]` | $115,000 | $165,000 |
| Executive | `mechanics.staffing.classification_levels[3]` | $145,000 | $250,000 |
### Budget Cost Allocation
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| Personnel | `mechanics.budget.cost_allocation.personnel` | float | 60% to salaries/benefits |
| Operations | `mechanics.budget.cost_allocation.operations` | float | 25% to operations |
| Transfers | `mechanics.budget.cost_allocation.transfers` | float | 10% to grants/transfers |
| Capital | `mechanics.budget.cost_allocation.capital` | float | 5% to capital projects |
| Reference FTE Cost | `mechanics.budget.reference_fte_cost` | int | $120,000 fully-loaded |
### Proposal & Voting Mechanics
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| Supermajority Threshold | `mechanics.proposals.supermajority_threshold` | float | 67% for major changes |
| Major Change Threshold | `mechanics.proposals.major_change_threshold` | float | % budget change requiring supermajority |
| Minimum Support | `mechanics.proposals.minimum_support_threshold` | float | 10% to advance from team |
| Amendment Limit | `mechanics.proposals.amendment_limit` | int | Max amendments per proposal |
### Cycle Phases
| Phase | Duration | Activities |
|-------|----------|------------|
| Consultation | 14 days | team_formation, research, initial_proposals |
| Deliberation | 21 days | amendments, debate, coalition_building |
| Voting | 7 days | final_vote, results |
| Implementation | 7 days | simulation_update, reflection |
---
## Tier 2: Administration Variables (`administration_2023-2027.yml`)
### Administration Info
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| Name | `administration.name` | string | "44th Canadian Ministry" |
| Governing Party | `administration.governing_party` | string | Current party |
| Term Start | `administration.term_start` | date | Start of term |
| Term End | `administration.term_end` | date | Expected end |
### Capital Expenditure Plan
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| Total Commitment | `capital_plan.total_commitment_billions` | float | Multi-year total ($188B) |
| Plan Duration | `capital_plan.plan_duration_years` | int | Years covered (5) |
#### Priority Areas (Housing, Clean Energy, Transit, Healthcare, Digital)
| Variable | Path | Type |
|----------|------|------|
| Allocation Percent | `capital_plan.priority_areas.{area}.allocation_percent` | float |
| Multi-Year Commitment | `capital_plan.priority_areas.{area}.multi_year_commitment_billions` | float |
| Departments | `capital_plan.priority_areas.{area}.departments` | array |
| Key Initiatives | `capital_plan.priority_areas.{area}.key_initiatives` | array |
### Fiscal Targets
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| Debt-to-GDP Trajectory | `fiscal_targets.debt_to_gdp_trajectory.{year}` | float | Target by year |
| Deficit Reduction Path | `fiscal_targets.deficit_reduction_path.{year}` | float | Deficit target by year |
| Debt Service Ceiling | `fiscal_targets.debt_service_ceiling_percent` | float | Max % of revenue (12%) |
### Major Program Commitments
Programs: `pharmacare`, `dental_care`, `childcare`, `indigenous_reconciliation`, `climate_action`
| Variable | Path | Type |
|----------|------|------|
| Status | `program_commitments.{program}.status` | string |
| Annual Cost | `program_commitments.{program}.annual_cost_billions` | float |
| Start Year | `program_commitments.{program}.start_year` | int |
### Defence Commitments
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| NATO Target | `defence.nato_spending_target_percent` | float | 2.0% target |
| Achievement Year | `defence.nato_achievement_year` | int | 2032 |
| Spending Trajectory | `defence.spending_trajectory.{year}` | float | % of GDP by year |
### Tax Policy Direction
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| Corporate Rate | `tax_policy.corporate_rate` | float | 15.0% |
| Top Marginal Rate | `tax_policy.personal_income.top_marginal_rate` | float | 33.0% |
| Top Bracket | `tax_policy.personal_income.top_bracket_threshold` | int | $235,675 |
| Capital Gains Inclusion | `tax_policy.capital_gains_inclusion_rate` | float | 0.6667 (2/3) |
| Carbon Price | `tax_policy.carbon_price_trajectory.{year}` | int | $/tonne by year |
### Transfer Payments
| Variable | Path | Type |
|----------|------|------|
| CHT Growth Rate | `transfers.canada_health_transfer.base_growth_rate` | float |
| CST Amount | `transfers.canada_social_transfer.annual_amount_billions` | float |
| Equalization Amount | `transfers.equalization.annual_amount_billions` | float |
---
## Tier 3: Year Variables (`2025.yml`)
### Exchange Rates
| Variable | Path | Type |
|----------|------|------|
| USD/CAD | `economic.exchange_rates.usd_cad` | float |
| EUR/CAD | `economic.exchange_rates.eur_cad` | float |
| GBP/CAD | `economic.exchange_rates.gbp_cad` | float |
| JPY/CAD | `economic.exchange_rates.jpy_cad` | float |
| CNY/CAD | `economic.exchange_rates.cny_cad` | float |
### Interest Rates
| Variable | Path | Type | Description |
|----------|------|------|-------------|
| BoC Overnight | `economic.interest_rates.boc_overnight` | float | Bank of Canada rate |
| Prime Rate | `economic.interest_rates.boc_prime` | float | Prime lending rate |
| 10Y Gov Bond | `economic.interest_rates.government_10y_yield` | float | 10-year yield |
| 2Y Gov Bond | `economic.interest_rates.government_2y_yield` | float | 2-year yield |
| 5Y Mortgage | `economic.interest_rates.mortgage_5y_fixed` | float | Average 5-year fixed |
### Inflation
| Variable | Path | Type |
|----------|------|------|
| Annual CPI | `economic.inflation.cpi_annual` | float |
| Core Inflation | `economic.inflation.core_inflation` | float |
| Food Inflation | `economic.inflation.food_inflation` | float |
| Shelter Inflation | `economic.inflation.shelter_inflation` | float |
### GDP
| Variable | Path | Type |
|----------|------|------|
| Nominal (Billions) | `economic.gdp.nominal_billions` | float |
| Real Growth | `economic.gdp.real_growth_percent` | float |
| Per Capita | `economic.gdp.per_capita` | int |
| GDP Deflator | `economic.gdp.gdp_deflator` | float |
### Employment
| Variable | Path | Type |
|----------|------|------|
| Unemployment Rate | `economic.employment.unemployment_rate` | float |
| Participation Rate | `economic.employment.participation_rate` | float |
| Employment Growth | `economic.employment.employment_growth` | float |
### Federal Budget
| Variable | Path | Type |
|----------|------|------|
| Total Expenditure | `budget.total_expenditure_billions` | float |
| Total Revenue | `budget.total_revenue_billions` | float |
| Projected Deficit | `budget.projected_deficit_billions` | float |
### Revenue Breakdown
| Variable | Path | Type |
|----------|------|------|
| Personal Income Tax | `budget.revenue_breakdown.personal_income_tax` | float |
| Corporate Income Tax | `budget.revenue_breakdown.corporate_income_tax` | float |
| GST | `budget.revenue_breakdown.gst` | float |
| EI Premiums | `budget.revenue_breakdown.ei_premiums` | float |
### Department Allocations
| Department | Main Estimates Path | Capital Path |
|------------|---------------------|--------------|
| National Defence | `budget.department_allocations.national_defence.main_estimates_billions` | `.capital_allocation_billions` |
| Health Transfers | `budget.department_allocations.health_transfers.cht_billions` | N/A |
| Infrastructure | `budget.department_allocations.infrastructure.capital_plan_year3_billions` | `.housing_accelerator_billions` |
| Indigenous Services | `budget.department_allocations.indigenous_services.main_estimates_billions` | `.water_infrastructure_billions` |
| Environment | `budget.department_allocations.environment.main_estimates_billions` | `.climate_action_billions` |
| Innovation/Science | `budget.department_allocations.innovation_science.main_estimates_billions` | `.research_grants_billions` |
| Global Affairs | `budget.department_allocations.global_affairs.main_estimates_billions` | `.development_assistance_billions` |
| Public Safety | `budget.department_allocations.public_safety.main_estimates_billions` | `.rcmp_billions` |
### Pay Scales
| Variable | Path | Type |
|----------|------|------|
| COLA Percent | `pay_scales.cola_percent` | float |
| Retroactive To | `pay_scales.retroactive_to` | date |
### Game State
| Variable | Path | Type |
|----------|------|------|
| Current Cycle | `game_state.current_cycle` | int |
| Cycle Phase | `game_state.cycle_phase` | string |
| Active Proposals | `game_state.active_proposals` | int |
| Pending Votes | `game_state.pending_votes` | int |
| Total Schools | `game_state.school_participation.total_schools` | int |
| Active Students | `game_state.school_participation.active_students` | int |
| Teams Formed | `game_state.school_participation.teams_formed` | int |
---
## Pay Scale Classifications (PayScaleService)
### Economics & Social Science (EC)
| Code | Label | Salary | Total Cost |
|------|-------|--------|------------|
| EC-01 | Junior Economist | $62,000 | $77,500 |
| EC-02 | Intermediate | $71,000 | $88,750 |
| EC-03 | Intermediate | $79,000 | $98,750 |
| EC-04 | Senior | $88,000 | $110,000 |
| EC-05 | Team Lead | $96,000 | $120,000 |
| EC-06 | Manager/Director | $108,000 | $135,000 |
| EC-07 | Senior Director | $122,000 | $152,500 |
| EC-08 | Executive Director | $140,000 | $175,000 |
### Information Technology (IT)
| Code | Label | Salary | Total Cost |
|------|-------|--------|------------|
| IT-01 | Technician | $60,000 | $75,000 |
| IT-02 | Systems Analyst | $75,000 | $93,750 |
| IT-03 | Senior Analyst | $92,000 | $115,000 |
| IT-04 | IT Manager | $108,000 | $135,000 |
| IT-05 | Director, IT | $125,000 | $156,250 |
### Executive Group (EX)
| Code | Label | Salary | Total Cost |
|------|-------|--------|------------|
| EX-01 | Director | $130,000 | $162,500 |
| EX-02 | Executive Director | $150,000 | $187,500 |
| EX-03 | Director General | $175,000 | $218,750 |
| EX-04 | Assistant Deputy Minister | $210,000 | $262,500 |
| EX-05 | Deputy Minister | $280,000 | $350,000 |
*(Additional classifications: PM, AS, FI, EG, SE-RES, GL, PG, IS, WP - see PayScaleService)*
---
## Geographic Weighting (GeographicWeightingService)
### Default Weights
| Variable | Value | Description |
|----------|-------|-------------|
| federal_all | 1.0 | All Canadians equal on federal matters |
| provincial_resident | 1.0 | Full weight for province residents |
| provincial_adjacent | 0.5 | Adjacent province weight |
| provincial_same_region | 0.3 | Same region weight |
| provincial_distant | 0.1 | Distant province weight |
| municipal_resident | 1.0 | Full weight for municipality residents |
| municipal_same_province | 0.3 | Same province weight |
| municipal_other_province | 0.1 | Other province weight |
### Provincial Adjacencies
```
BC: [AB, YT, NT]
AB: [BC, SK, NT]
SK: [AB, MB, NT, NU]
MB: [SK, ON, NU]
ON: [MB, QC]
QC: [ON, NB, NL]
NB: [QC, NS, PE]
NS: [NB, PE]
PE: [NB, NS]
NL: [QC]
YT: [BC, NT]
NT: [BC, AB, SK, YT, NU]
NU: [SK, MB, NT]
```
### Regional Groupings
| Region | Provinces |
|--------|-----------|
| West | BC, AB, SK, MB |
| Central | ON, QC |
| Atlantic | NB, NS, PE, NL |
| North | YT, NT, NU |
---
## Correlation Engine Computed Values
The `CorrelationEngine` calculates these derived metrics:
| Metric | Description |
|--------|-------------|
| `debt_service` | Debt service as % of revenue, ceiling check |
| `capital_space` | Remaining capital expenditure room |
| `currency_exposure` | USD-denominated spending impact |
| `inflation_pressure` | Imported inflation vs domestic |
| `trade_impact` | Tariff and trade environment effects |
| `program_viability` | Funding status of major programs |
| `fiscal_health` | Composite health score (0-100) |
| `staffing_impact` | FTE implications of budget changes |
---
## Usage Examples
```php
// Get merged config for current fiscal year
$config = \Drupal::service('ducklings_game_config.config')->getMergedConfig();
// Get specific value with dot notation
$usdCad = \Drupal::service('ducklings_game_config.config')->get('economic.exchange_rates.usd_cad');
// Get staffing ratios
$ratios = \Drupal::service('ducklings_game_config.config')->getStaffingRatios('defence');
// Calculate all correlation impacts
$impacts = \Drupal::service('ducklings_game_config.correlation_engine')->calculateImpacts();
```
---
*Generated: 2026-01-02*