planets

Planet microservice for Xandaris — procedurally generates planets with full physics simulation, surface geography, and resource deposits.

Quick start

# Requires the star service running at :8081
psql postgres -c "CREATE DATABASE planets;"
psql planets -f db/migrations/001_init.sql
psql planets -f db/migrations/002_seed.sql
sqlc generate
go build -o planets-bin .
./planets-bin -addr :8082 -star-url http://localhost:8081

Generate planets for a star system

# Get a system ID from the star service
SYS=$(curl -s 'http://localhost:8081/systems/nearest?x=0&y=0&z=0&limit=1' | jq '.[0].id')
curl -X POST "http://localhost:8082/generate/system/${SYS}"

Derivation chain

The formation engine runs a 18-step pipeline from stellar environment to surface settlements:

 1. Star API → stellar luminosity, frost line, metallicity
 2. Orbital distance vs frost line → available materials
 3. Accretion sim → total mass + composition
 4. Composition profile → planet class
 5. Mass + composition → density → radius → gravity
 6. Mass + iron fraction + age → core differentiation
 7. Core temp vs iron melting point → magnetic field (continuous)
 8. Volatiles + temp + gravity → atmosphere components
 9. Atmosphere → pressure + greenhouse factor
10. Stellar flux / dist² × (1-albedo) × (1+greenhouse) + tidal heat → surface temp
11. Surface temp + pressure → water state (liquid/ice/vapor)
12. All factors → habitability score
13. Planet class + water + tectonics → region generation
14. Latitude + temp + water → biome assignment
15. Adjacency graph (connected)
16. Tectonics + elevation → feature placement
17. Composition + geology → deposit placement
18. Habitability → settlement generation

Architecture

planets/
├── main.go                     Entry point, star service client wiring
├── internal/
│   ├── gen/
│   │   ├── physics.go          Derivation functions (16 tests)
│   │   ├── formation.go        Full planet formation sim (steps 1-12)
│   │   ├── geography.go        Surface generation (steps 13-18)
│   │   ├── names.go            Latin/Greek procedural name generator
│   │   └── id.go               JS-safe snowflake IDs
│   ├── starclient/             HTTP client for star service API
│   ├── service/                Orchestrates gen + DB + star API
│   ├── api/                    25 HTTP endpoints with CORS
│   └── db/                     sqlc generated (2700+ lines)
├── db/
│   ├── migrations/
│   │   ├── 001_init.sql        14 tables, 21 indexes
│   │   └── 002_seed.sql        5 planet classes, 17 materials, 12 biomes,
│   │                           8 region types, 12 feature types
│   └── queries/
│       └── planets.sql         53 queries

Schema (14 tables)

Reference: planet_class, biome_type, region_type, feature_type, material

Planet: planet (40+ columns: orbital elements, interior model, atmosphere, hydrosphere, cached derived), planet_composition, atmosphere_component

Geography: region, region_adjacency, feature, feature_region, deposit, settlement

API

Method	Endpoint	Description
GET	/planets/{id}	Planet with class info
GET	/planets/{id}/full	Full planet with subquery counts
GET	/planets/{id}/composition	Mass fractions by material
GET	/planets/{id}/atmosphere	Atmospheric components
GET	/planets/{id}/regions	Surface regions with biomes
GET	/planets/{id}/features	Geological features
GET	/planets/{id}/deposits	Resource deposits
GET	/planets/{id}/settlements	Settlements
GET	/planets/{id}/moons	Moon list
GET	/planets/{id}/resources	Aggregated resource summary
GET	/systems/{id}/planets	All planets in a star system
POST	/generate/system/{id}	Generate planets for a system

Design decisions

• Moons are recursive planets: Same table, nullable id_parent. Same physics, same generation. A gas giant's moon system generates like a star's planet system.
• Continuous magnetic field: core_iron_frac × core_temp feeds a continuous field strength (0-10000) instead of a solid/liquid/partial enum. Tidally locked planets get 0.3× penalty.
• Atmosphere chemistry: UV photolysis breaks down ammonia on warm planets (>250K). Inner rocky planets get nitrogen/water/CO2 via cometary bombardment. Gas giants get H/He.
• Lazy tick evaluation: dt_last_tick enables catch-up computation on stale reads. Atmospheric erosion, volcanic outgassing, and resource depletion can fast-forward.
• Integer math everywhere: mass in milli-earth-masses, pressure in milli-atm, fractions in basis points. Floats only during computation, never in storage or API.

Related

• we-be/star — Star service (this service queries it for stellar environments)