EVE Parallax

Embeddable 3D star map visualization library for EVE Online.

PRD.md | STATUS.md (development docs — not included in published package)

What Is This

EVE Parallax is a React + Three.js library for rendering the EVE Online universe as an interactive 3D map. It is built for embedding into EVE developer tools that require high performance and deep visual customization. The library focuses on deterministic data-driven rendering with a strict "data in, visuals out" model.

Features

• 3D rendering of approximately 5,500 solar systems (K-space, Pochven, Jovian) at 60fps
• Animated 3D↔2D map view transition with EVE client 2D layout positions
• Interactive camera controls (orbit, pan, zoom, programmatic fly-to with cubic ease-out)
• Per-system customization (color, size, opacity via SystemRenderConfig)
• Arbitrary named connection sets with independent styling (color, opacity, curved lines)
• Jump bridge rendering with online/offline/reinforced state-driven visuals
• BFS pathfinding with multi-waypoint routes, system avoidance, and jump bridge integration
• Metadata-driven heatmaps with radial glow sprites and configurable color gradients
• Sovereignty shading with owner-to-color mapping
• Animated 3D torus fleet/entity markers with pulsing animation and labels
• Jump range sphere visualization with cyno-restricted system highlighting
• Light-year distance calculations and systems-in-range spatial queries
• Region labels (always visible), per-system proximity labels (distance-culled), custom annotations
• Click-to-select with visual highlight, deselection via empty-space click
• EVE security classification using displayed security rounding rules
• Extensible metadata model (Record<string, unknown> per system)
• Composable layer architecture (systems, connections, labels, overlays, fleet markers)
• Zero network requests, zero browser storage access — strict "data in, visuals out"
• TypeScript-first API with full public type exports

Project Structure

EVEParallax/
├── src/
│   ├── index.ts                    # Public exports
│   ├── NewEdenMap.tsx              # Main embeddable component
│   ├── hooks/
│   │   └── useMapControl.ts       # Imperative control hook + binding bridge
│   ├── layers/
│   │   ├── SystemsLayer.tsx       # InstancedMesh for star systems
│   │   ├── ConnectionsLayer.tsx   # Batched LineSegments for stargates
│   │   ├── CameraController.tsx   # OrbitControls + fly-to + 2D mode
│   │   ├── LabelsLayer.tsx        # Region + system + annotation labels (billboard SDF)
│   │   ├── ConnectionSetLayer.tsx # Named custom connection group rendering
│   │   ├── JumpRangeLayer.tsx     # 3D sphere for capital jump range
│   │   ├── FleetMarkerLayer.tsx   # Animated 3D torus fleet markers
│   │   └── HeatmapGlowLayer.tsx   # Radial glow sprites for heatmap overlay
│   ├── types/
│   │   └── index.ts               # All public type definitions
│   └── utils/
│       ├── dataLoader.ts          # JSONL fetch + parse
│       ├── dataProcessor.ts       # Indexing, deduplication, normalization
│       ├── spatialMath.ts         # LY distance, jump range, security classification
│       └── graphBuilder.ts        # Adjacency graph, BFS pathfinding
├── demo/
│   ├── main.tsx                   # Demo app entry point
│   └── App.tsx                    # Dev demo app with control panel
├── public/
│   └── data/                      # EVE SDE JSONL files (dev/demo only)
├── index.html                     # Demo HTML shell
├── package.json
├── tsconfig.json
├── vite.config.ts                 # Library build config
├── LICENSE
├── PRD.md
├── README.md
└── STATUS.md

Prerequisites

• Node.js 18+
• npm or pnpm

Quick Start

1. Clone the repository and install dependencies.

   git clone <your-repo-url>
   cd EVEParallax
   npm install

2. Copy SDE JSONL files into public/data/ (mapSolarSystems.jsonl, mapStargates.jsonl, mapRegions.jsonl).
3. Start the demo app:

   npm run dev

