@cs2dak/maps 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Starfie1d
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @cs2dak/maps
+
+English | 简体中文
+
+Map calibration and world-to-radar transforms. Initial constants are aligned with the RivalHub/AWPy-style radar formula and can be expanded per map as fixtures grow.
+
+地图标定与世界坐标到 radar 像素坐标转换。第一版只放常用竞技地图的基础常量，后续根据 fixtures 和实际 demo 校准。

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@cs2dak/maps",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+export * from "./zones.js";
+
+export interface MapCalibration {
+  mapName: string;
+  posX: number;
+  posY: number;
+  scale: number;
+  radarSize: number;
+  lowerLevelMaxUnits?: number;
+}
+
+export interface RadarPoint {
+  x: number;
+  y: number;
+  outOfBounds: boolean;
+}
+
+export const MAP_CALIBRATIONS: Record<string, MapCalibration> = {
+  de_mirage: { mapName: "de_mirage", posX: -3230, posY: 1713, scale: 5, radarSize: 1024 },
+  de_dust2: { mapName: "de_dust2", posX: -2476, posY: 3239, scale: 4.4, radarSize: 1024 },
+  de_inferno: { mapName: "de_inferno", posX: -2087, posY: 3870, scale: 4.9, radarSize: 1024 },
+  de_anubis: { mapName: "de_anubis", posX: -2796, posY: 3328, scale: 5.22, radarSize: 1024 },
+  de_nuke: { mapName: "de_nuke", posX: -3453, posY: 2887, scale: 7, radarSize: 1024, lowerLevelMaxUnits: -495 },
+  de_ancient: { mapName: "de_ancient", posX: -2953, posY: 2164, scale: 5, radarSize: 1024 },
+  de_vertigo: { mapName: "de_vertigo", posX: -3168, posY: 1762, scale: 4, radarSize: 1024, lowerLevelMaxUnits: 11700 },
+  de_train: { mapName: "de_train", posX: -2308, posY: 2078, scale: 4.082077, radarSize: 1024 },
+  de_overpass: { mapName: "de_overpass", posX: -4831, posY: 1781, scale: 5.2, radarSize: 1024 },
+  de_cache: { mapName: "de_cache", posX: -2000, posY: 3250, scale: 5.5, radarSize: 1024 }
+};
+
+export function getMapCalibration(mapName: string): MapCalibration | null {
+  return MAP_CALIBRATIONS[mapName] ?? null;
+}
+
+export function worldToRadar(
+  point: { x: number; y: number },
+  calibration: MapCalibration
+): RadarPoint {
+  const x = (point.x - calibration.posX) / calibration.scale;
+  const y = (calibration.posY - point.y) / calibration.scale;
+  const pad = 96;
+
+  return {
+    x,
+    y,
+    outOfBounds:
+      x < -pad ||
+      x > calibration.radarSize + pad ||
+      y < -pad ||
+      y > calibration.radarSize + pad
+  };
+}

package/src/zones.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { pointInPolygon, zoneAt, type MapZones } from "./zones.js";
+
+// 合成地图：两个不相邻方块 + 一个上层方块（测 z 过滤）
+const zones: MapZones = {
+  mapName: "de_test",
+  version: "test-0",
+  zones: [
+    { id: "a_site", name: "A", role: "site", bombsite: "a", polygon: [[0, 0], [100, 0], [100, 100], [0, 100]] },
+    { id: "b_site", name: "B", role: "site", bombsite: "b", polygon: [[200, 0], [300, 0], [300, 100], [200, 100]] },
+    { id: "upper", name: "Upper", role: "other", polygon: [[0, 0], [100, 0], [100, 100], [0, 100]], zMin: 500, zMax: 700 },
+  ],
+};
+
+describe("pointInPolygon", () => {
+  it("detects inside / outside", () => {
+    const square: Array<[number, number]> = [[0, 0], [10, 0], [10, 10], [0, 10]];
+    expect(pointInPolygon(5, 5, square)).toBe(true);
+    expect(pointInPolygon(15, 5, square)).toBe(false);
+    expect(pointInPolygon(-1, 5, square)).toBe(false);
+  });
+
+  it("auto-closes the polygon (last→first edge)", () => {
+    const tri: Array<[number, number]> = [[0, 0], [10, 0], [5, 10]];
+    expect(pointInPolygon(5, 3, tri)).toBe(true);
+    expect(pointInPolygon(0, 9, tri)).toBe(false);
+  });
+});
+
+describe("zoneAt", () => {
+  it("resolves a point to its zone", () => {
+    expect(zoneAt(zones, 50, 50)?.id).toBe("a_site");
+    expect(zoneAt(zones, 250, 50)?.id).toBe("b_site");
+  });
+
+  it("returns null when no zone contains the point", () => {
+    expect(zoneAt(zones, 150, 50)).toBeNull();
+  });
+
+  it("respects z-range on multi-level overlap (a_site has no z, returned first)", () => {
+    // 同一 XY，z=600 仍落 a_site，因为 a_site 无 z 约束且排在前（优先级）
+    expect(zoneAt(zones, 50, 50, 600)?.id).toBe("a_site");
+  });
+
+  it("uses z to pick an upper-only zone when lower zone is z-bounded", () => {
+    const upperOnly: MapZones = { ...zones, zones: [zones.zones[2], zones.zones[0]] };
+    // a_site 无 z 约束，永远命中；把 upper 放前面且在其 z 段内才命中 upper
+    expect(zoneAt(upperOnly, 50, 50, 600)?.id).toBe("upper");
+    expect(zoneAt(upperOnly, 50, 50, 100)?.id).toBe("a_site"); // 不在 upper z 段 → 落 a_site
+  });
+});

