@esengine/procgen 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ESEngine Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,619 @@
+import { BlueprintNodeTemplate, INodeExecutor, BlueprintNode, ExecutionResult } from '@esengine/blueprint';
+
+/**
+ * @zh Perlin 噪声实现
+ * @en Perlin Noise Implementation
+ *
+ * @zh 基于 Ken Perlin 的改进版噪声算法
+ * @en Based on Ken Perlin's improved noise algorithm
+ */
+/**
+ * @zh Perlin 噪声生成器
+ * @en Perlin noise generator
+ */
+declare class PerlinNoise {
+    private readonly _perm;
+    private readonly _gradP;
+    /**
+     * @zh 创建 Perlin 噪声生成器
+     * @en Create Perlin noise generator
+     *
+     * @param seed - @zh 随机种子 @en Random seed
+     */
+    constructor(seed?: number);
+    private _seed;
+    private _fade;
+    private _lerp;
+    private _dot2;
+    private _dot3;
+    /**
+     * @zh 2D Perlin 噪声
+     * @en 2D Perlin noise
+     *
+     * @param x - @zh X 坐标 @en X coordinate
+     * @param y - @zh Y 坐标 @en Y coordinate
+     * @returns @zh 噪声值 [-1, 1] @en Noise value [-1, 1]
+     */
+    noise2D(x: number, y: number): number;
+    /**
+     * @zh 3D Perlin 噪声
+     * @en 3D Perlin noise
+     *
+     * @param x - @zh X 坐标 @en X coordinate
+     * @param y - @zh Y 坐标 @en Y coordinate
+     * @param z - @zh Z 坐标 @en Z coordinate
+     * @returns @zh 噪声值 [-1, 1] @en Noise value [-1, 1]
+     */
+    noise3D(x: number, y: number, z: number): number;
+}
+/**
+ * @zh 创建 Perlin 噪声生成器
+ * @en Create Perlin noise generator
+ */
+declare function createPerlinNoise(seed?: number): PerlinNoise;
+
+/**
+ * @zh Simplex 噪声实现
+ * @en Simplex Noise Implementation
+ *
+ * @zh 比 Perlin 噪声更快且没有方向性伪影
+ * @en Faster than Perlin noise with no directional artifacts
+ */
+/**
+ * @zh Simplex 噪声生成器
+ * @en Simplex noise generator
+ */
+declare class SimplexNoise {
+    private readonly _perm;
+    private readonly _permMod12;
+    private static readonly _grad3;
+    /**
+     * @zh 创建 Simplex 噪声生成器
+     * @en Create Simplex noise generator
+     *
+     * @param seed - @zh 随机种子 @en Random seed
+     */
+    constructor(seed?: number);
+    private _seed;
+    /**
+     * @zh 2D Simplex 噪声
+     * @en 2D Simplex noise
+     *
+     * @param x - @zh X 坐标 @en X coordinate
+     * @param y - @zh Y 坐标 @en Y coordinate
+     * @returns @zh 噪声值 [-1, 1] @en Noise value [-1, 1]
+     */
+    noise2D(x: number, y: number): number;
+    /**
+     * @zh 3D Simplex 噪声
+     * @en 3D Simplex noise
+     *
+     * @param x - @zh X 坐标 @en X coordinate
+     * @param y - @zh Y 坐标 @en Y coordinate
+     * @param z - @zh Z 坐标 @en Z coordinate
+     * @returns @zh 噪声值 [-1, 1] @en Noise value [-1, 1]
+     */
+    noise3D(x: number, y: number, z: number): number;
+}
+/**
+ * @zh 创建 Simplex 噪声生成器
+ * @en Create Simplex noise generator
+ */
+declare function createSimplexNoise(seed?: number): SimplexNoise;
+
+/**
+ * @zh Worley (Cellular) 噪声实现
+ * @en Worley (Cellular) Noise Implementation
+ *
+ * @zh 基于 Voronoi 图的噪声，适合生成细胞、石头纹理
+ * @en Voronoi-based noise, suitable for cellular and stone textures
+ */
+/**
+ * @zh 距离函数类型
+ * @en Distance function type
+ */
+type DistanceFunction = 'euclidean' | 'manhattan' | 'chebyshev';
+/**
+ * @zh Worley 噪声生成器
+ * @en Worley noise generator
+ */
+declare class WorleyNoise {
+    private readonly _seed;
+    private readonly _distanceFunc;
+    /**
+     * @zh 创建 Worley 噪声生成器
+     * @en Create Worley noise generator
+     *
+     * @param seed - @zh 随机种子 @en Random seed
+     * @param distanceFunc - @zh 距离函数 @en Distance function
+     */
+    constructor(seed?: number, distanceFunc?: DistanceFunction);
+    private _hash;
+    private _randomPoint;
+    private _randomPoint3D;
+    private _distance2D;
+    private _distance3D;
+    /**
+     * @zh 2D Worley 噪声
+     * @en 2D Worley noise
+     *
+     * @param x - @zh X 坐标 @en X coordinate
+     * @param y - @zh Y 坐标 @en Y coordinate
+     * @param pointsPerCell - @zh 每个单元格的点数 @en Points per cell
+     * @returns @zh 到最近点的距离 [0, ~1.4] @en Distance to nearest point [0, ~1.4]
+     */
+    noise2D(x: number, y: number, pointsPerCell?: number): number;
+    /**
+     * @zh 3D Worley 噪声
+     * @en 3D Worley noise
+     *
+     * @param x - @zh X 坐标 @en X coordinate
+     * @param y - @zh Y 坐标 @en Y coordinate
+     * @param z - @zh Z 坐标 @en Z coordinate
+     * @param pointsPerCell - @zh 每个单元格的点数 @en Points per cell
+     * @returns @zh 到最近点的距离 @en Distance to nearest point
+     */
+    noise3D(x: number, y: number, z: number, pointsPerCell?: number): number;
+    /**
+     * @zh 获取到第 N 近点的距离（用于更复杂的纹理）
+     * @en Get distance to Nth nearest point (for more complex textures)
+     *
+     * @param x - @zh X 坐标 @en X coordinate
+     * @param y - @zh Y 坐标 @en Y coordinate
+     * @param n - @zh 第 N 近 (1 = 最近) @en Nth nearest (1 = nearest)
+     * @returns @zh 距离值 @en Distance value
+     */
+    nthNearest2D(x: number, y: number, n?: number): number;
+}
+/**
+ * @zh 创建 Worley 噪声生成器
+ * @en Create Worley noise generator
+ */
+declare function createWorleyNoise(seed?: number, distanceFunc?: DistanceFunction): WorleyNoise;
+
+/**
+ * @zh 分形布朗运动 (FBM)
+ * @en Fractal Brownian Motion (FBM)
+ *
+ * @zh 通过叠加多层噪声创建更自然的效果
+ * @en Creates more natural effects by layering multiple noise octaves
+ */
+/**
+ * @zh 噪声函数接口
+ * @en Noise function interface
+ */
+interface INoise2D {
+    noise2D(x: number, y: number): number;
+}
+/**
+ * @zh 噪声函数接口 (3D)
+ * @en Noise function interface (3D)
+ */
+interface INoise3D {
+    noise3D(x: number, y: number, z: number): number;
+}
+/**
+ * @zh FBM 配置
+ * @en FBM configuration
+ */
+interface FBMConfig {
+    /**
+     * @zh 八度数（层数）
+     * @en Number of octaves (layers)
+     */
+    octaves: number;
+    /**
+     * @zh 频率倍增因子
+     * @en Frequency multiplier per octave
+     */
+    lacunarity: number;
+    /**
+     * @zh 振幅衰减因子
+     * @en Amplitude decay per octave
+     */
+    persistence: number;
+    /**
+     * @zh 初始频率
+     * @en Initial frequency
+     */
+    frequency: number;
+    /**
+     * @zh 初始振幅
+     * @en Initial amplitude
+     */
+    amplitude: number;
+}
+/**
+ * @zh FBM 噪声生成器
+ * @en FBM noise generator
+ */
+declare class FBM {
+    private readonly _noise;
+    private readonly _config;
+    /**
+     * @zh 创建 FBM 噪声生成器
+     * @en Create FBM noise generator
+     *
+     * @param noise - @zh 基础噪声函数 @en Base noise function
+     * @param config - @zh 配置 @en Configuration
+     */
+    constructor(noise: INoise2D & Partial<INoise3D>, config?: Partial<FBMConfig>);
+    /**
+     * @zh 2D FBM 噪声
+     * @en 2D FBM noise
+     *
+     * @param x - @zh X 坐标 @en X coordinate
+     * @param y - @zh Y 坐标 @en Y coordinate
+     * @returns @zh 噪声值 @en Noise value
+     */
+    noise2D(x: number, y: number): number;
+    /**
+     * @zh 3D FBM 噪声
+     * @en 3D FBM noise
+     *
+     * @param x - @zh X 坐标 @en X coordinate
+     * @param y - @zh Y 坐标 @en Y coordinate
+     * @param z - @zh Z 坐标 @en Z coordinate
+     * @returns @zh 噪声值 @en Noise value
+     */
+    noise3D(x: number, y: number, z: number): number;
+    /**
+     * @zh Ridged FBM（脊状，适合山脉）
+     * @en Ridged FBM (suitable for mountains)
+     */
+    ridged2D(x: number, y: number): number;
+    /**
+     * @zh Turbulence（湍流，使用绝对值）
+     * @en Turbulence (using absolute value)
+     */
+    turbulence2D(x: number, y: number): number;
+    /**
+     * @zh Billowed（膨胀，适合云朵）
+     * @en Billowed (suitable for clouds)
+     */
+    billowed2D(x: number, y: number): number;
+}
+/**
+ * @zh 创建 FBM 噪声生成器
+ * @en Create FBM noise generator
+ */
+declare function createFBM(noise: INoise2D & Partial<INoise3D>, config?: Partial<FBMConfig>): FBM;
+
+/**
+ * @zh 种子随机数生成器
+ * @en Seeded Random Number Generator
+ *
+ * @zh 基于 xorshift128+ 算法的确定性伪随机数生成器
+ * @en Deterministic PRNG based on xorshift128+ algorithm
+ */
+/**
+ * @zh 种子随机数生成器
+ * @en Seeded random number generator
+ */
+declare class SeededRandom {
+    private _s0;
+    private _s1;
+    private readonly _initialS0;
+    private readonly _initialS1;
+    /**
+     * @zh 创建种子随机数生成器
+     * @en Create seeded random number generator
+     *
+     * @param seed - @zh 随机种子 @en Random seed
+     */
+    constructor(seed?: number);
+    /**
+     * @zh 重置到初始状态
+     * @en Reset to initial state
+     */
+    reset(): void;
+    /**
+     * @zh 生成下一个随机数 [0, 1)
+     * @en Generate next random number [0, 1)
+     */
+    next(): number;
+    /**
+     * @zh 生成整数 [min, max]
+     * @en Generate integer [min, max]
+     */
+    nextInt(min: number, max: number): number;
+    /**
+     * @zh 生成浮点数 [min, max)
+     * @en Generate float [min, max)
+     */
+    nextFloat(min: number, max: number): number;
+    /**
+     * @zh 生成布尔值
+     * @en Generate boolean
+     *
+     * @param probability - @zh 为 true 的概率 [0, 1] @en Probability of true [0, 1]
+     */
+    nextBool(probability?: number): boolean;
+    /**
+     * @zh 生成正态分布随机数 (Box-Muller 变换)
+     * @en Generate normally distributed random number (Box-Muller transform)
+     *
+     * @param mean - @zh 均值 @en Mean
+     * @param stdDev - @zh 标准差 @en Standard deviation
+     */
+    nextGaussian(mean?: number, stdDev?: number): number;
+    /**
+     * @zh 生成指数分布随机数
+     * @en Generate exponentially distributed random number
+     *
+     * @param lambda - @zh 率参数 @en Rate parameter
+     */
+    nextExponential(lambda?: number): number;
+    /**
+     * @zh 在圆内生成均匀分布的随机点
+     * @en Generate uniformly distributed random point in circle
+     *
+     * @param radius - @zh 半径 @en Radius
+     */
+    nextPointInCircle(radius?: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * @zh 在圆环上生成随机点
+     * @en Generate random point on circle
+     *
+     * @param radius - @zh 半径 @en Radius
+     */
+    nextPointOnCircle(radius?: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * @zh 在球内生成均匀分布的随机点
+     * @en Generate uniformly distributed random point in sphere
+     *
+     * @param radius - @zh 半径 @en Radius
+     */
+    nextPointInSphere(radius?: number): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * @zh 生成随机方向向量
+     * @en Generate random direction vector
+     */
+    nextDirection2D(): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * @zh 创建种子随机数生成器
+ * @en Create seeded random number generator
+ */
+declare function createSeededRandom(seed?: number): SeededRandom;
+
+/**
+ * @zh 加权随机工具
+ * @en Weighted Random Utilities
+ */
+
+/**
+ * @zh 加权项
+ * @en Weighted item
+ */
+interface WeightedItem<T> {
+    /**
+     * @zh 项目值
+     * @en Item value
+     */
+    value: T;
+    /**
+     * @zh 权重（> 0）
+     * @en Weight (> 0)
+     */
+    weight: number;
+}
+/**
+ * @zh 加权随机选择器
+ * @en Weighted random selector
+ */
+declare class WeightedRandom<T> {
+    private readonly _items;
+    private readonly _cumulativeWeights;
+    private readonly _totalWeight;
+    /**
+     * @zh 创建加权随机选择器
+     * @en Create weighted random selector
+     *
+     * @param items - @zh 加权项数组 @en Array of weighted items
+     */
+    constructor(items: WeightedItem<T>[]);
+    /**
+     * @zh 随机选择一个项目
+     * @en Randomly select an item
+     *
+     * @param rng - @zh 随机数生成器 @en Random number generator
+     */
+    pick(rng: SeededRandom | {
+        next(): number;
+    }): T;
+    /**
+     * @zh 使用 Math.random 选择
+     * @en Pick using Math.random
+     */
+    pickRandom(): T;
+    /**
+     * @zh 获取项目的选中概率
+     * @en Get selection probability of an item
+     */
+    getProbability(index: number): number;
+    /**
+     * @zh 获取所有项目数量
+     * @en Get total item count
+     */
+    get size(): number;
+    /**
+     * @zh 获取总权重
+     * @en Get total weight
+     */
+    get totalWeight(): number;
+}
+/**
+ * @zh 从加权数组中随机选择
+ * @en Pick from weighted array
+ *
+ * @param items - @zh 加权项数组 @en Array of weighted items
+ * @param rng - @zh 随机数生成器 @en Random number generator
+ */
+declare function weightedPick<T>(items: WeightedItem<T>[], rng: SeededRandom | {
+    next(): number;
+}): T;
+/**
+ * @zh 从权重映射中随机选择
+ * @en Pick from weight map
+ *
+ * @param weights - @zh 值到权重的映射 @en Map of values to weights
+ * @param rng - @zh 随机数生成器 @en Random number generator
+ */
+declare function weightedPickFromMap<T extends string | number>(weights: Record<T, number>, rng: SeededRandom | {
+    next(): number;
+}): T;
+/**
+ * @zh 创建加权随机选择器
+ * @en Create weighted random selector
+ */
+declare function createWeightedRandom<T>(items: WeightedItem<T>[]): WeightedRandom<T>;
+
+/**
+ * @zh 洗牌和采样工具
+ * @en Shuffle and Sampling Utilities
+ */
+
+/**
+ * @zh Fisher-Yates 洗牌算法（原地修改）
+ * @en Fisher-Yates shuffle algorithm (in-place)
+ *
+ * @param array - @zh 要洗牌的数组 @en Array to shuffle
+ * @param rng - @zh 随机数生成器 @en Random number generator
+ * @returns @zh 洗牌后的数组（同一数组）@en Shuffled array (same array)
+ */
+declare function shuffle<T>(array: T[], rng: SeededRandom | {
+    next(): number;
+}): T[];
+/**
+ * @zh 创建洗牌后的副本（不修改原数组）
+ * @en Create shuffled copy (does not modify original)
+ *
+ * @param array - @zh 原数组 @en Original array
+ * @param rng - @zh 随机数生成器 @en Random number generator
+ * @returns @zh 洗牌后的新数组 @en New shuffled array
+ */
+declare function shuffleCopy<T>(array: readonly T[], rng: SeededRandom | {
+    next(): number;
+}): T[];
+/**
+ * @zh 从数组中随机选择一个元素
+ * @en Pick a random element from array
+ *
+ * @param array - @zh 数组 @en Array
+ * @param rng - @zh 随机数生成器 @en Random number generator
+ * @returns @zh 随机元素 @en Random element
+ */
+declare function pickOne<T>(array: readonly T[], rng: SeededRandom | {
+    next(): number;
+}): T;
+/**
+ * @zh 从数组中随机采样 N 个不重复元素
+ * @en Sample N unique elements from array
+ *
+ * @param array - @zh 数组 @en Array
+ * @param count - @zh 采样数量 @en Sample count
+ * @param rng - @zh 随机数生成器 @en Random number generator
+ * @returns @zh 采样结果 @en Sample result
+ */
+declare function sample<T>(array: readonly T[], count: number, rng: SeededRandom | {
+    next(): number;
+}): T[];
+/**
+ * @zh 从数组中随机采样 N 个元素（可重复）
+ * @en Sample N elements from array (with replacement)
+ *
+ * @param array - @zh 数组 @en Array
+ * @param count - @zh 采样数量 @en Sample count
+ * @param rng - @zh 随机数生成器 @en Random number generator
+ * @returns @zh 采样结果 @en Sample result
+ */
+declare function sampleWithReplacement<T>(array: readonly T[], count: number, rng: SeededRandom | {
+    next(): number;
+}): T[];
+/**
+ * @zh 生成范围内的随机整数数组（不重复）
+ * @en Generate array of random unique integers in range
+ *
+ * @param min - @zh 最小值（包含）@en Minimum (inclusive)
+ * @param max - @zh 最大值（包含）@en Maximum (inclusive)
+ * @param count - @zh 数量 @en Count
+ * @param rng - @zh 随机数生成器 @en Random number generator
+ * @returns @zh 随机整数数组 @en Array of random integers
+ */
+declare function randomIntegers(min: number, max: number, count: number, rng: SeededRandom | {
+    next(): number;
+}): number[];
+/**
+ * @zh 按权重从数组中采样（不重复）
+ * @en Sample from array by weight (without replacement)
+ *
+ * @param items - @zh 项目数组 @en Item array
+ * @param weights - @zh 权重数组 @en Weight array
+ * @param count - @zh 采样数量 @en Sample count
+ * @param rng - @zh 随机数生成器 @en Random number generator
+ */
+declare function weightedSample<T>(items: readonly T[], weights: readonly number[], count: number, rng: SeededRandom | {
+    next(): number;
+}): T[];
+
+/**
+ * @zh 程序化生成蓝图节点
+ * @en Procedural Generation Blueprint Nodes
+ */
+
+declare const SampleNoise2DTemplate: BlueprintNodeTemplate;
+declare class SampleNoise2DExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+declare const SampleFBMTemplate: BlueprintNodeTemplate;
+declare class SampleFBMExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+declare const SeededRandomTemplate: BlueprintNodeTemplate;
+declare class SeededRandomExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+declare const SeededRandomIntTemplate: BlueprintNodeTemplate;
+declare class SeededRandomIntExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+declare const WeightedPickTemplate: BlueprintNodeTemplate;
+declare class WeightedPickExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+declare const ShuffleArrayTemplate: BlueprintNodeTemplate;
+declare class ShuffleArrayExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+declare const PickRandomTemplate: BlueprintNodeTemplate;
+declare class PickRandomExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+declare const SampleArrayTemplate: BlueprintNodeTemplate;
+declare class SampleArrayExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+declare const RandomPointInCircleTemplate: BlueprintNodeTemplate;
+declare class RandomPointInCircleExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+declare const ProcGenNodeDefinitions: {
+    templates: BlueprintNodeTemplate[];
+    executors: Map<string, INodeExecutor>;
+};
+
+export { type DistanceFunction, FBM, type FBMConfig, type INoise2D, type INoise3D, PerlinNoise, PickRandomExecutor, PickRandomTemplate, ProcGenNodeDefinitions, RandomPointInCircleExecutor, RandomPointInCircleTemplate, SampleArrayExecutor, SampleArrayTemplate, SampleFBMExecutor, SampleFBMTemplate, SampleNoise2DExecutor, SampleNoise2DTemplate, SeededRandom, SeededRandomExecutor, SeededRandomIntExecutor, SeededRandomIntTemplate, SeededRandomTemplate, ShuffleArrayExecutor, ShuffleArrayTemplate, SimplexNoise, type WeightedItem, WeightedPickExecutor, WeightedPickTemplate, WeightedRandom, WorleyNoise, createFBM, createPerlinNoise, createSeededRandom, createSimplexNoise, createWeightedRandom, createWorleyNoise, pickOne, randomIntegers, sample, sampleWithReplacement, shuffle, shuffleCopy, weightedPick, weightedPickFromMap, weightedSample };