@buley/hexgrid-3d 3.6.0 → 3.6.2

package/README.md

@@ -2,6 +2,10 @@
 
 A reusable 3D hexagonal grid visualization component for displaying content in an immersive spherical layout.
 
+## Documentation
+
+- [Territory README](./src/territory/README.md)
+
 ## Features
 
 - **3D Hexagonal Grid Layout** - Spherical projection with customizable curvature
@@ -9,6 +13,7 @@ A reusable 3D hexagonal grid visualization component for displaying content in a
 - **Image Texture Mapping** - Automatic texture loading and caching
 - **Real-time Statistics** - Live telemetry and performance metrics
 - **Narration System** - Play-by-play commentary overlay
+- **Territory Globe** - Deterministic wrapped globe topology for paid seed claims, recursive subdivision, delegated territory overlays, and conquest-driven occupation
 - **Web Worker Rendering** - High-performance offloaded calculations
 - **Multi-Input Support** - Touch gestures, mouse, and keyboard controls
 - **Responsive Design** - Adapts to mobile and desktop viewports
@@ -78,6 +83,39 @@ function AdvancedExample() {
 }
 ```
 
+### Territory Globe Example
+
+```tsx
+import {
+  HexTerritoryGlobe,
+  generateCanonicalHexGlobe,
+} from "@buley/hexgrid-3d";
+
+const board = generateCanonicalHexGlobe({
+  boardId: "main",
+  curveUDeg: 360,
+  curveVDeg: 180,
+  rowCount: 180,
+  equatorColumns: 288,
+  minimumColumnsPerRow: 24,
+  poleMinScale: 0.25,
+});
+
+function TerritoryExample() {
+  return (
+    <HexTerritoryGlobe
+      cells={board.cells}
+      claimedCellIds={new Set(["main:r90:c144"])}
+      colorsByCellId={{ "main:r90:c144": "#59d0ff" }}
+    />
+  );
+}
+```
+
+When `tileRadius` is omitted, `HexTerritoryGlobe` auto-fits each latitude row to
+the available spacing to avoid overlap on dense boards. Pass `tileRadius` only
+when you intentionally want a manual radius override.
+
 ## Components
 
 ### HexGrid
@@ -112,8 +150,42 @@ Displays narration messages and real-time statistics in a dashboard-style overla
 | `isVisible`    | `boolean`            | Whether overlay is visible             |
 | `onClose`      | `() => void`         | Callback when overlay is closed        |
 
+### HexTerritoryGlobe
+
+Wrapped React Three Fiber surface for territory-aware hex cells on a sphere.
+
+**Props:**
+
+| Prop | Type | Description |
+| ---- | ---- | ----------- |
+| `cells` | `HexTerritoryCell[]` | Deterministic canonical globe cells |
+| `claimedCellIds` | `Iterable<string>` | Occupied or currently held roots |
+| `lockedCellIds` | `Iterable<string>` | Visible but unclaimable roots |
+| `colorsByCellId` | `Record<string, string>` | Per-root color overrides |
+| `selectedCellId` | `string` | Active root highlight |
+| `hoverCellId` | `string` | Hover highlight |
+| `tileRadius` | `number` | Optional manual radius override; omit to auto-fit row-safe tile radii |
+| `onSelectCell` | `(cell) => void` | Selection callback |
+| `onHoverCell` | `(cell) => void` | Hover callback |
+
 ## Types
 
+### Territory Types
+
+The package now exports territory-specific helpers:
+
+- `CanonicalHexGlobeConfig`
+- `HexTerritoryBoard`
+- `HexTerritoryCell`
+- `HexTerritoryAffiliation`
+- `HexTerritoryAllianceBinding`
+- `HexTerritoryRallyMarker`
+- `HexNodePath`
+- `HexwarEmbedRef`
+- `HexTerritoryTickState`
+- `HexwarNarrationEvent`
+- `createHexwarNarrationAdapter()`
+
 ### Photo
 
 ```typescript
@@ -207,6 +279,7 @@ setCustomAccentColor("#ff00ff");
 
 ### Peer Dependencies
 
+- `@react-three/fiber` ^9.4.2
 - `react` ^18.0.0
 - `react-dom` ^18.0.0
 - `next` ^14.0.0

package/dist/components/GamePieceRenderer.d.ts

