starmap-manager

sunholo-data's avatarfrom sunholo-data

Manage starmap data assets for Stapledons Voyage. Use when downloading star catalogs, galactic backgrounds, or processing astronomical data. (project)

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 6, 2025
[Developer Tools]

When & Why to Use This Skill

The Starmap Manager is a specialized developer tool designed to automate the acquisition, processing, and management of real-world astronomical data for 3D game environments. It streamlines the integration of Gaia star catalogs, NASA exoplanet archives, and ESA galactic backgrounds, providing a seamless pipeline that converts raw scientific datasets into game-ready JSON assets with standardized coordinate systems.

Use Cases

  • Rapidly prototyping 3D space environments by deploying minimal 'Quick' datasets for immediate development and testing.
  • Automating the retrieval and processing of high-fidelity astronomical data from NASA and ESA for production-level game releases.
  • Converting complex scientific celestial coordinates (RA/Dec) into game-compatible XYZ formats for accurate star and planet positioning.
  • Managing multi-tier asset deployments, allowing developers to easily switch between different data resolutions (Quick, Medium, Large) based on performance requirements.
nameStarmap Manager
descriptionManage starmap data assets for Stapledons Voyage. Use when downloading star catalogs, galactic backgrounds, or processing astronomical data. (project)

Starmap Manager

Download, process, and manage astronomical data for the game's 3D starmap. Handles real star catalogs (Gaia), exoplanet data (NASA), and galactic background imagery (ESA/ESO).

Quick Start

Most common usage:

# Download quick dataset (~2MB total, fastest start)
.claude/skills/starmap-manager/scripts/download_stars.sh quick

# Download medium dataset (~15MB, richer local bubble)
.claude/skills/starmap-manager/scripts/download_stars.sh medium

# Download galactic background
.claude/skills/starmap-manager/scripts/download_background.sh

# Check what's installed
.claude/skills/starmap-manager/scripts/status.sh

When to Use This Skill

Invoke this skill when:

  • User wants to download real star data for the game
  • User asks about Gaia, exoplanet, or astronomical data sources
  • User wants galactic background images/textures
  • Setting up starmap assets for the first time
  • Upgrading from quick to medium/large dataset

Data Tiers

Tier Stars Exoplanets Size Use Case
Quick 5,930 (CNS5) ~6,000 ~2 MB Rapid prototyping
Medium ~50,000 (filtered GCNS) ~6,000 ~15 MB Release candidate
Large 331,312 (full GCNS) ~6,000 ~75 MB HD/DLC option

Available Scripts

scripts/download_stars.sh <tier>

Download star catalog for specified tier (quick/medium/large).

# Quick: CNS5 nearby stars (~1.2MB)
.claude/skills/starmap-manager/scripts/download_stars.sh quick

# Medium: Filtered GCNS G/K/M dwarfs (~10MB)
.claude/skills/starmap-manager/scripts/download_stars.sh medium

# Large: Full GCNS 100pc catalog (~72MB compressed)
.claude/skills/starmap-manager/scripts/download_stars.sh large

scripts/download_exoplanets.sh

Download NASA Exoplanet Archive confirmed planets (~3MB).

.claude/skills/starmap-manager/scripts/download_exoplanets.sh

scripts/download_background.sh [resolution]

Download ESA Gaia all-sky map for galactic background.

# 4K version (4096x2048, ~5MB) - default
.claude/skills/starmap-manager/scripts/download_background.sh 4k

# 8K version (8192x4096, ~20MB)
.claude/skills/starmap-manager/scripts/download_background.sh 8k

scripts/process_stars.sh

Convert downloaded star catalogs to game-ready format.

# Process all downloaded catalogs
.claude/skills/starmap-manager/scripts/process_stars.sh

scripts/status.sh

Show current starmap asset status.

.claude/skills/starmap-manager/scripts/status.sh

Workflow

1. Initial Setup (Quick Start)

# Download minimal dataset for development
.claude/skills/starmap-manager/scripts/download_stars.sh quick
.claude/skills/starmap-manager/scripts/download_exoplanets.sh
.claude/skills/starmap-manager/scripts/download_background.sh
.claude/skills/starmap-manager/scripts/process_stars.sh

2. Upgrade to Medium (Pre-Release)

# Get richer dataset for release
.claude/skills/starmap-manager/scripts/download_stars.sh medium
.claude/skills/starmap-manager/scripts/process_stars.sh

3. HD Assets (Optional DLC)

# Full catalog + high-res background
.claude/skills/starmap-manager/scripts/download_stars.sh large
.claude/skills/starmap-manager/scripts/download_background.sh 8k
.claude/skills/starmap-manager/scripts/process_stars.sh

Output Files

All processed data goes to assets/data/starmap/:

assets/data/starmap/
├── stars.json          # Combined star catalog (positions, types, etc.)
├── exoplanets.json     # Confirmed exoplanets with orbital data
├── habitable.json      # Pre-filtered habitable zone candidates
└── background/
    └── galaxy_4k.png   # All-sky galactic panorama

Resources

Data Sources

See resources/data_sources.md for:

  • Complete data source documentation
  • API endpoints and download URLs
  • Data schemas and column descriptions
  • Licensing information (all CC BY-SA 3.0 compatible)

Processing Pipeline

See resources/processing.md for:

  • Coordinate conversion (RA/Dec to galactic XYZ)
  • Filtering criteria for each tier
  • JSON schema for game integration
  • Habitable zone calculations

Notes

  • Licensing: All data is CC BY-SA 3.0 or public domain
  • Updates: Star positions don't change; exoplanets update quarterly
  • Determinism: Same processing produces identical output
  • Dependencies: Requires curl, jq, python3 (for coordinate conversion)