Asymmetric world modifiers: two starts that differ

World modifiers could only tilt both sides equally. A world may now carry an
`asym: { player, ai }` block that overrides a modifier for just ONE side, so the
two corners play as a real asymmetric matchup.

- map.js: sideMod(state, owner, key) resolves the owner's asym override, then the
shared modifier, then the default — so symmetric worlds and map-less test
stubs behave exactly as before. Movement (speed), fog (sight), combat (aggro
sight), production (build time), and gather (a new per-side gatherMult economy
edge) all read it with owner context.
- Two asymmetric worlds, telegraphed on the map card:
- Oort "Contested frontier": player banks 20% more per haul (rich claim); the
AI builds 18% faster (war factory). Out-mine vs out-build.
- Nimbus "Storm front": player sees almost normally (0.95) where the AI stays
half-blind (0.75), but the AI's units are 12% faster. Out-scout vs out-tempo.

Safe for the resolves-to-a-winner guarantee by construction: an AI-side edge
only helps it finish, and a player-side edge doesn't help a passive player — so
every world still resolves (verified). Symmetric worlds (e.g. Glacius) still
tilt both sides identically. Determinism holds.

New test asserts per-side application on the asym worlds and equal application on
the symmetric ones. 234 pass. README updated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEQUVetLk31Jj7niDQAsXL

README.md

