Battle-for-Tismo/docs/simple_economy/03-construction.md

03 — Construction: immediate start, energy-driven speed

Depends on: 01-, 02-.

Goal

In the simple economy, building starts immediately and its construction speed is proportional to the energy available in the region, with modifiers. Every region must start with one power plant.

Current behaviour (hard economy)

• requestBuild / requestTrain (shared/game_state/orders.js) pay the money cost, reserve a material budget, push a queue entry in the "materials" phase, and gather steel/high-tech over days via _gatherBuildEntry before "construction" begins.
• Construction time is gated and scaled off GDP: ECONOMY.productionCapacity(this.getPlayerGdp(civ)) and ECONOMY.buildingHours(gdp, cost) in shared/data/economy.js, times constructionApprovalMultiplier(city) and constructionSpeedMultiplier(civ).
• Tile improvements become construction sites (shared/game_state/sites.js): _openConstructionSite, _tickConstructionSites, phases materials then construction, buying energy day by day (_buySiteEnergy).
• Starting cities/buildings are laid out in scenario.js (_seedStartingBuildings) and the generated world in shared/game_state/world.js.

Target behaviour

• No materials phase in simple mode. An order enters the construction/ training phase immediately. If a material bill exists, draw it from the player's pool at order time (02-), or make simple-mode builds cost no materials. Recommendation: draw from the pool up front, so ordering still consumes resources and cannot be spammed, but there is no multi-day gather and no stall.
• Construction capacity comes from regional energy, not GDP. Define a region energy figure — e.g. regionAvailableEnergy(city) = the connected region's power production that is not already committed — and make the build speed proportional to it. Keep the existing shape: totalHours = base * speedMultiplier, where base is a cost/energy ratio and the multiplier folds in approval and the existing technology/modifier bonus (constructionSpeedMultiplier, EFFECT_CONSTRUCTION_SPEED).
  • Put the tuning constants (energyPerConstructionHour, a minimum speed floor, and how energy maps to hours) in the simple-economy data module.
  • Define what happens when a region has no power: a guaranteed baseline construction power stands in for the grid, so the work is never free, never instant and never slower than the reference target (modern infantry in 45 game hours). Spare power above the baseline only makes a work quicker, and the floor avoids a divide-by-zero and a hard lock.
• Every region starts with one power plant. Seed one working plant per city region in the simple scenario so regions open with energy and the speed rule has a non-zero basis.
  • Decide the plant type and placement. Recommendation: one of the fuel-free/renewable plants (e.g. solar_power_plant or wind_turbines) on a valid land tile owned by the region, chosen deterministically, so no fuel resource is implied. Ensure the tile passes the existing resource-building placement rules and is connected.
• Public upgrades. Production-building upgrades (industry.js) are public works in simple mode and follow the same immediate, energy-driven rule.
• Remove the GDP capacity gate (productionCapacity) from simple-mode construction and training. GDP may still be computed for display only.

Files

• shared/game_state/orders.js — requestBuild, requestTrain, requestBuildImprovement, _pendingBuildingLevels.
• shared/game_state/sites.js — _openConstructionSite, _kickoffSite, _tickConstructionSites, _gatherSiteMaterials, _gatherBuildEntry, _buySiteEnergy, _siteForecastBudget. In simple mode a site should open already in "construction" and skip the gather/energy-buy phases.
• shared/game_state/industry.js — _startBuildingUpgrade, _buyBuilding Materials, _tickBuildingDecisions.
• shared/game_state/economy.js — constructionSpeedMultiplier, and a new energy-based equivalent; getPlayerGdp stays for display.
• shared/game_state/simple_economy.js — the overrides.
• shared/game_state/scenario.js / world.js — the starting plant per region.
• shared/data/economy.js or new simple data module — construction constants.
• tests/construction_site_test.js, tests/industry_test.js — extend for simple mode; or a new tests/simple_construction_test.js.

Acceptance criteria

• In simple mode, ordering a building raises it on the hourly tick with no "materials" phase and no _nearbySuppliers/trade-graph lookups.
• Construction time scales with the region's available energy: spare power above the guaranteed baseline shortens the clock, while a region at or below the baseline (including a powerless one) is held at the reference time -- never slower, never instantaneous.
• Every starting region has at least one working power plant in simple mode.
• Hard economy construction is untouched.

Notes / decisions

• What "available energy" means. Options: (a) the region grid's uncommitted power, (b) the region's gross plant output, (c) a per-region energy balance already computed in the daily resource tick. Define one and use it on both the server and (for display) the client. Do not read a value that only exists mid-tick elsewhere.
• Concurrency. Hard mode lets one queue line run at a time. Decide whether simple mode keeps one line per city or lets every queued item build in parallel off the same energy pool. Recommendation: keep one line, scaled by energy, to preserve the queue UI.
• Money. 05-money-and-taxes.md says money is not spent internally in the simple economy; if that is accepted, the _spendBudget calls here must be dropped in simple mode.