Merge PR #25: Add three-level campaign progression

Add Flooded Relay and Overgrown Archive with permanent sequential unlocks

Author: mcvalosborne

README.md

@@ -6,7 +6,7 @@ An explorable pixel-art micro-world rendered entirely in the browser. Walk throu
 
 ## Controls
 
-First-time players receive a short mission briefing. Reopen it at any time with the `?` control.
+First-time players receive a short mission briefing for the active zone. Reopen it at any time with the `?` control, or use the `L1`/`L2`/`L3` control to change unlocked zones.
 
 | Action | Input |
 | --- | --- |
@@ -23,6 +23,10 @@ The current mobile experience supports tap-to-move. A dedicated touch action con
 - Grid-based movement and click-to-move pathfinding
 - A radial scan that reveals character identities
 - A three-part signal recovery quest with resident hints and daily challenge codes
+- A three-level campaign with permanent sequential unlocks:
+  - **River Factory:** scan for three hidden signal carriers
+  - **Flooded Relay:** activate control banks to open floodgates between platforms
+  - **Overgrown Archive:** follow resident clues and restore memories in the daily sequence
 - Persistent progress, a discovery journal, replay, and completion sharing
 - Optional sound, haptic feedback, touch controls, and reduced-motion support
 - No runtime framework, backend, or asset bundle

index.html

@@ -94,8 +94,8 @@
     });
   }
 