4. Open the local URL printed in the terminal (typically http://localhost:5173).

Using as a Library

npm install eve-parallax

Peer dependencies:

• react
• react-dom
• three
• @react-three/fiber
• @react-three/drei

Minimal usage example:

import { useEffect, useState } from 'react';
import { NewEdenMap, useMapControl } from 'eve-parallax';
import type { SolarSystem, Stargate, Region } from 'eve-parallax';

async function parseJSONL<T>(url: string): Promise<T[]> {
  const response = await fetch(url);
  const text = await response.text();
  return text
    .trim()
    .split('\n')
    .filter(Boolean)
    .map((line) => JSON.parse(line) as T);
}

function App() {
  const [systems, setSystems] = useState<SolarSystem[]>([]);
  const [stargates, setStargates] = useState<Stargate[]>([]);
  const [regions, setRegions] = useState<Region[]>([]);
  const mapControl = useMapControl({ language: 'en' });

  useEffect(() => {
    Promise.all([
      parseJSONL<SolarSystem>('/data/mapSolarSystems.jsonl'),
      parseJSONL<Stargate>('/data/mapStargates.jsonl'),
      parseJSONL<Region>('/data/mapRegions.jsonl'),
    ]).then(([systemsData, stargatesData, regionsData]) => {
      setSystems(systemsData);
      setStargates(stargatesData);
      setRegions(regionsData);
    });
  }, []);

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <NewEdenMap
        systems={systems}
        stargates={stargates}
        regions={regions}
        mapControl={mapControl}
      />
    </div>
  );
}

Required Data Files

| File | Description | Approx Size | Record Count | | --- | --- | --- | --- | | mapSolarSystems.jsonl | Solar systems, names, positions, security, region and constellation IDs | ~3-5 MB | ~8,500 | | mapStargates.jsonl | Stargate records with directional destination links | ~3-4 MB | ~12,000 | | mapRegions.jsonl | Region names, positions, and constellation ID lists | ~0.1 MB | ~100 |

Data sources:

• Official EVE developer resources: EVE Developers
• EVE Static Data Export (SDE)

One-line JSON examples:

{"_key":30000142,"name":{"zh":"吉他","en":"Jita"},"position":{"x":-1.29e+17,"y":6.08e+16,"z":1.35e+17},"regionID":10000002,"constellationID":20000020,"securityStatus":0.9459}

{"_key":50001248,"solarSystemID":30000142,"destination":{"solarSystemID":30000144,"stargateID":50001249},"position":{"x":-1.29e+17,"y":6.08e+16,"z":1.35e+17},"typeID":29624}

{"_key":10000002,"name":{"zh":"The Forge","en":"The Forge"},"position":{"x":-1.05e+17,"y":5.68e+16,"z":1.34e+17},"constellationIDs":[20000017,20000018]}

Build as Library

Vite library mode (example):

import dts from 'vite-plugin-dts';
import { resolve } from 'path';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  root: '.',
  plugins: [react(), dts({ rollupTypes: true, outDir: 'dist' })],
  build: {
    copyPublicDir: false,
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      name: 'EVEParallax',
      formats: ['es', 'cjs'],
      fileName: (format) => (format === 'es' ? 'index.mjs' : 'index.cjs'),
    },
    rollupOptions: {
      external: [
        'react',
        'react-dom',
        'three',
        '@react-three/fiber',
        '@react-three/drei',
      ],
    },
  },
});

Build output targets:

• dist/index.mjs
• dist/index.cjs
• Type declarations (.d.ts)

Documentation

• PRD.md — Full product requirements, architecture, API, and public type contracts
• STATUS.md — Current state and milestone progress

CCP License Compliance

All EVE Online universe data belongs to CCP Games.

Usage complies with the CCP Developer License Agreement:
https://developers.eveonline.com/resource/license-agreement

The library source code is MIT licensed.
SDE data is redistributable under CCP terms for third-party developer tools.

Required attribution:
EVE Online and all related logos are trademarks of CCP hf.