miaoda-game-procgen-core

Use this engine-independent package to generate dungeons, caves, mazes, arenas, Rogue-style maps, distance fields, simplex noise, and bounded non-overlapping spawn layouts. Map generators return miaoda-game-grid-core grids containing 'wall', 'floor', and 'door', ready for pathfinding, vision, or engine rendering adapters.

Install

pnpm add miaoda-game-procgen-core miaoda-game-grid-core

Generate and use a dungeon

import { generateDungeon, rectCenter } from 'miaoda-game-procgen-core';
import { findPath } from 'miaoda-game-grid-core';

const { grid, rooms } = generateDungeon({ width: 40, height: 30, seed: 7 });
const start = rectCenter(rooms[0]);
const exit = rectCenter(rooms.at(-1)!);

const path = findPath(
  { width: grid.width, height: grid.height },
  start,
  exit,
  { isBlocked: (x, y) => grid.get(x, y) === 'wall' },
);

floor and door are walkable; wall is not. Dungeon generators also return room rectangles for spawn, loot, and objective placement. Use farthestFrom(grid, start) when an exit should be far by actual walking distance rather than straight-line distance.

Choose a generator

| API | Result | | --- | --- | | generateDungeon | Organic rooms and corridors plus room metadata | | generateUniformDungeon | More evenly distributed rooms plus metadata | | generateCave | Smoothed cellular cave; connectivity defaults on | | generateMaze | Connected single-tile maze corridors | | generateRogueDungeon | Structured room grid and corridors | | generateArena | Deterministic border wall with open interior |

All seeded generators reproduce ordinary maps for the same options. Extremely large or constrained generators may hit library wall-clock safety limits; for cross-machine authoritative play, generate once on the authority and persist or hash the resulting grid.

Place continuous-space objects

import { placeNonOverlappingCircles } from 'miaoda-game-procgen-core';

const result = placeNonOverlappingCircles(
  [
    { id: 'fort', radius: 28 },
    { id: 'hostage', radius: 18 },
  ],
  {
    sample: ({ attempt, index }) => seededPoint(attempt, index),
    maxAttemptsPerItem: 40,
    clearance: 8,
    occupied: [{ x: playerStart.x, y: playerStart.y, radius: 60 }],
    accept: (point) => terrainAt(point) === 'floor',
    fallback: ({ item }) => authoredFallbacks[item.id] ?? null,
  },
);

if (!result.complete) reportGenerationFailure(result.failure);
for (const placement of result.placements) spawn(placement.id, placement.x, placement.y);

Items are processed in stable input order. The host owns the sampler and therefore the RNG stream; the core checks finite positions, circle overlap, optional clearance, existing occupied circles, and the host terrain/bounds predicate. Each item has a finite attempt budget. A fallback is accepted only when it passes the same rules; otherwise the result identifies the failed item, attempt count, and attempt-budget or fallback-rejected reason.

The function returns frozen data and never mutates a Phaser/Cocos object. Persist the resulting placements when they are authoritative. Do not rerun a sampler on every client unless its RNG state and all host queries are identical.

Noise and RNG ownership

import { Noise2D, getRngState, seedRng, setRngState } from 'miaoda-game-procgen-core';

const noise = new Noise2D(7);
const height = noise.get01(x * 0.05, y * 0.05); // value in [0, 1]

seedRng(7);
const savedState = getRngState();
setRngState(savedState);

The generator RNG is shared within the JavaScript realm. Calling seedRng or a generator with a seed replaces that stream, so assign one authoritative owner and avoid interleaving unrelated random consumers. Save current RNG state, not only the seed, when later rolls must continue rather than restart. Treat RNG state as hidden authoritative data because it reveals future results.

Seeded Noise2D and Noise3D instances use their own reproducible stream. get returns approximately [-1, 1]; get01 remaps to [0, 1].

Public API

Map generators, placeNonOverlappingCircles, distanceField, farthestFrom, Noise2D, Noise3D, seedRng, getRngState, setRngState, randomInt, shuffle, pick, and weightedPick are exported. There is no separate procgen engine adapter: generate stable data, then render or instantiate it through the host or existing grid adapter for Cocos or Phaser.