@cs2dak/core 1.0.0 → 2.0.0

package/src/spatial/types.ts

@@ -0,0 +1,56 @@
+/**
+ * 空间分析的共享类型（严格重建 SP1）。
+ * 设计约束见 docs/design/rr-model.md §3。
+ *
+ * 两层结构：raw evidence（宽，复盘/shadow） → official gated features（窄，进 RR）。
+ * 本文件定义 phase 模型与 raw evidence 的形状；official 派生在后续 sub-project。
+ */
+
+/** 回合阶段。official scoring 排除 freeze / save / exit（见 OFFICIAL_EXCLUDED_PHASES）。 */
+export type RoundPhase =
+  | "freeze"
+  | "default"
+  | "take"
+  | "execute"
+  | "postPlant"
+  | "retake"
+  | "save"
+  | "exit"
+  | "clutch";
+
+/** save / exit / freeze 默认不进 official MapControl/UtilitySpatial（仍进 review 层）。 */
+export const OFFICIAL_EXCLUDED_PHASES: ReadonlySet<RoundPhase> = new Set<RoundPhase>([
+  "freeze",
+  "save",
+  "exit",
+]);
+
+export function isOfficialScoringPhase(phase: RoundPhase): boolean {
+  return !OFFICIAL_EXCLUDED_PHASES.has(phase);
+}
+
+/**
+ * 单回合的阶段关键 tick。phase 用 `phaseAtTick` 从这些边界派生，保持可序列化、无函数。
+ *
+ * MVP 覆盖：freeze / default / take / execute / postPlant / clutch（均可从
+ * rounds + bombs + kills（+ 可选 positions/routes）确定性派生）。
+ * retake / save / exit 留待后续细化——当前 postPlant 窗口对双方通用，
+ * side-aware gate 自行区分 T 守包 vs CT retake。
+ */
+export interface RoundPhaseModel {
+  roundNumber: number;
+  startTick: number;
+  freezeEndTick: number;
+  endTick: number;
+  /** 炸弹安放 tick；未安放为 null。 */
+  plantTick: number | null;
+  /** T 首次推进到出生区外（routeIndex ≥ 1）的 tick；无 positions/routes 时 null。 */
+  takeTick: number | null;
+  /** 多名 T 逼近包点入口或多颗进攻道具生效的 tick；无证据时 null。 */
+  executeTick: number | null;
+  /** 一方仅剩 1 人存活（另一方 ≥ 1）的首个 tick；未进入残局为 null。 */
+  clutchStartTick: number | null;
+  /** 阶段证据质量：positions/routes 是否可用（影响 take/execute 是否可信）。 */
+  hasPositions: boolean;
+  hasRoutes: boolean;
+}

