@cs2dak/core 1.0.0 → 2.0.0

package/src/spatial/annotate.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+import type { DemoPackage, Replay } from "@cs2dak/contract";
+import type { MapZones } from "@cs2dak/maps";
+import { annotatePositions, groupSamplesByRoundTick, loadSpatialAssets, type SpatialAssets } from "./annotate.js";
+
+function deltaArr(values: number[]): number[] {
+  const out: number[] = [];
+  let prev = 0;
+  for (const v of values) { out.push(v - prev); prev = v; }
+  return out;
+}
+
+/** Build a replay round with one (or more) player tracks at a single tick. */
+function replayRound(
+  tick: number,
+  tracks: { playerIdx: number; x: number; y: number; z: number; placeIdx: number }[],
+): Replay["rounds"][number] {
+  return {
+    roundNumber: 1,
+    startTick: tick,
+    tickStep: 8,
+    frameCount: 1,
+    players: tracks.map((t) => ({
+      playerIndex: t.playerIdx,
+      x: deltaArr([t.x]), y: deltaArr([t.y]), z: deltaArr([t.z]),
+      yaw: deltaArr([0]), pitch: deltaArr([0]),
+      hp: [100], armor: [100], money: [800], equipValue: [800],
+      place: [t.placeIdx], flash: [0],
+      flags: [1],
+      weapon: [-1],
+      grenades: [[]],
+    })),
+    projectiles: [],
+  };
+}
+
+function pkgWith(mapName: string, rows: { place: string; x: number; y: number; z: number }[]): DemoPackage {
+  const placeDict = [...new Set(rows.map((r) => r.place))];
+  const placeMap = new Map(placeDict.map((p, i) => [p, i]));
+  const tracks = rows.map((r, i) => ({
+    playerIdx: Math.min(i, 1), // player 0 or 1
+    x: r.x, y: r.y, z: r.z,
+    placeIdx: placeMap.get(r.place) ?? -1,
+  }));
+  return {
+    match: { mapName, tickrate: 64 },
+    players: [
+      { steamId64: "T1", teamKey: "teamA" },
+      rows.length > 1 ? { steamId64: "T2", teamKey: "teamA" } : { steamId64: "T2", teamKey: "teamA" },
+    ],
+    rounds: [{ roundNumber: 1, startTick: 1, freezeEndTick: 100, endTick: 2000, teamASide: "t", teamBSide: "ct" }],
+    replay: {
+      meta: { sampleRate: 8, tickrate: 64, coordScale: 1, angleScale: 10 },
+      weaponDict: [],
+      placeDict,
+      rounds: [replayRound(120, tracks)],
+    },
+  } as unknown as DemoPackage;
+}
+
+/** Create a package with no replay data (simulates unobservable positions). */
+function pkgWithoutReplay(): DemoPackage {
+  return {
+    match: { mapName: "de_dust2", tickrate: 64 },
+    players: [{ steamId64: "T1", teamKey: "teamA" }],
+    rounds: [{ roundNumber: 1, startTick: 1, freezeEndTick: 100, endTick: 2000, teamASide: "t", teamBSide: "ct" }],
+  } as unknown as DemoPackage;
+}
+
+describe("loadSpatialAssets", () => {
+  it("reports availability per asset for an active-duty map", () => {
+    const assets = loadSpatialAssets("de_dust2");
+    expect(assets.available.routes).toBe(true);
+    expect(assets.available.nav).toBe(true);
+    expect(assets.available.visibility).toBe(false); // no .tri passed
+  });
+
+  it("reports everything missing for an unknown map", () => {
+    const assets = loadSpatialAssets("de_unknown");
+    expect(assets.available.routes).toBe(false);
+    expect(assets.available.nav).toBe(false);
+  });
+});
+
+describe("annotatePositions", () => {
+  it("attaches callout and position from replay when nav is available", () => {
+    const assets = loadSpatialAssets("de_dust2");
+    const samples = annotatePositions(pkgWith("de_dust2", [{ place: "LongA", x: 760, y: 1660, z: 0 }]), assets);
+    expect(samples).toHaveLength(1);
+    expect(samples[0]!.callout).toBe("LongA");
+    expect(samples[0]!.position).toEqual({ x: 760, y: 1660, z: 0 });
+  });
+
+  it("leaves navAreaId null when nav is unavailable", () => {
+    const assets = loadSpatialAssets("de_unknown");
+    const samples = annotatePositions(pkgWith("de_unknown", [{ place: "Somewhere", x: 0, y: 0, z: 0 }]), assets);
+    expect(samples).toHaveLength(1);
+    expect(samples[0]!.navAreaId).toBeNull();
+    expect(samples[0]!.callout).toBe("Somewhere");
+  });
+
+  it("returns an empty array without positions", () => {
+    const assets = loadSpatialAssets("de_dust2");
+    expect(annotatePositions(pkgWithoutReplay(), assets)).toEqual([]);
+  });
+
+  it("groups samples by round then tick", () => {
+    const assets = loadSpatialAssets("de_dust2");
+    const samples = annotatePositions(
+      pkgWith("de_dust2", [{ place: "LongA", x: 760, y: 1660, z: 0 }, { place: "TSpawn", x: -500, y: -850, z: 96 }]),
+      assets,
+    );
+    const grouped = groupSamplesByRoundTick(samples);
+    expect(grouped.get(1)!.get(120)!).toHaveLength(2);
+  });
+
+  it("populates zoneId/zoneRole/zoneBombsite via zoneAt when zones are available", () => {
+    const TEST_ZONES: MapZones = {
+      mapName: "de_test",
+      version: "t",
+      zones: [{ id: "a_site", name: "A", role: "site", bombsite: "a", polygon: [[0, 0], [100, 0], [100, 100], [0, 100]] }],
+    };
+    const assets: SpatialAssets = {
+      mapName: "de_test", routes: null, zones: TEST_ZONES, nav: null, visibility: null,
+      available: { routes: false, zones: true, nav: false, visibility: false },
+    };
+    const samples = annotatePositions(pkgWith("de_test", [{ place: "A", x: 50, y: 50, z: 0 }]), assets);
+    expect(samples).toHaveLength(1);
+    expect(samples[0]!.zoneId).toBe("a_site");
+    expect(samples[0]!.zoneRole).toBe("site");
+    expect(samples[0]!.zoneBombsite).toBe("a");
+  });
+});