@@ -0,0 +1,133 @@
+/**
+ * GamePieceRenderer — Three.js mesh factory for game pieces on a geodesic sphere.
+ *
+ * Builds 3D meshes from PieceShape primitives, accepts custom Object3D instances,
+ * handles instanced rendering for performance, surface-normal alignment, stacking,
+ * and piece animations (spin, bob, pulse, wobble, orbit, glow).
+ */
+import * as THREE from 'three';
+import type { GamePiece, CellGameState } from '../types';
+/**
+ * Build a Three.js Object3D from a GamePiece definition.
+ * Returns a Group containing the mesh, optional label, and optional count badge.
+ */
+export declare function buildPieceMesh(piece: GamePiece): THREE.Group;
+/**
+ * Place a piece group onto the sphere surface at a given hex center position.
+ * Orients the piece so "up" points away from the sphere center (surface normal).
+ *
+ * @param pieceGroup - The group returned by buildPieceMesh
+ * @param hexCenter  - The 3D position of the hex center on the unit sphere
+ * @param sphereRadius - Radius of the rendered sphere
+ * @param offsetY    - Additional height above surface (from GamePiece.offsetY)
+ */
+export declare function placePieceOnSphere(pieceGroup: THREE.Group, hexCenter: {
+    x: number;
+    y: number;
+    z: number;
+}, sphereRadius: number, offsetY?: number): void;
+/**
+ * Animate a piece group based on its stored animation config.
+ * Call this every frame with the elapsed time.
+ *
+ * @param pieceGroup - The group with userData.animation
+ * @param time       - Elapsed time in seconds
+ * @param deltaTime  - Frame delta in seconds
+ */
+export declare function animatePiece(pieceGroup: THREE.Group, time: number, _deltaTime: number): void;
+/**
+ * Create a flat polygon mesh for a hex or pentagon cell on the sphere surface.
+ * Used by GameSphere to render the board itself.
+ *
+ * @param center    - Hex center on unit sphere
+ * @param vertices  - Ordered vertices of the hex/pentagon (on unit sphere)
+ * @param radius    - Sphere radius for scaling
+ * @param color     - Fill color
+ * @param elevation - How far above the sphere surface (0 = flush)
+ */
+export declare function buildCellMesh(center: {
+    x: number;
+    y: number;
+    z: number;
+}, vertices: {
+    x: number;
+    y: number;
+    z: number;
+}[], radius: number, color?: string, elevation?: number): THREE.Mesh;
+/**
+ * Build a cell border (wireframe outline) for a hex/pentagon on the sphere.
+ */
+export declare function buildCellBorder(vertices: {
+    x: number;
+    y: number;
+    z: number;
+}[], radius: number, color?: string, lineWidth?: number, elevation?: number): THREE.LineLoop;
+/**
+ * Create a fog overlay sphere slightly larger than the game sphere.
+ * Individual cell fog is handled by modifying cell material opacity,
+ * but this provides a global atmospheric effect.
+ */
+export declare function buildFogOverlay(radius: number, fogColor?: string): THREE.Mesh;
+/**
+ * Build a glowing ring around a cell for highlights (attack target, selection, etc.)
+ */
+export declare function buildHighlightRing(center: {
+    x: number;
+    y: number;
+    z: number;
+}, radius: number, ringRadius?: number, color?: string, intensity?: number): THREE.Mesh;
+export interface AttackAnimationConfig {
+    fromCenter: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    toCenter: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    sphereRadius: number;
+    color?: string;
+    particleCount?: number;
+    duration?: number;
+}
+/**
+ * Create an attack trail particle system between two cells on the sphere.
+ * Returns a Points object and an update function.
+ */
+export declare function buildAttackTrail(config: AttackAnimationConfig): {
+    points: THREE.Points;
+    update: (progress: number) => void;
+    dispose: () => void;
+};
+export interface OrbitalStrikeConfig {
+    targetCenter: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    sphereRadius: number;
+    color?: string;
+    trailColor?: string;
+}
+/**
+ * Create an orbital strike projectile that falls from high above to a cell.
+ * Returns the mesh, update function, and disposal.
+ */
+export declare function buildOrbitalStrike(config: OrbitalStrikeConfig): {
+    group: THREE.Group;
+    update: (progress: number) => void;
+    dispose: () => void;
+};
+export declare function disposePieceGroup(group: THREE.Group): void;
+/**
+ * Apply CellGameState to a cell's mesh and border.
+ * Updates color, opacity (fog), and highlight state.
+ */
+export declare function applyCellState(cellMesh: THREE.Mesh, cellBorder: THREE.LineLoop | null, state: CellGameState, config?: {
+    fogDimOpacity?: number;
+    fogHiddenOpacity?: number;
+    fogExploredOpacity?: number;
+}): void;
+//# sourceMappingURL=GamePieceRenderer.d.ts.map

package/dist/components/GamePieceRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GamePieceRenderer.d.ts","sourceRoot":"","sources":["../../src/components/GamePieceRenderer.ts"],"names":[],"mappings":"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"}