package/src/spatial/utility-geometry.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import type { CompactNav, MapZone } from "@cs2dak/maps";
+import {
+  areasWithinRadius,
+  buildNavIndex,
+  navPathCost,
+  nearestAreaId,
+  polygonCentroid,
+  segmentSphereIntersects,
+  smokeDetourCost,
+} from "./utility-geometry.js";
+
+const v = (x: number, y: number, z = 0) => ({ x, y, z });
+
+describe("segmentSphereIntersects", () => {
+  it("hits a sphere on the segment path", () => {
+    expect(segmentSphereIntersects(v(0, 0), v(100, 0), v(50, 10), 20)).toBe(true);
+  });
+  it("misses a sphere far from the segment", () => {
+    expect(segmentSphereIntersects(v(0, 0), v(100, 0), v(50, 200), 20)).toBe(false);
+  });
+  it("hits when an endpoint is inside the sphere", () => {
+    expect(segmentSphereIntersects(v(0, 0), v(100, 0), v(105, 0), 10)).toBe(true);
+  });
+  it("misses past the segment end (clamped)", () => {
+    expect(segmentSphereIntersects(v(0, 0), v(100, 0), v(200, 0), 10)).toBe(false);
+  });
+});
+
+describe("polygonCentroid", () => {
+  it("returns the center of a square", () => {
+    const zone = { id: "z", name: "z", role: "site", polygon: [[0, 0], [100, 0], [100, 100], [0, 100]] } as unknown as MapZone;
+    const c = polygonCentroid(zone);
+    expect(c.x).toBeCloseTo(50, 5);
+    expect(c.y).toBeCloseTo(50, 5);
+  });
+});
+
+/** 线性 nav：A(0)-B(100)-C(200)-D(300)，外加旁路 B-E(100,200)-C 绕远。 */
+function lineNav(): CompactNav {
+  return {
+    mapName: "de_test", buildId: 0, sourceFormat: { version: 0, subVersion: 0 },
+    areas: [
+      { id: 0, corners: [], centroid: v(0, 0), neighbors: [1] },
+      { id: 1, corners: [], centroid: v(100, 0), neighbors: [0, 2, 4] },
+      { id: 2, corners: [], centroid: v(200, 0), neighbors: [1, 3, 4] },
+      { id: 3, corners: [], centroid: v(300, 0), neighbors: [2] },
+      { id: 4, corners: [], centroid: v(150, 300), neighbors: [1, 2] }, // 旁路（绕远）
+    ],
+  } as unknown as CompactNav;
+}
+
+describe("navPathCost + smokeDetourCost", () => {
+  it("computes straight-line path cost", () => {
+    const idx = buildNavIndex(lineNav());
+    expect(navPathCost(idx, 0, 3)).toBeCloseTo(300, 3); // 0→1→2→3
+  });
+  it("returns null when blocked with no alternative", () => {
+    const idx = buildNavIndex(lineNav());
+    // 屏蔽 1 → 0 无法到达任何地方（0 只连 1）
+    expect(navPathCost(idx, 0, 3, new Set([1]))).toBeNull();
+  });
+  it("smoke detour: blocking the direct hop forces the long way around", () => {
+    const idx = buildNavIndex(lineNav());
+    // 屏蔽 2（直线中段）→ 1→4→2 不行（2 也被屏蔽），但 1→4→? ... 改测屏蔽直连边场景：
+    // 屏蔽节点 2 后从 1 到 3：1→4→2(blocked) 无效 → 实际不可达 → detour=base（全额）
+    const detour = smokeDetourCost(idx, 1, 3, new Set([2]));
+    expect(detour).toBeGreaterThan(0);
+  });
+  it("smoke detour is 0 when smoke does not lie on the path", () => {
+    const idx = buildNavIndex(lineNav());
+    expect(smokeDetourCost(idx, 0, 3, new Set([4]))).toBe(0); // 旁路被屏蔽不影响直线
+  });
+});
+
+describe("nearestAreaId + areasWithinRadius", () => {
+  it("finds the nearest area", () => {
+    const idx = buildNavIndex(lineNav());
+    expect(nearestAreaId(idx, v(190, 5))).toBe(2);
+  });
+  it("collects areas within a radius", () => {
+    const idx = buildNavIndex(lineNav());
+    const within = areasWithinRadius(idx, v(100, 0), 110);
+    expect(within.has(1)).toBe(true); // 距 0
+    expect(within.has(0)).toBe(true); // 距 100
+    expect(within.has(3)).toBe(false); // 距 200 > 110
+  });
+});

package/src/spatial/utility-geometry.ts

