Claude Claude Opus 4.8 commited on
Commit
b1fda0e
Β·
unverified Β·
1 Parent(s): 681e447

Escort order: right-click a friendly ship to guard and follow it

Browse files

Right-clicking a friendly ship with a group selected now puts the group into a
protective escort formation: each unit takes a stable slot on a ring around the
target and follows it wherever it's ordered, holding station until given another
order. A combat escort still auto-acquires threats that come near the target,
then reforms β€” so it actually protects the ship, not just trails it.

- movement.js: escortSlot() β€” the deterministic per-unit point on the ring around
the guarded ship (the ring expands to seat the whole group). Null when the
target is gone, so callers drop the order.
- commands.js: issueEscort() assigns each unit an {type:"escort", targetId, slot,
slots} order (stable slots β†’ deterministic formation).
- combat.js / sim.js: handle "escort" for combat, worker, and support units β€” a
persistent follow (never cleared on arrival). Combat escorts fall through the
normal auto-acquire first, so they defend then reform.
- input.js: a right-click on a friendly UNIT (not building/enemy/node) issues the
escort to the rest of the selection (the target is excluded).
- render.js: a green link from each selected escort to its guarded ship + a ring
on the target, so an active escort reads at a glance.

Player-only (the AI never issues it) and pure geometry, so byte-identical
skirmish determinism + engine purity are untouched. +6 tests (order assignment,
ring geometry, follow-a-moving-target, auto-engage-then-reform, drop-on-death,
worker path via full tick). 511 pass. Browser-verified: a real right-click forms
the ring and the units close in (screenshot in the session).

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

Files changed (7) hide show
  1. engine/combat.js +11 -1
  2. engine/commands.js +10 -0
  3. engine/movement.js +19 -0
  4. engine/sim.js +16 -1
  5. input.js +8 -1
  6. render.js +30 -1
  7. test/escort.test.js +107 -0
engine/combat.js CHANGED
@@ -15,7 +15,7 @@
15
 
16
  "use strict";
17
 
18
- import { stepToward } from "./movement.js";
19
  import { UNITS, BUILDINGS, upgradeMult } from "./entities.js";
20
  import { getEntity, removeEntity } from "./state.js";
21
  import { queryNeighbors } from "./grid.js";
@@ -77,6 +77,16 @@ export function updateCombat(state, unit, dt) {
77
  if (unit.order && unit.order.type === "attack-move") {
78
  const arrived = stepToward(state, unit, unit.order.x, unit.order.y, def.speed, dt);
79
  if (arrived) unit.order = null;
 
 
 
 
 
 
 
 
 
 
80
  }
81
  }
82
 
 
15
 
16
  "use strict";
17
 
18
+ import { stepToward, escortSlot } from "./movement.js";
19
  import { UNITS, BUILDINGS, upgradeMult } from "./entities.js";
20
  import { getEntity, removeEntity } from "./state.js";
21
  import { queryNeighbors } from "./grid.js";
 
77
  if (unit.order && unit.order.type === "attack-move") {
78
  const arrived = stepToward(state, unit, unit.order.x, unit.order.y, def.speed, dt);
79
  if (arrived) unit.order = null;
80
+ return;
81
+ }
82
+
83
+ // Escort: with no threat acquired above (that block returns when engaging), keep station on
84
+ // the protective ring around the guarded ship β€” a persistent follow, never cleared on arrival,
85
+ // so the escort trails the target wherever it's ordered until given a new order.
86
+ if (unit.order && unit.order.type === "escort") {
87
+ const slot = escortSlot(state, unit);
88
+ if (!slot) { unit.order = null; return; }
89
+ stepToward(state, unit, slot.x, slot.y, def.speed, dt);
90
  }
91
  }
92
 
engine/commands.js CHANGED
@@ -63,6 +63,16 @@ export function issueAttackMove(units, x, y, queue = false) {
63
  units.forEach((u, i) => dispatch(u, { type: "attack-move", x: spots[i].x, y: spots[i].y }, queue));
64
  }
65
 
 
 
 
 
 
 
 
 
 
 
66
  // Pays the cost up front, drops a constructing building on the spot, and
67
  // sends the chosen worker to stand at it until it finishes. Placement is
68
  // validated (and payment withheld) before anything is committed, so a bad
 
63
  units.forEach((u, i) => dispatch(u, { type: "attack-move", x: spots[i].x, y: spots[i].y }, queue));
64
  }
65
 