-  function completionText(challengeCode) {
-    return `I restored the Little Android factory (${challengeCode}). Explore it at https://littleandroid.com`;
+  function completionText(challengeCode, levelName = 'factory') {
+    return `I restored the Little Android ${levelName.toLowerCase()} (${challengeCode}). Explore it at https://littleandroid.com`;
   }
 
   return Object.freeze({

src/engagement.js

@@ -21,5 +21,86 @@
     dog: Object.freeze({ active: 'HAPPY STATIC. WARM TRAIL. GOOD TRAIL.', complete: 'FACTORY GOOD. YOU GOOD.' }),
   });
 
-  return Object.freeze({ SIGNAL_FRAGMENTS, NPC_DIALOGUE });
+  const LEVELS = Object.freeze([
+    Object.freeze({
+      id: 'river-factory',
+      number: 1,
+      name: 'RIVER FACTORY',
+      mode: 'scan',
+      seed: 77,
+      spawn: Object.freeze({ x: 4, y: 6, facing: 'south' }),
+      objectiveLabel: 'SIGNALS',
+      completeLabel: 'FACTORY ONLINE',
+      briefing: 'Three signal carriers are dark. Explore the river factory, scan for their locations, and recover all three.',
+      objectives: SIGNAL_FRAGMENTS,
+      gates: Object.freeze([]),
+      sign: Object.freeze({ x: 2, y: 3, width: 6, active: 'ROBOTS', complete: 'ONLINE' }),
+      npcs: Object.freeze([
+        Object.freeze({ type: 'worker', x: 3, y: 4, facing: 'south', label: 'UNIT-47' }),
+        Object.freeze({ type: 'worker', x: 6, y: 4, facing: 'east', label: 'UNIT-12' }),
+        Object.freeze({ type: 'scout', x: 8, y: 8, facing: 'south', label: 'RECON-3', patrol: Object.freeze([{x:8,y:8,f:'south'},{x:12,y:8,f:'east'},{x:12,y:6,f:'north'},{x:8,y:6,f:'west'}]) }),
+        Object.freeze({ type: 'elder', x: 5, y: 3, facing: 'south', label: 'OVERSEER' }),
+        Object.freeze({ type: 'farmer', x: 3, y: 14, facing: 'south', label: 'OLD DALE' }),
+        Object.freeze({ type: 'mechanic', x: 9, y: 5, facing: 'north', label: 'SPARKS' }),
+        Object.freeze({ type: 'child', x: 6, y: 12, facing: 'south', label: 'LIL BIT' }),
+        Object.freeze({ type: 'dog', x: 7, y: 11, facing: 'east', label: 'GOOD BOY' }),
+      ]),
+    }),
+    Object.freeze({
+      id: 'flooded-relay',
+      number: 2,
+      name: 'FLOODED RELAY',
+      mode: 'gates',
+      spawn: Object.freeze({ x: 3, y: 10, facing: 'east' }),
+      objectiveLabel: 'RELAYS',
+      completeLabel: 'CURRENT ROUTED',
+      briefing: 'The relay platforms are isolated. Activate each control bank to open the next floodgate and route current across the water.',
+      objectives: Object.freeze([
+        Object.freeze({ id: 'intake-relay', name: 'INTAKE RELAY', x: 5, y: 6, visible: true }),
+        Object.freeze({ id: 'spillway-relay', name: 'SPILLWAY RELAY', x: 12, y: 14, visible: true }),
+        Object.freeze({ id: 'tower-relay', name: 'TOWER RELAY', x: 20, y: 6, visible: true }),
+      ]),
+      gates: Object.freeze([
+        Object.freeze({ x: 8, y: 10, after: 'intake-relay' }),
+        Object.freeze({ x: 16, y: 10, after: 'spillway-relay' }),
+      ]),
+      sign: Object.freeze({ x: 9, y: 7, width: 7, active: 'RELAY', complete: 'ROUTED' }),
+      npcs: Object.freeze([
+        Object.freeze({ type: 'mechanic', x: 3, y: 6, facing: 'east', label: 'VALVE' }),
+        Object.freeze({ type: 'worker', x: 11, y: 5, facing: 'south', label: 'PUMP-8' }),
+        Object.freeze({ type: 'scout', x: 18, y: 13, facing: 'north', label: 'WADER', patrol: Object.freeze([{x:18,y:13,f:'north'},{x:21,y:13,f:'east'},{x:21,y:9,f:'north'},{x:18,y:9,f:'west'}]) }),
+      ]),
+    }),
+    Object.freeze({
+      id: 'overgrown-archive',
+      number: 3,
+      name: 'OVERGROWN ARCHIVE',
+      mode: 'sequence',
+      seed: 191,
+      spawn: Object.freeze({ x: 3, y: 10, facing: 'north' }),
+      objectiveLabel: 'MEMORY',
+      completeLabel: 'ARCHIVE AWAKE',
+      briefing: 'The archive terminals answer only in sequence. Speak with its residents, follow the current clue, and wake all three memories.',
+      objectives: Object.freeze([
+        Object.freeze({ id: 'root-index', name: 'ROOT INDEX', x: 4, y: 5, visible: true, clue: 'WEST WING · ABOVE THE OLD STONE' }),
+        Object.freeze({ id: 'moss-ledger', name: 'MOSS LEDGER', x: 12, y: 6, visible: true, clue: 'CENTRAL COURT · NORTH OF THE BROKEN WALL' }),
+        Object.freeze({ id: 'canopy-memory', name: 'CANOPY MEMORY', x: 20, y: 15, visible: true, clue: 'EAST GROVE · BELOW THE LAST ARCH' }),
+      ]),
+      gates: Object.freeze([]),
+      sign: Object.freeze({ x: 9, y: 9, width: 7, active: 'ARCHIVE', complete: 'AWAKE' }),
+      npcs: Object.freeze([
+        Object.freeze({ type: 'elder', x: 5, y: 10, facing: 'west', label: 'CURATOR', clue: true }),
+        Object.freeze({ type: 'farmer', x: 11, y: 12, facing: 'north', label: 'GROUNDSKEEP', clue: true }),
+        Object.freeze({ type: 'scout', x: 19, y: 8, facing: 'south', label: 'INDEXER', clue: true, patrol: Object.freeze([{x:19,y:8,f:'south'},{x:21,y:8,f:'east'},{x:21,y:12,f:'south'},{x:19,y:12,f:'west'}]) }),
+      ]),
+    }),
+  ]);
+
+  const LEVEL_IDS = Object.freeze(LEVELS.map(level => level.id));
+
+  function getLevel(levelId) {
+    return LEVELS.find(level => level.id === levelId) || LEVELS[0];
+  }
+
+  return Object.freeze({ SIGNAL_FRAGMENTS, NPC_DIALOGUE, LEVELS, LEVEL_IDS, getLevel });
 });

src/game-content.js

@@ -108,6 +108,74 @@
     return { width, height, map };
   }
 