@@ -0,0 +1,167 @@
+/**
+ * UtilitySpatial 几何地基（SP3 v2）。纯几何 + nav 拓扑，可独立单测，不依赖 demo。
+ * 供烟雾视线封锁（segment-sphere）与烟雾隔离（nav 绕路代价）使用。
+ */
+import type { CompactNav, MapZone, Vec3 } from "@cs2dak/maps";
+
+/** CS2 道具有效半径（世界单位，近似）。烟雾球 ~144、火焰面 ~150。 */
+export const SMOKE_RADIUS = 144;
+export const FIRE_RADIUS = 150;
+
+/** 线段 AB 是否穿过以 center 为心、radius 为半径的球（即最近点距离 < radius）。 */
+export function segmentSphereIntersects(a: Vec3, b: Vec3, center: Vec3, radius: number): boolean {
+  const abx = b.x - a.x, aby = b.y - a.y, abz = b.z - a.z;
+  const apx = center.x - a.x, apy = center.y - a.y, apz = center.z - a.z;
+  const abLen2 = abx * abx + aby * aby + abz * abz;
+  let t = abLen2 > 0 ? (apx * abx + apy * aby + apz * abz) / abLen2 : 0;
+  t = Math.max(0, Math.min(1, t));
+  const cx = a.x + abx * t, cy = a.y + aby * t, cz = a.z + abz * t;
+  const dx = center.x - cx, dy = center.y - cy, dz = center.z - cz;
+  return dx * dx + dy * dy + dz * dz <= radius * radius;
+}
+
+/** 多边形质心（XY，世界坐标）。退化时回退到顶点平均。 */
+export function polygonCentroid(zone: MapZone): { x: number; y: number } {
+  const p = zone.polygon;
+  let area = 0, cx = 0, cy = 0;
+  for (let i = 0, j = p.length - 1; i < p.length; j = i++) {
+    const [xi, yi] = p[i]!;
+    const [xj, yj] = p[j]!;
+    const cross = xj * yi - xi * yj;
+    area += cross;
+    cx += (xi + xj) * cross;
+    cy += (yi + yj) * cross;
+  }
+  if (Math.abs(area) < 1e-6) {
+    const n = p.length || 1;
+    return { x: p.reduce((s, q) => s + q[0], 0) / n, y: p.reduce((s, q) => s + q[1], 0) / n };
+  }
+  area *= 0.5;
+  return { x: cx / (6 * area), y: cy / (6 * area) };
+}
+
+/** nav 索引：id → area，邻接 + 质心，供 Dijkstra 复用（避免每次线性扫）。 */
+export interface NavIndex {
+  byId: Map<number, { centroid: Vec3; neighbors: number[] }>;
+}
+
+export function buildNavIndex(nav: CompactNav): NavIndex {
+  const byId = new Map<number, { centroid: Vec3; neighbors: number[] }>();
+  for (const area of nav.areas) {
+    byId.set(area.id, { centroid: area.centroid, neighbors: area.neighbors });
+  }
+  return byId.size ? { byId } : { byId };
+}
+
+/** 最近 nav area id（按质心欧氏距离）。 */
+export function nearestAreaId(index: NavIndex, point: Vec3): number | null {
+  let best: number | null = null;
+  let bestD = Infinity;
+  for (const [id, a] of index.byId) {
+    const dx = a.centroid.x - point.x, dy = a.centroid.y - point.y, dz = a.centroid.z - point.z;
+    const d = dx * dx + dy * dy + dz * dz;
+    if (d < bestD) { bestD = d; best = id; }
+  }
+  return best;
+}
+
+/** 质心落在 center 半径内的 nav area 集合（烟/火覆盖的可达区域）。 */
+export function areasWithinRadius(index: NavIndex, center: Vec3, radius: number): Set<number> {
+  const out = new Set<number>();
+  const r2 = radius * radius;
+  for (const [id, a] of index.byId) {
+    const dx = a.centroid.x - center.x, dy = a.centroid.y - center.y, dz = a.centroid.z - center.z;
+    if (dx * dx + dy * dy + dz * dz <= r2) out.add(id);
+  }
+  return out;
+}
+
+/**
+ * nav 最短路径代价（沿邻接、质心欧氏距离加权的 Dijkstra），可屏蔽 blocked 区域。
+ * 不可达 / 起终点被屏蔽 → 返回 null。
+ */
+export function navPathCost(
+  index: NavIndex,
+  startId: number,
+  endId: number,
+  blocked?: ReadonlySet<number>,
+): number | null {
+  if (blocked?.has(startId) || blocked?.has(endId)) return null;
+  if (startId === endId) return 0;
+  const dist = new Map<number, number>([[startId, 0]]);
+  const heap = new MinHeap();
+  heap.push(startId, 0);
+  while (heap.size > 0) {
+    const { id, cost } = heap.pop()!;
+    if (id === endId) return cost;
+    if (cost > (dist.get(id) ?? Infinity)) continue;
+    const area = index.byId.get(id);
+    if (!area) continue;
+    for (const nb of area.neighbors) {
+      if (blocked?.has(nb)) continue;
+      const nbArea = index.byId.get(nb);
+      if (!nbArea) continue;
+      const dx = nbArea.centroid.x - area.centroid.x;
+      const dy = nbArea.centroid.y - area.centroid.y;
+      const dz = nbArea.centroid.z - area.centroid.z;
+      const w = Math.sqrt(dx * dx + dy * dy + dz * dz);
+      const nd = cost + w;
+      if (nd < (dist.get(nb) ?? Infinity)) {
+        dist.set(nb, nd);
+        heap.push(nb, nd);
+      }
+    }
+  }
+  return null;
+}
+
+/** 烟雾绕路代价：屏蔽烟覆盖的 nav 区域后，enemy→objective 多走多少（≤0 表示无影响）。 */
+export function smokeDetourCost(
+  index: NavIndex,
+  enemyAreaId: number,
+  objectiveAreaId: number,
+  smokeBlocked: ReadonlySet<number>,
+): number {
+  const base = navPathCost(index, enemyAreaId, objectiveAreaId);
+  if (base == null) return 0;
+  const blockedCost = navPathCost(index, enemyAreaId, objectiveAreaId, smokeBlocked);
+  if (blockedCost == null) return base; // 烟把唯一路径彻底切断 → 全额计
+  return Math.max(0, blockedCost - base);
+}
+
+/** 极简二叉堆（id + cost）。 */
+class MinHeap {
+  private heap: Array<{ id: number; cost: number }> = [];
+  get size(): number { return this.heap.length; }
+  push(id: number, cost: number): void {
+    const h = this.heap;
+    h.push({ id, cost });
+    let i = h.length - 1;
+    while (i > 0) {
+      const p = (i - 1) >> 1;
+      if (h[p]!.cost <= h[i]!.cost) break;
+      [h[p], h[i]] = [h[i]!, h[p]!];
+      i = p;
+    }
+  }
+  pop(): { id: number; cost: number } | undefined {
+    const h = this.heap;
+    if (h.length === 0) return undefined;
+    const top = h[0];
+    const last = h.pop()!;
+    if (h.length > 0) {
+      h[0] = last;
+      let i = 0;
+      for (;;) {
+        const l = 2 * i + 1, r = 2 * i + 2;
+        let s = i;
+        if (l < h.length && h[l]!.cost < h[s]!.cost) s = l;
+        if (r < h.length && h[r]!.cost < h[s]!.cost) s = r;
+        if (s === i) break;
+        [h[s], h[i]] = [h[i]!, h[s]!];
+        i = s;
+      }
+    }
+    return top;
+  }
+}

