Bioma Generator

Biome generation library built on deterministic terrain noise and meteo-generator climate data.

bioma-generator samples biome data for points or map grids. It does not own a rendering runtime: PNG rendering, browser display, Worker execution, and WASM execution are integration concerns around the canonical biome sampling API.

Requirements

• Node.js 24 or newer
• TypeScript 6 for local development
• Vitest 4 for tests

Install

npm install bioma-generator

Entrypoints

• bioma-generator: API core browser-safe, senza loader filesystem.
• bioma-generator/browser: entrypoint browser esplicito.
• bioma-generator/node: API Node con configPath e loadBiomaConfigFromFile.

Il contratto stabile per salvataggi/world seed è esposto come BIOMA_VERSION_CONTRACT, con algorithmVersion e configVersion.

Basic usage

import Bioma from "bioma-generator";

const bioma = new Bioma({
  seed: "world-42",
  climateProfile: "moderate",
  position: { x: 0, y: 0, z: 0 },
  timeMode: "manual",
  timestampMs: 0,
});

const sample = bioma.getBiomeAt(12, -4);

console.log(sample.key); // FOREST, OCEAN, DESERT, ...
console.log(sample.temperatureC);
console.log(sample.elevation);
console.log(sample.meteo.weatherKey);

CommonJS:

const Bioma = require("bioma-generator").default;

const bioma = new Bioma({ seed: "world-42" });
const sample = bioma.getBiomeAt(12, -4);

Point samples

getBiomeAt(x, y, z?) returns a deterministic BiomeSample for the configured seed, climate, timestamp, and position.

type BiomeSample = {
  key: string;
  label: string;
  color: [number, number, number];
  position: { x: number; y: number; z: number };
  z: number;
  elevation: number;
  altitudeMeters: number;
  heat: number;
  moisture: number;
  temperatureC: number;
  humidity: number;
  precipitation: number;
  meteo: {
    weatherKey: string;
    seasonKey: string;
    climateProfile: string;
    extremeEventKey: string | null;
  };
};

If z is omitted, altitude is derived from generated elevation and ALTITUDE.MAX_METERS.

Map sampling

sampleMap(options?) returns a two-dimensional array of BiomeSample values: BiomeSample[][], indexed as [row][column].

const map = bioma.sampleMap({
  width: 128,
  height: 96,
  center: { x: 0, y: 0, z: 0 },
  spanX: 512,
  spanY: 384,
});

const topLeft = map[0][0];

You can sample explicit bounds instead of a center and span:

const map = bioma.sampleMap({
  width: 64,
  height: 64,
  bounds: {
    minX: -256,
    maxX: 256,
    minY: -256,
    maxY: 256,
  },
});

Async generation ports

sampleMapAsync does not chunk work on the main thread. It requires an explicit GenerationComputePort, so callers can route generation to a Worker, WASM module, remote job runner, or any other compute boundary.

import Bioma, { createInlineBiomeMapComputePort } from "bioma-generator";

const bioma = new Bioma({ seed: "world-42" });

const computePort = createInlineBiomeMapComputePort((x, y, z) =>
  bioma.getBiomeAt(x, y, z)
);

const map = await bioma.sampleMapAsync({
  width: 128,
  height: 128,
  center: { x: 0, y: 0, z: 0 },
  spanX: 512,
  spanY: 512,
  computePort,
});

The inline compute port is useful for tests, local scripts, and simple integrations. Worker or WASM integrations should implement the same contract:

import type {
  BiomeMapGenerationComputePort,
  BiomeMapSamplingRequest,
  BiomeSample,
} from "bioma-generator";

const workerComputePort: BiomeMapGenerationComputePort = {
  async compute(request: BiomeMapSamplingRequest): Promise<BiomeSample[][]> {
    return runBiomeWorker(request);
  },
};

Configuration

Every Bioma instance owns an immutable configuration snapshot. Runtime overrides are deep-merged into the base config.

const bioma = new Bioma({
  seed: "archipelago",
  config: {
    MAP: {
      DEFAULT_WIDTH: 256,
      DEFAULT_HEIGHT: 192,
      SPAN_X: 1024,
      SPAN_Y: 768,
    },
    BIOME_THRESHOLDS: {
      SEA_LEVEL: 0.52,
      MOUNTAIN_LEVEL: 0.64,
    },
  },
});

You can create and reuse config snapshots directly:

import { createBiomaConfig } from "bioma-generator";

const config = createBiomaConfig({
  BIOME_THRESHOLDS: {
    SEA_LEVEL: 0.48,
  },
});

Node integrations can load JSON overrides from disk:

import BiomaNode from "bioma-generator/node";

const bioma = new BiomaNode({
  configPath: "./configs/bioma-tune-a.json",
});

Main configurable groups:

• DEFAULTS: default seed, position, climate profile, and time mode.
• MAP: default map size and sampled world span.
• RANGE: temperature, humidity, and precipitation ranges.
• ALTITUDE: maximum generated altitude in meters.
• NOISE: elevation, moisture, and heat noise layers.
• WEATHER_EFFECTS: biome humidity and precipitation effects by weather key.
• BIOME_THRESHOLDS: biome selection thresholds.
• BIOMES: biome labels and RGB colors.

CLI map render

The repository includes a Node rendering script for local PNG smoke tests and tuning. It is a tool adapter around map sampling, not part of the canonical domain generation path.

npm run render:map -- \
  --out renders \
  --width 240 \
  --height 160 \
  --spanX 600 \
  --spanY 400 \
  --centerX 0 \
  --centerY 0 \
  --sea 0.46 \
  --seed demo-seed \
  --climate moderate

Useful arguments:

• --out: output directory, default renders.
• --width, --height: PNG dimensions.
• --spanX, --spanY: sampled world span.
• --centerX, --centerY: sampled map center.
• --sea: one or more comma-separated sea levels.
• --seed: deterministic world seed.
• --climate: meteo-generator climate profile.
• --config: path to a JSON BiomaConfigOverride.

Example with multiple sea levels:

npm run render:map -- --sea 0.42,0.46,0.5 --seed coast-test

Browser demos

The repository contains static browser demos:

• index.html
• bioma-point.html
• bioma-map.html

Build the browser bundle first:

npm run build

Then serve the repository with any static server:

python3 -m http.server 4173 --bind 127.0.0.1

Open http://127.0.0.1:4173/bioma-map.html.

Development

npm install
npm run build
npm test
npm run render:map -- --out /tmp/bioma-render-smoke --width 32 --height 24 --sea 0.48 --seed smoke

npm run build compiles TypeScript and writes dist/bioma.browser.js.

Published files

The npm package publishes:

• dist
• readme.md