Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(society): retiring an agent is an execution, not a row that vanishes

rubenluetke10-beepd3a6ddebf57a
diff --git a/docs/agent-society/world-behaviour-manual.md b/docs/agent-society/world-behaviour-manual.md
index 843ef46ab4..3a222078ec 100644
--- a/docs/agent-society/world-behaviour-manual.md
+++ b/docs/agent-society/world-behaviour-manual.md
@@ -111,6 +111,26 @@ in the turn's language.
The figure walks when, and only when, the derived checkpoint changes. A rejected `ASSIGN` (tier,
budget, kill switch) never moves anyone; the card shows the typed failure reason.
+## 5a. Retiring an agent — the one gesture that is final
+
+| Gesture in the world | Event | Guard |
+|---|---|---|
+| card → options rail → "Retire agent" (twice) | `DELETE /api/society/agents/{id}` → the row is archived | the lead is refused by `roster.archive`; the button says so before the call |
+
+Everything else on the island is reversible, so deletion is the one thing the
+world is asked to make you watch. The lead walks up to the condemned figure,
+raises a rifle, fires; the body goes over, two bearers carry it out on a
+stretcher and tip it into the mine. About twenty seconds, entirely client-side
+— the backend sees one archive call and no choreography at all, exactly like
+every other footstep (§1).
+
+The row is archived BEFORE the ceremony plays, so a refusal is an error the
+person sees immediately rather than the punchline of a scene. The roster's
+refetch pauses while the ceremony runs; the figure leaves the island when the
+body lands, not before. If the ceremony cannot play at all — reduced motion, no
+WebGL, the viewer on the Ledger — the agent is retired without it. Pressing
+Retire never depends on a canvas.
+
## 6. What the buildings do
Every hub has three faces, and all three are required before a building ships (finish-it-everywhere):
diff --git a/jarvis/ui/web/frontend/src/components/society/world/Landmarks.tsx b/jarvis/ui/web/frontend/src/components/society/world/Landmarks.tsx
index 53ae57680b..e12f436e13 100644
--- a/jarvis/ui/web/frontend/src/components/society/world/Landmarks.tsx
+++ b/jarvis/ui/web/frontend/src/components/society/world/Landmarks.tsx
@@ -150,6 +150,19 @@ function Lighthouse({ kit, paused }: { kit: Kit; paused: boolean }) {
);
}
+/**
+ * The cliff's south face, in metres along −z from the mine place's origin —
+ * where the rock starts. The retirement ceremony throws a body into the mouth
+ * cut into it (`retirementGeometry.ts`), so the number is shared, not copied.
+ */
+export const MINE_FACE_DZ = -6.8;
+
+/** The tunnel mouth's own z, half a metre into the rock behind the face. */
+export const MINE_PORTAL_DZ = MINE_FACE_DZ - 0.5;
+
+/** Half-way up the tunnel mouth: what a thrown body is aimed at, in metres. */
+export const MINE_PORTAL_Y = 1.6;
+
/**
* The mine: a timber portal cut into the cliff north of the quarry's forecourt,
* lanterns on its posts, rails running out of the dark to a cart of ore, a
@@ -162,7 +175,7 @@ function Mine({ kit, paused }: { kit: Kit; paused: boolean }) {
if (!wheel.current || paused) return;
wheel.current.rotation.x = clock.getElapsedTime() * 0.8;
});
- const face = -6.8; // the cliff's south face, relative z
+ const face = MINE_FACE_DZ;
return (
<group position={[x, y, z]}>
{/* the tunnel: a dark mouth set into the cliff */}
diff --git a/jarvis/ui/web/frontend/src/components/society/world/README.md b/jarvis/ui/web/frontend/src/components/society/world/README.md
index 260c3d6777..2ed65b8474 100644
--- a/jarvis/ui/web/frontend/src/components/society/world/README.md
+++ b/jarvis/ui/web/frontend/src/components/society/world/README.md
@@ -19,7 +19,28 @@ Binding design: `docs/agent-society/world-masterplan-v2.md` (look, kit, market,
| `SunRig.tsx` · `Clouds.tsx` · `Shadowed.tsx` | The sun with a view-following shadow camera, shadow-casting clouds, the cast/receive marker. |
| `Terrain.tsx` · `Village.tsx` · `Landmarks.tsx` · `Trees.tsx` | The scene: the terrain mesh and the shore-driven water shader, the village with the hub on its podium, the landmarks, every tree, palm, pine and boulder — all primitives, shared through `WorldKit.tsx`. |
| `Walkers.tsx` · `WalkerFigure.tsx` · `walkerRegistry.ts` | Agents on foot: state machine, stand-in figure, minimap pins. |
+| `retirement.ts` · `retirementRoute.ts` · `retireStore.ts` · `RetirementScene.tsx` | Deleting an agent, as a scene: the lead walks up, shoots it, and two bearers carry the body to the mine and tip it in. Curves and route are pure and tested; the scene drives the existing walkers through a mutable pose map and commits the `DELETE` only when the body lands. |
| `PlaceLabels.tsx` · `WorldHud.tsx` · `Minimap.tsx` · `world.css` | DOM over the canvas in the world's type. |
| `WorldStage.tsx` | The composition; mounted by `views/JarvisAgentsView.tsx` behind the World / Ledger switch. |
Strings live in the lazy `society` locale chunk (`src/i18n/locales/society/`).
+
+## Retiring an agent
+
+Deleting a row is a ceremony on the island, not a figure blinking out. It is
+started from the model card's options rail (`../card/AgentCardOverlay.tsx`),
+which archives the row FIRST — so a refusal is an error the person sees — and
+only then hands the island a `commit` that refreshes the roster once the body
+is in the mine. The roster's refetch interval pauses for the duration, or the
+figure being carried would vanish mid-scene.
+
+Two cuts keep it to about twenty seconds on a 500 m island: the lead walks on
+`MARCH_APPROACH_M` from its target rather than crossing the map, and the
+stretcher crew jumps forward along its own route once it has set off, with the
+camera flying after it. Both are film cuts along a route the figures were
+already walking — never a teleport somewhere else.
+
+If the ceremony cannot run — reduced motion, no WebGL, the viewer is on the
+ledger, an unreachable body — the agent is retired anyway. Pressing Retire must
+never depend on a working canvas; `retireStore.ts` holds the watchdogs that
+guarantee it.
diff --git a/jarvis/ui/web/frontend/src/components/society/world/RetirementScene.tsx b/jarvis/ui/web/frontend/src/components/society/world/RetirementScene.tsx
new file mode 100644
index 0000000000..13fce1661f
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/society/world/RetirementScene.tsx
@@ -0,0 +1,486 @@
+/**
+ * Retiring an agent, played out on the island — the R3F half of
+ * `retirement.ts`.
+ *
+ * The lead walks up to the condemned figure, levels a rifle, fires, and the
+ * body goes over backwards. Two bearers trot in from the mine road, roll it
+ * onto a stretcher, carry it out to the quarry and tip it into the tunnel.
+ * When the body lands in the dark, and not one moment before, the deletion is
+ * committed.
+ *
+ * Three things about how it is built:
+ *
+ * - it drives the EXISTING walkers rather than drawing copies of them. The
+ * lead and the condemned are ordinary roster figures; the ceremony writes
+ * their pose into `retireStore`'s mutable map each frame and the walkers
+ * read it instead of running their own sim. Nothing is duplicated, so the
+ * figures keep their own character, palette and nameplate throughout;
+ * - only the props are new: the stretcher, its two bearers (box stand-ins —
+ * they are scenery, not roster rows) and the mark left on the ground;
+ * - the whole route is planned ONCE, when the ceremony starts
+ * (`retirementRoute.ts`). No pathfinding runs inside the animation.
+ *
+ * The one cut: carrying a body from the town square to the mine is a hundred
+ * and twenty metres, and nobody wants to watch a two-minute walk. After a few
+ * seconds of the crew setting off, the ceremony jumps them forward ALONG
+ * THEIR OWN ROUTE to the last stretch, and the camera flies after them. It is
+ * a cut in a film, not a teleport to somewhere they were never going.
+ */
+import { useEffect, useMemo, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import type { Group, Mesh } from "three";
+
+import { useCameraStore } from "./cameraStore";
+import { buildIsland, groundY } from "./islandLayout";
+import * as R from "./retirement";
+import {
+ attachRetirement,
+ buryRetired,
+ poseAt,
+ releaseRetirementPose,
+ setRetirementPose,
+ useRetireStore,
+ type Ceremony,
+} from "./retireStore";
+import { planRetirement, type RetirementPlan } from "./retirementRoute";
+import { NOMINAL_WALK_MPS, TURN_RATE_RAD_S, headingFor, isMoving, stepAlong, turnToward } from "./walkerKinematics";
+import { walkerPins } from "./walkerRegistry";
+import { BoxWalkerFigure, type WalkerAnim } from "./WalkerFigure";
+import { useKit } from "./WorldKit";
+import { PAL } from "./worldMaterials";
+
+/** The lead does not stroll to an execution. */
+const MARCH_MPS = NOMINAL_WALK_MPS * 1.25;
+/** The camera is only re-aimed once the focus has moved this far, in metres. */
+const CAMERA_DEADBAND_M = 0.75;
+/** How wide the stage is framed while the ceremony runs (zoom step). */
+const CEREMONY_ZOOM = 1;
+/** The mark on the ground grows to this radius, in metres. */
+const STAIN_RADIUS_M = 0.85;
+/** How far behind the feet the head lies once the body is down, in metres. */
+const HEAD_OFFSET_M = 1.1;
+
+interface Body {
+ x: number;
+ z: number;
+ /** Height of the figure's origin above the ground, in metres. */
+ y: number;
+ heading: number;
+ pitch: number;
+}
+
+interface Run {
+ plan: RetirementPlan;
+ phase: R.RetirePhase;
+ /** Seconds inside the current phase. */
+ t: number;
+ lead: { x: number; z: number; heading: number };
+ leadIdx: number;
+ body: Body;
+ /** Where the body came to rest after the topple — the stretcher's target. */
+ restAt: [number, number];
+ /** The stretcher's centre and the heading it is carried on. */
+ crew: { x: number; z: number; heading: number };
+ crewIdx: number;
+ /** The route the crew is currently walking (in, out, then into the dark). */
+ crewPath: Array<[number, number]>;
+ /** Where the body left the stretcher, once it is in the air. */
+ launch: [number, number, number] | null;
+ /** The last point the camera was aimed at. */
+ camera: [number, number];
+ /** True once the lead has been handed back to its own sim. */
+ released: boolean;
+ /** Seconds since the ceremony started drawing — the stretcher's sway clock. */
+ clock: number;
+}
+
+export function RetirementScene({ paused }: { paused: boolean }) {
+ const ceremony = useRetireStore((s) => s.ceremony);
+
+ // Tell the store a stage exists, so its "nobody picked this up" watchdog
+ // stands down and the ceremony is actually played.
+ useEffect(() => {
+ if (ceremony) attachRetirement();
+ }, [ceremony]);
+
+ // Reduced motion freezes the island; an execution nobody can see must not
+ // hold an agent hostage, so it is retired without the ceremony.
+ useEffect(() => {
+ if (ceremony && paused) useRetireStore.getState().cutShort();
+ }, [ceremony, paused]);
+
+ if (!ceremony || paused) return null;
+ return <Execution key={ceremony.agentId} ceremony={ceremony} />;
+}
+
+function Execution({ ceremony }: { ceremony: Ceremony }) {
+ const kit = useKit();
+ const setPhase = useRetireStore((s) => s.setPhase);
+
+ const stretcher = useRef<Group>(null);
+ const bearerA = useRef<Group>(null);
+ const bearerB = useRef<Group>(null);
+ const stain = useRef<Mesh>(null);
+ const animA = useRef<WalkerAnim>({ mode: "carry", speed: 0 });
+ const animB = useRef<WalkerAnim>({ mode: "carry", speed: 0 });
+
+ const bearerPalette = useMemo(
+ () => ({ primary: PAL.bearerCloth, secondary: PAL.bearerTrim, accent: PAL.bearerLamp }),
+ [],
+ );
+
+ // The plan is made once, from where the two figures actually are.
+ const run = useRef<Run | null>(null);
+ if (run.current === null) {
+ const pins = walkerPins();
+ const victim = pins.get(ceremony.agentId);
+ const lead = ceremony.executionerId ? pins.get(ceremony.executionerId) : undefined;
+ const plan = victim && lead ? planRetirement([victim.x, victim.z], [lead.x, lead.z]) : null;
+ if (plan && victim && lead) {
+ run.current = {
+ plan,
+ phase: "march",
+ t: 0,
+ lead: { x: plan.leadStart.x, z: plan.leadStart.z, heading: plan.leadStart.heading },
+ leadIdx: 0,
+ body: { x: plan.body.x, z: plan.body.z, y: 0, heading: plan.body.heading, pitch: 0 },
+ restAt: [plan.body.x, plan.body.z],
+ crew: { x: plan.bearerPath[0]?.[0] ?? plan.body.x, z: plan.bearerPath[0]?.[1] ?? plan.body.z, heading: 0 },
+ crewIdx: 0,
+ crewPath: plan.bearerPath,
+ launch: null,
+ camera: [plan.body.x, plan.body.z],
+ released: false,
+ clock: 0,
+ };
+ }
+ }
+
+ // A body nothing can reach, or an executioner who is not on the island:
+ // the agent is still retired, just without the ceremony.
+ useEffect(() => {
+ if (run.current === null) useRetireStore.getState().cutShort();
+ }, []);
+
+ // Frame the stage once, at the start; the per-frame aim below only pans.
+ useEffect(() => {
+ const r = run.current;
+ if (!r) return;
+ useCameraStore.getState().focusOn(r.body.x, r.body.z, CEREMONY_ZOOM);
+ }, []);
+
+ useFrame((_, delta) => {
+ const r = run.current;
+ if (!r) return;
+ const { map } = buildIsland();
+ const dt = Math.min(delta, 0.1);
+ r.clock += dt;
+ r.t += dt;
+
+ const advance = () => {
+ r.phase = R.nextPhase(r.phase);
+ r.t = 0;
+ onEnterPhase(r);
+ setPhase(r.phase);
+ };
+ const sway = R.carrySway(r.clock);
+
+ // ----- the beat --------------------------------------------------------
+ if (r.phase === "march") {
+ const step = stepAlong(r.lead.x, r.lead.z, r.plan.leadPath, r.leadIdx, MARCH_MPS, dt);
+ r.lead.x = step.x;
+ r.lead.z = step.z;
+ r.leadIdx = step.index;
+ if (isMoving(step.vx, step.vz)) {
+ r.lead.heading = turnToward(r.lead.heading, headingFor(step.vx, step.vz), TURN_RATE_RAD_S * dt);
+ }
+ if (step.arrived) advance();
+ } else if (R.isDistancePhase(r.phase)) {
+ if (walkCrew(r, dt)) advance();
+ } else {
+ if (r.phase === "confront") {
+ r.lead.heading = turnToward(r.lead.heading, r.plan.stand.heading, TURN_RATE_RAD_S * dt);
+ } else if (r.phase === "fall") {
+ const u = R.clamp01(r.t / R.PHASE_SECONDS.fall);
+ r.body.pitch = R.fallPitch(u);
+ const slide = R.fallSlide(u);
+ r.body.x = r.plan.body.x - Math.sin(r.plan.body.heading) * slide;
+ r.body.z = r.plan.body.z - Math.cos(r.plan.body.heading) * slide;
+ r.body.y = R.fallLift(u);
+ r.restAt = [r.body.x, r.body.z];
+ } else if (r.phase === "load") {
+ // Rolled onto the stretcher and lined up along it.
+ const u = R.loadBlend(r.t);
+ const down = R.fallLift(1);
+ r.body.pitch = -Math.PI / 2;
+ r.body.heading = turnToward(r.body.heading, r.crew.heading, TURN_RATE_RAD_S * dt);
+ r.body.x = r.restAt[0] + (r.crew.x - r.restAt[0]) * u;
+ r.body.z = r.restAt[1] + (r.crew.z - r.restAt[1]) * u;
+ r.body.y = down + (R.STRETCHER_CARRY_Y - down) * u;
+ } else if (r.phase === "carry") {
+ walkCrew(r, dt);
+ } else if (r.phase === "depart") {
+ walkCrew(r, dt);
+ }
+
+ // Riding the stretcher: everything between the load and the release.
+ const flying = r.phase === "toss" && R.tossProgress(r.t).released;
+ if ((r.phase === "carry" || r.phase === "travel" || r.phase === "toss") && !flying) {
+ r.body.x = r.crew.x;
+ r.body.z = r.crew.z;
+ r.body.heading = r.crew.heading;
+ r.body.pitch = -Math.PI / 2;
+ r.body.y = R.STRETCHER_CARRY_Y + sway.lift;
+ }
+ if (flying) {
+ const toss = R.tossProgress(r.t);
+ if (r.launch === null) {
+ r.launch = [r.body.x, groundY(map, r.body.x, r.body.z) + r.body.y, r.body.z];
+ }
+ const [px, py, pz] = R.tossArc(toss.fly, r.launch, r.plan.portal, R.TOSS_APEX_M);
+ r.body.x = px;
+ r.body.z = pz;
+ r.body.y = py - groundY(map, px, pz);
+ }
+
+ if (r.t >= R.PHASE_SECONDS[r.phase]) advance();
+ }
+
+ // The `arrive` leg rides the stretcher too, and it is a distance phase.
+ if (r.phase === "arrive") {
+ r.body.x = r.crew.x;
+ r.body.z = r.crew.z;
+ r.body.heading = r.crew.heading;
+ r.body.pitch = -Math.PI / 2;
+ r.body.y = R.STRETCHER_CARRY_Y + sway.lift;
+ }
+
+ // ----- the two figures the roster owns ---------------------------------
+ const aim = R.aimBlend(r.phase, r.t);
+ const recoil = R.recoilM(r.phase, r.t);
+ if (ceremony.executionerId) {
+ // Once the rifle is down the lead goes back to its own life; it has no
+ // business standing over the body for the rest of the ceremony.
+ const stillArmed = r.phase === "march" || R.riflePhase(r.phase);
+ if (!stillArmed && !r.released) {
+ r.released = true;
+ releaseRetirementPose(ceremony.executionerId);
+ } else if (!r.released) {
+ const pose = poseAt(
+ r.lead.x - Math.sin(r.lead.heading) * recoil,
+ groundY(map, r.lead.x, r.lead.z),
+ r.lead.z - Math.cos(r.lead.heading) * recoil,
+ r.lead.heading,
+ );
+ pose.mode = r.phase === "march" ? "walk" : aim > 0.05 ? "aim" : "rest";
+ pose.speed = r.phase === "march" ? MARCH_MPS : 0;
+ pose.aim = aim;
+ pose.flash = R.muzzleFlash(r.phase, r.t);
+ setRetirementPose(ceremony.executionerId, pose);
+ }
+ }
+
+ const bodyPose = poseAt(r.body.x, groundY(map, r.body.x, r.body.z) + r.body.y, r.body.z, r.body.heading);
+ bodyPose.pitch = r.body.pitch;
+ bodyPose.mode = r.phase === "march" || r.phase === "confront" ? "rest" : "sleep";
+ if (r.phase === "toss") {
+ const toss = R.tossProgress(r.t);
+ // Tumbling on the way in, then swallowed by the dark.
+ if (toss.released) bodyPose.pitch = -Math.PI / 2 - toss.fly * 2.2;
+ bodyPose.hidden = R.tossFade(toss.fly) < 0.5;
+ } else if (r.phase === "depart" || r.phase === "done") {
+ bodyPose.hidden = true;
+ }
+ setRetirementPose(ceremony.agentId, bodyPose);
+
+ // ----- the props -------------------------------------------------------
+ const crewOut =
+ r.phase === "bearers" ||
+ r.phase === "load" ||
+ r.phase === "carry" ||
+ r.phase === "travel" ||
+ r.phase === "arrive" ||
+ r.phase === "toss" ||
+ r.phase === "depart";
+ const moving = r.phase === "bearers" || r.phase === "carry" || r.phase === "arrive" || r.phase === "depart";
+
+ if (stretcher.current) {
+ stretcher.current.visible = crewOut;
+ if (crewOut) {
+ const tilt = r.phase === "toss" ? R.tossProgress(r.t).wind * 0.55 : 0;
+ stretcher.current.position.set(
+ r.crew.x,
+ groundY(map, r.crew.x, r.crew.z) + R.STRETCHER_CARRY_Y + sway.lift,
+ r.crew.z,
+ );
+ stretcher.current.rotation.set(-tilt, r.crew.heading, sway.roll);
+ }
+ }
+
+ const slots = R.bearerSlots([r.crew.x, r.crew.z], r.crew.heading);
+ const bearers = [bearerA, bearerB];
+ for (let i = 0; i < bearers.length; i++) {
+ const g = bearers[i].current;
+ if (!g) continue;
+ g.visible = crewOut;
+ if (!g.visible) continue;
+ const [bx, bz] = slots[i];
+ g.position.set(bx, groundY(map, bx, bz), bz);
+ g.rotation.y = r.crew.heading;
+ }
+ animA.current.mode = moving ? "carry" : "rest";
+ animA.current.speed = moving ? R.BEARER_MPS : 0;
+ animB.current.mode = animA.current.mode;
+ animB.current.speed = animA.current.speed;
+
+ if (stain.current) {
+ const marked = R.PHASE_ORDER.indexOf(r.phase) >= R.PHASE_ORDER.indexOf("fall");
+ stain.current.visible = marked;
+ if (marked) {
+ const grow = r.phase === "fall" ? R.ease(r.t / R.PHASE_SECONDS.fall) : 1;
+ // Under the head, which lies behind the feet the body pivoted on.
+ const hx = r.restAt[0] - Math.sin(r.plan.body.heading) * HEAD_OFFSET_M;
+ const hz = r.restAt[1] - Math.cos(r.plan.body.heading) * HEAD_OFFSET_M;
+ stain.current.position.set(hx, groundY(map, hx, hz) + 0.03, hz);
+ stain.current.scale.set(grow * STAIN_RADIUS_M, 1, grow * STAIN_RADIUS_M * 1.3);
+ }
+ }
+
+ // ----- the camera ------------------------------------------------------
+ const focus = focusPoint(r);
+ if (
+ !useCameraStore.getState().dragging &&
+ Math.hypot(focus[0] - r.camera[0], focus[1] - r.camera[1]) > CAMERA_DEADBAND_M
+ ) {
+ r.camera = focus;
+ useCameraStore.getState().jumpTo(focus[0], focus[1]);
+ }
+
+ if (r.phase === "done") {
+ // The body is in the mine. Hold the figure off the island until the
+ // roster refetch drops the row, then commit the deletion.
+ buryRetired(ceremony.agentId);
+ if (ceremony.executionerId && !r.released) releaseRetirementPose(ceremony.executionerId);
+ run.current = null;
+ useRetireStore.getState().finish();
+ }
+ });
+
+ return (
+ <group>
+ <mesh ref={stain} geometry={kit.g.disc} material={kit.m.lit(PAL.stain)} visible={false} />
+ {/* The stretcher yaws with the crew and tilts about its OWN long axis on
+ the throw, so the pitch has to be applied before the yaw: YXZ. */}
+ <group ref={stretcher} rotation-order="YXZ" visible={false}>
+ {[-0.42, 0.42].map((px) => (
+ <mesh
+ key={px}
+ geometry={kit.g.box}
+ material={kit.m.lit(PAL.stretcherPole)}
+ position={[px, 0, 0]}
+ scale={[0.1, 0.1, 3.7]}
+ />
+ ))}
+ <mesh
+ geometry={kit.g.slab}
+ material={kit.m.lit(PAL.stretcherCloth)}
+ position={[0, 0.03, 0]}
+ scale={[0.86, 0.05, 3.0]}
+ />
+ </group>
+ <group ref={bearerA} visible={false}>
+ <BoxWalkerFigure palette={bearerPalette} anim={animA} paused={false} selected={false} />
+ </group>
+ <group ref={bearerB} visible={false}>
+ <BoxWalkerFigure palette={bearerPalette} anim={animB} paused={false} selected={false} />
+ </group>
+ </group>
+ );
+}
+
+/** Move the stretcher crew one step along its current route; true on arrival. */
+function walkCrew(r: Run, dt: number): boolean {
+ const step = stepAlong(r.crew.x, r.crew.z, r.crewPath, r.crewIdx, R.BEARER_MPS, dt);
+ r.crew.x = step.x;
+ r.crew.z = step.z;
+ r.crewIdx = step.index;
+ if (isMoving(step.vx, step.vz)) {
+ r.crew.heading = turnToward(r.crew.heading, headingFor(step.vx, step.vz), TURN_RATE_RAD_S * dt);
+ }
+ return step.arrived;
+}
+
+/** Per-phase setup the moment a beat begins. */
+function onEnterPhase(r: Run): void {
+ switch (r.phase) {
+ case "bearers": {
+ // The crew comes on down the road it will carry the body back along,
+ // and walks in to wherever the body actually came to rest.
+ const rest: [number, number] = [r.restAt[0], r.restAt[1]];
+ const path = r.plan.bearerPath.slice();
+ if (path.length > 0) path[path.length - 1] = rest;
+ const entry = path[0] ?? rest;
+ r.crew.x = entry[0];
+ r.crew.z = entry[1];
+ r.crew.heading = R.facingHeading(entry, rest);
+ const tail = path.slice(1);
+ r.crewPath = tail.length > 0 ? tail : [rest];
+ r.crewIdx = 0;
+ break;
+ }
+ case "carry": {
+ // Out to the mine, starting from the body's own resting place.
+ const path = r.plan.carryPath.slice();
+ path[0] = [r.restAt[0], r.restAt[1]];
+ r.crewPath = path;
+ r.crewIdx = path.length > 1 ? 1 : 0;
+ break;
+ }
+ case "travel": {
+ // The cut: forward along their own route to the last stretch, so the
+ // walk across the island is skipped instead of watched.
+ const ahead = R.pointBackFrom(r.crewPath, R.MINE_APPROACH_M);
+ if (ahead.index <= r.crewIdx) break; // already closer than the cut point
+ r.crew.x = ahead.x;
+ r.crew.z = ahead.z;
+ r.crew.heading = ahead.heading;
+ r.crewIdx = ahead.index;
+ break;
+ }
+ case "depart": {
+ // Into the tunnel, and gone.
+ r.crewPath = [[r.plan.portal[0], r.plan.portal[2]]];
+ r.crewIdx = 0;
+ break;
+ }
+ default:
+ break;
+ }
+}
+
+/** What the camera should be looking at for this beat. */
+function focusPoint(r: Run): [number, number] {
+ switch (r.phase) {
+ case "march":
+ // Hold the condemned and let the lead walk into frame; the two can still
+ // be far enough apart that their midpoint shows neither of them.
+ return [r.body.x, r.body.z];
+ case "confront":
+ case "raise":
+ case "hold":
+ case "shot":
+ return [(r.lead.x + r.body.x) / 2, (r.lead.z + r.body.z) / 2];
+ case "fall":
+ case "settle":
+ return [r.body.x, r.body.z];
+ case "bearers":
+ return [(r.crew.x + r.restAt[0]) / 2, (r.crew.z + r.restAt[1]) / 2];
+ case "toss":
+ case "depart":
+ return [(r.crew.x + r.plan.portal[0]) / 2, (r.crew.z + r.plan.portal[2]) / 2];
+ default:
+ return [r.crew.x, r.crew.z];
+ }
+}
+
+export default RetirementScene;
diff --git a/jarvis/ui/web/frontend/src/components/society/world/WalkerFigure.tsx b/jarvis/ui/web/frontend/src/components/society/world/WalkerFigure.tsx
index 62c70d68d9..c0a810352a 100644
--- a/jarvis/ui/web/frontend/src/components/society/world/WalkerFigure.tsx
+++ b/jarvis/ui/web/frontend/src/components/society/world/WalkerFigure.tsx
@@ -11,23 +11,33 @@
*/
import { useRef } from "react";
import { useFrame } from "@react-three/fiber";
-import type { Group } from "three";
+import type { Group, Mesh } from "three";
import type { AgentPalette } from "../data";
import { FigureRig, type FigureDrive, type FigureMode } from "../figures/FigureRig";
import type { FigureRecipe } from "../figures/figureRecipe";
import { figureAssetFor } from "../figures/figureRegistry";
import { useKit } from "./WorldKit";
+import { PAL } from "./worldMaterials";
/** A warm neutral for head and hands — a doll, not a skin tone. */
const SKIN = "#efe0cd";
-export type WalkerMode = "rest" | "walk" | "work" | "sleep";
+/**
+ * `carry` and `aim` belong to the retirement ceremony (`retirement.ts`): a
+ * stretcher bearer walks with its arms hanging on the poles, and the lead
+ * stands still behind a levelled rifle.
+ */
+export type WalkerMode = "rest" | "walk" | "work" | "sleep" | "carry" | "aim" | "talk";
export interface WalkerAnim {
mode: WalkerMode;
/** Current ground speed in m/s (drives the stride rate). */
speed: number;
+ /** How far the rifle is up, 0 (none drawn) to 1 (levelled). Ceremony only. */
+ aim?: number;
+ /** Muzzle-flash brightness this frame, 0..1. Ceremony only. */
+ flash?: number;
}
interface Props {
@@ -51,8 +61,21 @@ const MODE_TO_CLIP: Record<WalkerMode, FigureMode> = {
walk: "walk",
work: "work",
sleep: "sleep",
+ // A bearer walks; a shooter stands. Neither has a clip of its own, and
+ // inventing one would mean a new figure base for a fifteen-second scene.
+ carry: "walk",
+ aim: "idle",
+ // Authored on every base since the figure pipeline shipped, and never played
+ // until the island learned that agents talk to each other.
+ talk: "talk",
};
+/** Shoulder height as a fraction of the whole figure — where a rifle is held. */
+const SHOULDER_FRACTION = 0.7;
+
+/** The box stand-in's overall height in metres, at world hero scale. */
+const BOX_FIGURE_HEIGHT_M = 2.04;
+
/**
* The shipped character when the roster row carries a recipe whose base is
* built; the box stand-in otherwise. Both take the same sim-driven `anim`.
@@ -65,6 +88,62 @@ export function WalkerFigure(props: Props) {
return <BoxWalkerFigure {...props} />;
}
+/**
+ * The rifle the lead carries through a retirement (`retirement.ts`).
+ *
+ * It is not rigged to a hand: both figure kinds — the shipped GLB and the box
+ * stand-in — would need a weapon socket in the base for that, and this is a
+ * fifteen-second scene, not a combat system. It is held beside the figure at
+ * shoulder height instead, swinging up from slung to levelled with `aim`,
+ * which reads correctly from every camera angle the island allows.
+ *
+ * Drawn only while `aim > 0`, and it drives itself from the same `anim` ref
+ * the walker writes each frame — no React render is involved in a shot.
+ */
+function Rifle({ anim, heightM }: { anim: { current: WalkerAnim }; heightM: number }) {
+ const kit = useKit();
+ const group = useRef<Group>(null);
+ const flash = useRef<Group>(null);
+ const spark = useRef<Mesh>(null);
+ const shoulder = heightM * SHOULDER_FRACTION;
+
+ useFrame(() => {
+ const g = group.current;
+ if (!g) return;
+ const a = Math.max(0, Math.min(1, anim.current.aim ?? 0));
+ g.visible = a > 0.001;
+ if (!g.visible) return;
+ // Slung: low and pointing at the ground. Levelled: shoulder high and flat.
+ g.position.set(0.34, shoulder - 0.34 * (1 - a), 0.06 + 0.1 * a);
+ g.rotation.x = 0.95 * (1 - a);
+ const f = Math.max(0, Math.min(1, anim.current.flash ?? 0));
+ if (flash.current) {
+ flash.current.visible = f > 0.02;
+ const s = 0.16 + f * 0.5;
+ flash.current.scale.set(s, s, s);
+ }
+ if (spark.current) spark.current.rotation.z += 0.6;
+ });
+
+ return (
+ <group ref={group} visible={false}>
+ <mesh geometry={kit.g.box} material={kit.m.lit(PAL.metal)} position={[0, 0, 0.55]} scale={[0.07, 0.07, 1.06]} />
+ <mesh geometry={kit.g.box} material={kit.m.lit(PAL.woodDark)} position={[0, -0.02, -0.12]} scale={[0.11, 0.17, 0.52]} />
+ <mesh geometry={kit.g.box} material={kit.m.lit(PAL.woodDark)} position={[0, -0.16, 0.14]} scale={[0.09, 0.22, 0.11]} />
+ <mesh geometry={kit.g.box} material={kit.m.lit(PAL.metal)} position={[0, 0.08, 0.18]} scale={[0.05, 0.06, 0.34]} />
+ <group ref={flash} position={[0, 0, 1.14]} visible={false}>
+ <mesh ref={spark} geometry={kit.g.blob} material={kit.m.glow(PAL.muzzle)} />
+ <mesh
+ geometry={kit.g.disc}
+ material={kit.m.halo(PAL.muzzle, 0.6)}
+ rotation={[Math.PI / 2, 0, 0]}
+ scale={[2.4, 1, 2.4]}
+ />
+ </group>
+ </group>
+ );
+}
+
function RiggedWalkerFigure({ palette, anim, paused, selected, recipe }: Props & { recipe: FigureRecipe }) {
const kit = useKit();
const ring = useRef<Group>(null);
@@ -80,6 +159,8 @@ function RiggedWalkerFigure({ palette, anim, paused, selected, recipe }: Props &
}
});
+ const height = (recipe.heightM ?? 1.75) * WORLD_HERO_SCALE;
+
return (
<group>
{selected && (
@@ -87,12 +168,18 @@ function RiggedWalkerFigure({ palette, anim, paused, selected, recipe }: Props &
<mesh geometry={kit.g.ring} material={kit.m.glow(palette.accent)} rotation={[Math.PI / 2, 0, 0]} scale={[1.9, 1.9, 1.2]} />
</group>
)}
- <FigureRig recipe={recipe} drive={drive} paused={paused} heightM={(recipe.heightM ?? 1.75) * WORLD_HERO_SCALE} />
+ <FigureRig recipe={recipe} drive={drive} paused={paused} heightM={height} />
+ <Rifle anim={anim} heightM={height} />
</group>
);
}
-function BoxWalkerFigure({ palette, anim, paused, selected }: Props) {
+/**
+ * The box stand-in, exported because the retirement ceremony's two stretcher
+ * bearers are drawn with it: they are scenery, not roster rows, so they have
+ * no figure recipe of their own.
+ */
+export function BoxWalkerFigure({ palette, anim, paused, selected }: Props) {
const kit = useKit();
const body = useRef<Group>(null);
const legL = useRef<Group>(null);
@@ -121,6 +208,22 @@ function BoxWalkerFigure({ palette, anim, paused, selected }: Props) {
armLift = -1.25;
armSwing = Math.sin(t * 9) * 0.08;
bob = Math.sin(t * 2.2) * 0.012;
+ } else if (a.mode === "carry") {
+ // A bearer strides with the stretcher's poles in both hands: the legs
+ // walk, the arms hang still on the wood.
+ phase.current += (step * a.speed * (Math.PI * 2)) / 1.28;
+ legSwing = Math.sin(phase.current) * 0.5;
+ bob = Math.abs(Math.sin(phase.current)) * 0.035;
+ armLift = 0.12;
+ } else if (a.mode === "aim") {
+ // Behind a levelled rifle: both arms come up with the weapon.
+ armLift = -1.35 * (a.aim ?? 1);
+ bob = Math.sin(t * 1.4) * 0.008;
+ } else if (a.mode === "talk") {
+ // Standing and speaking: one hand comes up and the body carries the
+ // sentence. No steps — a conversation never moves a figure.
+ armLift = -0.25 + Math.sin(t * 6.2) * 0.18;
+ bob = Math.sin(t * 3.1) * 0.014;
} else if (a.mode === "sleep") {
bob = Math.sin(t * 0.9) * 0.01;
armLift = 0.15;
@@ -176,6 +279,7 @@ function BoxWalkerFigure({ palette, anim, paused, selected }: Props) {
<mesh geometry={box} material={glow(palette.accent)} position={[0, 1.76, 0.2]} scale={[0.36, 0.12, 0.06]} />
<mesh geometry={box} material={lit(palette.secondary)} position={[0, 1.96, -0.02]} scale={[0.46, 0.08, 0.42]} />
</group>
+ <Rifle anim={anim} heightM={BOX_FIGURE_HEIGHT_M} />
</group>
);
}
diff --git a/jarvis/ui/web/frontend/src/components/society/world/WorldStage.tsx b/jarvis/ui/web/frontend/src/components/society/world/WorldStage.tsx
index d05801f9ed..30d3f5bc72 100644
--- a/jarvis/ui/web/frontend/src/components/society/world/WorldStage.tsx
+++ b/jarvis/ui/web/frontend/src/components/society/world/WorldStage.tsx
@@ -36,6 +36,7 @@ import { MemoryDrawer } from "./MemoryDrawer";
import { PlaceLabels } from "./PlaceLabels";
import { HubDrawer } from "./HubDrawer";
import { QuestBoardDrawer } from "./QuestBoardDrawer";
+import { RetirementScene } from "./RetirementScene";
import { ACTIVE_STATES } from "./questBoard";
import { useSocietyQuests } from "./questsData";
import { Shadowed } from "./Shadowed";
@@ -216,6 +217,8 @@ export function WorldStage({ topRight, onOpenLedger, onSelectAgent, onSelectPlac
/>
<Trees />
<Walkers agents={agents} paused={reduced} selectedId={selected} onSelect={select} />
+ {/* A retirement drives the walkers above; it must mount after them. */}
+ <RetirementScene paused={reduced} />
</Shadowed>
{shadows && <Clouds paused={reduced} />}
{ready && <PlaceLabels />}
diff --git a/jarvis/ui/web/frontend/src/components/society/world/retireStore.ts b/jarvis/ui/web/frontend/src/components/society/world/retireStore.ts
new file mode 100644
index 0000000000..b0ca9614ac
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/society/world/retireStore.ts
@@ -0,0 +1,223 @@
+/**
+ * Which agent is being retired right now, and what the ceremony is doing to
+ * the figures on the island — the state half of `retirement.ts`.
+ *
+ * Two channels, on purpose:
+ *
+ * - the zustand store carries the ceremony itself (who, which beat, is one
+ * running at all). It changes about a dozen times over twenty seconds, so
+ * a React render per change costs nothing and the HUD can read it;
+ * - the pose map is a plain mutable `Map`, written and read inside
+ * `useFrame`, exactly like `walkerRegistry.ts`. A walker under the
+ * ceremony's control reads its pose every frame; re-rendering React at
+ * 60 fps to move a figure would be absurd.
+ *
+ * The commit — the actual `DELETE /api/society/agents/{id}` — is handed in by
+ * whoever started the ceremony and is fired ONCE, at the end. If the ceremony
+ * cannot run or cannot finish (no WebGL, reduced motion, the canvas torn down
+ * mid-execution, a path that never resolves), the commit still fires: someone
+ * who pressed Retire gets their agent retired, animation or no animation.
+ */
+import { create } from "zustand";
+
+import type { AgentPalette } from "../data";
+import type { FigureRecipe } from "../figures/figureRecipe";
+import type { WalkerMode } from "./WalkerFigure";
+import type { RetirePhase } from "./retirement";
+
+/**
+ * A ceremony that has run this long has hit something it cannot finish (an
+ * unreachable body, a path that never resolves). It is cut short and the
+ * agent is retired anyway.
+ */
+export const CEREMONY_TIMEOUT_MS = 90_000;
+
+/**
+ * A ceremony nobody picked up in this long has no stage to play on — the
+ * viewer is on the ledger, the canvas never mounted, WebGL is gone. The
+ * agent is retired without the show rather than sitting in limbo.
+ */
+export const ATTACH_GRACE_MS = 2_000;
+
+/** The pose the ceremony forces onto a walker; null means "you are free". */
+export interface WalkerOverride {
+ x: number;
+ z: number;
+ /** Height of the figure's origin above the ground plane, in metres. */
+ y: number;
+ heading: number;
+ /** Rotation about the figure's own X axis — the topple. 0 while upright. */
+ pitch: number;
+ mode: WalkerMode;
+ /** Ground speed for the stride rate, m/s. */
+ speed: number;
+ /** The body has been handed to the bearers: the walker stops drawing itself. */
+ hidden: boolean;
+ /** How far the rifle is up, 0..1; only the executioner ever gets this. */
+ aim: number;
+ /** Muzzle-flash brightness this frame, 0..1. */
+ flash: number;
+}
+
+export interface Ceremony {
+ /** The agent being retired. */
+ agentId: string;
+ name: string;
+ /** Kept so the body can be drawn after the roster row is gone. */
+ figure: FigureRecipe | null;
+ palette: AgentPalette;
+ /** Who does it — the lead's agent id, or null when the lead is not on the island. */
+ executionerId: string | null;
+ startedMs: number;
+ /** Fired once, when the body is in the mine (or when the ceremony is cut short). */
+ commit: () => void | Promise<void>;
+}
+
+interface RetireState {
+ ceremony: Ceremony | null;
+ phase: RetirePhase;
+ /**
+ * Start the ceremony. Returns false when one is already running — two
+ * executions at once would fight over the same lead.
+ */
+ begin: (ceremony: Omit<Ceremony, "startedMs">) => boolean;
+ /** The stage picked the ceremony up: it will be played, not cut short. */
+ attach: () => void;
+ setPhase: (phase: RetirePhase) => void;
+ /** The body is in the mine: commit the deletion and clear the stage. */
+ finish: () => void;
+ /**
+ * The ceremony cannot run or cannot finish. The agent is retired anyway —
+ * pressing Retire must not depend on a working canvas.
+ */
+ cutShort: () => void;
+}
+
+/** Per-frame poses, keyed by agent id. Mutable on purpose; see the file docstring. */
+const overrides = new Map<string, WalkerOverride>();
+
+/**
+ * Agents whose body is already in the mine. The deletion is committed the
+ * instant the body lands, but the roster refetch that removes the row takes a
+ * moment longer — without this the walker would pop back onto the plaza and
+ * stand there, alive, for a second. The entry is dropped when the walker
+ * finally unmounts.
+ */
+const buried = new Set<string>();
+
+/** The pose a buried figure holds: nowhere, and not drawn. */
+const BURIED_POSE: WalkerOverride = {
+ x: 0,
+ y: 0,
+ z: 0,
+ heading: 0,
+ pitch: 0,
+ mode: "rest",
+ speed: 0,
+ hidden: true,
+ aim: 0,
+ flash: 0,
+};
+
+/** Watchdogs for the running ceremony; cleared whenever it ends. */
+let attachTimer: ReturnType<typeof setTimeout> | null = null;
+let capTimer: ReturnType<typeof setTimeout> | null = null;
+
+function clearTimers(): void {
+ if (attachTimer !== null) clearTimeout(attachTimer);
+ if (capTimer !== null) clearTimeout(capTimer);
+ attachTimer = null;
+ capTimer = null;
+}
+
+export const useRetireStore = create<RetireState>((set, get) => ({
+ ceremony: null,
+ phase: "done",
+ begin: (ceremony) => {
+ if (get().ceremony !== null) return false;
+ overrides.clear();
+ clearTimers();
+ set({ ceremony: { ...ceremony, startedMs: Date.now() }, phase: "march" });
+ // Nothing may leave an agent half-retired: if no stage picks this up, or
+ // the ceremony wedges on an unreachable body, the deletion still lands.
+ attachTimer = setTimeout(() => {
+ attachTimer = null;
+ if (get().ceremony !== null) get().cutShort();
+ }, ATTACH_GRACE_MS);
+ capTimer = setTimeout(() => {
+ capTimer = null;
+ if (get().ceremony !== null) get().cutShort();
+ }, CEREMONY_TIMEOUT_MS);
+ return true;
+ },
+ attach: () => {
+ if (attachTimer === null) return;
+ clearTimeout(attachTimer);
+ attachTimer = null;
+ },
+ setPhase: (phase) => {
+ if (get().phase === phase) return;
+ set({ phase });
+ },
+ finish: () => {
+ const active = get().ceremony;
+ overrides.clear();
+ clearTimers();
+ set({ ceremony: null, phase: "done" });
+ void active?.commit();
+ },
+ cutShort: () => {
+ const active = get().ceremony;
+ overrides.clear();
+ clearTimers();
+ set({ ceremony: null, phase: "done" });
+ void active?.commit();
+ },
+}));
+
+/** Start a retirement. False when one is already under way. */
+export function beginRetirement(ceremony: Omit<Ceremony, "startedMs">): boolean {
+ return useRetireStore.getState().begin(ceremony);
+}
+
+/** Called by the stage the moment it takes the ceremony on. */
+export function attachRetirement(): void {
+ useRetireStore.getState().attach();
+}
+
+/** True while any agent is being retired. */
+export function retirementRunning(): boolean {
+ return useRetireStore.getState().ceremony !== null;
+}
+
+/** The pose the ceremony wants this walker in, or null when it is free. */
+export function retirementPose(agentId: string): WalkerOverride | null {
+ const live = overrides.get(agentId);
+ if (live) return live;
+ return buried.has(agentId) ? BURIED_POSE : null;
+}
+
+/** The body is in the mine: keep the figure off the island until its row goes. */
+export function buryRetired(agentId: string): void {
+ buried.add(agentId);
+}
+
+/** The walker unmounted — the roster row is gone, nothing left to hide. */
+export function forgetRetired(agentId: string): void {
+ buried.delete(agentId);
+}
+
+/** Written by the ceremony each frame for the figures it drives. */
+export function setRetirementPose(agentId: string, pose: WalkerOverride): void {
+ overrides.set(agentId, pose);
+}
+
+/** Hand a figure back to its own sim (the lead, once it has holstered). */
+export function releaseRetirementPose(agentId: string): void {
+ overrides.delete(agentId);
+}
+
+/** A blank override at a spot — the ceremony fills in what it needs. */
+export function poseAt(x: number, y: number, z: number, heading: number): WalkerOverride {
+ return { x, y, z, heading, pitch: 0, mode: "rest", speed: 0, hidden: false, aim: 0, flash: 0 };
+}
diff --git a/jarvis/ui/web/frontend/src/components/society/world/retirement.test.ts b/jarvis/ui/web/frontend/src/components/society/world/retirement.test.ts
new file mode 100644
index 0000000000..f1cbd591dc
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/society/world/retirement.test.ts
@@ -0,0 +1,261 @@
+/**
+ * The retirement ceremony's curves and geometry (`retirement.ts`), plus the
+ * one thing about the route that can actually break: whether a body can be
+ * carried from the town to the mine at all (`retirementRoute.ts`).
+ *
+ * The animation itself is not tested here — that is pixels. What is tested is
+ * everything a bug in would put a figure in the wrong place: which way the
+ * two face each other, which way a body topples, where the throw lands, and
+ * that the mine is reachable from the square.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+ BEARER_ENTRY_M,
+ EXECUTION_RANGE_M,
+ MINE_APPROACH_M,
+ PHASE_ORDER,
+ PHASE_SECONDS,
+ STRETCHER_HALF_M,
+ TOSS_APEX_M,
+ TOSS_STANDOFF_M,
+ aimBlend,
+ bearerSlots,
+ facingHeading,
+ fallPitch,
+ firingStand,
+ isDistancePhase,
+ muzzleFlash,
+ nextPhase,
+ pathLength,
+ pointBackFrom,
+ recoilM,
+ riflePhase,
+ tossArc,
+ tossFade,
+ tossProgress,
+} from "./retirement";
+import { planRetirement } from "./retirementRoute";
+import { CENTER_TILE, buildIsland, tileToWorld } from "./islandLayout";
+
+describe("the ceremony's beats", () => {
+ it("runs every phase once and ends on done", () => {
+ const seen: string[] = [];
+ let phase = PHASE_ORDER[0];
+ for (let i = 0; i < PHASE_ORDER.length + 5 && phase !== "done"; i++) {
+ seen.push(phase);
+ phase = nextPhase(phase);
+ }
+ expect(phase).toBe("done");
+ expect(seen).toEqual(PHASE_ORDER.slice(0, -1));
+ expect(nextPhase("done")).toBe("done");
+ });
+
+ it("gives every timed phase a duration and every distance phase none", () => {
+ for (const phase of PHASE_ORDER) {
+ if (phase === "done") continue;
+ if (isDistancePhase(phase)) expect(PHASE_SECONDS[phase]).toBe(0);
+ else expect(PHASE_SECONDS[phase]).toBeGreaterThan(0);
+ }
+ });
+});
+
+describe("the rifle", () => {
+ it("comes up over the raise, holds through the shot and goes down again", () => {
+ expect(aimBlend("march", 0)).toBe(0);
+ expect(aimBlend("raise", 0)).toBe(0);
+ expect(aimBlend("raise", PHASE_SECONDS.raise)).toBeCloseTo(1);
+ expect(aimBlend("hold", 0.3)).toBe(1);
+ expect(aimBlend("shot", 0.1)).toBe(1);
+ expect(aimBlend("fall", 0.5)).toBe(1);
+ expect(aimBlend("settle", 0)).toBeCloseTo(1);
+ expect(aimBlend("settle", PHASE_SECONDS.settle)).toBeCloseTo(0);
+ expect(aimBlend("bearers", 0)).toBe(0);
+ });
+
+ it("is only carried between the confrontation and the holster", () => {
+ expect(riflePhase("march")).toBe(false);
+ expect(riflePhase("confront")).toBe(true);
+ expect(riflePhase("settle")).toBe(true);
+ expect(riflePhase("bearers")).toBe(false);
+ expect(riflePhase("toss")).toBe(false);
+ });
+
+ it("flashes and kicks only on the shot", () => {
+ expect(muzzleFlash("hold", 0.1)).toBe(0);
+ expect(muzzleFlash("shot", 0)).toBeCloseTo(1);
+ expect(muzzleFlash("shot", PHASE_SECONDS.shot)).toBeCloseTo(0);
+ expect(muzzleFlash("fall", 0)).toBe(0);
+ expect(recoilM("hold", 0.1)).toBe(0);
+ expect(recoilM("shot", PHASE_SECONDS.shot / 2)).toBeGreaterThan(0.1);
+ });
+});
+
+describe("the fall", () => {
+ it("goes over backwards and ends flat", () => {
+ expect(fallPitch(0)).toBe(0);
+ expect(fallPitch(1)).toBeCloseTo(-Math.PI / 2);
+ // Backwards is a NEGATIVE pitch: the head lands behind the feet, away
+ // from the executioner the body was facing.
+ expect(fallPitch(0.5)).toBeLessThan(0);
+ });
+
+ it("accelerates rather than easing evenly", () => {
+ // A quarter of the way through the topple, less than a quarter of the way
+ // over — a body drops, it does not lower itself.
+ expect(Math.abs(fallPitch(0.25))).toBeLessThan(Math.PI / 8);
+ });
+
+ it("never pitches past flat once it is down", () => {
+ for (let u = 0.78; u <= 1; u += 0.02) {
+ expect(fallPitch(u)).toBeGreaterThanOrEqual(-Math.PI / 2 - 1e-9);
+ }
+ });
+});
+
+describe("who faces whom", () => {
+ it("stands the executioner at range, facing the body", () => {
+ const stand = firingStand([0, 0], [10, 0]);
+ expect(Math.hypot(stand.x, stand.z)).toBeCloseTo(EXECUTION_RANGE_M);
+ // A figure faces +Z in its own space: rotation.y = θ looks at (sin θ, cos θ).
+ expect(Math.sin(stand.heading)).toBeCloseTo(-1);
+ expect(Math.cos(stand.heading)).toBeCloseTo(0, 5);
+ });
+
+ it("survives both figures standing on the same spot", () => {
+ const stand = firingStand([4, 4], [4, 4]);
+ expect(Number.isFinite(stand.x)).toBe(true);
+ expect(Math.hypot(stand.x - 4, stand.z - 4)).toBeCloseTo(EXECUTION_RANGE_M);
+ });
+
+ it("turns the condemned to look straight at its executioner", () => {
+ const h = facingHeading([0, 0], [0, 5]);
+ expect(Math.sin(h)).toBeCloseTo(0, 5);
+ expect(Math.cos(h)).toBeCloseTo(1);
+ });
+});
+
+describe("routes measured backwards", () => {
+ const line: Array<[number, number]> = [
+ [0, 0],
+ [0, 10],
+ [6, 10],
+ ];
+
+ it("measures a polyline", () => {
+ expect(pathLength(line)).toBeCloseTo(16);
+ expect(pathLength([])).toBe(0);
+ expect(pathLength([[1, 1]])).toBe(0);
+ });
+
+ it("walks back from the end and keeps the forward heading", () => {
+ const p = pointBackFrom(line, 2);
+ expect(p.x).toBeCloseTo(4);
+ expect(p.z).toBeCloseTo(10);
+ expect(Math.sin(p.heading)).toBeCloseTo(1);
+ });
+
+ it("clamps to the start when asked for more than there is", () => {
+ const p = pointBackFrom(line, 999);
+ expect([p.x, p.z]).toEqual([0, 0]);
+ });
+
+ it("has no opinion about an empty line", () => {
+ expect(pointBackFrom([], 5).x).toBe(0);
+ expect(pointBackFrom([[3, 4]], 5)).toMatchObject({ x: 3, z: 4 });
+ });
+});
+
+describe("the throw", () => {
+ it("winds up before it lets go", () => {
+ expect(tossProgress(0).released).toBe(false);
+ expect(tossProgress(PHASE_SECONDS.toss).released).toBe(true);
+ expect(tossProgress(PHASE_SECONDS.toss).fly).toBeCloseTo(1);
+ });
+
+ it("arcs from the stretcher to the portal", () => {
+ const from: [number, number, number] = [0, 1, 0];
+ const to: [number, number, number] = [0, 2, -5];
+ expect(tossArc(0, from, to, TOSS_APEX_M)).toEqual([0, 1, 0]);
+ const end = tossArc(1, from, to, TOSS_APEX_M);
+ expect(end[1]).toBeCloseTo(2);
+ expect(end[2]).toBeCloseTo(-5);
+ // Highest in the middle, and higher than either end.
+ expect(tossArc(0.5, from, to, TOSS_APEX_M)[1]).toBeGreaterThan(2 + TOSS_APEX_M / 2);
+ });
+
+ it("only disappears once it is inside", () => {
+ expect(tossFade(0)).toBeCloseTo(1);
+ expect(tossFade(0.5)).toBeCloseTo(1);
+ expect(tossFade(1)).toBeCloseTo(0);
+ });
+});
+
+describe("the stretcher", () => {
+ it("puts one bearer in front and one behind", () => {
+ const [front, back] = bearerSlots([0, 0], 0);
+ expect(front[1]).toBeCloseTo(STRETCHER_HALF_M);
+ expect(back[1]).toBeCloseTo(-STRETCHER_HALF_M);
+ expect(Math.hypot(front[0] - back[0], front[1] - back[1])).toBeCloseTo(STRETCHER_HALF_M * 2);
+ });
+
+ it("turns them with the carry heading", () => {
+ const [front] = bearerSlots([0, 0], Math.PI / 2);
+ expect(front[0]).toBeCloseTo(STRETCHER_HALF_M);
+ expect(front[1]).toBeCloseTo(0, 5);
+ });
+});
+
+describe("planning a retirement on the island", () => {
+ // The one route failure that would strand a body forever: the mine being
+ // unreachable from the town. Everything else in the plan derives from it.
+ const square = tileToWorld(CENTER_TILE + 3, CENTER_TILE + 3);
+ const nearby = tileToWorld(CENTER_TILE + 8, CENTER_TILE + 6);
+
+ it("routes a body from the square to the mine's portal", () => {
+ const plan = planRetirement(square, nearby);
+ expect(plan).not.toBeNull();
+ if (!plan) return;
+ const end = plan.carryPath[plan.carryPath.length - 1];
+ // The crew stops the standoff short of the mouth, on the forecourt.
+ expect(Math.hypot(end[0] - plan.portal[0], end[1] - plan.portal[2])).toBeCloseTo(
+ TOSS_STANDOFF_M,
+ 1,
+ );
+ expect(pathLength(plan.carryPath)).toBeGreaterThan(MINE_APPROACH_M);
+ });
+
+ it("stands the executioner at firing range and walks it there", () => {
+ const plan = planRetirement(square, nearby);
+ expect(plan).not.toBeNull();
+ if (!plan) return;
+ expect(Math.hypot(plan.stand.x - plan.body.x, plan.stand.z - plan.body.z)).toBeCloseTo(
+ EXECUTION_RANGE_M,
+ 5,
+ );
+ const last = plan.leadPath[plan.leadPath.length - 1];
+ expect(last).toEqual([plan.stand.x, plan.stand.z]);
+ });
+
+ it("brings the bearers on from the mine road and walks them to the body", () => {
+ const plan = planRetirement(square, nearby);
+ expect(plan).not.toBeNull();
+ if (!plan) return;
+ const entry = plan.bearerPath[0];
+ const end = plan.bearerPath[plan.bearerPath.length - 1];
+ expect(end).toEqual([plan.body.x, plan.body.z]);
+ // They come on from up the road, not on top of the body.
+ expect(Math.hypot(entry[0] - plan.body.x, entry[1] - plan.body.z)).toBeGreaterThan(
+ BEARER_ENTRY_M / 3,
+ );
+ });
+
+ it("keeps the body on walkable ground", () => {
+ const { map } = buildIsland();
+ const plan = planRetirement(square, nearby);
+ expect(plan).not.toBeNull();
+ if (!plan) return;
+ expect(Number.isFinite(map.level[0])).toBe(true);
+ expect(Number.isFinite(plan.portal[1])).toBe(true);
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/components/society/world/retirement.ts b/jarvis/ui/web/frontend/src/components/society/world/retirement.ts
new file mode 100644
index 0000000000..d04c128e94
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/society/world/retirement.ts
@@ -0,0 +1,359 @@
+/**
+ * Retiring an agent, as a piece of choreography — the pure half.
+ *
+ * Deleting an agent is not a row disappearing from a table. On the island it
+ * is an execution: the lead walks up to the condemned figure, raises a rifle,
+ * fires, and the body is carried off by two bearers and tipped into the mine.
+ * Nothing about it is subtle, and that is the point — an agent you delete is
+ * gone, and the world should make you watch it happen.
+ *
+ * Everything here is a pure function of a phase and a local time, so the
+ * whole ceremony can be pinned by `retirement.test.ts` without a Canvas. The
+ * R3F side (`RetirementScene.tsx`) owns the meshes and the clock; the store
+ * (`retireStore.ts`) owns which agent is being retired and hands out the
+ * per-frame poses the walkers read.
+ *
+ * Two phases are NOT timed here, because their length is a distance:
+ * `march` (the lead walking to the condemned) and `bearers` / `arrive` (the
+ * stretcher crew closing on their target) run until they get there. The
+ * timed phases below are the beats in between.
+ */
+
+/** The beats of the ceremony, in order. */
+export type RetirePhase =
+ | "march" // the lead walks to the condemned (distance, not time)
+ | "confront" // the two stand face to face
+ | "raise" // the rifle comes up
+ | "hold" // the aim settles
+ | "shot" // the muzzle flash
+ | "fall" // the body topples
+ | "settle" // the lead lowers the rifle, the body lies still
+ | "bearers" // two bearers trot in from the mine road (distance)
+ | "load" // the body is rolled onto the stretcher
+ | "carry" // the crew sets off, the camera goes with them
+ | "travel" // the cut: the camera flies ahead, the crew is further along
+ | "arrive" // the last stretch to the mine's portal (distance)
+ | "toss" // the wind-up and the throw into the dark
+ | "depart" // the crew walks into the tunnel
+ | "done";
+
+/** How long each timed phase lasts, in seconds. Distance phases hold 0. */
+export const PHASE_SECONDS: Record<RetirePhase, number> = {
+ march: 0,
+ confront: 1.0,
+ raise: 0.75,
+ hold: 0.6,
+ shot: 0.22,
+ fall: 1.0,
+ settle: 0.8,
+ bearers: 0,
+ load: 1.4,
+ carry: 3.0,
+ travel: 1.3,
+ arrive: 0,
+ toss: 1.75,
+ depart: 1.4,
+ done: 0,
+};
+
+/** The order the ceremony runs in. */
+export const PHASE_ORDER: readonly RetirePhase[] = [
+ "march",
+ "confront",
+ "raise",
+ "hold",
+ "shot",
+ "fall",
+ "settle",
+ "bearers",
+ "load",
+ "carry",
+ "travel",
+ "arrive",
+ "toss",
+ "depart",
+ "done",
+];
+
+/** True while the phase ends on arrival rather than on a clock. */
+export function isDistancePhase(phase: RetirePhase): boolean {
+ return phase === "march" || phase === "bearers" || phase === "arrive";
+}
+
+/** The phase after `phase`; "done" is its own successor. */
+export function nextPhase(phase: RetirePhase): RetirePhase {
+ const i = PHASE_ORDER.indexOf(phase);
+ if (i < 0 || i >= PHASE_ORDER.length - 1) return "done";
+ return PHASE_ORDER[i + 1];
+}
+
+// ---------------------------------------------------------------------------
+// distances and speeds
+// ---------------------------------------------------------------------------
+
+/** How far the lead stops from the condemned, in metres. Close enough to be personal. */
+export const EXECUTION_RANGE_M = 2.6;
+/** The bearers trot; they are not on a stroll. */
+export const BEARER_MPS = 3.1;
+/**
+ * The lead walks on from this far out. The island is 500 m across and the
+ * condemned figure can be anywhere on it — a full walk from the square to the
+ * summit is a minute of watching a figure cross a map. So the ceremony opens
+ * with the lead already most of the way there, on its own route, and the
+ * camera holds the condemned while it comes into frame. Same cut as `travel`,
+ * at the other end of the story.
+ */
+export const MARCH_APPROACH_M = 14;
+/** Where the bearers come in from: this far back along the route to the mine. */
+export const BEARER_ENTRY_M = 18;
+/** After the cut, the crew stands this far from the mine's portal. */
+export const MINE_APPROACH_M = 15;
+/**
+ * The bearers stop this far from the portal's mouth and throw from there.
+ * Tuned so their stand point lands on the middle of a walkable forecourt tile:
+ * the rail head right in front of the portal blocks pathing (islandLayout).
+ */
+export const TOSS_STANDOFF_M = 5.3;
+/** How high the body flies on its way into the dark, in metres. */
+export const TOSS_APEX_M = 2.4;
+/**
+ * Half the distance between the two bearers along the stretcher, in metres.
+ * A walker is drawn at hero scale (WORLD_HERO_SCALE), so a body on the deck is
+ * closer to 2.8 m than to 1.75 m. The bearers stand clear of it, or the figure
+ * lying between them covers them both.
+ */
+export const STRETCHER_HALF_M = 1.95;
+/** The stretcher rides this high while it is being carried, in metres. */
+export const STRETCHER_CARRY_Y = 0.95;
+
+// ---------------------------------------------------------------------------
+// curves
+// ---------------------------------------------------------------------------
+
+export function clamp01(v: number): number {
+ return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+
+/** Smoothstep — the house ease for anything that starts and stops. */
+export function ease(u: number): number {
+ const t = clamp01(u);
+ return t * t * (3 - 2 * t);
+}
+
+/**
+ * How far the rifle is up, 0 (slung at the hip) to 1 (levelled at the head).
+ * It rises over `raise`, stays up through the shot and the fall, and comes
+ * down again over `settle`.
+ */
+export function aimBlend(phase: RetirePhase, local: number): number {
+ switch (phase) {
+ case "raise":
+ return ease(local / PHASE_SECONDS.raise);
+ case "hold":
+ case "shot":
+ case "fall":
+ return 1;
+ case "settle":
+ return 1 - ease(local / PHASE_SECONDS.settle);
+ default:
+ return 0;
+ }
+}
+
+/** True while the lead is carrying the rifle at all (it is not always drawn). */
+export function riflePhase(phase: RetirePhase): boolean {
+ return (
+ phase === "confront" ||
+ phase === "raise" ||
+ phase === "hold" ||
+ phase === "shot" ||
+ phase === "fall" ||
+ phase === "settle"
+ );
+}
+
+/** Muzzle flash brightness, 0..1 — a hard spike that dies inside the shot. */
+export function muzzleFlash(phase: RetirePhase, local: number): number {
+ if (phase !== "shot") return 0;
+ const u = clamp01(local / PHASE_SECONDS.shot);
+ // Full at the trigger, gone a fifth of a second later.
+ return (1 - u) ** 2;
+}
+
+/** How far the lead is shoved back by the recoil, in metres. */
+export function recoilM(phase: RetirePhase, local: number): number {
+ if (phase !== "shot") return 0;
+ const u = clamp01(local / PHASE_SECONDS.shot);
+ return Math.sin(u * Math.PI) * 0.12;
+}
+
+/**
+ * The condemned body's pitch, in radians. It faces its executioner, so it
+ * goes over BACKWARDS: negative rotation about local X lays the head down
+ * behind the feet. It accelerates like a toppling plank and settles with two
+ * small bounces.
+ */
+export function fallPitch(u: number): number {
+ const t = clamp01(u);
+ const HIT = 0.78;
+ if (t <= 0) return 0;
+ if (t < HIT) {
+ const k = t / HIT;
+ return -(Math.PI / 2) * k * k;
+ }
+ const over = (t - HIT) / (1 - HIT);
+ const bounce = Math.abs(Math.sin(over * Math.PI * 2)) * 0.18 * (1 - over);
+ return -Math.PI / 2 + bounce;
+}
+
+/** How far the body slides back as it goes down, in metres along its own −Z. */
+export function fallSlide(u: number): number {
+ return ease(u) * 0.55;
+}
+
+/** How high the body's origin sits once it is down: lying on its side, not standing. */
+export function fallLift(u: number): number {
+ return ease(u) * 0.18;
+}
+
+/**
+ * The body being rolled onto the stretcher: 0 on the ground, 1 on the deck.
+ * It lifts late, so the bearers are visibly bent over it first.
+ */
+export function loadBlend(local: number): number {
+ return ease(clamp01((local - 0.45) / (PHASE_SECONDS.load - 0.45)));
+}
+
+/** The stretcher's sway while it is carried — a slow roll, not a bounce. */
+export function carrySway(t: number): { roll: number; lift: number } {
+ return { roll: Math.sin(t * 4.4) * 0.055, lift: Math.abs(Math.sin(t * 4.4)) * 0.04 };
+}
+
+/**
+ * The throw, as one number: 0 through the wind-up, then 0→1 over the flight.
+ * `toss` is one phase so the wind-up and the release read as one motion.
+ */
+export const TOSS_WIND_S = 0.9;
+
+export function tossProgress(local: number): { wind: number; fly: number; released: boolean } {
+ if (local < TOSS_WIND_S) {
+ // Two swings back and forth before the release.
+ return { wind: Math.sin((local / TOSS_WIND_S) * Math.PI * 2) * 0.5 + 0.5, fly: 0, released: false };
+ }
+ const fly = clamp01((local - TOSS_WIND_S) / (PHASE_SECONDS.toss - TOSS_WIND_S));
+ return { wind: 1, fly, released: true };
+}
+
+/** A ballistic arc from `from` to `to` peaking `apex` metres above the straight line. */
+export function tossArc(
+ u: number,
+ from: readonly [number, number, number],
+ to: readonly [number, number, number],
+ apex: number,
+): [number, number, number] {
+ const t = clamp01(u);
+ return [
+ from[0] + (to[0] - from[0]) * t,
+ from[1] + (to[1] - from[1]) * t + Math.sin(Math.PI * t) * apex,
+ from[2] + (to[2] - from[2]) * t,
+ ];
+}
+
+/** How much of the body is still visible as it drops into the dark, 1 → 0. */
+export function tossFade(fly: number): number {
+ // It only disappears over the last third: the mouth of the tunnel swallows it.
+ return 1 - ease(clamp01((fly - 0.66) / 0.34));
+}
+
+// ---------------------------------------------------------------------------
+// placement
+// ---------------------------------------------------------------------------
+
+/**
+ * Where the lead stands to fire: `EXECUTION_RANGE_M` in front of the
+ * condemned, on the line between them, and the heading that puts them
+ * face to face. A figure faces +Z in its own space, hence atan2(dx, dz).
+ */
+export function firingStand(
+ target: readonly [number, number],
+ from: readonly [number, number],
+): { x: number; z: number; heading: number } {
+ const dx = from[0] - target[0];
+ const dz = from[1] - target[1];
+ const len = Math.hypot(dx, dz);
+ // Degenerate (standing on the same tile): back off along +X, any side will do.
+ const ux = len > 1e-3 ? dx / len : 1;
+ const uz = len > 1e-3 ? dz / len : 0;
+ return {
+ x: target[0] + ux * EXECUTION_RANGE_M,
+ z: target[1] + uz * EXECUTION_RANGE_M,
+ heading: Math.atan2(-ux, -uz),
+ };
+}
+
+/** The heading that turns the condemned to look straight at its executioner. */
+export function facingHeading(
+ self: readonly [number, number],
+ other: readonly [number, number],
+): number {
+ return Math.atan2(other[0] - self[0], other[1] - self[1]);
+}
+
+/**
+ * Walk `distanceM` back from the END of a polyline, and return the point plus
+ * the heading a figure walking the line forwards would have there. Used for
+ * both "where do the bearers come in from" and "where does the cut drop them".
+ * A line shorter than the distance yields its first point.
+ */
+export function pointBackFrom(
+ path: ReadonlyArray<readonly [number, number]>,
+ distanceM: number,
+): { x: number; z: number; heading: number; index: number } {
+ if (path.length === 0) return { x: 0, z: 0, heading: 0, index: 0 };
+ if (path.length === 1) return { x: path[0][0], z: path[0][1], heading: 0, index: 0 };
+ let left = Math.max(0, distanceM);
+ for (let i = path.length - 1; i > 0; i--) {
+ const [ax, az] = path[i - 1];
+ const [bx, bz] = path[i];
+ const seg = Math.hypot(bx - ax, bz - az);
+ if (seg <= 1e-6) continue;
+ if (seg >= left) {
+ const t = left / seg;
+ return {
+ x: bx + (ax - bx) * t,
+ z: bz + (az - bz) * t,
+ heading: Math.atan2(bx - ax, bz - az),
+ index: i,
+ };
+ }
+ left -= seg;
+ }
+ const [x0, z0] = path[0];
+ const [x1, z1] = path[1];
+ return { x: x0, z: z0, heading: Math.atan2(x1 - x0, z1 - z0), index: 1 };
+}
+
+/** Total length of a polyline in metres. */
+export function pathLength(path: ReadonlyArray<readonly [number, number]>): number {
+ let sum = 0;
+ for (let i = 1; i < path.length; i++) {
+ sum += Math.hypot(path[i][0] - path[i - 1][0], path[i][1] - path[i - 1][1]);
+ }
+ return sum;
+}
+
+/**
+ * The two bearers' stand points: one ahead of the stretcher's centre, one
+ * behind, along the heading it is being carried on.
+ */
+export function bearerSlots(
+ centre: readonly [number, number],
+ heading: number,
+): [[number, number], [number, number]] {
+ const fx = Math.sin(heading) * STRETCHER_HALF_M;
+ const fz = Math.cos(heading) * STRETCHER_HALF_M;
+ return [
+ [centre[0] + fx, centre[1] + fz],
+ [centre[0] - fx, centre[1] - fz],
+ ];
+}
diff --git a/jarvis/ui/web/frontend/src/components/society/world/retirementRoute.ts b/jarvis/ui/web/frontend/src/components/society/world/retirementRoute.ts
new file mode 100644
index 0000000000..2feeeb400e
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/society/world/retirementRoute.ts
@@ -0,0 +1,147 @@
+/**
+ * The route half of a retirement: everything the ceremony needs to know about
+ * the island before the first frame — where the lead stops, where the body
+ * ends up, how the stretcher gets to the mine, and where the bearers come on
+ * from.
+ *
+ * Planned once, when the ceremony starts, so the choreography never re-plans
+ * mid-execution. A plan that cannot be made (a body nothing can reach, a mine
+ * with no route to it) is `null`, and the caller retires the agent without
+ * the show rather than freezing a figure on the plaza.
+ */
+import { MINE_PORTAL_DZ, MINE_PORTAL_Y } from "./Landmarks";
+import {
+ buildIsland,
+ findPath,
+ groundY,
+ isWalkable,
+ nearestWalkable,
+ smoothPath,
+ tileToWorld,
+ worldToTile,
+} from "./islandLayout";
+import {
+ BEARER_ENTRY_M,
+ EXECUTION_RANGE_M,
+ MARCH_APPROACH_M,
+ TOSS_STANDOFF_M,
+ facingHeading,
+ firingStand,
+ pathLength,
+ pointBackFrom,
+} from "./retirement";
+
+export interface RetirementPlan {
+ /** Where the lead stops to fire, and the heading that puts it face to face. */
+ stand: { x: number; z: number; heading: number };
+ /** Where the lead walks on from — MARCH_APPROACH_M back along its own route. */
+ leadStart: { x: number; z: number; heading: number };
+ /** The lead's route from `leadStart` to the stand point, in world metres. */
+ leadPath: Array<[number, number]>;
+ /** Where the body is, and the heading that has it looking at its executioner. */
+ body: { x: number; z: number; heading: number };
+ /** From the body to the throwing spot in front of the mine, world metres. */
+ carryPath: Array<[number, number]>;
+ /** Where the bearers walk on from, and their route in to the body. */
+ bearerPath: Array<[number, number]>;
+ /** The mouth of the tunnel the body is thrown into, world metres. */
+ portal: [number, number, number];
+}
+
+/** The tile a point falls on, nudged to the nearest walkable one when it is inside something. */
+function walkableTile(x: number, z: number): [number, number] | null {
+ const { map } = buildIsland();
+ const [tx, tz] = worldToTile(x, z);
+ if (isWalkable(map, tx, tz)) return [tx, tz];
+ return nearestWalkable(map, tx, tz);
+}
+
+/** A smoothed world-metre route between two points, or null when there is none. */
+function route(from: [number, number], to: [number, number]): Array<[number, number]> | null {
+ const { map } = buildIsland();
+ const a = walkableTile(from[0], from[1]);
+ const b = walkableTile(to[0], to[1]);
+ if (!a || !b) return null;
+ const raw = findPath(map, a, b);
+ if (!raw) return null;
+ return smoothPath(map, raw).map(([tx, tz]) => tileToWorld(tx, tz));
+}
+
+/** Drop the tail of a route that is already within `radius` of `target`. */
+function trimTail(
+ path: Array<[number, number]>,
+ target: readonly [number, number],
+ radius: number,
+): Array<[number, number]> {
+ let end = path.length;
+ while (end > 1 && Math.hypot(path[end - 1][0] - target[0], path[end - 1][1] - target[1]) < radius) {
+ end--;
+ }
+ return path.slice(0, end);
+}
+
+/**
+ * Plan the whole ceremony. `bodyAt` is where the condemned figure is standing
+ * when the order is given; `leadAt` is where its executioner is.
+ */
+export function planRetirement(
+ bodyAt: readonly [number, number],
+ leadAt: readonly [number, number],
+): RetirementPlan | null {
+ const { map, content } = buildIsland();
+
+ // The body stays exactly where it was ordered to stop — but never inside a
+ // building it happened to be crossing.
+ const bodyTile = walkableTile(bodyAt[0], bodyAt[1]);
+ if (!bodyTile) return null;
+ const bodyWorld = isWalkable(map, ...worldToTile(bodyAt[0], bodyAt[1]))
+ ? ([bodyAt[0], bodyAt[1]] as [number, number])
+ : tileToWorld(bodyTile[0], bodyTile[1]);
+
+ const stand = firingStand(bodyWorld, leadAt);
+ const body = {
+ x: bodyWorld[0],
+ z: bodyWorld[1],
+ heading: facingHeading(bodyWorld, [stand.x, stand.z]),
+ };
+
+ const leadRoute = route([leadAt[0], leadAt[1]], bodyWorld);
+ if (!leadRoute) return null;
+ const fullLead: Array<[number, number]> = [
+ ...trimTail(leadRoute.slice(1), bodyWorld, EXECUTION_RANGE_M),
+ [stand.x, stand.z],
+ ];
+ // Open with the lead already on its way in, so the walk is a few seconds
+ // rather than a march across the island.
+ const onset = pointBackFrom(fullLead, MARCH_APPROACH_M);
+ const leadStart =
+ pathLength(fullLead) > MARCH_APPROACH_M
+ ? { x: onset.x, z: onset.z, heading: onset.heading }
+ : { x: leadAt[0], z: leadAt[1], heading: onset.heading };
+ const leadPath: Array<[number, number]> =
+ pathLength(fullLead) > MARCH_APPROACH_M ? fullLead.slice(onset.index) : fullLead;
+
+ // The mine: the throwing spot sits on the forecourt, straight out from the
+ // tunnel mouth. The rail head right in front of the portal blocks pathing,
+ // so the route ends on the forecourt and the last step is walked free.
+ const [mtx, mtz] = content.places.mine.tile;
+ const [mx, mz] = tileToWorld(mtx, mtz);
+ const portalZ = mz + MINE_PORTAL_DZ;
+ const portal: [number, number, number] = [mx, groundY(map, mx, mz) + MINE_PORTAL_Y, portalZ];
+ const tossSpot: [number, number] = [mx, portalZ + TOSS_STANDOFF_M];
+
+ const mineRoute = route(bodyWorld, tossSpot);
+ if (!mineRoute) return null;
+ const carryPath: Array<[number, number]> = [...trimTail(mineRoute, tossSpot, 1.5), tossSpot];
+
+ // The bearers come on from further down the same road they will carry the
+ // body back along — they are the mine's crew, so that is where they are.
+ const total = pathLength(carryPath);
+ const entry = pointBackFrom(carryPath, Math.max(0, total - BEARER_ENTRY_M));
+ const bearerPath: Array<[number, number]> = [
+ ...carryPath.slice(0, entry.index).reverse(),
+ [body.x, body.z],
+ ];
+
+ return { stand, leadStart, leadPath, body, carryPath, bearerPath, portal };
+}
diff --git a/jarvis/ui/web/frontend/src/components/society/world/worldMaterials.ts b/jarvis/ui/web/frontend/src/components/society/world/worldMaterials.ts
index 85231556f3..0beb05be57 100644
--- a/jarvis/ui/web/frontend/src/components/society/world/worldMaterials.ts
+++ b/jarvis/ui/web/frontend/src/components/society/world/worldMaterials.ts
@@ -24,7 +24,7 @@ import {
import { RoundedBoxGeometry } from "three/examples/jsm/geometries/RoundedBoxGeometry.js";
import { mergeGeometries } from "three/examples/jsm/utils/BufferGeometryUtils.js";
-import { BUILDING, NATURE } from "./worldPalette";
+import { BUILDING, CEREMONY, NATURE } from "./worldPalette";
/**
* The four-step light ramp every lit object shares (world-masterplan-v2.md §3.4):
@@ -194,4 +194,4 @@ export function useWorldGeometries(): WorldGeometries {
}
/** The palette entries most components reach for, re-exported for brevity. */
-export const PAL = { ...BUILDING, ...NATURE };
+export const PAL = { ...BUILDING, ...NATURE, ...CEREMONY };
diff --git a/jarvis/ui/web/frontend/src/components/society/world/worldPalette.ts b/jarvis/ui/web/frontend/src/components/society/world/worldPalette.ts
index 5c390e6a4a..56870a0b19 100644
--- a/jarvis/ui/web/frontend/src/components/society/world/worldPalette.ts
+++ b/jarvis/ui/web/frontend/src/components/society/world/worldPalette.ts
@@ -139,6 +139,26 @@ export const NATURE = {
bench: "#a9723a",
};
+/**
+ * The retirement ceremony (`retirement.ts`): the muzzle flash, the stretcher
+ * the bearers carry, and the mark the body leaves on the ground. Its own
+ * block because none of it belongs to a building or to the landscape.
+ */
+export const CEREMONY = {
+ /** The flash at the barrel — hot white with a warm edge. */
+ muzzle: "#ffe9a8",
+ /** The stretcher's poles. */
+ stretcherPole: "#6b4a2a",
+ /** The canvas slung between them. */
+ stretcherCloth: "#c9c0ac",
+ /** The bearers' work clothes. */
+ bearerCloth: "#4a4f5c",
+ bearerTrim: "#2f333c",
+ bearerLamp: "#ffd98a",
+ /** What is left on the ground where the body fell. Dark, not lurid. */
+ stain: "#4a1418",
+};
+
/** In-world labels (drawn as DOM over the canvas, in the world's own type). */
export const LABEL = {
font: '"Pixelify Sans", "Inter Variable", "Inter", ui-sans-serif, sans-serif',