@boltr/geometry 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boltr/geometry",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared geometry primitives for BOLTR tactical combat game",
   "main": "src/index.js",
   "exports": {
@@ -13,12 +13,17 @@
   "scripts": {
     "test": "node --test __tests__/*.test.js"
   },
-  "keywords": ["boltr", "geometry", "game"],
+  "keywords": [
+    "boltr",
+    "geometry",
+    "game"
+  ],
   "license": "UNLICENSED",
   "engines": {
     "node": ">=18.0.0"
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "types": "src/index.d.ts"
 }

package/src/index.d.ts

@@ -0,0 +1,46 @@
+// Re-export types
+export type { Point } from './primitives';
+export type { TerrainPiece } from './terrain';
+export type { LOSResult, Positioned } from './los';
+export type {
+  GameUnit,
+  Operative,
+  PathBlockResult,
+  WaypointValidationResult,
+  WaypointPathOptions,
+} from './movement';
+
+// Primitives
+export {
+  calculateDistance,
+  isPointInPolygon,
+  lineSegmentsIntersect,
+  lineIntersectsPolygon,
+  pointToLineSegmentDistance,
+  pointToPolygonDistance,
+  lineSegmentIntersectsCircle,
+  isBaseOverlappingTerrain,
+} from './primitives';
+
+// Terrain
+export {
+  BLOCKED_TERRAIN_TYPES,
+  PENALTY_TERRAIN_TYPES,
+  checkTargetOnBlockedTerrain,
+  checkMovementBlocked,
+  countPenaltyTerrainPieces,
+  checkTerrainMovementPenalty,
+} from './terrain';
+
+// Line of Sight
+export { checkLineOfSight } from './los';
+
+// Movement
+export {
+  DEFAULT_BASE_RADIUS,
+  isPositionOccupied,
+  isInFriendlyExclusionZone,
+  isInEnemyExclusionZone,
+  isPathBlockedByEnemies,
+  validateWaypointPath,
+} from './movement';

package/src/los.d.ts

@@ -0,0 +1,24 @@
+import { Point } from './primitives';
+import { TerrainPiece } from './terrain';
+
+/** Line of sight result. */
+export type LOSResult = 'CLEAR' | 'LIGHT_COVER' | 'HEAVY_COVER' | 'BLOCKED';
+
+/** Entity with a position, used by checkLineOfSight. */
+export interface Positioned {
+  position: Point;
+}
+
+/**
+ * Check line of sight between shooter and target through terrain.
+ *
+ * - Shooter bracing on cover (within 1"): shoots across without penalty
+ * - Target in cover (within 1"): gets defense bonus
+ * - Heavy cover blocks LOS when neither operative is within 1"
+ * - Light cover at distance has no effect
+ */
+export function checkLineOfSight(
+  shooter: Positioned,
+  target: Positioned,
+  terrain: TerrainPiece[]
+): LOSResult;

package/src/movement.d.ts

@@ -0,0 +1,98 @@
+import { Point } from './primitives';
+import { TerrainPiece } from './terrain';
+
+/** Default base radius when not specified on a unit. */
+export const DEFAULT_BASE_RADIUS: number;
+
+/** A game unit with position, player ownership, and optional base radius. */
+export interface GameUnit {
+  unit_index: number;
+  position: Point;
+  player_id: number;
+  eliminated?: boolean;
+  base_radius?: number;
+  [key: string]: unknown;
+}
+
+/** The moving operative, extends GameUnit. */
+export interface Operative extends GameUnit {}
+
+/** Result of path blocking check. */
+export interface PathBlockResult {
+  blocked: boolean;
+  blocker?: GameUnit;
+}
+
+/** Result of waypoint path validation. */
+export interface WaypointValidationResult {
+  valid: boolean;
+  error?: string;
+  totalDistance?: number;
+  effectiveDistance?: number;
+  terrainPenalty?: number;
+}
+
+/** Options for validateWaypointPath. */
+export interface WaypointPathOptions {
+  exemptEnemyUnitIndex?: number | null;
+  checkEnemyBlocking?: boolean;
+  isWithinBounds?: (point: Point, mapData?: unknown) => boolean;
+}
+
+/**
+ * Check if a position's base overlaps another unit's base.
+ */
+export function isPositionOccupied(
+  position: Point,
+  baseRadius: number,
+  units: GameUnit[],
+  excludeUnitIndex?: number | null
+): boolean;
+
+/**
+ * Check if a position is within the exclusion zone of any friendly operative.
+ * Uses sum-of-radii: two friendly bases cannot overlap.
+ */
+export function isInFriendlyExclusionZone(
+  position: Point,
+  operative: Operative,
+  units: GameUnit[]
+): boolean;
+
+/**
+ * Check if position is within 1" exclusion zone of any enemy operative.
+ */
+export function isInEnemyExclusionZone(
+  position: Point,
+  operative: Operative,
+  units: GameUnit[]
+): boolean;
+
+/**
+ * Check if a straight-line path is blocked by any enemy operatives.
+ * An enemy blocks a path when the line segment comes within
+ * (enemy.base_radius + 1.0) inches of the enemy center.
+ */
+export function isPathBlockedByEnemies(
+  startPos: Point,
+  endPos: Point,
+  operative: Operative,
+  units: GameUnit[],
+  exemptUnitIndex?: number | null
+): PathBlockResult;
+
+/**
+ * Validate a waypoint path: checks each segment for terrain blocking,
+ * enemy path blocking, and computes total distance with per-piece penalty.
+ */
+export function validateWaypointPath(
+  startPos: Point,
+  waypoints: Point[],
+  baseRadius: number,
+  maxDistance: number,
+  operative: Operative,
+  units: GameUnit[],
+  terrain: TerrainPiece[],
+  mapData?: unknown,
+  options?: WaypointPathOptions
+): WaypointValidationResult;

package/src/primitives.d.ts

@@ -0,0 +1,64 @@
+/** A point in 2D space. */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/** Euclidean distance between two points. */
+export function calculateDistance(pos1: Point, pos2: Point): number;
+
+/** Point-in-polygon test (ray casting algorithm). */
+export function isPointInPolygon(point: Point, vertices: Point[]): boolean;
+
+/**
+ * Test whether two line segments intersect (exclusive of endpoints).
+ */
+export function lineSegmentsIntersect(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  x3: number,
+  y3: number,
+  x4: number,
+  y4: number
+): boolean;
+
+/** Test whether a line segment intersects any edge of a polygon. */
+export function lineIntersectsPolygon(
+  lineStart: Point,
+  lineEnd: Point,
+  vertices: Point[]
+): boolean;
+
+/** Shortest distance from a point to a line segment. */
+export function pointToLineSegmentDistance(
+  point: Point,
+  lineStart: Point,
+  lineEnd: Point
+): number;
+
+/** Shortest distance from a point to the boundary of a polygon. */
+export function pointToPolygonDistance(point: Point, vertices: Point[]): number;
+
+/**
+ * Test whether a line segment intersects a circle.
+ * Used for path-vs-enemy blocking checks.
+ */
+export function lineSegmentIntersectsCircle(
+  lineStart: Point,
+  lineEnd: Point,
+  center: Point,
+  radius: number
+): boolean;
+
+/**
+ * Test whether a base circle overlaps a terrain polygon.
+ * The center is inside the polygon OR the center-to-boundary
+ * distance is less than the base radius.
+ */
+export function isBaseOverlappingTerrain(
+  position: Point,
+  baseRadius: number,
+  vertices: Point[]
+): boolean;

package/src/terrain.d.ts

@@ -0,0 +1,53 @@
+import { Point } from './primitives';
+
+/** Terrain piece with type and polygon vertices. */
+export interface TerrainPiece {
+  type: string;
+  vertices: Point[];
+  [key: string]: unknown;
+}
+
+/** Terrain types that block placement / ending movement. */
+export const BLOCKED_TERRAIN_TYPES: readonly string[];
+
+/** Terrain types that add a movement penalty when crossed. */
+export const PENALTY_TERRAIN_TYPES: readonly string[];
+
+/**
+ * Check whether a position's base circle sits on blocked terrain.
+ * Returns the terrain type string if blocked, or null.
+ */
+export function checkTargetOnBlockedTerrain(
+  position: Point,
+  baseRadius: number,
+  terrain: TerrainPiece[]
+): string | null;
+
+/**
+ * Check whether a straight-line movement path is blocked by impassable terrain.
+ * Also checks whether the destination base overlaps impassable terrain.
+ */
+export function checkMovementBlocked(
+  startPos: Point,
+  endPos: Point,
+  baseRadius: number,
+  terrain: TerrainPiece[]
+): 'path_blocked' | 'target_blocked' | null;
+
+/**
+ * Count distinct terrain pieces that impose a movement penalty along a path segment.
+ */
+export function countPenaltyTerrainPieces(
+  startPos: Point,
+  endPos: Point,
+  terrain: TerrainPiece[]
+): number;
+
+/**
+ * Returns true if ANY penalty terrain is crossed along the path.
+ */
+export function checkTerrainMovementPenalty(
+  startPos: Point,
+  endPos: Point,
+  terrain: TerrainPiece[]
+): boolean;