66
+ // Escort a friendly ship: each unit takes a stable slot on a protective ring around the
67
+ // target and follows it wherever it's ordered (engine/movement.js escortSlot), holding the
68
+ // formation until given another order. A combat escort still auto-acquires threats that come
69
+ // near, then reforms. The target itself is never told to escort (it's filtered out by the
70
+ // caller). `slot`/`slots` fix each unit's place at issue time, so the ring is deterministic.
71
+ export function issueEscort(units, targetId, queue = false) {
72
+ const n = units.length;
73
+ units.forEach((u, i) => dispatch(u, { type: "escort", targetId, slot: i, slots: n }, queue));
74
+ }
75
+
76
  // Pays the cost up front, drops a constructing building on the spot, and
77
  // sends the chosen worker to stand at it until it finishes. Placement is
78
  // validated (and payment withheld) before anything is committed, so a bad
engine/movement.js CHANGED
@@ -28,6 +28,25 @@ function radiusOf(entity) {
28
  return UNITS[entity.type] ? UNITS[entity.type].radius : 9;
29
  }
30
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
31
  // Moves `unit` at most `speed * dt` toward (tx, ty). Returns true once it
32
  // has arrived (within 1 unit), so callers can clear the order that got it
33
  // there.
 
28
  return UNITS[entity.type] ? UNITS[entity.type].radius : 9;
29
  }
30
 
31
+ // The formation slot for an escorting unit β€” a point on a protective ring around the friendly
32
+ // ship it's guarding (order {type:"escort", targetId, slot, slots}). The ring expands if the
33
+ // group is large enough to crowd it, so N escorts space out evenly around the target. Returns
34
+ // null when the target is gone or dead, so the caller drops the order. Pure + deterministic:
35
+ // geometry only (no clock/RNG). The escort re-seeks this point every tick, so it trails the
36
+ // target wherever it's ordered β€” and a combat escort still auto-acquires threats that come near.
37
+ const ESCORT_GAP = 22; // arc spacing between neighbouring escorts
38
+ const ESCORT_STANDOFF = 26; // clearance from the target's hull out to the ring
39
+ export function escortSlot(state, unit) {
40
+ const o = unit.order;
41
+ const target = state.units.get(o.targetId);
42
+ if (!target || target.hp <= 0) return null;
43
+ const n = Math.max(1, o.slots || 1);
44
+ const angle = ((o.slot || 0) / n) * Math.PI * 2 - Math.PI / 2; // start at the top, go round
45
+ const minR = (n * ESCORT_GAP) / (2 * Math.PI); // ring big enough to seat the whole group
46
+ const R = Math.max(radiusOf(target) + ESCORT_STANDOFF, minR);
47
+ return { x: target.x + Math.cos(angle) * R, y: target.y + Math.sin(angle) * R };
48
+ }
49
+
50
  // Moves `unit` at most `speed * dt` toward (tx, ty). Returns true once it
51
  // has arrived (within 1 unit), so callers can clear the order that got it
52
  // there.
engine/sim.js CHANGED
@@ -6,7 +6,7 @@
6
 
7
  "use strict";
8
 
9
- import { stepToward } from "./movement.js";
10
  import { buildUnitGrid } from "./grid.js";
11
  import { updateGather } from "./gather.js";
12
  import { updateScoutMode } from "./scout.js";