@@ -34,6 +34,8 @@ A Refinery (built by a Worker, like the Barracks) researches army-wide upgrades
 
 Each world gives the AI a different temperament — Rusher (small economy, commits early), Economist (out-scales before attacking, expands and turtles behind turrets), or Balanced — and it plays the whole toolkit: it attacks in repeated waves, not just once (a fresh batch of units becomes the next wave once it's big enough or the timeout comes back around); it scouts, building the direct counter to whatever combat type the player fields most every third unit; and it expands when its home ore runs thin, fortifies the approach lane with turrets, runs multiple Barracks, and raises Habitats to stay under supply. Six of the nine worlds also carry a single rule modifier that applies to both sides — Glacius's ice slows everyone, Nimbus's storms shorten sight, Pyralis's open dunes lengthen it, Helix packs an extra crystal field, Oort's deposits run rich, and Forge's industry speeds construction — so where you fight changes how the fight plays, not just what you can build. Six of the nine worlds also carry **terrain**: rough ground you cross slower (Glacius's ice fields, Forge's industrial sprawl, and Oort's rugged flanks funnel armies through the open lanes) and high ground that sees farther and hits harder — Pyralis's central mesa, Helix's crystal ridge, and Nimbus's vantages (doubly worth taking on a storm-shortened world, since high ground extends sight) are real objectives to seize. Terrain is never impassable — it slows and shapes, it doesn't wall — and it's mirrored, so both sides face the same ground. You can't build on rough ground, so base and turret layout have to work around it. The three original worlds (Ferros, Korrath, Vesper) stay clean open plains.
 
+Two worlds are **asymmetric matchups** — the modifier hits the two sides *differently*, so which corner you start in defines your plan. On Oort ("Contested frontier") your claim struck a rich vein (your hauls bank 20% more) while the enemy's forward base is a war factory (18% faster construction) — you out-mine, they out-build. On Nimbus ("Storm front") the storm has half-cleared your side (you see almost normally where the enemy is half-blind) but the enemy surges fast out of the murk (12% quicker units) — you out-scout, they out-tempo. The card flags these, so you know the matchup before you commit.
+
 A minimap (bottom-left) shows the whole map at a glance — fog, resource deposits, and every unit/building you can currently see — and doubles as a camera shortcut: click anywhere on it to jump the main view there. An "Under Attack" banner (with its own alarm sound and a pulsing ping on both the main view and the minimap) fires when the AI hits something of yours, so a raid on an unwatched flank doesn't go unnoticed. Combat itself is legible at a glance too: a tracer flashes from attacker to target on every hit (colored by weapon type), and a brief ring marks a kill.
 
 Placing a building shows a live green/red footprint preview under the cursor before you click — invalid spots (off the map, overlapping another building, too close to a resource node) are rejected with no cost and no need to reselect. The selection panel shows what's queued at a selected Command Center or Barracks (with live progress on the in-progress job) and lets you cancel any queued unit for a full refund; selecting a group of units collapses the panel to one row per type ("12× Skiff — 84% hp") instead of one per unit.

engine/combat.js

@@ -19,7 +19,7 @@ import { stepToward } from "./movement.js";
 import { UNITS, BUILDINGS, UPGRADES } from "./entities.js";
 import { getEntity, removeEntity } from "./state.js";
 import { queryNeighbors } from "./grid.js";
-import { sampleTerrain } from "./map.js";
+import { sampleTerrain, sideMod } from "./map.js";
 
 export function updateCombat(state, unit, dt) {
   const def = UNITS[unit.type];
@@ -161,7 +161,7 @@ function isAlive(state, id) {
 function stillEngageable(state, unit, def, id) {
   const e = getEntity(state, id);
   if (!e || e.hp <= 0) return false;
-  const aggro = def.aggroRange * (state.map?.modifiers?.sightMult ?? 1);
+  const aggro = def.aggroRange * sideMod(state, unit.owner, "sightMult");
   return Math.hypot(e.x - unit.x, e.y - unit.y) <= aggro;
 }
 
@@ -218,7 +218,7 @@ function acquireTarget(state, unit, def) {
   // The same sight modifier that scales fog reveal also scales how far a unit
   // (or turret) reaches out to acquire — so a storm-shortened world bites both
   // sides' aggro symmetrically. Optional-chained for map-less test states.
-  const aggro = def.aggroRange * (state.map?.modifiers?.sightMult ?? 1);
+  const aggro = def.aggroRange * sideMod(state, unit.owner, "sightMult");
   // Units through the broad-phase grid (there can be hundreds); buildings stay a
   // straight scan since there are only ever a handful. Full-scan fallback when
   // no grid is present (direct combat tests).

engine/fog.js

@@ -17,7 +17,7 @@
 "use strict";
 
 import { UNITS, BUILDINGS } from "./entities.js";
-import { sampleTerrain } from "./map.js";
+import { sampleTerrain, sideMod } from "./map.js";
 
 export const FOG_CELL_SIZE = 40;
 
@@ -75,7 +75,7 @@ export function updateFog(state, fog, owner) {
   fog.visible.fill(0);
   // A world's sight modifier scales every reveal radius (see PLANET_MODIFIERS).
   // Optional-chained so the fog tests' map-less stubs read the default 1.
-  const sightMult = state.map?.modifiers?.sightMult ?? 1;
+  const sightMult = sideMod(state, owner, "sightMult");   // per-side on an asymmetric world (updateFog is already called per owner)
   // A source standing on high ground sees farther (terrain sightMult); OPEN and
   // the map-less test stubs read 1. One sample per source per tick.
   const terr = state.map?.terrain;

engine/gather.js

@@ -8,6 +8,7 @@
 
 import { stepToward } from "./movement.js";
 import { UNITS } from "./entities.js";
+import { sideMod } from "./map.js";
 
 const ORBIT_RADIUS = 16;   // workers ring the node instead of stacking on its exact center
 const ARRIVE_REACH = 4;
@@ -75,7 +76,10 @@ export function updateGather(state, unit, dt) {
     const dist = Math.hypot(drop.x - unit.x, drop.y - unit.y);
     if (dist <= DROP_REACH) {
       const player = state.players[unit.owner];
-      player.resources[unit.cargo.com] = (player.resources[unit.cargo.com] || 0) + unit.cargo.qty;
+      // Per-side economy modifier for an asymmetric world (default 1 elsewhere):
+      // a richer claim banks more per haul.
+      const banked = unit.cargo.qty * sideMod(state, unit.owner, "gatherMult", 1);
+      player.resources[unit.cargo.com] = (player.resources[unit.cargo.com] || 0) + banked;
       unit.cargo.qty = 0;
       order.phase = node.amount > 0 ? "toNode" : null;
       if (!order.phase) unit.order = null;

engine/map.js

@@ -80,6 +80,20 @@ function generateTerrain(width, height, specs) {
   return { cols, rows, cell: TERRAIN_CELL_SIZE, type };
 }
 
+// A world modifier as seen by ONE side. Most worlds tilt both sides equally
+// (a plain `modifiers[key]`), but a world may carry an `asym: { player, ai }`
+// block that overrides a key for just one owner — an asymmetric matchup where
+// the two starts differ. Lookup order: the owner's asym override, then the
+// shared modifier, then the default. Owner-less / map-less test stubs read the
+// shared value (or the default), so existing symmetric behaviour is unchanged.
+export function sideMod(state, owner, key, dflt = 1) {
+  const m = state && state.map && state.map.modifiers;
+  if (!m) return dflt;
+  const a = m.asym && m.asym[owner];
+  if (a && a[key] != null) return a[key];
+  return m[key] ?? dflt;
+}
+
 // The TERRAIN entry at a world point. Returns OPEN for a missing grid or an
 // out-of-bounds point, so every consumer degrades to "no terrain effect"
 // safely (map-less test stubs, off-map coords).
@@ -224,11 +238,15 @@ export const PLANET_MODIFIERS = {
     terrain: [[0.5, 0.13, 0.34, 0.2, 1, false], [0.5, 0.87, 0.34, 0.2, 1, false]],
   },
   nimbus:  {
-    sightMult: 0.75, label: "Storm bands: sight 25% shorter; two high vantages rise above the murk",
+    sightMult: 0.75, label: "Storm front (asymmetric): your skies are clearer; the enemy surges out of the murk",
     // On a short-sight world, high ground (which extends sight) is doubly worth
     // taking — a way to see over the storm. Two vantages, north and south of
     // the midline, kept off the centre so neither base overlooks the field.
     terrain: [[0.5, 0.28, 0.12, 0.14, 2, false], [0.5, 0.72, 0.12, 0.14, 2, false]],
+    // Asymmetric matchup: the storm has half-cleared YOUR side (you see almost
+    // normally, 0.95 vs the enemy's 0.75), but the enemy strikes fast out of it
+    // (units 12% quicker). You out-scout; they out-tempo.
+    asym: { player: { sightMult: 0.95 }, ai: { speedMult: 1.12 } },
   },
   pyralis: {
     sightMult: 1.15, label: "Open dunes: long sightlines, and a central mesa worth holding",
@@ -243,10 +261,14 @@ export const PLANET_MODIFIERS = {
     terrain: [[0.5, 0.5, 0.1, 0.38, 2, false]],
   },
   oort:    {
-    nodeAmountMult: 1.3, label: "Rich frontier: deposits hold 30% more, but rugged ground breaks up the flanks",
+    nodeAmountMult: 1.3, label: "Contested frontier (asymmetric): your claim is richer; the enemy's foundry runs hotter",
     // Rugged rough ground on the flanks funnels the fight through the open
     // centre — the price of the world's rich but broken frontier.
     terrain: [[0.4, 0.28, 0.12, 0.18, 1, true], [0.4, 0.72, 0.12, 0.18, 1, true]],
+    // Asymmetric matchup: YOUR claim struck a rich vein (every haul banks 20%
+    // more), while the enemy's forward base is a war factory (18% faster
+    // construction and production). You out-mine; they out-build.
+    asym: { player: { gatherMult: 1.2 }, ai: { buildTimeMult: 0.82 } },
   },
   forge:   {
     buildTimeMult: 0.85, label: "Factory world: 15% faster construction; rough industrial sprawl midfield",

engine/movement.js

@@ -18,7 +18,7 @@
 
 import { UNITS } from "./entities.js";
 import { queryNeighbors } from "./grid.js";
-import { sampleTerrain } from "./map.js";
+import { sampleTerrain, sideMod } from "./map.js";
 
 const AVOID_RANGE = 30;     // how far out a unit senses neighbors to steer around, beyond their combined radii
 const AVOID_WEIGHT = 1.6;   // how strongly a sensed neighbor bends the seek direction
@@ -53,7 +53,7 @@ export function stepToward(state, unit, tx, ty, speed, dt) {
   // slow-down only (rough ground), never zero, so a unit always makes forward
   // progress — nothing can be trapped. Optional-chained so map-less test stubs
   // read the default 1; `allTerrain` on a def opts a unit out (forward-compat).
-  const speedMult = state.map?.modifiers?.speedMult ?? 1;
+  const speedMult = sideMod(state, unit.owner, "speedMult");
   const def = UNITS[unit.type];
   const terrainMult = state.map?.terrain && !(def && def.allTerrain)
     ? sampleTerrain(state.map.terrain, unit.x, unit.y).speedMult : 1;

engine/production.js

@@ -7,6 +7,7 @@
 import { BUILDINGS, UNITS, UPGRADES, canAfford, payCost, prereqsMet, committedDoctrine } from "./entities.js";
 import { makeUnit } from "./state.js";
 import { supplyUsed, supplyCap } from "./supply.js";
+import { sideMod } from "./map.js";
 
 // How close a worker has to stand to actually count as building, not just
 // walking over. Shared with sim.js's arrival check for the 'build' order.
@@ -38,9 +39,9 @@ export function updateBuildingConstruction(state, building, dt) {
     building.hp = def.hp;
     return;
   }
-  // A world's build-time modifier speeds (or slows) construction; optional-
-  // chained so production tests' map-less states read the default 1.
-  const bt = def.buildTime * (state.map?.modifiers?.buildTimeMult ?? 1);
+  // A world's build-time modifier speeds (or slows) construction; per-side on an
+  // asymmetric world (sideMod reads the default 1 for map-less test states).
+  const bt = def.buildTime * sideMod(state, building.owner, "buildTimeMult");
   // The founding worker alone still builds at the original pace even if
   // it wanders off or dies — extra workers on-site are a bonus, not a
   // requirement.
@@ -65,9 +66,9 @@ export function updateProductionQueue(state, building, dt) {
   if (building.constructing || building.queue.length === 0) return;
   const job = building.queue[0];
   const def = UNITS[job.unitType];
-  // Same build-time modifier applies to unit production (a factory world
-  // trains faster too); optional-chained for map-less test states.
-  const bt = def.buildTime * (state.map?.modifiers?.buildTimeMult ?? 1);
+  // Same build-time modifier applies to unit production (a factory world trains
+  // faster too), per-side on an asymmetric world.
+  const bt = def.buildTime * sideMod(state, building.owner, "buildTimeMult");
   job.progress += dt / bt;
   if (job.progress >= 1) {
     building.queue.shift();

test/map.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { generateMap, MAP_WIDTH, MAP_HEIGHT, PLANET_MODIFIERS } from "../engine/map.js";
+import { generateMap, MAP_WIDTH, MAP_HEIGHT, PLANET_MODIFIERS, sideMod } from "../engine/map.js";
 import { PLANET_ARCHETYPE } from "../engine/aiArchetypes.js";
 import { PLANETS } from "../data.js";
 
@@ -102,6 +102,25 @@ test("generateMap is deterministic: the same planet and rng seed reproduce the s
   assert.deepEqual(a.nodes, b.nodes);
 });
 
+test("asymmetric worlds apply per-side modifiers; symmetric worlds tilt both sides equally", () => {
+  const oort = { map: generateMap("oort", () => 0.5) };
+  assert.equal(sideMod(oort, "player", "gatherMult"), 1.2, "the player's richer claim banks more");
+  assert.equal(sideMod(oort, "ai", "gatherMult", 1), 1, "the enemy gets no gather bonus");
+  assert.equal(sideMod(oort, "ai", "buildTimeMult"), 0.82, "the enemy's factory builds faster");
+  assert.equal(sideMod(oort, "player", "buildTimeMult"), 1, "the player builds at the normal rate");
+
+  const nimbus = { map: generateMap("nimbus", () => 0.5) };
+  assert.equal(sideMod(nimbus, "player", "sightMult"), 0.95, "the player sees through the thinning storm");
+  assert.equal(sideMod(nimbus, "ai", "sightMult"), 0.75, "the enemy stays in the murk (the world's shared value)");
+  assert.equal(sideMod(nimbus, "ai", "speedMult"), 1.12, "but the enemy strikes faster out of it");
+
+  // A symmetric world tilts both sides equally, and an unmodified one is neutral.
+  const glacius = { map: generateMap("glacius", () => 0.5) };
+  assert.equal(sideMod(glacius, "player", "speedMult"), sideMod(glacius, "ai", "speedMult"), "glacius slows both sides the same");
+  const ferros = { map: generateMap("ferros", () => 0.5) };
+  assert.equal(sideMod(ferros, "player", "speedMult"), 1, "ferros has no modifier -> default");
+});
+
 test("generateMap attaches the planet's modifiers (empty for the unmodified worlds)", () => {
   assert.deepEqual(generateMap("ferros", () => 0.5).modifiers, {}, "ferros carries no modifiers");
   assert.equal(generateMap("glacius", () => 0.5).modifiers.speedMult, 0.9, "glacius slows every unit");