package/src/spatial/annotate.ts

@@ -0,0 +1,163 @@
+/**
+ * Raw evidence 地基：位置标注 + 空间资产装载（严格重建 SP1）。
+ * 设计见 docs/design/rr-model.md §3、§5（计算流程）。
+ *
+ * 当前控图/战术语义真相源是 replay place 生成的 callout grid，不是手标 zone polygon。
+ * zone 字段只保留给旧 shadow spatial/utility 几何路径；新增控图 finding 不应消费 zoneId。
+ * 这些是 official MapControl gate（SP2：solo pressure 的 nav 距离、denial 的 LOS）的输入底座。
+ *
+ * v3 replay 8Hz 流替代了 v2 的 positions-1s。每帧解码后转换：
+ * - track.tick（差分编码 → decodeDelta）
+ * - track.x/y/z（差分编码 × coordScale → 游戏单位）
+ * - track.place（索引 → placeDict）
+ * - track.flags（FLAG_ALIVE）
+ * - track.hp（原始值）
+ */
+import type { DemoPackage } from "@cs2dak/contract";
+import { decodeDelta, FLAG_ALIVE } from "@cs2dak/contract";
+import { createResolverFromPackage } from "../resolve.js";
+import {
+  getMapNav,
+  getMapRoutes,
+  getMapZones,
+  zoneAt,
+  type CompactNav,
+  type MapRoutes,
+  type MapZones,
+  type TriangleBvh,
+  type Vec3,
+  type ZoneRole,
+} from "@cs2dak/maps";
+
+export interface SpatialAssets {
+  mapName: string;
+  routes: MapRoutes | null;
+  zones: MapZones | null;
+  nav: CompactNav | null;
+  /** 静态视线 BVH；Node 下经 tri-assets 装载，浏览器降级为 null。 */
+  visibility: TriangleBvh | null;
+  available: {
+    routes: boolean;
+    zones: boolean;
+    nav: boolean;
+    visibility: boolean;
+  };
+}
+
+export function loadSpatialAssets(mapName: string, triBvh?: TriangleBvh | null): SpatialAssets {
+  const routes = getMapRoutes(mapName);
+  const zones = getMapZones(mapName);
+  const nav = getMapNav(mapName);
+  const visibility = triBvh ?? null;
+  return {
+    mapName,
+    routes,
+    zones,
+    nav,
+    visibility,
+    available: {
+      routes: routes != null,
+      zones: zones != null,
+      nav: nav != null,
+      visibility: visibility != null,
+    },
+  };
+}
+
+export interface AnnotatedSample {
+  roundNumber: number;
+  tick: number;
+  steamId64: string;
+  teamKey: string;
+  side: string | null;
+  alive: boolean;
+  position: Vec3;
+  /** callout（replay placeDict）；缺失为 null。 */
+  callout: string | null;
+  /** legacy 手标 zone id；当前控图/战术语义不要把它当真相源。 */
+  zoneId: string | null;
+  /** zone 语义角色（site/mid/connector/lane…）；无 zone 为 null。 */
+  zoneRole: ZoneRole | null;
+  /** zone 关联包点；无则 null。 */
+  zoneBombsite: "a" | "b" | null;
+  /** 最近 nav area id；无 nav 资产为 null。 */
+  navAreaId: number | null;
+  /** 当前血量（火焰逼退掉血判定用）；缺失为 100。 */
+  health: number;
+}
+
+/**
+ * 从 replay 8Hz 流标注位置样本（v3 替代 v2 positions-1s）。
+ * 返回所有存活/阵亡玩家的逐帧标注，zone/nav 判定暂缺（需 maps 包导出 zoneAt/nearestNavArea）。
+ */
+export function annotatePositions(pkg: DemoPackage, assets: SpatialAssets): AnnotatedSample[] {
+  const resolver = createResolverFromPackage(pkg);
+  const replay = pkg.replay;
+  if (!replay) return [];
+
+  const coordScale = replay.meta.coordScale;
+  const placeDict = replay.placeDict ?? [];
+  const samples: AnnotatedSample[] = [];
+
+  const roundByNumber = new Map(pkg.rounds.map((r) => [r.roundNumber, r]));
+
+  for (const round of replay.rounds) {
+    const roundRow = roundByNumber.get(round.roundNumber);
+    if (!roundRow) continue;
+    const tickStep = round.tickStep;
+
+    for (const track of round.players) {
+      const player = resolver.byIndexOrNull(track.playerIndex);
+      if (!player) continue;
+
+      const xs = decodeDelta(track.x);
+      const ys = decodeDelta(track.y);
+      const zs = decodeDelta(track.z);
+      const side: string | null =
+        player.teamKey === "teamA" ? roundRow.teamASide : roundRow.teamBSide;
+
+      for (let i = 0; i < xs.length; i++) {
+        const placeIdx = track.place[i] ?? -1;
+        const px = (xs[i] ?? 0) * coordScale;
+        const py = (ys[i] ?? 0) * coordScale;
+        const pz = (zs[i] ?? 0) * coordScale;
+        const zone = assets.zones ? zoneAt(assets.zones, px, py, pz) : null;
+        samples.push({
+          roundNumber: round.roundNumber,
+          tick: round.startTick + i * tickStep,
+          steamId64: player.steamId64,
+          teamKey: player.teamKey,
+          side,
+          alive: ((track.flags[i] ?? 0) & FLAG_ALIVE) !== 0,
+          position: { x: px, y: py, z: pz },
+          callout: placeIdx >= 0 && placeIdx < placeDict.length ? placeDict[placeIdx] : null,
+          zoneId: zone?.id ?? null,
+          zoneRole: (zone?.role as ZoneRole | undefined) ?? null,
+          zoneBombsite: (zone?.bombsite as "a" | "b" | undefined) ?? null,
+          navAreaId: null,
+          health: track.hp[i] ?? 100,
+        });
+      }
+    }
+  }
+
+  return samples;
+}
+
+/** 按 (round, tick) 分组的标注样本，供逐帧 gate 消费。 */
+export function groupSamplesByRoundTick(
+  samples: AnnotatedSample[],
+): Map<number, Map<number, AnnotatedSample[]>> {
+  const out = new Map<number, Map<number, AnnotatedSample[]>>();
+  for (const s of samples) {
+    let byTick = out.get(s.roundNumber);
+    if (!byTick) {
+      byTick = new Map();
+      out.set(s.roundNumber, byTick);
+    }
+    const arr = byTick.get(s.tick) ?? [];
+    arr.push(s);
+    byTick.set(s.tick, arr);
+  }
+  return out;
+}