package/src/spatial/utility.integration.test.ts

@@ -0,0 +1,38 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import type { DemoPackage } from "@cs2dak/contract";
+import { getMapTri } from "@cs2dak/maps/tri-assets";
+import { loadDemoPackageFromZip } from "../loader.js";
+import { loadSpatialAssets } from "./annotate.js";
+import { buildOfficialUtilitySpatial } from "./utility.js";
+
+let deAncientPkg: DemoPackage | null = null;
+
+beforeAll(async () => {
+  const zip = await readFile(fileURLToPath(new URL("../../../../fixtures/input/sample-2026-05-17_de_ancient_Team_Spirit_13-10_Team_Falcons.zip", import.meta.url)));
+  deAncientPkg = await loadDemoPackageFromZip(zip);
+}, 30_000);
+
+describe("UtilitySpatial LOS metrics on real fixture (tri-backed)", () => {
+  it("derives non-null sightline denial / protected crossings when tri-BVH is available", () => {
+    const pkg = deAncientPkg!;
+    const mapName = pkg.match.mapName;
+    const tri = getMapTri(mapName);
+    if (!tri) {
+      // 本机未下载 ~/.awpy/tris/{mapName}.tri -> 跳过（CI 无 tri）
+      return;
+    }
+    const assets = loadSpatialAssets(mapName, tri);
+    expect(assets.available.visibility).toBe(true);
+
+    const u = buildOfficialUtilitySpatial(pkg, assets);
+    let sightTotal = 0;
+    for (const v of u.values()) {
+      expect(v.actualSmokeSightlineDenialSeconds).not.toBeNull();
+      expect(v.actualSmokeProtectedCrossings).not.toBeNull();
+      sightTotal += v.actualSmokeSightlineDenialSeconds ?? 0;
+    }
+    expect(sightTotal).toBeGreaterThanOrEqual(0);
+  }, 60_000);
+});

package/src/spatial/utility.test.ts