+  function createFloodedRelayMap() {
+    const width = 24;
+    const height = 20;
+    const map = Array.from({ length: height }, () => Array(width).fill(5));
+
+    const carvePlatform = (x1, y1, x2, y2, tile) => {
+      for (let y = y1; y <= y2; y++) {
+        for (let x = x1; x <= x2; x++) map[y][x] = tile;
+      }
+    };
+    carvePlatform(1, 3, 7, 16, 2);
+    carvePlatform(9, 2, 15, 17, 10);
+    carvePlatform(17, 3, 22, 16, 2);
+
+    for (const x of [7, 8, 9, 15, 16, 17]) map[10][x] = 12;
+    map[10][8] = 18;
+    map[10][16] = 18;
+
+    for (const [x, y] of [[2, 4], [6, 15], [10, 3], [14, 16], [18, 4], [21, 15]]) {
+      map[y][x] = 15;
+    }
+    for (const [x, y] of [[3, 8], [12, 8], [20, 12]]) map[y][x] = 10;
+
+    return { width, height, map };
+  }
+
+  function createOvergrownArchiveMap(seed = 191) {
+    const width = 24;
+    const height = 20;
+    const map = Array.from({ length: height }, () => Array(width).fill(0));
+    const random = mulberry32(seed);
+
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        if (random() < 0.38) map[y][x] = 1;
+      }
+    }
+    for (let x = 0; x < width; x++) {
+      map[0][x] = 14;
+      map[height - 1][x] = 14;
+    }
+    for (let y = 0; y < height; y++) {
+      map[y][0] = 14;
+      map[y][width - 1] = 14;
+    }
+
+    for (let y = 1; y <= 14; y++) map[y][8] = 8;
+    for (const y of [5, 11]) map[y][8] = 2;
+    for (let y = 5; y <= 18; y++) map[y][16] = 8;
+    for (const y of [9, 15]) map[y][16] = 2;
+    for (let x = 8; x <= 16; x++) map[9][x] = 9;
+    map[9][12] = 2;
+
+    for (const [x, y] of [[3, 2], [6, 3], [3, 15], [6, 17], [11, 2], [14, 4], [11, 14], [14, 17], [19, 2], [21, 7], [19, 17]]) {
+      map[y][x] = 6;
+      if (y + 1 < height - 1) map[y + 1][x] = 7;
+    }
+    for (const [x, y] of [[4, 8], [12, 4], [20, 11]]) map[y][x] = 15;
+
+    return { width, height, map };
+  }
+
+  function createLevelMap(levelId, seed) {
+    if (levelId === 'flooded-relay') return createFloodedRelayMap();
+    if (levelId === 'overgrown-archive') return createOvergrownArchiveMap(seed || 191);
+    return createWorldMap(seed || 77);
+  }
+
   function findPath(startX, startY, endX, endY, isWalkable, options = {}) {
     const sx = Math.round(startX);
     const sy = Math.round(startY);
@@ -190,14 +258,29 @@
     return items.filter(item => item.timer > 0);
   }
 
+  function isGateOpen(gate, collectedObjectiveIds) {
+    return Boolean(gate && Array.isArray(collectedObjectiveIds) && collectedObjectiveIds.includes(gate.after));
+  }
+
+  function canCollectObjective(mode, orderedObjectiveIds, collectedObjectiveIds, objectiveId) {
+    if (mode !== 'sequence') return true;
+    const nextId = orderedObjectiveIds.find(id => !collectedObjectiveIds.includes(id));
+    return nextId === objectiveId;
+  }
+
   return Object.freeze({
     DIR,
     oppositeDir,
     mulberry32,
     createWorldMap,
+    createFloodedRelayMap,
+    createOvergrownArchiveMap,
+    createLevelMap,
     findPath,
     entityOccupiesTile,
     isTileReserved,
     tickTimedItems,
+    isGateOpen,
+    canCollectObjective,
   });
 });

src/game-logic.js

@@ -6,6 +6,7 @@
   'use strict';
 
   const SAVE_KEY = 'littleandroid.progress';
+  const CAMPAIGN_KEY = 'littleandroid.campaign';
   const SAVE_VERSION = 2;
 
   function defaultProgress() {
@@ -114,8 +115,78 @@
     }
   }
 
+  function createLevelStorage(storage, levelId) {
+    const levelKey = levelId === 'river-factory' ? SAVE_KEY : `${SAVE_KEY}.${levelId}`;
+    return Object.freeze({
+      getItem(key) {
+        return storage && storage.getItem(key === SAVE_KEY ? levelKey : key);
+      },
+      setItem(key, value) {
+        if (storage) storage.setItem(key === SAVE_KEY ? levelKey : key, value);
+      },
+      removeItem(key) {
+        if (storage) storage.removeItem(key === SAVE_KEY ? levelKey : key);
+      },
+    });
+  }
+
+  function defaultCampaign(levelIds = []) {
+    return {
+      activeLevelId: levelIds[0] || 'river-factory',
+      completedLevelIds: [],
+    };
+  }
+
+  function parseCampaign(raw, levelIds = []) {
+    const fallback = defaultCampaign(levelIds);
+    try {
+      const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+      if (!parsed || typeof parsed !== 'object') return fallback;
+      const completedLevelIds = normalizeStringList(parsed.completedLevelIds)
+        .filter(levelId => levelIds.includes(levelId));
+      return {
+        activeLevelId: levelIds.includes(parsed.activeLevelId) ? parsed.activeLevelId : fallback.activeLevelId,
+        completedLevelIds,
+      };
+    } catch {
+      return fallback;
+    }
+  }
+
+  function loadCampaign(storage, levelIds = []) {
+    try { return parseCampaign(storage && storage.getItem(CAMPAIGN_KEY), levelIds); }
+    catch { return defaultCampaign(levelIds); }
+  }
+
+  function saveCampaign(storage, campaign, levelIds = []) {
+    try {
+      if (!storage) return false;
+      storage.setItem(CAMPAIGN_KEY, JSON.stringify(parseCampaign(campaign, levelIds)));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function isLevelUnlocked(campaign, levelId, levelIds = []) {
+    const index = levelIds.indexOf(levelId);
+    if (index <= 0) return index === 0;
+    const normalized = parseCampaign(campaign, levelIds);
+    return normalized.completedLevelIds.includes(levelIds[index - 1]);
+  }
+
+  function completeCampaignLevel(campaign, levelId, levelIds = []) {
+    const normalized = parseCampaign(campaign, levelIds);
+    if (!levelIds.includes(levelId)) return normalized;
+    return {
+      ...normalized,
+      completedLevelIds: normalizeStringList([...normalized.completedLevelIds, levelId]),
+    };
+  }
+
   return Object.freeze({
     SAVE_KEY,
+    CAMPAIGN_KEY,
     SAVE_VERSION,
     defaultProgress,
     parseProgress,
@@ -124,5 +195,12 @@
     mergeProgress,
     saveProgress,
     clearProgress,
+    createLevelStorage,
+    defaultCampaign,
+    parseCampaign,
+    loadCampaign,
+    saveCampaign,
+    isLevelUnlocked,
+    completeCampaignLevel,
   });
 });

