Planet Forge 🪐

A procedural planet generation library for React and Three.js.

Installation

npm install planet-forge

Usage

import { Canvas } from '@react-three/fiber';
import { Planet } from 'planet-forge';

function Scene() {
  return (
    <Canvas>
      <Planet 
        type="rocky" 
        radius={2} 
        seed={12345} 
        resolution={64} 
      />
    </Canvas>
  );
}

Architecture

Planet Forge uses a Factory Pattern combined with Strategy Pattern for planet generation.

Core Components

• PlanetFactory: The main entry point. It takes a type and configuration (seed, radius) and returns the appropriate Generator instance.
• BasePlanetGenerator: Abstract base class that defines the interface for all planet generators. It handles common tasks like mesh generation and material setup.
• Specific Generators (e.g., RockyPlanetGenerator, GasGiantGenerator): Implement the specific noise functions, color palettes, and shader logic for each biome.

Flow

1. The <Planet /> component receives props.
2. It calls PlanetFactory.create(type, seed, ...) to get a generator.
3. The generator creates the geometry (often a sphere with displacement) and a specialized shader material.
4. The Planet component renders a Three.js <mesh> with these assets.

Extending the Library

To add a new planet type (e.g., LavaWorld), follow these steps:

1. Create a New Generator

Create a new file in src/generators/lava-generator.ts extending BasePlanetGenerator.

import { BasePlanetGenerator } from './base-generator';

export class LavaPlanetGenerator extends BasePlanetGenerator {
  // 1. Define specific fragment shader with lava logic
  protected getFragmentShaderInvokation(): string {
    return `
      // Custom noise logic for lava
      float noise = cnoise(vPosition * 2.0);
      vec3 lavaColor = mix(vec3(0.1, 0.0, 0.0), vec3(1.0, 0.2, 0.0), noise);
      return vec4(lavaColor, 1.0);
    `;
  }

  // 2. Override geometry generation if needed (e.g., more jagged)
  generateGeometry() {
    // ... custom logic or call super
    return super.generateGeometry();
  }
}

2. Register in Factory

Update src/factory.planet.ts:

1. Add new type to PlanetType.
2. Import your new generator.
3. Add a case in PlanetFactory.create.

// src/types/planet.types.ts
export type PlanetType = 'rocky' | ... | 'lava';

// src/factory.planet.ts
static create(type: PlanetType, ...): BasePlanetGenerator {
  switch (type) {
    // ...
    case 'lava':
      return new LavaPlanetGenerator(seed, radius, resolution);
  }
}

3. Add to Type Registry

Update getAllTypes and getTypeName in PlanetFactory for UI integration.

static getTypeName(type: PlanetType): string {
    // ...
    lava: 'Mundo de Lavá',
}