@@ -0,0 +1,120 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import type { DemoPackage, Replay } from "@cs2dak/contract";
+import type { MapZones } from "@cs2dak/maps";
+import { loadDemoPackageFromZip } from "../loader.js";
+import { loadSpatialAssets, type SpatialAssets } from "./annotate.js";
+import { buildOfficialUtilitySpatial, buildUtilityWindows } from "./utility.js";
+
+let deAncientPkg: DemoPackage | null = null;
+
+beforeAll(async () => {
+  const zip = await readFile(fileURLToPath(new URL("../../../../fixtures/input/sample-2026-05-17_de_ancient_Team_Spirit_13-10_Team_Falcons.zip", import.meta.url)));
+  deAncientPkg = await loadDemoPackageFromZip(zip);
+}, 30_000);
+
+function deltaArr(values: number[]): number[] {
+  const out: number[] = [];
+  let prev = 0;
+  for (const v of values) { out.push(v - prev); prev = v; }
+  return out;
+}
+
+// 合成 1 个方形 A 点 zone（无 nav/tri）——测归属 + 火焰逼退（zone-based，不需要 nav）。
+const SITE_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 TEST_ASSETS: SpatialAssets = {
+  mapName: "de_test", routes: null, zones: SITE_ZONES, nav: null, visibility: null,
+  available: { routes: false, zones: true, nav: false, visibility: false },
+};
+
+/** Build replay round for C1 at two positions: (50,50) at tick 96, (500,500) at tick 160. */
+function molotovReplay(): Replay {
+  return {
+    meta: { sampleRate: 1, tickrate: 64, coordScale: 1, angleScale: 10 },
+    weaponDict: [],
+    placeDict: [],
+    rounds: [{
+      roundNumber: 1,
+      startTick: 96,
+      tickStep: 64,
+      frameCount: 2,
+      players: [{
+        playerIndex: 1, // C1
+        x: deltaArr([50, 500]), y: deltaArr([50, 500]), z: deltaArr([0, 0]),
+        yaw: deltaArr([0, 0]), pitch: deltaArr([0, 0]),
+        hp: [100, 100], armor: [100, 100], money: [800, 800], equipValue: [800, 800],
+        weapon: [-1, -1], place: [-1, -1], flash: [0, 0], flags: [1, 1], grenades: [[], []],
+      }],
+      projectiles: [],
+    }],
+  };
+}
+
+function makeMolotovPkg(): DemoPackage {
+  return {
+    match: { mapName: "de_test", tickrate: 64 },
+    players: [{ steamId64: "T1", teamKey: "teamA" }, { steamId64: "C1", teamKey: "teamB" }],
+    rounds: [{ roundNumber: 1, startTick: 1, freezeEndTick: 64, endTick: 1000, teamASide: "t", teamBSide: "ct" }],
+    bombs: [], kills: [],
+    grenades: [{ roundNumber: 1, grenadeId: "g1", grenade: "molotov", throwerSteamId64: "T1", throwerTeamKey: "teamA", throwTick: 80, effectTick: 100, destroyTick: 196, effectPosition: { x: 50, y: 50, z: 0 } }],
+    replay: molotovReplay(),
+  } as unknown as DemoPackage;
+}
+
+describe("buildUtilityWindows (zone attribution, doc §18)", () => {
+  it("attributes a grenade to its effectPosition zone", () => {
+    const windows = buildUtilityWindows(makeMolotovPkg(), TEST_ASSETS);
+    expect(windows[0]!.zoneId).toBe("a_site");
+    expect(windows[0]!.zoneRole).toBe("site");
+    expect(windows[0]!.type).toBe("molotov");
+  });
+});
+
+describe("incendiary displacement / path delay (zone-based)", () => {
+  it("counts displacement when an enemy leaves the fire zone, and path delay", () => {
+    const u = buildOfficialUtilitySpatial(makeMolotovPkg(), TEST_ASSETS);
+    const t1 = u.get("T1")!;
+    expect(t1.actualIncendiaryDisplacementEvents).toBe(1); // site weight 1.0
+    expect(t1.actualIncendiaryPathDelaySeconds).toBeGreaterThan(0);
+    // 无 visibility → LOS 两项发 null
+    expect(t1.actualSmokeProtectedCrossings).toBeNull();
+    expect(t1.actualSmokeSightlineDenialSeconds).toBeNull();
+  });
+
+  it("returns an empty map without zone assets", () => {
+    const noZones: SpatialAssets = { ...TEST_ASSETS, zones: null, available: { ...TEST_ASSETS.available, zones: false } };
+    expect(buildOfficialUtilitySpatial(makeMolotovPkg(), noZones).size).toBe(0);
+  });
+});
+
+describe("UtilitySpatial end-to-end on real fixture (nav-detour isolation, no tri)", () => {
+  it("attributes real grenades and derives nav-backed isolation; LOS null without tri", () => {
+    const pkg = deAncientPkg!;
+    const mapName = pkg.match.mapName;
+    const assets = loadSpatialAssets(mapName); // 匹配 fixture 的实际地图
+    expect(assets.available.nav).toBe(true);
+
+    const windows = buildUtilityWindows(pkg, assets);
+    if (assets.available.zones) {
+      const zoneRatio = windows.filter((w) => w.zoneId != null).length / windows.length;
+      expect(zoneRatio).toBeGreaterThan(0.5);
+    }
+
+    const u = buildOfficialUtilitySpatial(pkg, assets);
+    let isoTotal = 0;
+    for (const v of u.values()) {
+      if (assets.available.zones) {
+        expect(v.actualSmokeProtectedCrossings).toBeNull(); // 无 tri
+        expect(v.actualSmokeSightlineDenialSeconds).toBeNull();
+        expect(v.actualIncendiaryDisplacementEvents).toBeGreaterThanOrEqual(0);
+      }
+      isoTotal += v.actualSmokeIsolationSeconds;
+    }
+    expect(isoTotal).toBeGreaterThanOrEqual(0); // nav 绕路隔离，因地图/比赛可能为零
+  });
+});