package/src/spatial/index.ts

@@ -0,0 +1,16 @@
+/**
+ * 空间分析（严格重建）。两层：raw evidence（宽，复盘/shadow） → official gated（窄，进 RR）。
+ * 设计与边界见 docs/design/rr-model.md §3。
+ *
+ * SP1（已落地）：RoundPhase 模型 + 位置标注地基。
+ * SP2/SP3（计划）：official MapControl / UtilitySpatial gates + strategicIsolationDeathCredits。
+ */
+export type { RoundPhase, RoundPhaseModel } from "./types.js";
+export { OFFICIAL_EXCLUDED_PHASES, isOfficialScoringPhase } from "./types.js";
+export { inferRoundPhases, phaseAtTick } from "./phase.js";
+export type { SpatialAssets, AnnotatedSample } from "./annotate.js";
+export { loadSpatialAssets, annotatePositions, groupSamplesByRoundTick } from "./annotate.js";
+export type { OfficialMapControl } from "./mapcontrol.js";
+export { buildOfficialMapControl } from "./mapcontrol.js";
+export type { OfficialUtilitySpatial, UtilityWindow, GrenadeType } from "./utility.js";
+export { buildOfficialUtilitySpatial, buildUtilityWindows } from "./utility.js";

package/src/spatial/mapcontrol.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import type { DemoPackage, Replay } from "@cs2dak/contract";
+import { loadSpatialAssets } from "./annotate.js";
+import { buildOfficialMapControl } from "./mapcontrol.js";
+
+function deltaArr(values: number[]): number[] {
+  const out: number[] = [];
+  let prev = 0;
+  for (const v of values) { out.push(v - prev); prev = v; }
+  return out;
+}
+
+function replayTracks(t1Places: string[], idxByPlace: Map<string, number>) {
+  return [
+    {
+      playerIndex: 0,
+      x: deltaArr([0, 0, 0, 0]), y: deltaArr([0, 0, 0, 0]), z: deltaArr([0, 0, 0, 0]),
+      yaw: deltaArr([0, 0, 0, 0]), pitch: deltaArr([0, 0, 0, 0]),
+      hp: [100, 100, 100, 100], armor: [100, 100, 100, 100],
+      money: [800, 800, 800, 800], equipValue: [800, 800, 800, 800],
+      weapon: [-1, -1, -1, -1],
+      place: t1Places.map((p) => idxByPlace.get(p) ?? -1),
+      flash: [0, 0, 0, 0], flags: [1, 1, 1, 1],
+    },
+    {
+      playerIndex: 1,
+      x: deltaArr([0, 0, 0, 0]), y: deltaArr([0, 0, 0, 0]), z: deltaArr([0, 0, 0, 0]),
+      yaw: deltaArr([0, 0, 0, 0]), pitch: deltaArr([0, 0, 0, 0]),
+      hp: [100, 100, 100, 100], armor: [100, 100, 100, 100],
+      money: [800, 800, 800, 800], equipValue: [800, 800, 800, 800],
+      weapon: [-1, -1, -1, -1],
+      place: [idxByPlace.get("TSpawn")!, idxByPlace.get("TSpawn")!, idxByPlace.get("TSpawn")!, idxByPlace.get("TSpawn")!],
+      flash: [0, 0, 0, 0], flags: [1, 1, 1, 1],
+    },
+    {
+      playerIndex: 2,
+      x: deltaArr([0, 0, 0, 0]), y: deltaArr([0, 0, 0, 0]), z: deltaArr([0, 0, 0, 0]),
+      yaw: deltaArr([0, 0, 0, 0]), pitch: deltaArr([0, 0, 0, 0]),
+      hp: [100, 100, 100, 100], armor: [100, 100, 100, 100],
+      money: [800, 800, 800, 800], equipValue: [800, 800, 800, 800],
+      weapon: [-1, -1, -1, -1],
+      place: [idxByPlace.get("BombsiteA")!, idxByPlace.get("BombsiteA")!, idxByPlace.get("BombsiteA")!, idxByPlace.get("BombsiteA")!],
+      flash: [0, 0, 0, 0], flags: [1, 1, 1, 1],
+    },
+    {
+      playerIndex: 3,
+      x: deltaArr([0, 0, 0, 0]), y: deltaArr([0, 0, 0, 0]), z: deltaArr([0, 0, 0, 0]),
+      yaw: deltaArr([0, 0, 0, 0]), pitch: deltaArr([0, 0, 0, 0]),
+      hp: [100, 100, 100, 100], armor: [100, 100, 100, 100],
+      money: [800, 800, 800, 800], equipValue: [800, 800, 800, 800],
+      weapon: [-1, -1, -1, -1],
+      place: [idxByPlace.get("CTSpawn")!, idxByPlace.get("CTSpawn")!, idxByPlace.get("CTSpawn")!, idxByPlace.get("CTSpawn")!],
+      flash: [0, 0, 0, 0], flags: [1, 1, 1, 1],
+    },
+  ];
+}
+
+/** T1 独推 a_long（LongDoors→ARamp），T2 留 TSpawn，C1 守 BombsiteA（同线施压），C2 离线。 */
+function makePkg(over: { kills?: unknown[] } = {}): DemoPackage {
+  const t1 = ["LongDoors", "LongA", "ARamp", "ARamp"];
+  const allPlaces = [...new Set([...t1, "TSpawn", "BombsiteA", "CTSpawn"])];
+  const idxByPlace = new Map(allPlaces.map((p, i) => [p, i]));
+  return {
+    match: { mapName: "de_dust2", tickrate: 64 },
+    players: [
+      { steamId64: "T1", teamKey: "teamA" },
+      { steamId64: "T2", teamKey: "teamA" },
+      { steamId64: "C1", teamKey: "teamB" },
+      { steamId64: "C2", teamKey: "teamB" },
+    ],
+    rounds: [{ roundNumber: 1, startTick: 1, freezeEndTick: 100, endTick: 2000, teamASide: "t", teamBSide: "ct" }],
+    bombs: [],
+    kills: over.kills ?? [],
+    replay: {
+      meta: { sampleRate: 1, tickrate: 64, coordScale: 1, angleScale: 10 },
+      weaponDict: [],
+      placeDict: allPlaces,
+      rounds: [{
+        roundNumber: 1,
+        startTick: 150,
+        tickStep: 64,
+        frameCount: 4,
+        players: replayTracks(t1, idxByPlace) as unknown as Replay["rounds"][number]["players"],
+        projectiles: [],
+      }],
+    },
+  } as unknown as DemoPackage;
+}
+
+const untradedDeath = [{ roundNumber: 1, tick: 410, killerIndex: 2, victimIndex: 0, victimSteamId64: "T1", victimTeamKey: "teamA", killerSteamId64: "C1", killerTeamKey: "teamB", tradeDeath: false, weapon: "ak47", headshot: false }];
+
+describe("buildOfficialMapControl", () => {
+  it("accumulates activeSoloPressureSeconds for a lone route pusher with enemy on the lane", () => {
+    const mc = buildOfficialMapControl(makePkg(), loadSpatialAssets("de_dust2"));
+    expect(mc.get("T1")!.activeSoloPressureSeconds).toBe(4); // 4 个 1Hz 样本
+    expect(mc.get("T2")?.activeSoloPressureSeconds ?? 0).toBe(0); // 始终在 TSpawn，未上线
+  });
+
+  it("accumulates denial for the defending anchor and firstControl for the pusher", () => {
+    const mc = buildOfficialMapControl(makePkg(), loadSpatialAssets("de_dust2"));
+    // C1 守 BombsiteA（a_long 末端）、T1 同线施压、无 plant → CT 防守 → C1 计 denial
+    expect(mc.get("C1")!.sidePhaseAwareDenialSeconds).toBeGreaterThan(0);
+    // T1 推进到 a_long 关键段（LongA idx3 ≥ ceil(6×0.4)=3）→ firstControl 一次
+    expect(mc.get("T1")!.firstMeaningfulControlEvents).toBe(1);
+    // T1 是进攻方，非防守 → 无 denial
+    expect(mc.get("T1")!.sidePhaseAwareDenialSeconds).toBe(0);
+  });
+
+  it("awards strategicIsolationDeaths credit for an untraded death after sustained solo pressure", () => {
+    const mc = buildOfficialMapControl(makePkg({ kills: untradedDeath }), loadSpatialAssets("de_dust2"));
+    // credit = clamp(0.25 + 0.10×4, 0, 1) = 0.65
+    expect(mc.get("T1")!.strategicIsolationDeaths).toBeCloseTo(0.65, 3);
+  });
+
+  it("gives no credit when the death was traded", () => {
+    const traded = [{ ...untradedDeath[0], tradeDeath: true }];
+    const mc = buildOfficialMapControl(makePkg({ kills: traded }), loadSpatialAssets("de_dust2"));
+    expect(mc.get("T1")?.strategicIsolationDeaths ?? 0).toBe(0);
+  });
+
+  it("gives no credit when there was no prior solo pressure (TSpawn camper)", () => {
+    const death = [{ roundNumber: 1, tick: 410, killerIndex: 2, victimIndex: 1, victimSteamId64: "T2", victimTeamKey: "teamA", killerSteamId64: "C1", killerTeamKey: "teamB", tradeDeath: false, weapon: "ak47", headshot: false }];
+    const mc = buildOfficialMapControl(makePkg({ kills: death }), loadSpatialAssets("de_dust2"));
+    expect(mc.get("T2")?.strategicIsolationDeaths ?? 0).toBe(0);
+  });
+
+  it("returns an empty map without route assets", () => {
+    const mc = buildOfficialMapControl(makePkg(), loadSpatialAssets("de_unknown"));
+    expect(mc.size).toBe(0);
+  });
+});