src/progress.js

@@ -48,3 +48,9 @@ test('completion copy contains only challenge and public URL', () => {
     'I restored the Little Android factory (D20260716-0042). Explore it at https://littleandroid.com',
   );
 });
+
+test('completion copy identifies the restored campaign zone', () => {
+  const text = completionText('D20260717-0001', 'OVERGROWN ARCHIVE');
+  assert.match(text, /overgrown archive/);
+  assert.match(text, /D20260717-0001/);
+});

tests/engagement.test.cjs

@@ -2,8 +2,8 @@
 
 const test = require('node:test');
 const assert = require('node:assert/strict');
-const { SIGNAL_FRAGMENTS, NPC_DIALOGUE } = require('../src/game-content.js');
-const { createWorldMap } = require('../src/game-logic.js');
+const { SIGNAL_FRAGMENTS, NPC_DIALOGUE, LEVELS, LEVEL_IDS } = require('../src/game-content.js');
+const { createWorldMap, createLevelMap, findPath, isGateOpen } = require('../src/game-logic.js');
 
 test('signal fragments have unique identities and walkable positions', () => {
   const { map, width, height } = createWorldMap(77);
@@ -31,3 +31,50 @@ test('every resident type has active and completed dialogue', () => {
     assert.ok(NPC_DIALOGUE[type].complete.length > 0);
   }
 });
+
+test('all campaign levels have unique objectives on valid map tiles', () => {
+  assert.deepEqual(LEVEL_IDS, ['river-factory', 'flooded-relay', 'overgrown-archive']);
+  for (const level of LEVELS) {
+    const world = createLevelMap(level.id, level.seed);
+    const ids = new Set();
+    for (const objective of level.objectives) {
+      assert.equal(ids.has(objective.id), false, `${level.id} has duplicate objective ${objective.id}`);
+      ids.add(objective.id);
+      assert.ok(objective.x >= 0 && objective.x < world.width);
+      assert.ok(objective.y >= 0 && objective.y < world.height);
+      assert.equal([4, 5, 6, 7, 8, 9, 11, 13, 14, 17, 18].includes(world.map[objective.y][objective.x]), false);
+    }
+    assert.equal(level.objectives.length, 3);
+  }
+});
+
+test('flooded relay gates connect its three platforms in order', () => {
+  const relay = LEVELS[1];
+  const world = createLevelMap(relay.id);
+  assert.deepEqual(relay.gates.map(gate => world.map[gate.y][gate.x]), [18, 18]);
+  assert.deepEqual(relay.gates.map(gate => gate.after), ['intake-relay', 'spillway-relay']);
+});
+
+test('every level objective is reachable under its progression rules', () => {
+  const blockedTiles = new Set([4, 5, 6, 7, 8, 9, 11, 13, 14, 17]);
+  for (const level of LEVELS) {
+    const world = createLevelMap(level.id, level.seed);
+    const collected = [];
+    let position = level.spawn;
+    const walkable = (x, y) => {
+      if (x < 0 || y < 0 || x >= world.width || y >= world.height) return false;
+      const tile = world.map[y][x];
+      if (tile === 18) {
+        const gate = level.gates.find(item => item.x === x && item.y === y);
+        return isGateOpen(gate, collected);
+      }
+      return !blockedTiles.has(tile);
+    };
+    for (const objective of level.objectives) {
+      const path = findPath(position.x, position.y, objective.x, objective.y, walkable, { allowNearest: false });
+      assert.ok(path.length > 0, `${objective.name} must be reachable in ${level.name}`);
+      collected.push(objective.id);
+      position = objective;
+    }
+  }
+});