package/src/zones.ts

@@ -0,0 +1,91 @@
+/**
+ * map-zones — 地图区域语义层（P4 空间分析的基础）
+ *
+ * 定位：把世界坐标的一个点映射到一个**有名字、有角色**的区域（A 点 / mid / banana …），
+ * 供 Area（区域占有）、Utility Block（道具封锁）等空间指标使用。
+ *
+ * 坐标系：多边形顶点用**世界坐标 XY**（与 positions-1s / replay 的 position 同系），
+ * 分辨率无关、无需 radar 标定。多层地图（nuke / vertigo）用可选 [zMin, zMax] 区分上下层。
+ *
+ * 边界：本文件只做「点 → 区域」的几何归属，不算任何指标，不依赖 demo 数据。
+ * 真实多边形坐标由人工在 `map-zones/<map>.json` 标定（这是唯一需要人工的一步）。
+ */
+
+/** 区域角色：决定该区域在分析里的语义分类（不限定地图）。 */
+export type ZoneRole =
+  | "site"        // 包点（A/B）
+  | "connector"   // 连接通道（mid-to-B、connector…）
+  | "mid"         // 中路
+  | "lane"        // 主路（banana / long / apps…）
+  | "spawn"       // 出生区
+  | "approach"    // 进攻方接近区
+  | "backsite"    // 包点后区 / 残余空间
+  | "other";
+
+export interface MapZone {
+  /** 稳定唯一 id（如 "a_site" / "banana" / "mid"）。 */
+  id: string;
+  /** 人类可读名（如 "A 点" / "Banana"）。 */
+  name: string;
+  role: ZoneRole;
+  /** 该区域归属的包点（site/connector 常关联），无则 null。 */
+  bombsite?: "a" | "b" | null;
+  /** 世界坐标 XY 多边形顶点，首尾不必闭合（自动闭合）。至少 3 点。 */
+  polygon: Array<[number, number]>;
+  /** 多层地图的高度范围（含），单层地图省略。 */
+  zMin?: number;
+  zMax?: number;
+}
+
+export interface MapZones {
+  /** 如 "de_mirage"。 */
+  mapName: string;
+  /** 标定版本，便于演进。 */
+  version: string;
+  zones: MapZone[];
+}
+
+/**
+ * 射线法判断点是否在多边形内（世界坐标 XY）。多边形自动闭合。
+ * 边界视为命中（<=），避免相邻区域漏判。
+ */
+export function pointInPolygon(x: number, y: number, polygon: Array<[number, number]>): boolean {
+  let inside = false;
+  const n = polygon.length;
+  for (let i = 0, j = n - 1; i < n; j = i++) {
+    const [xi, yi] = polygon[i];
+    const [xj, yj] = polygon[j];
+    const intersect = yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi;
+    if (intersect) inside = !inside;
+  }
+  return inside;
+}
+
+/**
+ * 把一个世界坐标点归属到一个区域。
+ *  - 多层地图：先按 [zMin,zMax] 过滤再做多边形判定。
+ *  - 重叠区域：返回**第一个**命中的（调用方应保证 zones 顺序 = 优先级，窄区域在前）。
+ *  - 无命中：返回 null。
+ */
+export function zoneAt(zones: MapZones, x: number, y: number, z?: number): MapZone | null {
+  for (const zone of zones.zones) {
+    if (z !== undefined && (zone.zMin !== undefined || zone.zMax !== undefined)) {
+      if (zone.zMin !== undefined && z < zone.zMin) continue;
+      if (zone.zMax !== undefined && z > zone.zMax) continue;
+    }
+    if (pointInPolygon(x, y, zone.polygon)) return zone;
+  }
+  return null;
+}
+
+/** 当前 CS2 现役图池（train 已移除）。zone 标定与 P4 分析的优先地图。 */
+export const ACTIVE_DUTY_MAPS = [
+  "de_ancient",
+  "de_anubis",
+  "de_dust2",
+  "de_inferno",
+  "de_mirage",
+  "de_nuke",
+  "de_overpass",
+] as const;
+export type ActiveDutyMap = (typeof ACTIVE_DUTY_MAPS)[number];