Skip to content

Roadmap

Ultimate goal (AGENTS.md): parse Victoria 3 game data into structured formats, simulate the economy mechanics, and provide a tool for optimising production chains.

Project foundation & parsing layer

  • Initial scaffolding:
  • uv toolchain
  • pyproject.toml
  • MkDocs Material docs
  • GitHub Actions CI
  • examples/ scripts
  • tests/ suite
  • Core parsers:
  • common/buildings
  • common/building_groups
  • common/goods
  • common/production_methods
  • common/production_method_groups
  • common/technology
  • common/buy_packages
  • common/pop_needs
  • map_data/state_regions.
  • parse_merge utility: UTF-8-SIG read, ?=/!= neutralisation, multi-file merge into a pyradox.Tree.
  • get_vic3_directory() auto-detection across Steam library paths on Windows / Linux / macOS.

Production optimisation (LP-based)

  • ProductionUnit, production_table() for production-chain modelling.
  • Economy, EconomyState for general-equilibrium economy modelling.
  • NominalOptimizer for scipy.optimize.linprog optimisation over building levels with named objectives, throughput bonuses, and fluent constraint builders.
  • Architecture refactor: Scenario is immutable configuration data; public sibling NominalOptimizer and MarketOptimizer classes inherit shared context and constraint compilation from BaseOptimizer. Their inspectable LinearProblem / MarketProblem objects keep formulation, solving, dual lookup, and optimizer-backed analysis consistent.

Documentation & agent infrastructure

  • MkDocs Material site with auto-generated API reference (mkdocstrings) and usage/parse.md, usage/analysis.md guides.
  • AGENTS.md agent instructions with external file-loading protocol.
  • docs/project_structure.md per-folder map.

Vanilla sync cadence

  • Adapted parsed CSV snapshots to vanilla versions (historical releases):
  • 1.13.1
  • 1.13.8
  • 1.13.9
  • 1.13.11

General-equilibrium economy model

  • Implement the Economy class as a solver state for iterative equilibrium computation.
  • Implement the solver method for nominal price
  • Implement the solver method with market price mechanics
  • Implement MarketOptimizer for bounded endogenous-price GDP and GDP-per-capita scenarios
  • Implement EquilibriumOptimizer for bounded building-level searches maximizing GDP, GDP per capita, or average wealth, with endogenous household demand and verified equilibrium states
  • Implement SupplyChainEquilibriumOptimizer for fixed-recipe chain-level searches with transformed constraints and verified building equilibria
  • Implement the solver method with population composition and wealth levels

Supply chain analysis (nominal)

The nominal supply-chain toolkit is implemented as the analysis/supply_chain/ package and deliberately analyzes one terminal good per solve.

  • Scenario dataclass (now in optimize/scenario.py): an optimisation recipe as data (goods-balance floor and fixed import/export orders, objective, banned PMs / buildings / building groups, per-building level caps, throughput multipliers, era / construction-cost / employment caps, minimum net infrastructure surplus, urban-center tie).
  • SupplyChainAnalyzer validates positive terminal exports and an enabled balance floor, then performs exactly one nominal solve.
  • Immutable SupplyChainResult snapshots matrices, state arrays, production metadata, graphs, and solver diagnostics.
  • Cyclic bipartite NetworkX graphs provide realized and scenario-static allowed views without treating cycle cutoffs as raw resources.
  • Stable DataFrame reports cover goods, processes, flows, workforce, constraints, bottlenecks, and alternative producers.
  • Process-level coproduct attribution is exact; no implicit good-level allocation policy is applied.
  • Mermaid and Matplotlib renderers return in-memory objects and prune large allowed views deterministically.
  • sweep_supply_chains() sets minimum base-price export targets for all producible goods, retains economy order, and records failures while continuing sequentially.
  • Synthetic tests cover cycles, coproducts, alternatives, imports, resources, throughput bonuses, infeasible/unbounded cases, stable schemas, visualization objects, and sweeps without requiring a game installation.

Pop consumption & wealth loop

  • Integrate buy_packages (per-wealth pop-need baskets), pop_needs (per-need goods baskets), and pop_types (per-profession wealth) into the economy model so demand reflects population composition and wealth levels rather than exogenous inputs.

State-region resource constraints

  • Use StateRegionsParser total-potential resource_* columns to cap building levels for resource-limited buildings (gold, oil, iron, ...) in NominalOptimizer.