@@ -111,6 +111,13 @@ function updateUnit(state, unit, dt) {
111
  case "gather":
112
  updateGather(state, unit, dt);
113
  break;
 
 
 
 
 
 
 
114
  case "scout":
115
  updateScoutMode(state, unit, dt);
116
  break;
@@ -139,6 +146,14 @@ function updateUnit(state, unit, dt) {
139
  function updateSupport(state, unit, def, dt) {
140
  const o = unit.order;
141
  if (!o) return;
 
 
 
 
 
 
 
 
142
  let tx, ty, follow = false;
143
  if (o.type === "attack") {
144
  const t = getEntity(state, o.targetId);
 
6
 
7
  "use strict";
8
 
9
+ import { stepToward, escortSlot } from "./movement.js";
10
  import { buildUnitGrid } from "./grid.js";
11
  import { updateGather } from "./gather.js";
12
  import { updateScoutMode } from "./scout.js";
 
111
  case "gather":
112
  updateGather(state, unit, dt);
113
  break;
114
+ case "escort": {
115
+ // A non-combat escort (worker) just keeps station on the ring around the guarded ship.
116
+ const slot = escortSlot(state, unit);
117
+ if (!slot) { unit.order = null; break; }
118
+ stepToward(state, unit, slot.x, slot.y, def.speed, dt);
119
+ break;
120
+ }
121
  case "scout":
122
  updateScoutMode(state, unit, dt);
123
  break;
 
146
  function updateSupport(state, unit, def, dt) {
147
  const o = unit.order;
148
  if (!o) return;
149
+ // A support escort (Mender) trails the guarded ship in formation, mending whatever's near it
150
+ // via the global repair pass β€” a medic keeping station on the fleet it's protecting.
151
+ if (o.type === "escort") {
152
+ const slot = escortSlot(state, unit);
153
+ if (!slot) { unit.order = null; return; }
154
+ stepToward(state, unit, slot.x, slot.y, def.speed, dt);
155
+ return;
156
+ }
157
  let tx, ty, follow = false;
158
  if (o.type === "attack") {
159
  const t = getEntity(state, o.targetId);
input.js CHANGED
@@ -8,7 +8,7 @@
8
 
9
  "use strict";
10
 
11
- import { issueMove, issueGather, issueAttack, issueAttackMove, issueBuild, issueAssistBuild, issueSetRally, issueStop, issueScout, issueHold } from "./engine/commands.js";
12
  import { UNITS, BUILDINGS } from "./engine/entities.js";
13
  import { isVisibleAt, isNodeDiscovered } from "./engine/fog.js";
14
  import { createCamera, screenToWorld, zoomAt, panCamera, clampCamera, dragCamera, pinchZoomPan } from "./camera.js";
@@ -180,6 +180,13 @@ export function attachInput(canvas, state, onChange) {
180
  if (attackers.length) { issueAttack(attackers, target.id, queue); sound.playOrder(); }
181
  return;
182
  }
 
 
 
 
 
 
 
183
  const node = nodeAt(p.x, p.y);
184
  if (node) {
185
  const workers = selected.filter(u => u.cargo);
 
8
 
9
  "use strict";
10
 
11
+ import { issueMove, issueGather, issueAttack, issueAttackMove, issueBuild, issueAssistBuild, issueSetRally, issueStop, issueScout, issueHold, issueEscort } from "./engine/commands.js";
12
  import { UNITS, BUILDINGS } from "./engine/entities.js";
13
  import { isVisibleAt, isNodeDiscovered } from "./engine/fog.js";
14
  import { createCamera, screenToWorld, zoomAt, panCamera, clampCamera, dragCamera, pinchZoomPan } from "./camera.js";
 
180
  if (attackers.length) { issueAttack(attackers, target.id, queue); sound.playOrder(); }
181
  return;
182
  }
183
+ // A friendly SHIP as the target: the selection forms a protective escort ring around it and
184
+ // follows it wherever it's ordered (engine/commands.js issueEscort). The target itself is
185
+ // excluded, so right-clicking a ship that's part of the selection escorts it with the rest.
186
+ if (target && target.owner === "player" && target.kind === "unit") {
187
+ const escorts = selected.filter(u => u.id !== target.id);
188
+ if (escorts.length) { issueEscort(escorts, target.id, queue); sound.playOrder(); return; }
189
+ }
190
  const node = nodeAt(p.x, p.y);
191
  if (node) {
192
  const workers = selected.filter(u => u.cargo);
render.js CHANGED
@@ -133,6 +133,7 @@ export function drawFrame(ctx, state, camera, viewportW, viewportH, dragBox, bui
133
  drawEffects(ctx);
134
  if (buildGhost) drawBuildGhost(ctx, state, buildGhost);
135
  drawWaypoints(ctx, state);
 
136
  drawSelectionRings(ctx, state);
137
  drawRallyPoint(ctx, state);
138
  if (dragBox) drawDragBox(ctx, dragBox);
@@ -1502,13 +1503,41 @@ function drawWaypoints(ctx, state) {
1502
  ctx.restore();
1503
  }
1504
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1505
  // Where an order points on the map, for its waypoint marker β€” a fixed spot
1506
  // for move/attack-move, or the live position of the unit/building/node it's
1507
  // chasing. Null for an order with nowhere to point.
1508
  function orderPoint(state, order) {
1509
  if (!order) return null;
1510
  if (order.type === "move" || order.type === "attack-move") return { x: order.x, y: order.y };
1511
- if (order.type === "attack") {
1512
  const t = state.units.get(order.targetId) || state.buildings.get(order.targetId);
1513
  return t ? { x: t.x, y: t.y } : null;
1514
  }
 
133
  drawEffects(ctx);
134
  if (buildGhost) drawBuildGhost(ctx, state, buildGhost);
135
  drawWaypoints(ctx, state);
136
+ drawEscortLinks(ctx, state);
137
  drawSelectionRings(ctx, state);
138
  drawRallyPoint(ctx, state);
139
  if (dragBox) drawDragBox(ctx, dragBox);
 
1503
  ctx.restore();
1504
  }
1505
 
1506
+ // A faint link from each selected escort to the friendly ship it's guarding, plus a ring on the
1507
+ // target β€” so an active escort order reads at a glance (it carries no waypoint line otherwise).
1508
+ // Escort green, distinct from the cyan waypoint colour.
1509
+ function drawEscortLinks(ctx, state) {
1510
+ const guarded = new Set();
1511
+ ctx.save();
1512
+ ctx.setLineDash([3, 4]);
1513
+ ctx.strokeStyle = "rgba(120, 230, 170, 0.5)";
1514
+ ctx.lineWidth = 1.1;
1515
+ for (const id of state.selection) {
1516
+ const u = state.units.get(id);
1517
+ if (!u || u.owner !== "player" || !u.order || u.order.type !== "escort") continue;
1518
+ const t = state.units.get(u.order.targetId);
1519
+ if (!t || t.hp <= 0) continue;
1520
+ ctx.beginPath(); ctx.moveTo(u.x, u.y); ctx.lineTo(t.x, t.y); ctx.stroke();
1521
+ guarded.add(t);
1522
+ }
1523
+ ctx.setLineDash([]);
1524
+ ctx.strokeStyle = "rgba(120, 230, 170, 0.75)";
1525
+ ctx.lineWidth = 1.4;
1526
+ for (const t of guarded) {
1527
+ ctx.beginPath();
1528
+ ctx.arc(t.x, t.y, (UNITS[t.type]?.radius || 10) + 6, 0, Math.PI * 2);
1529
+ ctx.stroke();
1530
+ }
1531
+ ctx.restore();
1532
+ }
1533
+
1534
  // Where an order points on the map, for its waypoint marker β€” a fixed spot
1535
  // for move/attack-move, or the live position of the unit/building/node it's
1536
  // chasing. Null for an order with nowhere to point.
1537
  function orderPoint(state, order) {
1538
  if (!order) return null;
1539
  if (order.type === "move" || order.type === "attack-move") return { x: order.x, y: order.y };
1540
+ if (order.type === "attack" || order.type === "escort") {
1541
  const t = state.units.get(order.targetId) || state.buildings.get(order.targetId);
1542
  return t ? { x: t.x, y: t.y } : null;
1543
  }
test/escort.test.js ADDED
@@ -0,0 +1,107 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { test } from "node:test";
2
+ import assert from "node:assert/strict";
3
+ import { createGameState, makeUnit } from "../engine/state.js";
4
+ import { tick } from "../engine/sim.js";
5
+ import { updateCombat } from "../engine/combat.js";
6
+ import { issueEscort } from "../engine/commands.js";
7
+ import { escortSlot } from "../engine/movement.js";
8
+
9
+ // A minimal state (as the movement/combat tests use): just a unit Map + players, so we can drive
10
+ // updateCombat directly without the AI/win-checks of a full tick.
11
+ function miniState(...units) {
12
+ return {
13
+ units: new Map(units.map(u => [u.id, u])),
14
+ buildings: new Map(),
15
+ players: { player: { color: "#0ff", resources: {} }, ai: { color: "#f00", resources: {} } },
16
+ events: [], // performAttack (combat.js) pushes hit/kill events here
17
+ };
18
+ }
19
+
20
+ test("issueEscort gives every unit an escort order with a stable slot", () => {
21
+ const target = makeUnit("skiff", "player", 600, 600);
22
+ const escorts = [makeUnit("skiff", "player", 200, 200), makeUnit("skiff", "player", 210, 200), makeUnit("ranger", "player", 220, 200)];
23
+ issueEscort(escorts, target.id);
24
+ escorts.forEach((u, i) => {
25
+ assert.equal(u.order.type, "escort");
26
+ assert.equal(u.order.targetId, target.id);
27
+ assert.equal(u.order.slot, i);
28
+ assert.equal(u.order.slots, 3);
29
+ });
30
+ });
31
+
32
+ test("escortSlot places escorts on a ring around the target; null once it's gone", () => {
33
+ const target = makeUnit("skiff", "player", 500, 500);
34
+ const escorts = [makeUnit("skiff", "player", 0, 0), makeUnit("skiff", "player", 0, 0), makeUnit("skiff", "player", 0, 0), makeUnit("skiff", "player", 0, 0)];
35
+ const s = miniState(target, ...escorts);
36
+ issueEscort(escorts, target.id);
37
+ const pts = escorts.map(u => escortSlot(s, u));
38
+ for (const p of pts) {
39
+ const r = Math.hypot(p.x - target.x, p.y - target.y);
40
+ assert.ok(r > 12 && r < 200, `on a ring at a sane radius (${r.toFixed(1)})`);
41
+ }
42
+ assert.notEqual(`${pts[0].x.toFixed(1)},${pts[0].y.toFixed(1)}`, `${pts[1].x.toFixed(1)},${pts[1].y.toFixed(1)}`, "distinct slots β†’ distinct points");
43
+ s.units.delete(target.id);
44
+ assert.equal(escortSlot(s, escorts[0]), null, "a vanished target β†’ no slot (caller drops the order)");
45
+ });
46
+
47
+ test("a combat escort closes to formation and then trails a moving target (persistent follow)", () => {
48
+ const target = makeUnit("skiff", "player", 600, 600);
49
+ const u = makeUnit("skiff", "player", 200, 200);
50
+ const s = miniState(target, u);
51
+ issueEscort([u], target.id);
52
+
53
+ for (let i = 0; i < 300; i++) updateCombat(s, u, 0.1);
54
+ let slot = escortSlot(s, u);
55
+ assert.ok(Math.hypot(u.x - slot.x, u.y - slot.y) < 8, "reached its formation slot beside the target");
56
+ assert.ok(u.order && u.order.type === "escort", "still escorting β€” arrival never clears an escort");
57
+
58
+ target.x = 1600; target.y = 1600; // the guarded ship is ordered far away
59
+ for (let i = 0; i < 500; i++) updateCombat(s, u, 0.1);
60
+ assert.ok(Math.hypot(u.x - target.x, u.y - target.y) < 90, "the escort trailed the target to its new position");
61
+ });
62
+
63
+ test("a combat escort auto-engages a threat near its charge, then reforms", () => {
64
+ const target = makeUnit("skiff", "player", 600, 600);
65
+ const u = makeUnit("skiff", "player", 560, 560);
66
+ const s = miniState(target, u);
67
+ issueEscort([u], target.id);
68
+ for (let i = 0; i < 150; i++) updateCombat(s, u, 0.1); // form up
69
+
70
+ const enemy = makeUnit("skiff", "ai", u.x + 20, u.y); // a raider right on the escort
71
+ enemy.hp = enemy.maxHp = 100000; // a sponge, so it survives to be measured (no death-cleanup path)
72
+ s.units.set(enemy.id, enemy);
73
+ for (let i = 0; i < 80; i++) updateCombat(s, u, 0.1); // only the escort acts; the enemy sits
74
+ assert.ok(enemy.hp < enemy.maxHp, "the escort broke formation to defend the target and hit the threat");
75
+
76
+ s.units.delete(enemy.id); // threat gone
77
+ for (let i = 0; i < 300; i++) updateCombat(s, u, 0.1);
78
+ const slot = escortSlot(s, u);
79
+ assert.ok(Math.hypot(u.x - slot.x, u.y - slot.y) < 12, "with the threat cleared, the escort returns to formation");
80
+ });
81
+
82
+ test("an escort drops the order the moment its target dies", () => {
83
+ const target = makeUnit("skiff", "player", 600, 600);
84
+ const u = makeUnit("skiff", "player", 500, 500);
85
+ const s = miniState(target, u);
86
+ issueEscort([u], target.id);
87
+ updateCombat(s, u, 0.1);
88
+ assert.equal(u.order.type, "escort");
89
+ s.units.delete(target.id);
90
+ updateCombat(s, u, 0.1);
91
+ assert.equal(u.order, null, "no target β†’ the escort stops escorting (free to take a new order)");
92
+ });
93
+
94
+ test("a worker (non-combat) escort follows via the sim tick path", () => {
95
+ const s = createGameState({ planetId: "ferros", seed: 2 });
96
+ const cx = s.map.width / 2, cy = s.map.height / 2; // mid-map, clear of both bases
97
+ const target = makeUnit("skiff", "player", cx, cy);
98
+ const worker = makeUnit("worker", "player", cx - 300, cy);
99
+ s.units.set(target.id, target);
100
+ s.units.set(worker.id, worker);
101
+ issueEscort([worker], target.id);
102
+ const d0 = Math.hypot(worker.x - target.x, worker.y - target.y);
103
+ for (let i = 0; i < 120; i++) tick(s, 0.1);
104
+ const d1 = Math.hypot(worker.x - target.x, worker.y - target.y);
105
+ assert.ok(d1 < d0 - 100, `the worker escort closed on its target through the tick (${d0.toFixed(0)} β†’ ${d1.toFixed(0)})`);
106
+ assert.ok(worker.order && worker.order.type === "escort", "and it's still escorting");
107
+ });