🌍 astro3d

Create realistic 3D spheres of planets, moons, and satellites — without reinventing the rocket.

This package lets you easily generate customizable 3D mesh spheres with high-quality textures for use in any three.js scene. Whether you're building an educational planetarium, simulating satellite orbits, or just want a cool spinning moon on your homepage — you don't need to write boilerplate material and texture code. Just plug it in and let it orbit.

---

🚀 Features

• One-liner setup for textured 3D planetary bodies and satellites
• Fully customizable geometry and material parameters
• High-quality default color and normal maps, with options to customize
• Orbital simulation capabilities
• Designed for use with Three.js

---

📦 Installation

npm install astro3d
# or
yarn add astro3d

---

🔧 Usage

Creating a Moon

import * as THREE from "three";
import { createMoon } from "astro3d";

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();

renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

const moon = createMoon({
  radius: 5,
  widthSegments: 64,
  heightSegments: 64,
  roughness: 0.8,
  metalness: 0.2,
});

scene.add(moon);
camera.position.z = 15;

function animate() {
  requestAnimationFrame(animate);
  moon.rotation.y += 0.005;
  renderer.render(scene, camera);
}

animate();

Adding a Satellite

import { createSatellite } from "astro3d";

// Create a satellite
const satellite = createSatellite({
  satelliteScale: 0.2,
  lookAtTarget: [0, 0, 0], // Make it face toward the center
});

// Create an orbit path for the satellite
const orbitRadius = 7;
const satelliteOrbit = new THREE.Object3D();
scene.add(satelliteOrbit);

// Position the satellite in its orbit
satellite.position.set(orbitRadius, 0, 0);
satelliteOrbit.add(satellite);

// Animate the orbit
function animate() {
  requestAnimationFrame(animate);
  moon.rotation.y += 0.005;
  satelliteOrbit.rotation.y += 0.01; // Rotate the satellite around the moon
  renderer.render(scene, camera);
}

---

🛠️ Parameters

Moon Parameters

Here's the full list of options you can pass to createMoon:

Parameter	Type	Default	Description
radius	number	3	Radius of the sphere
widthSegments	number	256	Number of horizontal segments
heightSegments	number	256	Number of vertical segments
colorMapURL	string	colorMap	Path to the diffuse texture (color)
normalMapURL	string	normalMap	Path to the normal map
oblateness	number	0.0012	Slight squashing for realism
roughness	number	1.0	How rough the surface appears
metalness	number	0.0	How metallic the surface appears
reflectivity	number	0.05	Reflectiveness of the material
clearcoat	number	0.0	Clearcoat layer for extra gloss
aoMapIntensity	number	1.2	Intensity of ambient occlusion
lightMapIntensity	number	1.0	Intensity of baked lighting
envMapIntensity	number	0.05	Strength of environment reflection
bumpScale	number	0.2	Scale of bump mapping
normalScale	number	3.05	Intensity of normal mapping
flatShading	boolean	false	Enable flat shading
transparent	boolean	false	Enable transparency
side	THREE.Side	THREE.FrontSide	Which side(s) of the material to render
color	THREE.Color	new THREE.Color(0x707070)	Base material color
initialRotation	number	-Math.PI / 2	Initial Y rotation of the sphere

Satellite Parameters

Here's the full list of options for createSatellite:

Parameter	Type	Default	Description
satelliteScale	number	0.7	Overall scale factor for satellite
satelliteWidth	number	0.04	Width of satellite body
satelliteHeight	number	0.04	Height of satellite body
satelliteDepth	number	0.04	Depth of satellite body
wingWidth	number	0.08	Width of solar panels
wingHeight	number	0.02	Height of solar panels
wingDepth	number	0.002	Depth of solar panels
wingOffset	number	0.06	Distance of wings from center
satelliteMapURL	string	satelliteMap	Path to satellite texture
solarPanelMapURL	string	solarPanelMap	Path to solar panel texture
satelliteRoughness	number	0.5	Satellite material roughness
satelliteMetalness	number	0.8	Satellite material metalness
panelRoughness	number	0.2	Solar panel roughness
panelMetalness	number	0.5	Solar panel metalness
satelliteColor	THREE.Color	new THREE.Color(0xFFFFFF)	Base color for satellite
panelColor	THREE.Color	new THREE.Color(0x2244AA)	Base color for panels
lookAtTarget	Array|THREE.Vector3	[0, 0, 0]	Point the satellite toward this position

---

🖼️ Built-in Textures

Each celestial object function like createMoon and createSatellite comes with its own built-in textures, no need to import or configure separately.

---

🌌 Credits

Textures used for color and normal maps are courtesy of NASA, who generously provide high-resolution planetary data to the public.

---

🚧 Current Status

Currently, the package includes:

• Moon
• Satellite with solar panels
• Earth
• Jupiter

Contributions to add more celestial bodies (like Earth, Mars, Jupiter...) are very welcome!

---

🚀 Examples

Create a Moon with Orbiting Satellite

import * as THREE from "three";
import { createMoon, createSatellite } from "astro3d";

// Standard Three.js setup
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// Add lights
const ambientLight = new THREE.AmbientLight(0x404040);
const directionalLight = new THREE.DirectionalLight(0xffffff, 10);
directionalLight.position.set(1, 0, 1).normalize();
scene.add(ambientLight);
scene.add(directionalLight);

// Create moon
const moon = createMoon({ radius: 3 });
scene.add(moon);

// Create satellite and orbit
const satellite = createSatellite({
  satelliteScale: 0.2,
  satelliteColor: new THREE.Color(0xcccccc),
  panelColor: new THREE.Color(0x2244ff),
});

// Create orbit system
const orbitRadius = 7;
const satelliteOrbit = new THREE.Object3D();
scene.add(satelliteOrbit);
satellite.position.set(orbitRadius, 0, 0);
satelliteOrbit.add(satellite);

// Add visual orbit path (optional)
const orbitPath = new THREE.Mesh(
  new THREE.RingGeometry(orbitRadius - 0.03, orbitRadius + 0.03, 64),
  new THREE.MeshBasicMaterial({
    color: 0x3366ff,
    side: THREE.DoubleSide,
    transparent: true,
    opacity: 0.3,
  })
);
orbitPath.rotation.x = Math.PI / 2;
scene.add(orbitPath);

// Set camera position
camera.position.z = 15;

// Animation loop
function animate() {
  requestAnimationFrame(animate);
  moon.rotation.y += 0.001;
  satelliteOrbit.rotation.y += 0.005;
  satellite.rotation.y = -satelliteOrbit.rotation.y;
  renderer.render(scene, camera);
}

animate();

---

💫 Final Thoughts

This library was built to save you time and boilerplate, and make your planetary and satellite visualizations look good. If it helps you, consider giving a star 🌟 or contributing with a pull request.